Docs & usage

Everything a developer needs to install Codevira, wire it into every AI tool, and use the CLI + MCP surface. Local-first, MIT, ~83 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 — git-committed and team-shareable. The code graph lives in a rebuildable, gitignored cache. The MCP server starts in under 100 ms.

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.

Connect your AI tools

codevira setup auto-detects installed tools (strong signals: binary on PATH + valid config) and configures each one. Pass --force if the detector misses an install, or --dry-run to preview.

Tool	What codevira writes
Claude Code	MCP server entry + PreToolUse / SessionStart lifecycle hooks (the only client with hard enforcement)
Cursor · Windsurf	MCP server entry (stdio) + reads `AGENTS.md`
Claude Desktop	stdio MCP entry (per-project `--project-dir`)
Antigravity · 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, windsurf mcp_config.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

23 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 replay`	Browse the decision timeline (terminal / markdown / HTML)
`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 reflect --from-sessions` 3.5	Mine local Claude Code / Codex / Gemini transcripts for lessons
`codevira uninstall`	Reverse every system write codevira made (`--keep-data` to keep memory)

MCP tool surface

50 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`, `set_decision_flag`, `get_history`
Code graph	`get_node`, `get_impact`, `get_signature`, `get_code`, `query_graph`
Roadmap / phases	`get_phase`, `add_phase`, `update_phase_status`, `complete_phase`, `update_next_action`, `write_session_log`
Memory subsystems	working memory, skills, spatial, consensus, reflections (`working_add`, `record_skill`, `spatial_nearby`, `consensus_status`, `reflect`, …)
Preferences	`distill_preferences`, `search_preferences`

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

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

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.

Still stuck? See the FAQ or open an issue.