SuperAPI AI Directory

vibe-git

General & other

View repository

Updated 10-16 09:30

About this skill

Vibe-Git CLI

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:

  1. 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.
  2. First confirm whether the user is currently intheir own project Git workspace, not the Vibe-Git source directory, and not an empty folder.
  3. 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.
  4. 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 submit or other commands that change the room state.
  5. 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 execute npm install -g @vibe-git/vibe-git, then run vibe-git --help to verify. Do not recommend a nonexistent npm 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 use vibe-git open to 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 check status and 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, run vibe-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 run vibe-git codex status to 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-id and status, assist with task 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/pull and align 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

  1. 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 invoke node <源码目录>/apps/cli/dist/index.js --help。
  2. 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, rerun vibe-git --help。
  3. 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 use npm.cmd to bypass the script execution policy.
  4. 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 start and connect will 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 status to read the current node identity, tasks, and background processes; when the captain checks the Host, use vibe-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.
  • --help lets 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 → open to see the panel; when review capability is needed, at each node separately codex bind; after receiving at least one proposal, explicitly align start, after reviewing the alignment draft tasks publish <alignment-id>。
  • Member: in your own workspace, run the connect <join-url> → status → opengiven by the captain; use plan 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 submit is a proposal,task push is task execution details,pr submit is an internal requirement change; the file name does not determine the document type.
  • Members first task list、task pull <task-id>, can use task push to upload execution details; only call task startafter explicitly deciding to start. After Codex ends normally and enters WAITING_CONFIRMATION , first freshly sync, then have the member confirm and call task done。
  • During development can pr submit <文件.md>; ordinary members cannot initiate review. Captain review start --force will notify in advance and pause affected tasks;review apply / review reject needs 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:

  1. Enter the project root directory, confirm there is .git, then run vibe-git host start。
  2. 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.
  3. Run vibe-git open to view the room; do not treat the web address as the join command.
  4. After members submit proposals, run vibe-git status; when there is at least one proposal, run vibe-git align start。
  5. Use align status、align show <alignment-id> to view conflicts; when adjudication is needed, use the real issue-id and option-id to run align resolve。
  6. After all substantive conflicts are adjudicated, first as needed task assign, then run tasks publish <alignment-id>。
  7. When a requirement change is received during development, run review start --force、review status, based on the actual review results run review apply or review 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:

  1. In the project root directory where you want to write code, run vibe-git connect <join-url>。
  2. Run vibe-git status to confirm the node identity, then run vibe-git open to view the room.
  3. Have the Skill organize proposal.mdaccording to the user's project goals; after the user confirms the content, run vibe-git plan submit proposal.md。
  4. After receiving a task, first run vibe-git task list, then use the real task-id to run task pull。
  5. When implementation steps need to be supplemented, use task push; only use task start。
  6. 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 run task done。
  7. 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.json or ~/.vibe-git/audit-codex .
  • codex bind uses 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.