flowchart TB

Start([Start Session])

subgraph Orientation
A[Check Open Changesets]
B[Get Project Roadmap]
C[Search Past Decisions]
D[Load Graph Context\nget_node • get_impact]
end

subgraph Execution
E[Plan Task]
F[Implement Code]
G[Run Tests / Validation]
end

subgraph Completion
H[Update Graph Metadata]
I[Write Session Log]
J[Complete Changeset]
end

Start --> A
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J

flowchart TB

A[Source Code]

subgraph Structural Analysis
B[AST Parser]
C[Function / Class Extraction]
D[Dependency Analysis]
end

subgraph Knowledge Stores
E[(Semantic Index<br/>ChromaDB)]
F[(Context Graph<br/>SQLite DB)]
end

subgraph Runtime Access
G[MCP Query Layer<br/>search_codebase • get_node • get_impact]
end

H[AI Coding Agent<br/>Claude Code • Cursor]

A --> B
B --> C
C --> E

B --> D
D --> F

E --> G
F --> G

G --> H

pip install codevira-mcp

cd your-project
codevira init

{
  "mcpServers": {
    "codevira": {
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/your-project"]
    }
  }
}

{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

{
  "mcpServers": {
    "codevira": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

your-project/
├── src/                   ← your code (indexed)
├── .codevira/             ← Codevira data directory (git-ignored)
│   ├── config.yaml        ← project configuration
│   ├── roadmap.yaml       ← project roadmap (auto-generated, human-enrichable)
│   ├── codeindex/         ← ChromaDB index (auto-regenerated)
│   └── graph/             ← context graph and session memory
│       ├── graph.db       ← SQLite database for nodes, edges, logs, and decisions
│       └── changesets/    ← active multi-file change records
└── requirements.txt       ← add: codevira-mcp>=1.0.0

list_open_changesets()      → resume any unfinished work first
get_roadmap()               → current phase, next action
search_decisions("topic")   → check what's already been decided
get_node("src/service.py")  → read rules before touching a file
get_impact("src/service.py") → check blast radius

complete_changeset(id, decisions=[...])
update_node(file_path, changes)
update_next_action("what the next agent should do")
write_session_log(...)

.agents/
├── PROTOCOL.md              # Session protocol — read this first
├── config.example.yaml      # Config template
├── config.yaml              # Your config (git-ignored)
├── roadmap.yaml             # Phase tracker (auto-created, git-ignored)
├── mcp-server/
│   ├── server.py            # MCP server entry point
│   └── tools/
│       ├── graph.py
│       ├── roadmap.py
│       ├── changesets.py
│       ├── search.py
│       ├── playbook.py
│       └── code_reader.py
├── indexer/
│   ├── index_codebase.py    # Build/update ChromaDB index + background file watcher
│   ├── chunker.py           # AST-based code chunker
│   ├── treesitter_parser.py # Multi-language AST parsing (16+ languages)
│   ├── sqlite_graph.py      # SQLite graph database backend
│   └── graph_generator.py   # Auto-generate graph stubs
├── requirements.txt         # Python dependencies
├── agents/                  # Role definitions
│   ├── orchestrator.md
│   ├── planner.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── builder.md
│   └── documenter.md
├── rules/                   # Engineering standards
│   ├── master_rule.md
│   ├── coding-standards.md
│   ├── testing-standards.md
│   └── ...13 more
├── graph/
│   ├── graph.db             # SQLite Context Graph and Session Memory (git-ignored)
│   └── changesets/
├── hooks/
│   └── install-hooks.sh
└── codeindex/               # ChromaDB files (git-ignored)

pip install -r .agents/requirements.txt