VibeCompass/docs
HomeSign in

Stay current · Upgrade

Upgrade

The short version lives on Getting started. This page starts with what’s new in the latest release, then walks through how to install a new @vibecompass/vibecompass release, preview the catch-up, apply it, and decide when to move the canonical package-version stamp.

What’s new

The latest release of each package, and anything you need to do after upgrading. Skipping a version? The releases before these are just below.

@vibecompass/vibecompass

0.17.5

A behind-the-scenes release that the MCP server's opt-in brief tool needs. Nothing you run changes.

After upgrading: Nothing to do. A refresh (the walkthrough below) moves the version number in workflows/docs-review.md, and moves the version stamp only if you ask it to.

@vibecompass/vibecompass-mcp

0.1.8

Adds get_brief, an opt-in tool that gives your AI a session brief for a task as a starting point. It appears only where you turned the brief on.

  • On a memory folder whose project.yaml sets brief.enabled: true, Local and Hybrid mode offer get_brief. It returns the same brief vibecompass brief prints for a task, then a short summary of it as data. It's never offered in Hosted mode.
  • A brief is a starting point of cut excerpts that can miss the doc your task depends on. The server never tells your AI to call it, and nothing about it asks to be called first.
  • It never hands back an old brief: a build that fails or takes more than 5 seconds returns an error, and the other tools keep answering meanwhile.
  • Updated dependencies: npm audit now reports no known vulnerabilities.
  • Needs core 0.17.5, which installs with it.

After upgrading: Restart your AI tool, or reconnect its MCP servers, so the new version starts. If your MCP config pins a version, change it to 0.1.8. To try get_brief, turn the brief on in project.yaml (see the MCP page) and restart again.

Earlier releases: MCP 0.1.7 and 0.1.6, core 0.17.4 back to 0.16.0, and MCP 0.1.5

@vibecompass/vibecompass-mcp

0.1.7

Local mode now answers like the hosted app: the same size limits, a feature's decisions, and notes that say where Local differs.

  • Local answers keep to the hosted app's size limits. The overview and feature answers drop their least important detail first to fit, and anything still too large comes back as a preview with a note pointing to a narrower tool. Before, Local answers had no limit.
  • The Local overview lists the 5 most recent decisions by number and title, instead of 20 full entries.
  • Local feature answers now include decisions (the newest 20 from the feature's domain decision file) and an empty conflicts list. Notes say that decisions are matched by domain file, because decision entries don't record their feature, and that conflicts live in the hosted app.
  • A feature's decision log in Local mode now reads every decision in its domain file. Before, it looked only at the newest 100 decisions overall, so an older file could come back empty.
  • The server now tells your AI tool what each tool is for and where your source of truth is, and it reports its real version.
  • Needs core 0.17.4.

After upgrading: Restart your AI tool, or reconnect its MCP servers, so the new version starts. No settings change.

@vibecompass/vibecompass

0.17.4

A small sync fix: pull-preview and sync-adopt now work on a memory folder that has never synced, such as a fresh clone or a second computer. The session brief stays an opt-in experiment.

  • pull-preview and sync-adopt no longer fail before your first sync. Before, with no record yet of where this folder left off, they sent the hosted app an empty starting point and got an error (a 422) instead of a preview. Now they leave it out until there is one, as push already did.
  • Behind the scenes, the package's own tests now pass wherever your computer keeps temporary files. Nothing you run changes.

After upgrading: Nothing to do. If pull-preview or sync-adopt failed for you on a newly connected folder, run it again. If your folder is already caught up with 0.17.3, a refresh (the walkthrough below) changes one shared file, workflows/docs-review.md, where the version number moves to 0.17.4. It also rewrites the machine-local state/manifest.json, and moves the version stamp only if you ask it to. Skipping releases? Read their notes below too.

@vibecompass/vibecompass

0.17.3

push now tells you right away when the dashboard couldn't show part of what you pushed. Nothing else changes.

  • After a push, anything the hosted dashboard couldn't build from your files is printed as a Note: line that names the file. For example, if VibeCompass couldn't read how the decisions in one file connect, you see that in your terminal instead of only as a notice on the dashboard. The push itself still went through.
  • A push with nothing to report prints exactly what it printed before.

After upgrading: Nothing to do. If a script reads push output, it may now see Note: lines after the Run: line.

@vibecompass/vibecompass

0.17.2

A clean-up release: decision links handle one more unusual line, commands leave nothing behind in a folder that isn't set up yet, and your agent files show where each repo lives online.

  • Decision links: a line of prose that happens to start with three backticks no longer hides every heading after it. The decisions listed under a later ## Decisions made heading are found again, and citations stay under the right section.
  • A command run in a folder that isn't a memory root yet no longer leaves an empty state/ folder (or the folder itself) behind when it fails.
  • Agent files and context.md show a repo's remote address next to its local folder when project.yaml gives that repo a path:. Before, such a repo read as a local folder only.
  • New roots made by init keep lane scratch (sessions/active/) out of Git. Existing roots aren't changed.
  • The missing-section warnings ignore example headings inside code blocks.

After upgrading: If any repo in project.yaml has a path:, run the walkthrough below so your agent files and context.md pick up its remote address. If you commit your memory root to Git, add sessions/active/ to its .gitignore yourself.

@vibecompass/vibecompass

0.17.1

A hardening release. If VibeCompass can't read how your decisions connect in some file, everything else keeps working and it says so, instead of failing outright.

  • Decision links (which decision replaces or changes which) are read by a parser. If it fails on a file, your AI's MCP reads, agent-file sync, and the brief keep working, and the links show as unavailable rather than empty. Before, one such file stopped all of them.
  • While decision links are unavailable, the brief holds back: it shows only your lane and points you to the file it couldn't read, the overview, and your decision index.
  • An example heading inside a code block no longer replaces a doc's real section, such as a sample ## Description in a schema doc.
  • A code example with a line that mixes backticks and tildes no longer ends early, so a sample ## Decisions made heading inside it isn't mistaken for the real list.
  • close-session no longer stops halfway when it removes a lane worktree with a large node_modules folder.

After upgrading: Nothing to do. If a lane's brief was written while decision links were unavailable, the next continue-session rebuilds it.

@vibecompass/vibecompass

0.17.0

Retrieval and framing fixes for the session brief, which stays an opt-in experiment. The fixes were checked on the earlier evaluation's tuning tasks with briefs alone, not with agents, and the evaluation meant to decide default-on stopped before any grading. Nothing about your sessions changes unless you turned the brief on or a script reads brief --json.

  • Better matching: a decision is also found through the sentences in your architecture docs that mention it, a doc is reached through the decisions it describes, and common abbreviations match their long forms (repo and repository, config and configuration, auth and authentication, and a few more).
  • no-match with nearby reads: when the task's distinctive words match nothing in your memory, the brief says no-match and lists at most four nearby reads that share the task's other words. This replaces the old partial brief built from loose matches. Words about how a task feels or what kind of work it is ("flaky", "clearer", "investigate", "bug") never count as its topic.
  • Starting-point framing: a brief that picked anything opens with a reminder that it's a starting point of cut excerpts that can miss the doc your task depends on, and names up to six of the task's words to search for beyond it.
  • Breaking for scripts that read brief --json: contract version 2 replaces selection.narrowed with selection.topic_absent and selection.search_terms, and follow-up reads gain the nearby priority. Other commands are unchanged.
  • The lane's brief.md moves to format 2: its header shows at most four exclude patterns and repo aliases, with a digest that still covers the full lists, and says the token budget covers the body only. A brief written by 0.16.0 reads as stale.
  • A rare parsing fix: a code example in a decision entry no longer ends early at a line that mixes backticks and tildes, so lineage lines shown inside an example aren't read as real ones.

After upgrading: With the lane brief on, the next continue-session in each open lane rebuilds its brief.md once (or run brief --write). If a script reads brief --json, update it for contract version 2. If you already refreshed with 0.16.0, this release adds no new instructions to your agent files or context.md. Still preview the refresh below, especially if you skipped a release.

@vibecompass/vibecompass-mcp

0.1.6

A compatibility release that moves the MCP server onto core 0.17.0. No new MCP tools or features.

  • Your AI tool still can't fetch a brief over MCP. A brief lives only in the lane's brief.md file.

After upgrading: No change to your MCP settings is needed. It works with every core 0.17 release, and a fresh install uses the newest one, so it also picks up 0.17.1 through 0.17.4.

@vibecompass/vibecompass

0.16.0

The session brief arrives as an opt-in experiment. Nothing about your sessions changes unless you turn it on; you'll just see a Brief: off line when you start or resume a lane.

  • New vibecompass brief prints a short pick of the docs, decisions, and notes a task should start from. It writes nothing, and it works whether or not you turn on the lane brief.
  • New, opt-in: with enabled: true under brief: in project.yaml, start-session and continue-session write the lane's brief.md. --no-brief skips that for one command, and brief --write / brief --check save or check a lane's brief on request.
  • New exclude setting under brief: keeps the files you list out of every brief.
  • New decision entries can say what they change with optional **Supersedes:**, **Partially supersedes:**, **Amends:**, and **Preserves:** lines. The brief uses them to show a decision together with the later decisions that replace or amend it.
  • context.md and the managed block in your agent files now tell your AI to read the lane's brief.md when there is one, and a new lane's wip.md has an optional ## Context used section for the docs and decisions the lane actually relied on.

After upgrading: Run the walkthrough below so your agent files pick up the new instructions. The brief ships opt-in because the project's own evaluation didn't support turning it on for everyone.

@vibecompass/vibecompass-mcp

0.1.5

A compatibility release that moves the MCP server onto core 0.16.0. No new MCP tools and no behavior changes.

  • Your AI tool can't fetch a brief over MCP. A brief lives only in the lane's brief.md file.

After upgrading: No change to your MCP settings is needed.

New to the brief? Start with What is a session brief?, then turn it on with the brief settings.

How upgrades work

An upgrade has two moving parts. The CLI you installed runs new logic straight away — newer commands, fixed bugs, friendlier prompts. The scaffolded files VibeCompass owns inside your repo (context.md, the workflow guide READMEs, the managed sections of your agent files, and the local state/manifest.json) only catch up when you run refresh-workflow. That split is intentional — it keeps the upgrade explicit and the blast radius visible before anything on disk changes.

Installed CLI

Whichever version you ran last

npx fetches the latest published version on each invocation. A global install pins to whatever you last upgraded to. Every command runs a quick preflight against the local root before doing its job, so a mismatch shows up as Compatibility warnings: at the top of the output without blocking the command.

Scaffolded files in your repo

Refreshed only when you ask

The package-owned scaffolds change at the same cadence as the CLI, but they only move when you run refresh-workflow --apply. The canonical project.yaml.metadata.package_version stamp is even stickier — on a stamped root it only moves when you pass --update-package-stamp. Legacy roots with no stamp get one written automatically on the first apply.

Walkthrough

Five steps, all safe to run in order. Steps 1–3 are read-only or install-only. Steps 4–5 are the explicit writes — and even those touch only files that VibeCompass owns.

1

Install the newer CLI

Pick whichever install path you used the first time. npx always fetches the latest published version, so it is the simplest way to pull a new release without touching anything globally. A global install gives you a shorter command (vibecompass … instead of npx -y @vibecompass/vibecompass@latest …) at the cost of running the upgrade explicitly.

Either path produces the same CLI. Mixing them is fine — npx pulls the latest published version regardless of what is installed globally.

# Option A — always use npx (no install step needed)
npx -y @vibecompass/vibecompass@latest --version

# Option B — upgrade your global install
npm install -g @vibecompass/vibecompass@latest
vibecompass --version

If vibecompass --version still reports the old number after a global upgrade, your shell is likely caching the path — open a new terminal tab and try again.

2

Run status to see what changed

status is strictly read-only. It compares the package version that initialized the root with the CLI you just installed, checks whether the local manifest can still be read, and prints any compatibility warnings the newer CLI has surfaced. Use it as the first move after any upgrade — nothing on disk changes.

npx -y @vibecompass/vibecompass@latest status

# Machine-readable form for scripts
npx -y @vibecompass/vibecompass@latest status --json

If you see Compatibility warnings: at the top, that is exactly the signal the next two steps catch up on.

3

Preview the catch-up

refresh-workflow defaults to dry-run. It prints the exact set of writes it would make against the package-owned scaffolds — context.md, workflow guide READMEs that still match the generated shape, managed sections inside your agent files, and the local state/manifest.json — without touching any of them. Hand-written content in CLAUDE.md, AGENTS.md, your architecture docs, and your decisions are never on this list.

npx -y @vibecompass/vibecompass@latest refresh-workflow --dry-run
4

Apply the catch-up

When the dry-run looks right, re-run with --apply. The same set of files is rewritten in place. User-authored workflow guide files that have drifted from the generated shape are left alone so your edits are preserved.

Compatibility warnings disappear once the scaffolds match the installed CLI. If they linger, jump to Troubleshooting.

npx -y @vibecompass/vibecompass@latest refresh-workflow --apply
5

Decide whether to move the package-version stamp

The canonical project.yaml.metadata.package_version stamp is sticky once it exists: on a stamped root, a routine refresh never silently changes which CLI your project says it is using. The currently observed CLI version lives in machine-local state/manifest.json instead, so collaborators on different versions do not fight over the canonical value. Move the stamp explicitly with --update-package-stamp once you have verified the refresh looks clean and you want to make the new version official for the project.

Legacy roots with no metadata.package_version are a special case — the first --apply writes a stamp automatically, since there is nothing yet to be sticky about. See the legacy / unknown root scenario in Troubleshooting.

# Verify the refresh first, then make the new version canonical
npx -y @vibecompass/vibecompass@latest refresh-workflow --apply --update-package-stamp

Skip this on team projects until the rest of the team has installed the same release — the stamp is the version everyone is expected to match.

What gets touched

A refresh is bounded. It rewrites the files VibeCompass owns and leaves everything else — your architecture docs, your decisions, your session notes, the unmarked parts of your agent files — exactly as you left them.

context.md

Regenerated from the current project.yaml, architecture docs, and decisions index.

Not authored by hand — always treated as derived output.

architecture/README.md, decisions/README.md, sessions/README.md

Rewritten when the file still matches the generated workflow-guide shape.

If you have customized a guide, refresh leaves your version untouched and prints a note that it skipped.

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

Only the managed VibeCompass block inside each file is rewritten.

Content outside the managed markers — your own protocol notes, repo rules, custom prompts — is preserved verbatim.

state/manifest.json

Regenerated to match the installed CLI. Also records the observed package version locally.

Machine-local file; safe to delete and regenerate. Not part of the canonical project memory.

project.yaml.metadata.package_version

On a stamped root, only changes when you pass --update-package-stamp. Legacy roots with no stamp get a first-time one written automatically on --apply.

The canonical version stamp — sticky by design so the project's official CLI version stays under your control.

Troubleshooting

A handful of scenarios cover most of what comes up after a real-world bump. If something else surfaces, run status first — it usually names the exact command that resolves the drift.

Compatibility warnings keep showing after refresh

Re-run status to confirm what is still drifting. If the warning names a file you do not see in the dry-run, you may be running refresh against a different memory root — pass --root <path> explicitly to point at the canonical one. If a hand-edited workflow guide (architecture/README.md, decisions/README.md, or sessions/README.md) is keeping the warning alive, refresh deliberately leaves it alone — there is no flag override. The recovery is to back the file up, delete it, then re-run refresh-workflow --apply so refresh sees no existing file and regenerates the guide from scratch.

# Diagnose first
npx -y @vibecompass/vibecompass@latest status --root .compass
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --dry-run

# If a hand-edited workflow guide is keeping the warning alive
cp architecture/README.md architecture/README.md.bak
rm architecture/README.md
npx -y @vibecompass/vibecompass@latest refresh-workflow --root .compass --apply

Status reports a legacy / unknown root

That means your project.yaml has no metadata.package_version stamp yet — common for roots created before the upgrade story shipped. Refresh treats this as a first-time stamp and writes one when you --apply. Nothing else is forced; commands keep running against legacy roots without complaint.

npx -y @vibecompass/vibecompass@latest refresh-workflow --apply

I am on an older CLI than the stamp expects

If the root is stamped by a newer CLI, refresh refuses to downgrade the templates on its own. Install the newer CLI to match (Step 1), or, when you intentionally need to roll back, pass --allow-downgrade-templates to opt into the older shape. Downgrades are rare — usually the cleaner path is to install the right version.

# Preferred: install the matching CLI
npm install -g @vibecompass/vibecompass@<version>

# Or, for an intentional downgrade
npx -y @vibecompass/vibecompass@latest refresh-workflow --apply --allow-downgrade-templates

My CLAUDE.md or AGENTS.md has no managed markers

Refresh leaves an unmarked file alone — you do not lose hand-written content. To bring it under management, run sync-agents --adopt-existing once. That appends the managed VibeCompass block at the bottom of the file, preserving everything above it. After adoption, subsequent refreshes update only the managed block.

npx -y @vibecompass/vibecompass@latest sync-agents --adopt-existing

state/manifest.json is missing, unreadable, or on an unsupported state_version

state/manifest.json is machine-local derived state, not canonical project memory — losing it is recoverable. status surfaces all three failure modes as compatibility warnings (codes state-manifest-missing, state-manifest-unreadable, and state-version-unsupported when you pass --json; the plain status output shows the matching human-readable message). The fix in every case is the same: run refresh-workflow --apply once. Refresh always regenerates the manifest, so the next command after apply starts from a clean derived state.

npx -y @vibecompass/vibecompass@latest refresh-workflow --apply

Keep going

For the short version of this story — the two-command summary plus a quick read on the compatibility-warning block — return to Stay current. For the full surface of every command referenced here, head to the CLI page.

CLI commandsStay current