vcoding

One command to scaffold a vibe-coding project — the RIPER-5 agent harness with shared config bridges for every major AI coding tool.

npx @gaosichun/vcoding

Installs a vcoding command. Run it directly with npx @gaosichun/vcoding, or npm i -g @gaosichun/vcoding once and then just vcoding.

vcoding drops a complete, opinionated AI-agent workflow into any project: a RIPER-5 spec-driven process (RESEARCH → INNOVATE → PLAN → EXECUTE → FAST MODE → UPDATE PROCESS), specialized agents, auto-discovered skills, lifecycle hooks, and ready-to-use config files so all your tools read the same source of truth — no per-tool copy-paste, no config drift.

This project packages and extends the excellent vibecode-pro-max-kit harness (see Attribution).

中文速览:vcoding 一条命令把一整套 AI 编程工作流装进任意项目。命令行 默认中文(--en 切英文)。安装分三步:① 选工具包(pro-max-kit / ECC) → ② 选 IDE → ③ 选安装内容(默认全装)。直接 npx @gaosichun/vcoding 即可交互式安装;vcoding update 原地更新。详见下文 选择工具包、三级选择、 常见问题。

Requirements

| Requirement | Notes | | --- | --- | | Node.js ≥ 18 | The CLI and resolver are dependency-free and run on any Node ≥ 18 (node -v to check). | | OS | Works on macOS, Linux, and Windows. | | Windows | The shared .agents/skills link uses a junction (no admin needed); if that fails it falls back to a real directory copy — so no Developer Mode or admin shell is required. | | ECC toolkit only | --kit ecc runs npx ecc-universal under the hood, so it needs network access on first use to fetch the ECC installer. |

Quick start

# scaffold into the current folder
npx @gaosichun/vcoding

# scaffold into a new folder
npx @gaosichun/vcoding my-app

# preview the file list without writing anything
npx @gaosichun/vcoding --dry-run

# update an existing install in place (reuses your previous selection)
npx @gaosichun/vcoding update

# English interface (default is Chinese / 默认中文)
npx @gaosichun/vcoding --en

The CLI is bilingual: it defaults to a Chinese interface and switches to English with --en (or --lang en, or VCODING_LANG=en). The confirmation prompt accepts both Chinese (是 / 否) and English (y / n) answers.

Then open your AI IDE in the project and say “Run vc-setup” to tailor the harness to your codebase.

Choose your toolkit

vcoding is a thin orchestrator over multiple upstream AI-coding toolkits. The install flow is toolkit → IDE → content: you first pick which toolkit to scaffold, then which IDE(s), then what to install (default: everything).

| Toolkit (--kit) | What it is | How it installs | | --- | --- | --- | | pro-max-kit (default) | Bundled vibecode-pro-max-kit RIPER-5 harness, 10 IDE bridges | Shipped inside this package | | ecc | affaan-m/ECC (ecc-universal), profile-based | Fetched from npm and delegated to ECC's own installer |

# interactive: prompts for toolkit, then IDE, then content
npx @gaosichun/vcoding

# scaffold the default pro-max-kit for Cursor
npx @gaosichun/vcoding --kit pro-max-kit --ide cursor

# scaffold ECC for Cursor with the "developer" profile
npx @gaosichun/vcoding --kit ecc --ide cursor --profile developer

For ecc, --ide selects ECC targets (claude, cursor, codex, gemini, opencode, codebuddy, antigravity) and --profile selects an ECC content profile (core, developer, security, research, full). Each run scaffolds one toolkit; run again to add another.

What gets installed

| Layer | What it is | | --- | --- | | Agents | RIPER-5 mode agents + specialists (research, plan, execute, debug, review, …) | | Skills | Auto-discovered SKILL.md capabilities (scout, audit, security, frontend, …) | | Hooks | Lifecycle hooks (naming checks, privacy guards, post-edit reminders, …) | | Process | Shared process/ protocols, plan/context scaffolding, seeds | | IDE bridges | Thin per-tool config files that all point back to AGENTS.md |

Existing files are backed up to .vibecode-backup/ before any overwrite, and your local .claude/settings.json and example plans are preserved.

Works across your tools

The harness is built on two open standards — AGENTS.md and SKILL.md — so the same workflow runs everywhere with no adapters:

| Tool | Reads | Wiring | | --- | --- | --- | | Claude Code | CLAUDE.md + .claude/ | Native (canonical) | | Codex | AGENTS.md + .codex/ + .agents/skills/ | Native (canonical) | | Cursor | AGENTS.md, .cursor/rules/*.mdc | Native + bridge | | Windsurf | AGENTS.md, .windsurf/rules/*.md | Native + bridge | | Gemini CLI / Antigravity | GEMINI.md | Bridge (imports @./AGENTS.md) | | Grok CLI | AGENTS.md + .agents/skills/ | Native (no .grok/ rule file) | | Kiro | .kiro/steering/*.md | Bridge (inclusion: always) | | Trae | .trae/rules/*.md | Bridge (alwaysApply: true) | | Qoder | AGENTS.md, .qoder/rules/*.md | Native + bridge (alwaysApply: true) | | GitHub Copilot | .github/copilot-instructions.md | Bridge |

Any other tool that follows the AGENTS.md standard works with zero extra config. Full details in docs/AI-IDE-COMPATIBILITY.md.

CLI reference

npx @gaosichun/vcoding [directory] [options]   # or: vcoding [directory] [options]

Arguments
  directory          Target project directory (default: current directory)

Commands
  (default)          Install the harness into a project
  update [directory] Refresh an existing install to the latest harness,
                     reusing the IDE/content selection it was installed with

Options
  -y, --yes          Skip the confirmation prompt (non-interactive)
      --dir <path>   Target directory (alternative to positional arg)
      --ide <list>   Only generate config for these IDEs (comma-separated)
                     e.g. --ide cursor,windsurf,claude
      --all          Generate config for every supported IDE (default)
      --parts <list> Only install these content components (comma-separated)
                     e.g. --parts agents,skills · keys: agents, skills, hooks, process
      --full         Install every content component (default)
      --skills <list>  Only these skills (comma-separated; default: all)
      --agents <list>  Only these agents (comma-separated; default: all)
      --hooks <list>   Only these hooks (comma-separated; default: all)
      --process <list> Only these process folders (comma-separated; default: all)
      --prune        On update, remove files dropped by the new harness version
      --lang <zh|en> Interface language (default: zh; also --en / --zh)
      --dry-run      Show what would be installed without writing anything
      --no-backup    Do not back up existing files before overwriting
  -h, --help         Show help
  -v, --version      Show CLI and harness versions

Three levels of selection

Installation narrows in three independent, composable steps:

1. IDE (--ide) — which tool config bridges to generate.
2. Content (--parts) — which categories to install: agents, skills, hooks, process.
3. Items / details (--skills, --agents, --hooks, --process) — which specific items inside a category. Interactively, after you pick a category you are shown its items and can pick a subset; Enter = all items in that category.

# Only the vc-scout and vc-debug skills, nothing else from skills:
npx @gaosichun/vcoding . --parts skills --skills vc-scout,vc-debug

# Two specific agents + one specific hook:
npx @gaosichun/vcoding . --agents vc-plan-agent,vc-execute-agent --hooks post-edit.sh

The shared core (AGENTS.md, CLAUDE.md, settings) and the bridges for your selected IDEs are always installed. Item selections are recorded in .vc-meta.json and reused by update (override per category with the same --skills/--agents/--hooks/--process flags).

Updating & versions

Every install records a small .vc-meta.json in the target project capturing the package version, the harness version, and the IDE / content / item selection you chose. vcoding update reads it to refresh the same set of files in place:

npx @gaosichun/vcoding update           # reuse the recorded selection
npx @gaosichun/vcoding update --ide cursor   # override the IDE selection
npx @gaosichun/vcoding update --prune        # also delete files dropped upstream

Updates back up overwritten files to .vibecode-backup/ first and report the harness version delta (old → new) plus how many files changed. Installs that predate .vc-meta.json are still detected via the legacy .vc-installed-files snapshot, so older projects update cleanly too.

Maintainers: syncing the upstream kit

The tool-agnostic “brain” (agents, skills, hooks, process/, AGENTS.md) is owned by vibecode-pro-max-kit. To pull upstream changes into this package without disturbing the CLI or the multi-IDE bridges:

npm run sync:upstream -- --dry-run   # preview brain changes + version delta
npm run sync:upstream                # apply, then bump package.json + npm publish

The script mirrors the brain from upstream, bumps the harness version in vc-manifest.json to match, and leaves bin/, lib/, package.json, and all bridge files untouched.

Troubleshooting & FAQ

vcoding --version shows an old version after a global install. The globally installed binary is cached by npm. Reinstall the latest explicitly, or just use npx which always resolves the published latest:

npm i -g @gaosichun/vcoding@latest   # refresh the global binary
npx @gaosichun/vcoding@latest        # or always run the latest without installing

Windows: EPERM: operation not permitted, symlink … during install. This was fixed — current versions create the .agents/skills link as a Windows junction (no admin/Developer Mode needed) and fall back to a directory copy if even that is blocked. If you still see it, you are on an old cached binary; reinstall with @latest as above.

Where does ECC install? With --kit ecc, some targets are home-scoped and install into your home directory rather than the current project:

| ECC target | Installs to | | --- | --- | | claude, codex, opencode | your home dir (e.g. ~/.claude, ~/.codex) | | cursor, gemini, codebuddy, antigravity | the current project |

The CLI prints a warning listing exactly which selected targets are home-scoped before it proceeds.

Can I install more than one toolkit? Yes — each run scaffolds one toolkit. Run vcoding again and pick the other toolkit (e.g. once for pro-max-kit, again for ecc).

How do I undo an install / restore my old files? Every overwrite is backed up first to .vibecode-backup/<timestamp>/ in the target project (unless you pass --no-backup). To revert, copy the files back from the latest backup folder and remove the harness files vcoding added. .claude/settings.json and your example plans are preserved across installs and updates.

Nothing is written when I expected an install. You probably ran with --dry-run (preview only) — drop the flag to actually write. In non-interactive contexts (no TTY) without --yes, the CLI also previews rather than writing; add -y/--yes to install non-interactively.

How it works

vcoding ships the harness inside the npm package. On run, it reads vc-manifest.json, resolves the exact set of files meant for end-user projects (excluding kit-only files like CI workflows and this README), copies them into your target directory, and recreates the .agents/skills → .claude/skills symlink that lets Codex and Claude share one skill tree. The resolver is dependency-free and runs on Node ≥ 18.

npm test   # verifies the resolver matches the kit manifest + a real install

Attribution

vcoding is built on top of vibecode-pro-max-kit by its original authors, used under the MIT License. This repository preserves that license (see LICENSE) and adds:

• a professional vcoding npm CLI for one-command bootstrapping, and
• expanded multi-IDE compatibility bridges (Gemini, Cursor, Windsurf, Kiro, Trae, Qoder, Copilot) wired into the install manifest, plus Grok support via the native AGENTS.md standard, and
• interactive IDE selection (--ide) so you generate only the configs you need, and
• interactive content selection (--parts) so you can install only part of the harness (agents, skills, hooks, process); the shared core and selected IDE bridges always install.

License

MIT