@vibecompass/vibecompass

Local-first project memory for AI coding sessions.

VibeCompass creates a .compass/ project-memory root with architecture docs, decision logs, session notes, and agent instructions so Claude Code, Codex, Cursor, and Copilot can pick up where the last session left off.

Full docs: https://vibecompass.dev/developers

Install

Most people can run VibeCompass without installing it globally:

npx -y @vibecompass/vibecompass@latest --help

Or install it globally if you want the shorter vibecompass command:

npm install -g @vibecompass/vibecompass@latest

Requires Node.js 20+.

Quick Start

Easiest path: ask your AI coding tool

Open Claude Code, Codex, Cursor, or Copilot in the project folder you want VibeCompass to remember, then paste:

VibeCompass is project memory for vibe coding. Use the npm package
@vibecompass/vibecompass@latest.

Please set it up in this project:
1. Run the needed VibeCompass commands 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 session lane for this setup work.
5. If you run docs review, continue until either architecture docs are applied
   or you are waiting for my explicit coverage-plan approval. Do not call docs
   review done just because the marker was created.
6. Tell me which files changed, whether docs were actually applied, and what I
   should review next.

Do not ask me to paste secret tokens into chat.

After setup, start a fresh AI session in the same project and type:

docs review

That asks the AI to inspect your code and create the first real architecture docs. If it asks you to approve a coverage plan, approve it or ask for changes; the package prints the output file and exact apply command after the accepted docs are ready.

Terminal path

Run this from your project folder:

npx -y @vibecompass/vibecompass@latest init --guided

If the folder is not a Git repo, use a local folder source:

npx -y @vibecompass/vibecompass@latest init \
  --root .compass \
  --name "My Project" \
  --mode local-primary \
  --repo-local app=.

Check what to do next:

npx -y @vibecompass/vibecompass@latest status --root .compass

Start a builder session:

npx -y @vibecompass/vibecompass@latest start-session \
  --root .compass \
  --id feature-lane \
  --working-on "Build the next feature"

Generate evidence-backed architecture docs:

npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided

Close the session:

npx -y @vibecompass/vibecompass@latest close-session \
  --root .compass \
  --session feature-lane \
  --title "Feature Lane" \
  --completed "Shipped the slice" \
  --architecture-docs updated \
  --decision-log not-needed \
  --session-maintenance updated \
  --next-step "Review and publish"

Common Commands

# Create or inspect project memory
npx -y @vibecompass/vibecompass@latest init --guided
npx -y @vibecompass/vibecompass@latest status --root .compass

# Session workflow
npx -y @vibecompass/vibecompass@latest start-session --root .compass --id auth-flow --working-on "Auth flow"
npx -y @vibecompass/vibecompass@latest list-sessions --root .compass            # --json for the machine-readable lane inventory
npx -y @vibecompass/vibecompass@latest continue-session --root .compass         # resume the open lane (D-353); name it with 2+ lanes: continue-session auth-flow
npx -y @vibecompass/vibecompass@latest switch-session auth-flow --root .compass
npx -y @vibecompass/vibecompass@latest docs-update --root .compass --session auth-flow
npx -y @vibecompass/vibecompass@latest close-session --root .compass --session auth-flow --title "Auth Flow" --completed "Built auth" --architecture-docs updated --decision-log not-needed --session-maintenance updated --next-step "Review"

# Resuming (D-353): an active lane is an open session, not a crash. continue-session
# keeps the lane's opening date and session number, records resumed_at/resume_count
# in session.yaml, appends a dated "Resumed" line to wip.md, moves the index current
# hint and the Current session block to the lane, and prints the files to read next
# plus resume-staleness warnings. With two or more active lanes and no worktree
# marker it fails closed and prints the lane inventory instead of guessing;
# start-session --id <existing-lane> fails closed and points at continue-session.
npx -y @vibecompass/vibecompass@latest continue-session auth-flow --root .compass --working-on "Auth flow, phase 2"

# Session brief in the lane (D-359, D-364), opt-in (D-368): with
# project.yaml `brief: { enabled: true }`, start-session and continue-session
# write sessions/active/<lane-id>/brief.md — the memory the lane's task should
# start from, with a YAML header binding the inputs it read. continue-session
# keeps a current brief and regenerates a stale one; a brief failure is a
# warning, never a failed start or resume. Without the setting nothing is
# written, and --no-brief skips it for one command. brief --write briefs any
# lane on request; `brief.exclude` lists root-relative globs no brief may read.
npx -y @vibecompass/vibecompass@latest brief --root .compass --session auth-flow --write   # write or regenerate it
npx -y @vibecompass/vibecompass@latest brief --root .compass --session auth-flow --check   # current or stale, and why

# Optional git binding for a lane (D-281): create/reuse a branch in each bound
# repo; --worktree provisions per-repo worktrees under
# <workspace>/worktrees/<lane-id>/<repo-id> with the lane marker in the
# container, so commands run from inside a worktree need no --root/--session.
# At close, close-session removes the recorded worktrees when they are clean
# (guarded, never forced; branches are never deleted); dirty or in-use
# worktrees survive with guidance and the lane marker stays as a breadcrumb.
# Gitignored files (e.g. .env) do not count as dirty and are deleted with a
# clean worktree — copy ignored local files out before closing. Git does the
# removal with no time limit, so a large node_modules can take a while; it
# keeps locked worktrees and worktrees with submodules.
# close-session and docs-update also print a pre-close staleness set: new
# decisions since lane start, stale base revisions, newer finalized notes
# that mention the lane's scope, and claim overlap with other active lanes.
npx -y @vibecompass/vibecompass@latest start-session \
  --id auth-flow \
  --working-on "Auth flow" \
  --repo app \
  --claim src/app/auth \
  --architecture-doc architecture/product/auth/login.md \
  --decision-domain-file cross-cutting.md \
  --branch feature/auth \
  --worktree

# Per-lane runtime isolation (D-282): every lane gets its own port and temp
# dir at start (recorded in the lane's session.yaml; defaults configurable
# under project.yaml runtime: port_base/port_step/tmp_base). Export them into
# a shell — includes conventional PORT/TMPDIR aliases so unmodified dev
# servers pick them up — before running dev servers or build tools, so
# parallel lanes never fight over ports or temp paths. close-session removes
# the lane temp dir (guarded; the port record vanishes with the lane).
eval "$(npx -y @vibecompass/vibecompass@latest lane-env)"

# Agent instruction files
npx -y @vibecompass/vibecompass@latest sync-agents --root .compass

# Decision log maintenance: append-decision allocates the D-number at write
# time and refreshes the grouped decisions/INDEX.md when it can label the
# group from the lane context (D-283, structure-preserving — hand-authored
# session group headings are preserved verbatim; unparseable structure fails
# closed). refresh-decision-index --check validates the index against the
# canonical decision files without writing.
npx -y @vibecompass/vibecompass@latest append-decision --root .compass --target cross-cutting.md --entry staged-entry.md
npx -y @vibecompass/vibecompass@latest refresh-decision-index --root .compass --check

# Session brief (read-only): the memory a task should start from, packed into
# an estimated token budget, with a complete/partial/incomplete/no-match status
# and follow-up reads. Decisions always appear with their declared successors.
npx -y @vibecompass/vibecompass@latest brief --root .compass --task "Change the refresh denial message" --files app:src/lib/entitlements.ts
npx -y @vibecompass/vibecompass@latest brief --root .compass --session auth-flow --budget 3000 --json

# Targeted and comprehensive architecture docs maintenance
npx -y @vibecompass/vibecompass@latest docs-update --root .compass --session auth-flow --changed app:src/auth/login.ts
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --guided --source-root app=../app
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --apply-output

# Rerun docs review from an archived architecture-doc slate
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --path architecture
npx -y @vibecompass/vibecompass@latest docs-review --root .compass --rebuild --apply --stale-policy archive --path architecture

What It Creates

.compass/
  project.yaml
  context.md
  architecture/
  decisions/
  sessions/
  state/

Docs review writes derived state under state/, including scanned source inventory, accepted coverage, and the accepted documentation-plan projection. init adds state/ and sessions/active/ (local-only lane scratch) to the root's .gitignore. A command that fails in a folder that is not a project memory root yet leaves nothing behind there.

Generated agent files can also include managed VibeCompass blocks:

CLAUDE.md
AGENTS.md
.cursorrules
.github/copilot-instructions.md

Prompt Commands

After setup, use these phrases inside your AI coding tool:

• start session
• join as reviewer
• planning mode
• review handoff
• address review
• docs update
• close session / end session
• docs review

The npm package owns the file mechanics. Your AI session owns reading the workflow files, updating handoffs, and applying reviewed changes. Use docs review for the broad baseline and scoped deepening work; use docs update / vibecompass docs-update for ordinary session-delta maintenance tied to the current lane.

Session Brief (opt-in)

vibecompass brief picks the architecture docs, decisions, and session notes a task should start from, and packs them into a short markdown brief with a complete, partial, incomplete, or no-match status and a list of follow-up reads. It runs locally and deterministically: no network, no model, no account. A decision always appears together with any later decision whose own text explicitly declares that it replaces or amends it, and the brief never claims that a decision governs your task. It cannot spot a replacement that is only implied, so read the follow-up list too. When the task's distinctive words match nothing in memory, the status is no-match, with at most four nearby reads that share the task's other words. If decision lineage cannot be read from a file, the brief shows no decisions or docs: it is incomplete and lists that file, the overview, and the decision index to read first.

The brief in a session lane is an experiment you turn on (D-368):

# .compass/project.yaml
brief:
  enabled: true

With it on, start-session and continue-session write sessions/active/<lane-id>/brief.md, and your AI tool reads it before planning. Without it, nothing changes, and vibecompass brief --session <lane-id> --write still briefs one lane on request. brief.exclude lists files no brief may read.

The brief is opt-in because of the project's own evaluation, which did not fully follow its protocol. Agents with a brief found about as much of the relevant memory as agents without one, and made none of the specific false authority claims the evaluation checked for. But they missed nine facts the others found, in one case after the brief left out the key document. A second evaluation, after retrieval fixes, stopped at a protocol deviation before any grading, so turning the brief on by default still waits for a conforming one. Treat a brief as a starting point, not the whole answer.

Hosted Sync

Use hosted sync when you want browser review, team workflows, or hosted docs-review proposals. The quickest path signs you in from the terminal and keeps the token in your OS keychain (or a private per-user file), so it works in every new terminal and in agents launched from a desktop app:

npx -y @vibecompass/vibecompass@latest login --root .compass
# opens vibecompass.dev, you confirm a short code and pick the project,
# the token is stored locally, and the hosted binding is written to project.yaml

npx -y @vibecompass/vibecompass@latest push --root .compass

Advanced (CI, scripts, a machine without a browser, or a hosted-only demote): bind the root with a dashboard-created token, pasted at the hidden prompt or piped in. On a terminal, pressing Enter at that prompt starts the browser sign-in instead:

npx -y @vibecompass/vibecompass@latest connect-hosted \
  --root .compass \
  --sync-api-url https://vibecompass.dev \
  --sync-project-id vc_proj_example \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
# "Paste the sync token from the dashboard (input hidden)"

# non-interactive:
printf '%s' "$TOKEN" | npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass \
  --sync-api-url https://vibecompass.dev --sync-project-id vc_proj_example \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN --token-stdin

After close-session, run push again when a connected local-primary root changed canonical project-memory files and the hosted dashboard should catch up. Hosted-only projects do not use a local authoritative push; update or refresh them through the hosted dashboard/proposal flow.

push prints a Note: <code> (<path>): <message> line for anything the hosted dashboard could not build from your files, such as a file whose decision links could not be read. The push itself succeeded; the note names the file so you can check it.

Where the token lives (D-355)

Hosted commands look for the token in this order:

1. the environment variable named in project.yaml (VIBECOMPASS_SYNC_TOKEN by default) — a per-shell override for CI and scripts;
2. the local credential store, keyed by hosted URL + project id: the OS keychain when available (macOS Keychain, Linux secret-tool), otherwise ~/.config/vibecompass/credentials.json (0600; %APPDATA%\vibecompass on Windows; VIBECOMPASS_CONFIG_DIR overrides the location).

The token value is never written to project.yaml, state/, or any file in your repo. Manage stored tokens with:

npx -y @vibecompass/vibecompass@latest sync-credential list --root .compass
npx -y @vibecompass/vibecompass@latest sync-credential set --root .compass    # hidden prompt, --token-stdin, or --from-env
npx -y @vibecompass/vibecompass@latest sync-credential remove --root .compass

vibecompass status shows which source is in use (never the value). Lost a token? Run login again, or create a new one on the dashboard under Setup -> Hosted sync and revoke the old one there.

Multiple environments

One project can have named sync targets (for example a local dev server and production) so you never have to rebind:

# add targets once — the first one becomes the default
npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target dev \
  --sync-api-url http://localhost:3000 --sync-project-id vc_proj_dev \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN
npx -y @vibecompass/vibecompass@latest connect-hosted --root .compass --target prod \
  --sync-api-url https://vibecompass.dev --sync-project-id vc_proj_prod \
  --sync-credential-env-var VIBECOMPASS_SYNC_TOKEN_PROD

# then pick per command, or switch the default
npx -y @vibecompass/vibecompass@latest push --root .compass --sync-target prod
npx -y @vibecompass/vibecompass@latest sync-target prod --root .compass

Tip: if you already have a single (flat) binding, add it as your first named target using the same URL and project id — its sync history carries over.

See https://vibecompass.dev/developers for the full local-primary workflow.

JavaScript API

import {
  initializeProjectMemory,
  getProjectStatus,
  scanProjectMemory,
  loadProjectReadModel,
  getProjectContext,
  getDecisionLineage,
  buildSessionBrief,
  renderBrief,
  readBriefSettingsForRoot,
  detectChangelogShapedLines,
  ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES,
} from "@vibecompass/vibecompass";

Use the JavaScript API when building tools that need to inspect or manage a local VibeCompass project-memory root.

detectChangelogShapedLines(body) takes architecture-doc body text (frontmatter already stripped) and returns the changelog-shaped lines it matched — the same D-292 advisory detector the scanner and docs-review --apply-output use, shared so external validators (for example the hosted proposal parser) stay in parity. ARCHITECTURE_DOC_SOFT_SIZE_LIMIT_BYTES is the byte-valued soft size budget (12000) both docs-review apply warnings and the docs-update size advisory read.

loadProjectReadModel(root) also returns decision_lineage: evidence-typed relations between documents and decisions. Architecture docs cites decisions; session notes references them and made the ones listed under "Decisions made". Decision entries declare supersedes, amends, or preserves only from their own wording, with an extent and scope; anything the parser cannot certify is unknown. Every relation carries its source path, section, line, and content hashes. getDecisionLineage(readModel, id) returns one decision's incoming and outgoing lineage and its declared successors, followed transitively. Nothing is ever reported as "governs" or "currently valid". If the parser throws on any file, decision_lineage.status is unavailable, with the file in unavailable_sources and null relations and counts, never empty ones; the rest of the read model still loads, and getProjectContext reports the lineage status. Architecture components also carry retrieval_guidance and retrieval_scope when their docs define them; their sections are read fence-aware, so a heading inside a code example never replaces a real section.

buildSessionBrief({ rootDir, task, files, featureSlugs, claims, laneId, budget }) is the read-only engine behind vibecompass brief: it returns the selection result (status, packed units, omitted units, follow-up reads, gaps, and the estimated size), and renderBrief(result) turns it into markdown. It never writes to the root, and it never reads a path the root's project.yaml brief.exclude names.

readBriefSettingsForRoot(rootDir) reads the root's project.yaml brief: settings with the same parser the brief and lifecycle generation use. It returns { enabled, enabledDeclared, exclude, problems, repos }: enabled is true only when brief.enabled is the boolean true, and any entry in problems (an unreadable project.yaml, an unknown field, a malformed exclude) means the brief fails closed and reads no canonical document. repos is the root's repos: list. The MCP server reads it to decide whether to offer get_brief (D-386).

More Documentation

• Developer guide: https://vibecompass.dev/developers
• CLI reference: https://vibecompass.dev/developers/cli
• Session protocol: https://vibecompass.dev/developers/protocol
• Concepts: https://vibecompass.dev/developers/concepts