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. Pick the path that matches how you want to work, then follow the matching Quickstart steps below.
LLM path
Recommended for vibe codersBest 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. The first pass may stop at a docs-review coverage-plan gate; that is setup plus proposed scope, not finished architecture docs.
Terminal path
Direct controlBest if you want to run every package command yourself.
Use the same package mechanics directly. This is better for scripts, CI, or when you want to inspect each command before it runs.
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.
Already decided you want the hosted dashboard for a local-only project? Jump to Connect local-only docs to hosted.
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.
Add the hosted app later
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.
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.
Connect local-only docs to hosted
This is the start-to-finish path after you have decided to add the hosted dashboard. Start here if you already ran VibeCompass locally and only have a .compass folder on your machine. You do not download VIBECOMPASS_SYNC_TOKEN. The hosted app creates a raw sync token for one hosted project, then you store that token in a local environment variable named VIBECOMPASS_SYNC_TOKEN.
Step 1
Create the hosted project
Go to vibecompass.dev, log in, and choose Connect local project. This creates the browser-side project that your local docs will push into.
Step 2
Create a sync token
Open that project’s Setup page and click Create sync token. The token appears once. Keep it in your shell or password manager, not in chat or Git.
Step 3
Push your local baseline
Run the generated commands from your project root. connect-hosted saves only non-secret project info; push uploads the docs snapshot.
# 1. Confirm you are in the project that already has local memory.
npx -y @vibecompass/vibecompass@latest status --root .compass
# 2. In the VibeCompass website, create a hosted project:
# Log in -> Connect local project -> create/open project -> Setup
# 3. Click "Create sync token" on that Setup page.
# Copy the token once, then store it in your terminal:
export VIBECOMPASS_SYNC_TOKEN='vcsync_...'
# 4. Run the command the Setup page prints.
# The project id comes from that hosted project.
npx -y @vibecompass/vibecompass@latest connect-hosted \
--root .compass \
--sync-api-url https://vibecompass.dev \
--sync-project-id <project-id-from-setup> \
--sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
# 5. Push your local docs baseline to the hosted app.
npx -y @vibecompass/vibecompass@latest push --root .compassWhat should I see after it works?
- The Setup checklist should mark the hosted baseline as pushed.
- The dashboard can show projected docs, decisions, and project-memory state from your local files.
- Your local files are still the source of truth. Hosted suggestions must come back through preview/export/apply before they become local docs.
If an AI agent is helping, launch it from the same terminal where VIBECOMPASS_SYNC_TOKEN is set, or have it stop and ask you to set the variable outside chat.
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.
`npx` runs the package without adding it to your project dependencies or leaving a local `vibecompass` binary behind. This is the cleanest path if you do not want to learn the npm commands first. In Claude Code, the LLM path also lets the AI drive guided setup when a direct `init --guided` terminal run needs an interactive TTY.
VibeCompass is project memory for vibe coding. The npm package is @vibecompass/vibecompass@latest 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. If this folder is not a Git repo, use a local folder source.
4. Start a named lane for this work — pick a short kebab-case slug like setup-project-memory.
5. If you can read the newly generated agent instructions in this same session, run docs review only through the coverage-plan approval gate. If not, stop and tell me to start a fresh AI session and type docs review.
6. If docs review reaches the approval gate, show me the proposed coverage plan, say clearly that no architecture docs have been applied yet, and ask me to approve or change the plan before spending more review tokens.
7. Do not call docs review done unless architecture docs were actually generated and applied. Tell me which files changed, whether docs were applied, and what I should review next.
Keep the terminal commands in the background unless you need my approval.Let the AI write the first real docs
If your setup session only reached the coverage-plan gate, approve or revise that plan before asking the AI to generate and apply architecture docs. If setup did not run docs review at all, type `docs review` into a fresh AI session in the same project and expect the same approval gate.
Fresh sessions are often better here because some tools do not immediately reload newly written agent files. The useful completion signal is changed `architecture/` docs plus a completed docs-review marker, not just an `external-review-requested` marker.
What should happen next
- First, the AI inventories the project broadly, proposes a coverage plan, and says no architecture docs have been applied yet.
- You approve or revise that plan before it spends more tokens generating docs.
- After approval, the AI writes accepted fenced output to `.compass/state/docs-review-output.md`.
- The package applies that output with `docs-review --apply-output` and reports the changed `architecture/` files.
- Choose any feature or system that needs a deeper follow-up pass at the plan gate or after the baseline lands.
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@latest and the docs are at https://vibecompass.dev/developers#connect-local-to-hosted — 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. Confirm this folder has .compass/project.yaml.
2. Tell me to open vibecompass.dev, log in, choose Connect local project, and create a sync token from the project Setup page.
3. Explain that the website shows the raw token only once, and that VIBECOMPASS_SYNC_TOKEN is just the local environment variable name I store it in.
4. After I set VIBECOMPASS_SYNC_TOKEN in the same terminal environment, run the generated connect-hosted and push commands from my project root.
5. 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, targeted docs-update planning, 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`). Add `--repo <id> --branch <name> --worktree` when the lane should work on its own branch in its own checkout — commands run from inside that worktree select the lane automatically. The lane also gets its own dev-server port and temp directory, so parallel lanes can run dev servers side by side — `eval "$(vibecompass lane-env)"` exports them into your shell. 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 `docs update` for an ad hoc documentation-maintenance plan when useful, then `close session` (or `end session`) at the end. Close-session prints the same plan plus a pre-close staleness set, requires architecture-doc, decision-log, and session-maintenance statuses before finalizing, cleans up a git-bound lane's clean worktrees (dirty ones survive with guidance; branches are never deleted) along with the lane's temp directory, and reminds connected local-primary roots to push when the hosted app should catch up.
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
docs update
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`. With multiple active lanes, name the lane explicitly: `review handoff <lane-id>`.
address reviewReads reviewer findings, responds inline (`[accepted]` / `[deferred]` / `[rejected]`), applies accepted changes, and refreshes the builder side of `handoff.md`.
docs updateRuns a targeted session-delta documentation plan through `vibecompass docs-update --session <lane-id>` so architecture docs, decisions, and session notes stay tied to what changed.
close sessionRuns the close-out checklist, prints the docs-update plan and pre-close staleness warnings, records document-maintenance checkpoint statuses, cleans up a git-bound lane's worktrees when they are safely removable, and ends with `vibecompass close-session`. It also surfaces hosted push/refresh guidance by project mode. `end session` is accepted as a synonym.
Underlying CLI commands
The prompt commands above run package CLI commands as part of their protocol. docs-update is the session-scoped documentation check: it maps changed files, lane claims, and new decisions to the architecture and decision files that may need maintenance, and surfaces a pre-close staleness set — new decisions since the lane started, base revisions the repos have moved past, newer session notes that touch the lane's scope, and claim overlap with other active lanes — which close-session re-emits as warnings. Close-session also prints mode-aware hosted guidance: local-primary roots can push after close when the hosted dashboard should catch up, while hosted-only projects refresh through the app. Each lane also gets its own dev-server port and temp directory at start, so parallel lanes never fight over port 3000 — lane-env exports them into your shell, and close-session cleans the temp directory up. You can also invoke them directly from the terminal — see the CLI page for the full surface (list-sessions, switch-session, docs-update, sync-agents):
vibecompass start-session --id <lane-id> --working-on "<short summary>"
# Optional per-lane git binding: create or reuse a branch in each bound repo;
# --worktree gives the lane its own checkout under <workspace>/worktrees/<lane-id>/
# (commands run from inside that worktree need no --root or --session)
vibecompass start-session --id <lane-id> --working-on "<short summary>" \
--repo <repo-id> --branch <branch-name> --worktree
# Each lane gets its own dev-server port (3100, 3101, ...) and temp dir, so two
# lanes can run "npm run dev" at once without colliding. Export them into the
# lane's shell — an unmodified dev server picks up PORT and TMPDIR for free:
eval "$(vibecompass lane-env)"
vibecompass docs-update --session <lane-id>
# Check the grouped decisions/INDEX.md against the decision files
# (append-decision keeps it refreshed automatically inside a lane):
vibecompass refresh-decision-index --check
vibecompass close-session \
--session <lane-id> \
--title "<finalized title>" \
--completed "<what changed>" \
--architecture-docs updated|not-needed|deferred \
--decision-log updated|not-needed|deferred \
--session-maintenance updated|not-needed|deferred \
--next-step "<where to resume>"
# Close-session also cleans up a git-bound lane: clean worktrees are removed
# (never forced), dirty ones survive with guidance, branches are never deleted.
# For connected local-primary roots, push after close when the app should catch up:
vibecompass push --root .compassThere 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@latest status --root .compassRefresh
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. Add --update-package-stamp when you want project.yaml to remember the newer package version.
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --dry-run
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --apply --update-package-stampWhat 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 --update-package-stamp. 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.