Install the client.
Authorize the machine.
VibeCommit records your coding-agent sessions from a client that runs on your own machine. vibecommit connect registers capture with every agent it finds installed — Claude Code, Codex CLI, Cursor — handing over the session on Stop, PreCompact, and SessionEnd.
- 01 · install · in your shell$npm install -g @vibe-commit/capture
Puts the vibecommit command on your PATH. The next two steps need it.
- 02 · authorize · in your shell$vibecommit auth
Opens your browser to sign in and approve a machine credential for this computer, then saves it to ~/.vibecommit/credentials.json, mode 0600. The approval page states its terms: it lasts 90 days, is not rotated, is stored in plain text, and the only way to stop it sooner is to revoke it in settings. If a browser step fails, or you run it with --paste, it asks you to paste a credential created in settings instead. The paste is read without echoing, and a credential is never taken as an argument, because arguments are kept in your shell history and are readable by other processes while the command runs. Until a credential is set, sessions are captured to a local spool and nothing is sent. Signing in to this website alone does not set one up.
- 03 · connect · in each clone$vibecommit connect
Registers session capture with each agent on this machine, and writes a git post-commit hook into the clone you run it in — unconditionally, with no flag to skip it — so a commit is recorded alongside the session that was capturing when it landed. It is per clone, and it is safe to delete.
It carries the capture client inside it, so it needs no npm at all, and it brings the MCP server and the rules files the client does not. Run both lines inside Claude Code.
The plugin registers its own hooks and does not edit your settings.json. It does not put vibecommit on your PATH, so steps 01–03 are still how you authorize the machine and bind commits.
Three agents, two config shapes
vibecommit connect writes a config only for an agent that is already here — the directory has to exist first. Creating ~/.cursor/hooks.json on a machine with no Cursor would leave a file you never asked for, in a tool you do not run, that a later install would silently inherit.
- Claude Code
- ~/.claude/settings.json, honouring CLAUDE_CONFIG_DIR.
- Codex CLI
- ~/.codex/hooks.json, honouring CODEX_HOME. ⛔ Codex asks you to trust new hooks the next time it starts — until you do, it will not run them. Installing here does not make Codex capture; accepting that prompt does.
- Cursor
- ~/.cursor/hooks.json, in Cursor’s own flat shape.
Hooks you already had are added to, never replaced, and they still run. If one of these files cannot be read as JSON it is left exactly as it is and the failure is reported — overwriting a file we cannot parse would discard settings we cannot see.
What the install writes
Hooks on Stop, PreCompact, and SessionEnd, in the config file belonging to each agent that is installed here. They hand the session to the client when the agent finishes a turn, compacts, or exits.
A git hook, in the clone you ran vibecommit connect in. It records the commit against the session that was capturing in that clone when the commit landed — what was active, not who wrote the code. This is per clone — another clone of the same repo has none until you connect there — and the hook is safe to delete.
Three cases where a naive install would do nothing and say nothing. Here is what happens instead — and none of them change what vibecommit connect exits with, because observing commits is an addition to capturing sessions, not a precondition for it.
- core.hooksPath redirects hooks elsewhere
- Git ignores .git/hooks entirely when core.hooksPath points somewhere else, so this is a refusal rather than a warning: nothing is written, into .git/hooks or into the configured directory, and vibecommit connect reports that the commit hook is not active. Writing a file that silently never runs would be worse.
- you already have a post-commit hook
- Yours is moved aside and chained, never overwritten — and it runs first, with its exit status preserved. Ours runs after and cannot change the outcome.
- the send fails
- Captures are spooled on disk, and the spool is truncated only on a 2xx from the server. A send that fails stays in the spool and is retried rather than dropped.
The MCP server
A separate surface your coding agent talks to in-session, so it can reach the record while it works. Capture does not depend on it — install it only if you want your agent to have it. Setup for nine clients lives in the docs.
mcp setup →