VibeCompass/docs
HomeSign in

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.

How it fits together
How VibeCompass fits togetherThe @vibecompass/vibecompass npm package writes a local project memory root containing project.yaml, architecture, decisions, sessions, and generated agent instruction files. AI coding tools — Claude Code, Codex, Cursor, and Copilot — read those agent files directly from the memory root at session start through their own built-in conventions. For deeper context during a session, those tools can also query the vibecompass-mcp adapter, which serves the same memory root on demand. The hosted vibecompass.dev app optionally syncs two-way with the same root and projects to a browser dashboard.writesreads throughlive queriesagent filessyncsprojectslocal filesProject memory rootproject.yaml · architecturedecisions · sessions · agent filesnpm package@vibecompass/vibecompassinit · sync-agentsstart- / close-sessionMCP adaptervibecompass-mcpon-demand queries into thememory root during a sessionAI coding toolsClaude · Codex · Cursor · Copilotread agent files at start;query MCP for the restweb hostingvibecompass.devoptional projection layer:search · proposals · teamshuman viewDashboarda browser view of thesame project memory

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.

Your AI tools read it at the start of a session

VibeCompass writes a managed section into CLAUDE.md, AGENTS.md, .cursorrules, and Copilot's instructions. Claude Code, Codex, Cursor, and Copilot read those files on their own, so there is nothing else to install.

MCP answers the deeper questions

When your AI needs more than that summary, such as one feature's docs or the decisions about billing, it can ask the vibecompass-mcp server instead of loading every file up front. It's optional.

Quickstart

Pick how you want to work; both paths create the same files. On the LLM path, recommended, you paste instructions into your AI tool, and it runs the commands and tells you what changed. On the Terminal path, you run each package command yourself, which suits scripts or seeing every step.

  1. Ask your AI to set up project memory

    Paste this into Claude Code, Codex, Cursor, or Copilot, opened in the project you want VibeCompass to remember. Your AI runs the package with npx, so nothing is added to your project's dependencies, and tells you which files it changed. In Claude Code, this path also lets your AI drive guided setup when running init --guided yourself would need an interactive terminal.

    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.

  2. Approve the plan for your first docs

    Type docs review in your AI tool to turn the starter files into real architecture docs. It stops first with a coverage plan and applies nothing until you approve it; that pause is expected. If setup already reached that plan, answer it there. Otherwise use a fresh AI session in the same project, because some tools only read new instructions when a session starts.

    How docs review works

  3. Connect MCP (optional)

    MCP lets your AI look things up in project memory during a session. Working alone in one repo with Claude Code, Codex, or Cursor, you can skip it.

    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.

    When you need MCP

Next, work in sessions (below). Want a browser view of your project memory too? Add the hosted app.

Session workflow

Each piece of work runs in a lane: a named session with its own notes. You steer your AI with a few prompt commands, and it runs the package commands for you. One AI builds; a second can review, and the two pass notes through the lane’s files.

start session
Builder

Opens a lane for new work. Your AI reads the latest session note and the project's context before it changes anything.

continue session
Builder

Picks up a lane you already opened, with its date and notes. With several lanes open, your AI asks which one: continue session <lane-id>.

planning mode
Builder

Agrees on a plan before risky or unclear work. Nothing broad changes until you approve it.

docs update
Builder

Lists the architecture docs, decisions, and notes that this lane's changes affect, so they are current before you close.

docs review
Builder

Writes or refreshes your architecture docs in one broad pass, after you approve its coverage plan.

join as reviewer
Reviewer

Makes a second AI session the reviewer. It reads and reports; it doesn't change code.

review handoff
Reviewer

Runs one review pass and writes the findings into the lane's wip.md and handoff.md. With several lanes open, name one: review handoff <lane-id>.

address review
Builder

Answers each finding: accepted, accepted with a qualification, deferred, or rejected with evidence.

close session
Builder

Writes the permanent session note, records whether the docs and decisions were kept current, and closes the lane. end session works too.

How lanes open and resume, how review rounds work, and how to run several lanes at once are on the Protocol page. Every package command is on the CLI page.

Add the hosted app

Hosting is optional. Add it when you want to see your project memory in a browser, share it with a team, run docs review on the hosted side, or review suggested changes in one place. Your local files stay the source of truth. Hosting modes explains the choice.

Connect a local project

You sign in from the terminal and approve it in your browser. There is nothing to copy: the package keeps the sync token in your OS keychain or ~/.config/vibecompass, never in project.yaml or in chat.

LLM path: paste this into your AI tool

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. Run: npx -y @vibecompass/vibecompass@latest login --root .compass
   It prints a short code and opens my browser (or prints a link). I will log in, confirm the code, and pick the project. Wait for it to finish; it can take a few minutes.
3. Explain that the package stored the sync token in my OS keychain (or ~/.config/vibecompass) and wrote only the hosted URL, project id, and env-var name to .compass/project.yaml.
4. Then run: npx -y @vibecompass/vibecompass@latest push --root .compass
5. Explain that the sync token is for package upload, while an MCP API key is only for AI tool access.
Never ask me to paste a sync token into chat, and never print one. If I already have a dashboard token, tell me to run "vibecompass sync-credential set --root .compass" myself; it asks at a hidden prompt.

Terminal path

# 1. On vibecompass.dev: log in, choose Connect local project, and create the project.

# 2. From your project root, sign in. Your browser opens; confirm the code and pick that project.
npx -y @vibecompass/vibecompass@latest login --root .compass

# 3. Upload your local docs to the hosted project.
npx -y @vibecompass/vibecompass@latest push --root .compass

No browser on this machine, or setting up CI? Use connect-hosted with a token from the project’s Setup page instead.

When it worked

  • The Setup checklist marks the hosted baseline as pushed.
  • The dashboard shows your docs, decisions, and sessions.
  • Suggested changes made in the hosted app reach your files only when you preview, export, and apply them.

The sync token is only for uploading. An AI tool that reads the hosted project over MCP uses a separate API key, described on the MCP page.

Stay current

After you install a newer vibecompass, these commands bring your memory folder’s generated files up to date. Both show what they would do before they do it. A command that prints Compatibility warnings: at the top is pointing you here.

# Read-only: what is out of date, and the safest next command
npx -y @vibecompass/vibecompass@latest status --root .compass

# Refresh the generated files: preview first, then apply
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --dry-run
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --apply --update-package-stamp

What changed in each release, what a refresh touches, and fixes for common problems are on the Upgrade page.

Packages

Three parts, each optional except the first. How they fit together is on the Concepts page.

@vibecompass/vibecompass

Creates and updates the project-memory files: setup, sessions, docs checks, and syncing with the hosted app.

Use it when: Always. It's the part that owns your files.

@vibecompass/vibecompass-mcp

An MCP server that lets your AI tool ask project memory questions mid-session.

Use it when: You want structured lookups or write-back from your AI tool.

vibecompass.dev

The hosted app: a browser view of your project memory, team sync, and suggested changes to review.

Use it when: You want a dashboard, or to share project memory with a team.

Keep going

For what happens under the hood (hosting modes, how the parts fit together, docs review, the session brief, and syncing), continue to Concepts.

Read conceptsOpen the app