Getting started · Concepts
Concepts
Once the basics click, here is what is actually happening under the hood: where your project memory lives, how the parts talk, and what the technical words mean in plain English.
You can skip this page and still ship. Come back when you want to know why something works the way it does.
Hosting modes
Where does the “real” copy of your project memory live — on your machine, or on the web? VibeCompass calls that the canonical copy, and there are three modes.
The first two keep files on your machine and are the recommended paths. The third exists only for teams that prefer the dashboard as the single home for project memory.
Architecture
Four pieces, one job: keep a project notebook that humans, AI tools, and (optionally) a browser dashboard can all read from the same source. Here is how they stack.
1. Canonical root — the files
The actual notebook on disk.
project.yaml, the architecture docs, the decision log, and finalized session notes. This is the source of truth — everything else just reads from or writes to it.
2. Local core — the npm package
The thing that reads and writes those files for you.
@vibecompass/vibecompass opens the root, checks the files are well-formed, and keeps small bookkeeping files (like state/manifest.json) so it knows what it already did.
3. MCP adapter — the bridge
Hands the memory to your AI tool mid-session.
@vibecompass/vibecompass-mcp exposes the same set of queries whether you stay local, sync to hosted, or run both. Skippable for solo work on file-access tools.
4. Hosted projection — the optional dashboard
A browser view of the same notebook.
vibecompass.dev adds search, proposals, and team workflows on top. For local-primary projects, it never silently overwrites your files.
What the canonical root looks like on disk
PROJECT_MEMORY_ROOT/
project.yaml
architecture/
decisions/
sessions/
context.md
state/
manifest.jsonDocs review
When you run init you get a small starter map of your project. To turn that into real architecture docs, you type docs review in your AI coding session — the AI does the reading and writing, you approve what lands. It is a separate, opt-in step so installing VibeCompass never calls an AI on its own.
1. Trigger the workflow
Prompt your current Claude Code, Codex, Cursor, or Copilot session with docs review. The generated agent instructions point it at the package-owned workflow file and the canonical docs-review contract.
2. Your AI writes the docs
The agent inspects project memory and source files, then writes accepted architecture docs as explicit fenced blocks that docs-review --apply-output can write into architecture/<domain>/<feature>/<component>.md.
3. Mark the review done
The package records which LLM/model ran the review. docs-review --complete remains available when accepted docs were written manually outside the output file.
Local first, provider-agnostic
You pick the AI session and model. Adding a new provider should not require a new prompt flow. --guided is the package mechanic the agent can use to record marker state and print the canonical review contract. --run-local --provider <name> is the package-owned local runtime shape; today the supported provider is anthropic.
Hosted review creates proposals, not silent writes
--submit-hosted posts the review request to the hosted app and records a run ID. For local-primary projects, hosted output becomes proposals and docs-review artifacts. You export and apply accepted output locally, then push to confirm the canonical files.
Team source of truth
On a team, only one machine’s notebook can be the “real one” on the dashboard at any moment — the last machine that ran push. The dashboard does not try to merge half-written docs from everyone’s laptops; it trusts whichever local copy you pushed last.
That keeps things predictable: there is always a clear current baseline, and a teammate’s edits land by you intentionally pulling or them intentionally pushing.
Pick which machine is the baseline
Run vibecompass pull-preview first so you can see what is on the dashboard, then vibecompass push from the machine you want the team to start from.
Bring in a teammate's notes on purpose
If someone else has useful local docs, copy them into the chosen machine through normal edits or through the hosted proposal flow before pushing.
If hosted review says the baseline moved on
The dashboard will tell you when your local copy is older than what it has. Pull or push intentionally, then ask for the review again.
vibecompass pull-preview
vibecompass push
vibecompass docs-review --submit-hosted
vibecompass docs-review --poll-hostedSync lifecycle
The order things happen in, from a brand-new project to a synced team. Every step is something you ask for — nothing happens behind your back.
1. Set up the notebook
Create the project memory folder and point it at the repo (or repos) you want VibeCompass to remember.
2. Read locally first
At the start of every AI session, the tool reads from your local files. Basic orientation never needs the hosted app to be up.
3. Push to hosted when you want a dashboard
push makes a copy on vibecompass.dev so you (or your team) can see it in the browser, search it, or run hosted reviews.
4. Pull preview-first, never silent
If the dashboard has changes, pull-preview shows them before anything touches your local files. You confirm what gets applied.
What VibeCompass will and won’t do on its own
A quick map of what touches what — so you know exactly where the guard rails are.
What it reads
- The project memory files on your machine (in local mode)
- The hosted copy of those files (in hosted mode)
- Your repo, only during onboarding and explicit sync runs
What it writes
- Decisions and session summaries you ask it to record
- Small bookkeeping files like `state/manifest.json` (so it knows what it already did)
- Proposals and sync metadata in the hosted dashboard
What it will never touch on its own
- Quietly overwriting your local files from the hosted dashboard
- Resolving conflicts or deleting feature docs without you confirming
- Killing your AI session because the hosted side is offline for a moment
Current gaps
An honest list of what is not shipped yet — kept on its own page so you always see the latest. Head to the Roadmap for the current state.
Next steps
Where the work is going next, in priority order. The Roadmap is the source of truth — this page links there so you do not have to keep two lists in sync.
Keep going
For an honest look at what isn’t shipped yet and the recommended way to try VibeCompass today, continue to the Roadmap.