Docs & usage

Everything a developer needs to install Codevira, wire it into every AI tool, and use the CLI + MCP surface. Local-first, MIT, ~66 MB — no cloud, no vectors, no account.

Install

pipx is recommended (isolated). Plain pip works too.

# 1 — install (isolated, recommended)
pipx install codevira          # or: pip install codevira

# 2 — bootstrap a project (writes .codevira/, AGENTS.md, .gitignore)
cd ~/Projects/my-project
codevira init

# 3 — wire codevira into every AI tool detected on this machine
codevira setup

That's it. Decisions live in <repo>/.codevira/decisions.jsonl. By default that memory stays per-machine (not committed), so unrelated projects never bleed into each other; run codevira init --shared to commit it and share decisions with teammates on the same repo. The code graph lives in a rebuildable, gitignored cache. With no ML model to load, warm tool calls return in a few milliseconds.

Requires Python ≥ 3.10. After codevira setup, restart your AI tool so it picks up the new MCP server and (for Claude Code) lifecycle hooks.

3.7 Opt-in tracking. codevira init is the explicit opt-in: codevira tracks only the projects you init. A project you merely open in your editor stays inert — its tools return a "run codevira init" hint and nothing is written, so ~/.codevira/projects/ never fills with projects you never chose. Existing tracked projects (they have an in-repo .codevira/config.yaml) are grandfathered in with zero migration. Want the old track-everything behavior? Set CODEVIRA_AUTO_ADOPT=1.

Connect your AI tools

codevira setup auto-detects installed tools (strong signals: binary on PATH + valid config) and configures each one. 3.7 By default it registers one user-scope codevira server that resolves the active project from your editor's workspace roots — so N projects don't create N entries in your IDE. Opt back into per-project entries with --per-project. Pass --force if the detector misses an install, or --dry-run to preview.

Tool	What codevira writes
Claude Code	one user-scope MCP entry + PreToolUse / SessionStart lifecycle hooks (verified hard enforcement)
Cursor	one user-scope MCP entry (stdio, roots-resolved) + reads `AGENTS.md`
Antigravity	per-project MCP entry (sets its own working dir per window) + a `PreToolUse` hook that surfaces and can block decision-reverting edits 3.7.1 + reads `AGENTS.md`
Claude Desktop	per-project stdio MCP entry (`--project-dir` — can't advertise roots)
Codex · Copilot	read `AGENTS.md` natively — the decisions are portable, no MCP entry required

Prefer manual config? Add this stdio entry to your tool's MCP config — codevira resolves the active project from the client's workspace roots:

// e.g. project .mcp.json, .cursor/mcp.json
{
  "mcpServers": {
    "codevira": { "command": "codevira", "args": [] }
  }
}

Verify a connection any time with codevira doctor — it reports which project the server bound to and why, plus an MCP-visibility check for Claude Code.

CLI commands

26 commands total; codevira <cmd> --help shows flags for any one. The daily drivers:

Command	What it does
`codevira setup`	Detect AI tools + write MCP configs + Claude Code hooks
`codevira doctor`	Read-only health check (✓ / ⚠ / ✗ with exact fix commands)
`codevira status`	Index health + project state
`codevira projects`	List tracked projects with staleness; `projects archive <name>`
`codevira index`	Build / refresh the code graph cache
`codevira sync`	Regenerate AGENTS.md + manifest from `decisions.jsonl`
`codevira repair-ids` 3.7	Detect/repair cross-engineer decision-id collisions (`--apply`; `--semantic` reports near-duplicate decisions)
`codevira replay`	Browse the decision timeline (terminal / markdown / HTML)
`codevira search` 3.6	Search decisions from the terminal; `--all-projects` searches every registered repo, `--json` for scripts
`codevira eval` 3.5	Score read-side relevance (recall@k / MRR) on self-derived cases
`codevira tune-weights` 3.5	Learn ranking weights from your memory; persist only a proven win
`codevira uninstall`	Reverse every system write codevira made (`--keep-data` to keep memory)

MCP tool surface

36 tools are surfaced to AI clients via tools/list (one admin tool, refresh_graph, is hidden). They're summary-first by default — pass full=true or expand(ids=[…]) for detail. Set CODEVIRA_TOOL_PROFILE=lean to advertise only the 12 daily-driver tools (~71% smaller tools/list).

Group	Representative tools
Orientation	`get_session_context`, `get_roadmap`
Decisions	`search_decisions`, `list_decisions`, `expand`, `record_decision`, `supersede_decision`, `mark_decision_outdated`, `set_decision_flag`, `get_history`
Code graph	`get_node`, `get_impact`, `query_graph`
Roadmap / phases	`get_phase`, `add_phase`, `update_phase_status`, `complete_phase`, `update_next_action`, `write_session_log`
Memory subsystems	working memory, skills, provenance (`working_add`, `working_promote`, `record_skill`, `get_skill`, `origin_of`, …)

Code-graph tools (get_impact / query_graph) cover Python, TypeScript, JS/JSX, Go, and Rust. For other languages the agent reads the file directly.

Changed in 4.0: 15 tools were removed on measured usage — the consensus, reflections, spatial and preferences subsystems, plus get_code / get_signature. Nothing recorded was deleted; see MIGRATING.md.

New in 3.6: record_decision(symbol="login") scopes a do_not_revert decision to a single function/class — the lock then blocks only edits that land inside that symbol (edits elsewhere in the file warn). And search_decisions(query, all_projects=true) searches every registered project's decisions, each result tagged with the repo it came from (also via codevira search --all-projects).

New in 3.7 — memory stays fresh: record_decision now supersedes a strong, unprotected near-duplicate instead of appending a stale twin; get_session_context hides superseded / outdated / reverted decisions; and mark_decision_outdated(id) retires a decision that's simply no longer true (reversible). Protected do_not_revert decisions are never auto-retired — the conflict is surfaced for you.

Configuration

Codevira works with zero config. These environment variables (set them in your MCP server's env block) tune the surface — all default to the conservative behavior.

Surface & tokens

Variable	Effect
`CODEVIRA_TOOL_PROFILE=lean`	Advertise only the 12 daily-driver tools (~71% smaller `tools/list`)
`CODEVIRA_DECISION_DETAIL=full`	Restore verbose (pre-v3.5) decision payloads instead of summary-first

Project tracking 3.7

Variable	Effect
`CODEVIRA_AUTO_ADOPT=1`	Track every project you open (pre-3.7 behavior), instead of only the ones you `codevira init`
`CODEVIRA_AUTO_ADOPT=0`	Strict — un-init'd projects refuse without a hint (default is a friendly hint)

Enforcement engine

Variable	Effect
`CODEVIRA_ENGINE=0`	Kill switch — disable all hooks/policies for this session
`CODEVIRA_DECISION_LOCK_MODE`	`off` / `warn` / `block` (default `block`)
`CODEVIRA_DECISION_LOCK_CONTENT_AWARE=0`	Restore strict file-level locking (default is content-aware)
`CODEVIRA_BLAST_RADIUS_MODE` / `_THRESHOLD`	Tune the blast-radius veto (default `block`, threshold 5)

Opt-in read-side smarts 3.5

Variable	Effect
`CODEVIRA_LEARNED_WEIGHTS=1`	Use tuner-learned ranking weights at the hot path (from `tune-weights`)
`CODEVIRA_SYNONYM_WIDENING=1`	Widen queries via a curated synonym map (e.g. `database` → `postgres`)

Troubleshooting

Start with codevira doctor — every ⚠ / ✗ ships the exact fix command.

Symptom	Fix
Codevira tools don't show up in the AI tool	Re-run `codevira setup`, then fully restart the IDE. `codevira doctor` includes a Claude Code MCP-visibility check.
Agent reads memory from the wrong project	`codevira doctor` shows which project the server bound to and why. A shared, user-scope server resolves per-call from the client's workspace roots (v3.4+).
“0 decisions” / empty results	Decisions are keyword-searched (FTS5/BM25). Query the rarest distinct keyword; `search_decisions` is not semantic by default.
Stale code graph after edits	The live watcher + git post-commit hook normally keep it fresh; run `codevira index` to force a rebuild.
Starting fresh	`codevira reset` (auto-exports decisions first) or `codevira uninstall` to reverse every system write.

3.7.1 Upgrading is automatic. Codevira migrates your memory on the first server start after an upgrade — no manual steps, and your existing decisions stay put. If an IDE then shows the wrong project, doesn't show codevira at all, or memory looks missing, it's almost always a stale IDE-config entry, not lost data. Two fixes cover most cases: (1) remove a stray or temporary codevira entry with codevira untrack <path> (or sweep dead ones with codevira prune --ghosts); (2) run codevira doctor, which names the bound project and ships the exact fix for each ⚠ / ✗. Full guides: IDE config hygiene and Antigravity.

Still stuck? See the FAQ or open an issue.