Vibe-Git is a CLI-driven multi-person collaboration tool. Invoke it through the terminal at vibe-gitthe web page is opened by vibe-git open to view team status. Do not treat old AgentGit MCP commands as commands of this CLI.
General principles for first-time users
Guide the user as someone encountering Git, the CLI, and multi-person collaboration for the first time; do not just throw out a single command. Every time the user says "first time using it," "I don't know how to install it," "how do I start," or gives only a vague goal, explain and proceed in the following order:
- First use one sentence to explain the relationship between the two things: the Skill lets the Agent know how to collaborate, and the CLI provides the room, status, and upload commands; the user only needs to install the Skill first, and when the user explicitly requests "automatic installation," the Agent directly performs the npm install of the CLI.
- First confirm whether the user is currently intheir own project Git workspace, not the Vibe-Git source directory, and not an empty folder.
- Confirm whether Node.js 24+, Git, and Codex CLI are available; if anything is missing, first give the installation direction and do not assume it is already installed.
- After installation is complete, you must ask clearly whether the user is the "team leader" or a "member." Before the identity is clear, do not execute
host start、connect、plan submitor other commands that change the room state. - Based on the identity, give only the commands needed for the current stage, and after each command explain "what you should see." Do not dump the entire command table at once.
Recommended first sentence:
Are you the team leader who wants to create a room, or a member who wants to join someone else's room? The team leader is responsible for starting the Host, collecting proposals, aligning, and publishing tasks; members are responsible for joining, submitting their own proposals, executing tasks, and confirming completion.
What the Skill can do for the user
The Skill will not decide requirements for the user out of thin air, but once the user's goal and identity are clear, it should proactively convert natural language into a safe, receipt-producing CLI flow:
- Installation assistant: check
vibe-git --help, dependency versions, and the current workspace; if the CLI is missing and the user has explicitly requested automatic installation, after confirming Node.js/npm are available, directly executenpm install -g @vibe-git/vibe-git, then runvibe-git --helpto verify. Do not recommend a nonexistentnpm install -g vibe-git。 - Team leader creating a room: after confirming the user is the team leader and is in the project workspace, assist in running
vibe-git host start, tell the user how to save and privately send the join command, then usevibe-git opento open the panel. - Member joining a room: ask the user to paste the complete join command or URL provided by the team leader, confirm the current workspace is the correct project workspace, then run
vibe-git connect <join-url>, then checkstatusand open the panel. - Automatically upload a proposal: after the user provides the goal, current state, plan, acceptance criteria, or code context, help organize it into UTF-8 Markdown; after the user explicitly says "submit/upload proposal," save it as a
.mdthat does not overwrite existing files, runvibe-git plan submit <文件.md>, and tell the user the CLI success receipt and version. - Automatically upload task details: when the user wants to add implementation steps, testing methods, or risks after claiming a task, organize the Markdown and, after confirming the task ID, run
vibe-git task push <task-id> <文件.md>。 - Auto-submit requirement changes: When the user explicitly says "change the requirement," "submit a change," or "submit a PR," first explain that PR here means a requirement change request internal to Vibe-Git, not a GitHub Pull Request; organize the change background, original requirement, modification content, impact scope, and acceptance method, and after confirming the user wants to submit, run
vibe-git pr submit <文件.md>。 - Connect to the Codex review/compute pool: When the user wants to connect to the Codex pool or review capability, run
vibe-git codex bind, have the user complete interactive device-auth, then runvibe-git codex statusto verify. This dedicated account is only used for review, does not replace the user's daily Codex configuration, and does not read or print credentials. - Task progress assistant: Based on the real
task-idand status, assist withtask list、task pull、task start、task sync、task integrate、task done; do not guess IDs, and do not falsely report Codex exiting as completion. - Advanced workflow assistant: Only when the user explicitly needs phased delivery, workflow contracts, or task dependencies, introduce
stage activate/replan、contract list/show/ack/publish、work list/pullandalign downgrade; first read the status and real IDs, and do not create stages, contracts, or dependencies out of thin air.
Only say "submitted," "connected," or "completed" after the CLI returns a success receipt. If it fails, preserve the original error, preferably suggest vibe-git status or vibe-git logs, and do not pretend success.
Install or locate the CLI
- First run
vibe-git --help. If the command is already available, use it directly; if already in the source repository and the build artifact exists, you can also invokenode <源码目录>/apps/cli/dist/index.js --help。 - When the user requests automatic installation and the CLI is unavailable, check Node.js 24+, npm, Git, and Codex CLI, then execute
npm install -g @vibe-git/vibe-git; after installation completes, rerunvibe-git --help。 - Only when the user explicitly chooses source installation or is developing Vibe-Git, enter the source repository and execute
npm ci、npm run build、npm link. On Windows PowerShell, you can usenpm.cmdto bypass the script execution policy. - For installation commands, one-line agent prompts, and troubleshooting, see Installation reference. Read it only when installing, updating, or when the command is unavailable.
First-time tutorial after installation
After installation succeeds and vibe-git --help can display commands, do not stop at "installation complete." Continue asking for identity and complete the corresponding minimal loop:
- Captain: Confirm the project workspace →
host start→ Save the join command →open→ Wait for members → Guide members to submit proposals →align start→ Review and decide →tasks publish。 - Member: Confirm the project workspace → Paste the join URL →
connect→status→open→ Prepare and submit your own proposal →task list→ Claim and start work.
After each state-changing command, reread status or the CLI receipt; do not treat a web button click, the end of a Codex conversation, or local file generation as the server having accepted it.
Check before invoking
- Confirm the current terminal is inthe user's own Git workspace。
host startandconnectwill record the current directory as that node's workspace; do not run them in the Vibe-Git tool source directory in place of the user's project directory, unless that directory is the project. - Use
vibe-git statusto read the current node identity, tasks, and background processes; when the captain checks the Host, usevibe-git host status. Maintain only one active node configuration on this machine at a time, and explain the impact before switching rooms or workspaces. - Obtain the real
alignment-id、task-id、node-id、review-idfrom the CLI receipt or panel; do not guess the ID. When waiting a long time for review, use a blocking wait script with a timeout to avoid frequent manual polling. --helplets you see the commands for the currently installed version. For the specific workflow, see Command Reference; read it before executing the corresponding role or phase.
Workflow Highlights
- Captain:
host start→ give the output join command to members →opento see the panel; when review capability is needed, at each node separatelycodex bind; after receiving at least one proposal, explicitlyalign start, after reviewing the alignment drafttasks publish <alignment-id>。 - Member: in your own workspace, run the
connect <join-url>→status→opengiven by the captain; useplan submit <文件.md>to submit or updateyour ownproposal. All nodes can view the team's latest proposal, but cannot modify others' proposals. - The file can be any name of
.md, must be non-empty UTF-8 and no larger than 256 KiB.plan submitis a proposal,task pushis task execution details,pr submitis an internal requirement change; the file name does not determine the document type. - Members first
task list、task pull <task-id>, can usetask pushto upload execution details; only calltask startafter explicitly deciding to start. After Codex ends normally and entersWAITING_CONFIRMATION, first freshly sync, then have the member confirm and calltask done。 - During development can
pr submit <文件.md>; ordinary members cannot initiate review. Captainreview start --forcewill notify in advance and pause affected tasks;review apply/review rejectneeds to make a decision based on the actual review results.
Role tutorial for "foolproof users"
Captain Tutorial
When the user chooses captain, follow this order and guide them through it; do not let the user guess the next step:
- Enter the project root directory, confirm there is
.git, then runvibe-git host start。 - From the successful receipt, find the join command and send it only to the intended members; do not publish it to the repository, Issues, or group announcements.
- Run
vibe-git opento view the room; do not treat the web address as the join command. - After members submit proposals, run
vibe-git status; when there is at least one proposal, runvibe-git align start。 - Use
align status、align show <alignment-id>to view conflicts; when adjudication is needed, use the realissue-idandoption-idto runalign resolve。 - After all substantive conflicts are adjudicated, first as needed
task assign, then runtasks publish <alignment-id>。 - When a requirement change is received during development, run
review start --force、review status, based on the actual review results runreview applyorreview reject。
Member Tutorial
When the user chooses member, require the captain to first send the complete join command, then follow this order and guide them through it:
- In the project root directory where you want to write code, run
vibe-git connect <join-url>。 - Run
vibe-git statusto confirm the node identity, then runvibe-git opento view the room. - Have the Skill organize
proposal.mdaccording to the user's project goals; after the user confirms the content, runvibe-git plan submit proposal.md。 - After receiving a task, first run
vibe-git task list, then use the realtask-idto runtask pull。 - When implementation steps need to be supplemented, use
task push; only usetask start。 - after explicitly deciding to start. After Codex ends normally, first run
task sync, confirm the status is fresh and the user agrees to complete, then runtask done。 - When a requirement change is discovered during development, have the Skill prepare a change request; after the user confirms, run
pr submit. This does not create a GitHub PR.
Codex Pool Tutorial
When the user says "connect compute", "bind review Codex", or "have Vibe-Git check the impact for me", first explain that this is a dedicated review account independent for each node, then run:
vibe-git codex bind
vibe-git codex status
When encountering a device-auth page, only tell the user to complete authorization; do not read, copy, or display local credentials. When you need to switch transport methods, then run based on the user's explicit choice vibe-git config set work.transport auto|app-server|cli。
Credentials and Receipts
- The join link contains a registration key; give it only to intended members; do not write it into the repository, Issues, or public logs. Do not read, print, or upload the credentials of
~/.vibe-git/client.json、data/v20/captain.jsonor~/.vibe-git/audit-codex. codex binduses interactive device-auth; the dedicated review account is stored locally in~/.vibe-git/audit-codex, and does not replace the daily Codex configuration. When encountering a login prompt, have the user complete device authorization.- Only report the operation as successful after the CLI returns a success receipt. On failure, retain the error message and check
vibe-git logs; the team lead can also check the local Host logs. Do not describe an internal Vibe-Git Pull Request as a GitHub PR.