Docs · Getting started
VibeCompass
VibeCompass is project memory for vibe coding. It keeps the story of your app next to the code, then gives that story to Claude Code, Codex, Cursor, and Copilot before they start changing files.
Overview
Think of VibeCompass as a shared project notebook for you and your AI coding tools. You still own the code. VibeCompass just keeps the important context organized so each new session knows what exists, why it exists, and what happened last time.
Project memory lives with your repo
VibeCompass creates a small set of files that act like a project notebook: what the app is, what decisions were made, and where the last coding session stopped.
Agent files are read directly by your tools
VibeCompass generates or adopts managed sections in CLAUDE.md, AGENTS.md, .cursorrules, and Copilot instructions next to your code. Claude Code, Codex, Cursor, and Copilot pick those up at session start through their own built-in conventions — no extra integration needed.
MCP serves the deeper memory on demand
When the AI needs more than the orienting summary — a specific decision, the full architecture for one feature, the last session note — it queries vibecompass-mcp instead of stuffing every doc into the start-of-session prompt.
When do I need MCP?
Skippable when: you’re solo on a file-access AI tool (Claude Code, Codex, Cursor) in one local repo. The generated agent files give the AI everything it needs to orient and read the rest of the memory root with its own filesystem tools.
Becomes load-bearing when:
- You want structured queries — “show me decision D-174”— instead of the AI grep-hunting through
decisions/*.md. One MCP call returns just that block. - Project memory moves to the hosted
vibecompass.devapp (team setup, dashboard-canonical). The AI on your machine can’t read remote files; MCP is the bridge. - You want write-back — the AI appending session notes or proposing decisions through tool calls instead of just reading.
Choose your setup path
You do not have to learn the npm commands first. If you prefer to work like a typical vibe coder, paste the LLM path into your AI coding tool and let the tool run the package mechanics for you.
LLM path
Best if you want to stay in Claude Code, Codex, Cursor, or Copilot.
Paste one short instruction into your AI tool. The model runs the package commands, explains approvals, and reports what changed.
Heads up if you use Claude Code: the LLM path exists because running vibecompass init --guided directly inside Claude Code can fail silently when it needs an interactive terminal (TTY).
Paste this into your AI session
VibeCompass is project memory for vibe coding. The npm package is @vibecompass/vibecompass and the docs are at https://vibecompass.dev/developers — read them if you need details.
1. Run the needed VibeCompass package commands for me with npx.
2. Initialize project memory with guided setup.
3. Start a named lane for this work — pick a short kebab-case slug like setup-project-memory.
4. If you can read the newly generated agent instructions in this same session, run docs review. If not, stop and tell me to start a fresh AI session and type docs review.
5. Tell me which files changed and what I should review.
Keep the terminal commands in the background unless you need my approval.Both paths end up with the same project memory files. The LLM path can tee up your first session and docs review automatically; the terminal path lets you do each step yourself when you are ready.
Using the hosted app
You can use VibeCompass without the hosted app. Add hosting only when you want browser views, team visibility, hosted docs-review, or a shared place to review proposals. The local package still owns the files in your project.
Use VibeCompass locally only
Install the npm package, keep `.compass` next to your code, run sessions, and use docs review locally. Nothing has to talk to vibecompass.dev.
Connect an existing local project
Log in, choose Connect local project, create a hosted project, then create a sync token on the Setup page. The dashboard prints the exact `connect-hosted` and `push` commands for your project.
Start hosted first
This is for people who want to create a hosted project or team before installing the local package. The dashboard shows this path, but the smooth self-serve flow is still being built.
Sync token vs MCP API key
A sync token connects the local package to one hosted project. Use it for connect-hosted, push, and hosted docs-review. An MCP API key is different: it lets Claude Code, Codex, Cursor, or another AI tool read hosted context through MCP. Create the sync token first; add MCP later if you need live AI tool access.
Quickstart
Pick the same path here that you chose above. The LLM path gives you prompts to paste into your AI coding tool; the Terminal path shows the package commands directly.
Ask your AI to set up project memory
Paste this into Claude Code, Codex, Cursor, or Copilot from the project you want VibeCompass to remember. The AI should run the package commands, explain approvals, and show you the files it changed.
This is the cleanest path if you do not want to learn the npm commands first.
VibeCompass is project memory for vibe coding. The npm package is @vibecompass/vibecompass and the docs are at https://vibecompass.dev/developers — read them if you need details.
1. Run the needed VibeCompass package commands for me with npx.
2. Initialize project memory with guided setup.
3. Start a named lane for this work — pick a short kebab-case slug like setup-project-memory.
4. If you can read the newly generated agent instructions in this same session, run docs review. If not, stop and tell me to start a fresh AI session and type docs review.
5. Tell me which files changed and what I should review.
Keep the terminal commands in the background unless you need my approval.Let the AI write the first real docs
If your setup session did not already run docs review, type `docs review` into a fresh AI session in the same project.
Fresh sessions are often better here because some tools do not immediately reload newly written agent files.
docs reviewAsk the AI to connect MCP
MCP lets the coding tool query deeper project memory during a session instead of relying only on startup instructions.
The AI may need to edit `.mcp.json`, Cursor settings, Claude Code MCP config, or Codex TOML depending on the tool.
VibeCompass is project memory for vibe coding. The MCP package is @vibecompass/vibecompass-mcp and the docs are at https://vibecompass.dev/developers — read them if you need details.
Ask me which AI coding tool I am using.
Use @vibecompass/vibecompass-mcp and point VIBECOMPASS_ROOT at the absolute path of the project memory root.
Update the right MCP settings for that tool, then tell me what changed.Add hosting only when you need it
Hosting is optional. Use it when you want the browser dashboard, team sync, hosted docs-review, or shared proposal review. The easiest path is to create the hosted project from the dashboard, then run the commands it prints.
Do not paste raw sync tokens into chat. Let the dashboard show the token once, then keep it in your shell or password manager.
VibeCompass is project memory for vibe coding. The npm package is @vibecompass/vibecompass and the docs are at https://vibecompass.dev/developers — read them if you need details.
I already have local project memory, and I want to connect it to the hosted dashboard.
Help me do this safely:
1. Open the VibeCompass dashboard and use Connect local project.
2. Create a sync token from the project Setup page.
3. Run the generated connect-hosted and push commands from my project root.
4. Explain that the sync token is for package upload, while an MCP API key is only for AI tool access.
Do not ask me to paste the raw sync token into chat.Session workflow
The workflow has two layers. The vibecompass package owns the file lifecycle: bootstrap, session start, and session end. Committed repo instructions like AGENTS.md and CLAUDE.md own the prompt commands and protocol so the coding tool knows whether it should behave as the builder, the reviewer, or the builder responding to review feedback.
How a session flows
Every session has two roles — builder and reviewer — that swap back and forth on the same scratch files. The package handles the file lifecycle; the prompt commands tell each AI session which hat to wear.
- Builder opens. Run `vibecompass start-session --id <lane-id>`, then prompt the AI with `start session` to load context and create the lane scratch files (`session.yaml`, `wip.md`, `handoff.md`). Make changes; keep both files current as you go.
- Reviewer joins. In a second AI session, prompt the AI with `join as reviewer`, then `review handoff`. The reviewer reads the selected lane's scratch files plus recent diffs, appends findings into `wip.md`, and refreshes `handoff.md`.
- Builder addresses. Back in the builder session, prompt `address review`. The builder responds inline to each finding (`[accepted]` / `[deferred]` / `[rejected]`), applies accepted changes, and refreshes `handoff.md`. Repeat steps 2–3 until findings are resolved.
- Builder closes. Prompt the AI with `close session` (or `end session` synonym). The builder runs the close-out checklist (sweep, architecture-doc updates, decision log refresh, finalized session note, doc-consistency check, Current-session block) and ends with `vibecompass close-session --session <lane-id>` plus any configured Git publish step.
Both roles can be the same person at the keyboard — running two AI sessions side-by-side, or one after the other. The lane scratch files (wip.md and handoff.md) are the canonical baton-pass between them.
Prompt commands
These are repo-instruction prompts, not package subcommands. Use them to select the role and the next action inside an active lane.
start session
join as reviewer
review handoff
address review
close sessionstart sessionOpens the builder lane: loads the latest session note + repo instructions, creates lane-local `wip.md` and `handoff.md`, and updates the current-session marker.
join as reviewerSwitches the AI into reviewer role for the selected lane — read-only context loading, no edits to canonical files.
review handoffRuns an actual review pass: reads lane scratch files plus recent diffs, appends findings into `wip.md`, and refreshes the reviewer side of `handoff.md`.
address reviewReads reviewer findings, responds inline (`[accepted]` / `[deferred]` / `[rejected]`), applies accepted changes, and refreshes the builder side of `handoff.md`.
close sessionRuns the close-out checklist (conversation sweep, architecture-doc updates, decision log refresh, finalized session note, doc-consistency check, Current-session block) and ends with `vibecompass close-session`. `end session` is accepted as a synonym.
Underlying CLI commands
The start session and close session prompts run these CLI commands as part of their protocol. You can also invoke them directly from the terminal — see the CLI page for the full surface (list-sessions, switch-session, sync-agents):
vibecompass start-session --id <lane-id> --working-on "<short summary>"
vibecompass close-session --session <lane-id> --title "<finalized title>"There is intentionally no review complete prompt. A review pass ends when the reviewer has updated the selected lane's wip.md and handoff.md; the builder picks it up with the next address review pass.
Guided init can also store workflow defaults in project.yaml.metadata.workflow, including whether close-session should include a Git publish step and which remote name that step should use.
For the deeper protocol reference — role responsibilities, scratch files, and multiple active lanes — head to the Protocol page. For every CLI command and a copy-ready example, use the CLI page.
Stay current
Once your project memory is set up, two commands keep it healthy and keep you on a recent vibecompass release: one to check, one to refresh. Both are safe to run any time — they tell you what they would do before they do it.
Check
vibecompass status
A read-only “is everything okay?” report. It prints your project identity, which session lanes are open, whether anything has drifted, and the safest next command to run. Nothing is changed on disk — copy whatever command it suggests when you are ready.
npx -y @vibecompass/vibecompass statusRefresh
vibecompass refresh-workflow
Re-generates the package-owned helper files — context.md, the workflow guide READMEs, the managed sections of your agent files, and the local state/manifest.json — so they match the CLI you just installed. Defaults to a dry run; add --apply when the plan looks right.
npx -y @vibecompass/vibecompass refresh-workflow --dry-run
npx -y @vibecompass/vibecompass refresh-workflow --applyWhat about “Compatibility warnings” at the top of the output?
Starting in 0.4.0, every vibecompasscommand runs a quick preflight check before doing its job. If the generated files in your memory root were last refreshed by an older CLI, you’ll see a short Compatibility warnings:block above the normal output. The command still runs — it’s just letting you know there’s newer scaffolding available.
The usual move is status → refresh-workflow --dry-run → refresh-workflow --apply. For the full walkthrough — installing a newer CLI, the sticky package-version stamp, what does and does not get touched, and the common troubleshooting paths — head to the Upgrade page.
Packages
VibeCompass is deliberately split so ownership of project memory stays separate from the transport layer that feeds AI tools.
Keep going
That covers the surface needed to get a project memory root running and connected to your coding tool. For the deeper picture — hosting modes, the four-layer architecture, sync semantics, trust boundaries, and what isn’t shipped yet — continue to Concepts.