# naprila/code-pilot architecture

> Architecture diagram of the GitHub repository naprila/code-pilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naprila/code-pilot
- Repository: https://github.com/naprila/code-pilot

## Overview

CodePilot is a command-line coding assistant for exploring and working with the current codebase. The main workflow initializes a repository index and agent, then routes `/ask` questions through session-aware query handling; answers may use a semantic cache. The CLI also supports approved, resumable `/plan` execution and task-status inspection. The tree and excerpts establish these entry points and capabilities, but do not show the agent’s tool wiring or indexer/retriever implementations in detail, so those internal links are left out where uncertain.

Main entry points: [`codepilot/main.py`](https://github.com/naprila/code-pilot/blob/main/codepilot/main.py) (Command interface), [`codepilot/tasks/orchestrator.py`](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/orchestrator.py) (Plan command), [`codepilot/agent/factory.py`](https://github.com/naprila/code-pilot/blob/main/codepilot/agent/factory.py) (Coding agent), [`codepilot/agent/orchestrator.py`](https://github.com/naprila/code-pilot/blob/main/codepilot/agent/orchestrator.py) (Query handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and sessions"]
  node_cli["Command interface<br/>[main.py]"]
  node_session["Session management<br/>[session.py]"]
  node_short_memory[("Conversation checkpoint<br/>[short_term.py]")]
end

subgraph group_knowledge["Codebase knowledge"]
  node_indexer["Repository indexer"]
  node_parser["Source chunking<br/>[code_parser.py]"]
  node_retriever["Code retrieval"]
  node_vector_store[("Vector store")]
  node_watcher["Change watcher<br/>[watcher.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_query_flow["Query handling<br/>[orchestrator.py]"]
  node_agent["Coding agent<br/>[factory.py]"]
  node_agent_tools["Agent tools<br/>[tools.py]"]
  node_files["Filesystem tools"]
  node_terminal["Terminal tools<br/>[terminal_tools.py]"]
  node_llm["Model provider<br/>[factory.py]"]
  node_mcp_client["MCP tools client"]
end

subgraph group_planning["Task planning"]
  node_plan_flow["Plan command<br/>[orchestrator.py]"]
  node_planner["Plan generation<br/>[planner.py]"]
  node_approval["Plan approval<br/>[approval.py]"]
  node_executor["Task execution<br/>[executor.py]"]
  node_recovery["Task recovery<br/>[recovery.py]"]
  node_status["Task status<br/>[status.py]"]
end

subgraph group_state["State and cache"]
  node_task_store[("Task records<br/>[task_store.py]")]
  node_semantic_cache["Semantic cache<br/>[semantic_cache.py]"]
end

node_user(("Engineer"))
node_model_service(("LLM service"))
node_mcp_service(("MCP servers"))
node_redis[("Redis cache")]

node_user -->|"enters commands"| node_cli
node_cli -->|"selects session"| node_session
node_cli -->|"opens checkpoint"| node_short_memory
node_cli -->|"initializes or reindexes"| node_indexer
node_indexer -->|"writes index"| node_vector_store
node_cli -->|"starts watcher"| node_watcher
node_cli -->|"builds agent"| node_agent
node_cli -->|"dispatches /ask"| node_query_flow
node_query_flow -->|"checks and stores"| node_semantic_cache
node_semantic_cache -->|"reads and writes"| node_redis
node_query_flow -->|"invokes on cache miss"| node_agent
node_agent -->|"uses model factory"| node_llm
node_llm -->|"connects to model"| node_model_service
node_cli -->|"dispatches /plan"| node_plan_flow
node_plan_flow -->|"creates plan"| node_planner
node_plan_flow -->|"requests approval"| node_approval
node_plan_flow -->|"recovers tasks"| node_recovery
node_plan_flow -->|"persists and reads tasks"| node_task_store
node_plan_flow -->|"runs ready tasks"| node_executor
node_executor -->|"updates task state"| node_task_store
node_cli -->|"shows task status"| node_status
node_status -->|"reads progress"| node_task_store
node_agent -->|"registers tools"| node_agent_tools
node_agent_tools -->|"exposes filesystem"| node_files
node_agent_tools -->|"exposes terminal"| node_terminal
node_mcp_client -.->|"loads tools"| node_mcp_service

click node_cli "https://github.com/naprila/code-pilot/blob/main/codepilot/main.py"
click node_session "https://github.com/naprila/code-pilot/blob/main/codepilot/memory/session.py"
click node_short_memory "https://github.com/naprila/code-pilot/blob/main/codepilot/memory/short_term.py"
click node_indexer "https://github.com/naprila/code-pilot/tree/main/codepilot/context/indexers"
click node_parser "https://github.com/naprila/code-pilot/blob/main/codepilot/context/indexers/code_parser.py"
click node_retriever "https://github.com/naprila/code-pilot/tree/main/codepilot/context/retrievers"
click node_watcher "https://github.com/naprila/code-pilot/blob/main/codepilot/context/indexers/watcher.py"
click node_query_flow "https://github.com/naprila/code-pilot/blob/main/codepilot/agent/orchestrator.py"
click node_agent "https://github.com/naprila/code-pilot/blob/main/codepilot/agent/factory.py"
click node_agent_tools "https://github.com/naprila/code-pilot/blob/main/codepilot/agent/tools.py"
click node_files "https://github.com/naprila/code-pilot/blob/main/codepilot/tools/filesystem_tools.py"
click node_terminal "https://github.com/naprila/code-pilot/blob/main/codepilot/tools/terminal_tools.py"
click node_llm "https://github.com/naprila/code-pilot/blob/main/codepilot/llm/factory.py"
click node_mcp_client "https://github.com/naprila/code-pilot/blob/main/codepilot/mcp/codepilot_mcp_client.py"
click node_plan_flow "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/orchestrator.py"
click node_planner "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/planner.py"
click node_approval "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/approval.py"
click node_executor "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/executor.py"
click node_recovery "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/recovery.py"
click node_status "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/status.py"
click node_task_store "https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/task_store.py"
click node_semantic_cache "https://github.com/naprila/code-pilot/blob/main/codepilot/cache/semantic_cache.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_session,node_short_memory toneBlue
class node_indexer,node_parser,node_retriever,node_vector_store,node_watcher,node_redis toneAmber
class node_query_flow,node_agent,node_agent_tools,node_files,node_terminal,node_llm,node_mcp_client,node_mcp_service toneMint
class node_plan_flow,node_planner,node_approval,node_executor,node_recovery,node_status toneRose
class node_task_store,node_semantic_cache,node_user,node_model_service toneIndigo
```

## Components

### CLI and sessions

- [Command interface](https://github.com/naprila/code-pilot/blob/main/codepilot/main.py): `codepilot/main.py`
- [Session management](https://github.com/naprila/code-pilot/blob/main/codepilot/memory/session.py): `codepilot/memory/session.py`
- [Conversation checkpoint](https://github.com/naprila/code-pilot/blob/main/codepilot/memory/short_term.py): `codepilot/memory/short_term.py`

### Codebase knowledge

- [Repository indexer](https://github.com/naprila/code-pilot/tree/main/codepilot/context/indexers): `codepilot/context/indexers`
- [Source chunking](https://github.com/naprila/code-pilot/blob/main/codepilot/context/indexers/code_parser.py): `codepilot/context/indexers/code_parser.py`
- [Code retrieval](https://github.com/naprila/code-pilot/tree/main/codepilot/context/retrievers): `codepilot/context/retrievers`
- **Vector store**
- [Change watcher](https://github.com/naprila/code-pilot/blob/main/codepilot/context/indexers/watcher.py): `codepilot/context/indexers/watcher.py`

### Assistant runtime

- [Query handling](https://github.com/naprila/code-pilot/blob/main/codepilot/agent/orchestrator.py): `codepilot/agent/orchestrator.py`
- [Coding agent](https://github.com/naprila/code-pilot/blob/main/codepilot/agent/factory.py): `codepilot/agent/factory.py`
- [Agent tools](https://github.com/naprila/code-pilot/blob/main/codepilot/agent/tools.py): `codepilot/agent/tools.py`
- [Filesystem tools](https://github.com/naprila/code-pilot/blob/main/codepilot/tools/filesystem_tools.py): `codepilot/tools/filesystem_tools.py`
- [Terminal tools](https://github.com/naprila/code-pilot/blob/main/codepilot/tools/terminal_tools.py): `codepilot/tools/terminal_tools.py`
- [Model provider](https://github.com/naprila/code-pilot/blob/main/codepilot/llm/factory.py): `codepilot/llm/factory.py`
- [MCP tools client](https://github.com/naprila/code-pilot/blob/main/codepilot/mcp/codepilot_mcp_client.py): `codepilot/mcp/codepilot_mcp_client.py`

### Task planning

- [Plan command](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/orchestrator.py): `codepilot/tasks/orchestrator.py`
- [Plan generation](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/planner.py): `codepilot/tasks/planner.py`
- [Plan approval](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/approval.py): `codepilot/tasks/approval.py`
- [Task execution](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/executor.py): `codepilot/tasks/executor.py`
- [Task recovery](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/recovery.py): `codepilot/tasks/recovery.py`
- [Task status](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/status.py): `codepilot/tasks/status.py`

### State and cache

- [Task records](https://github.com/naprila/code-pilot/blob/main/codepilot/tasks/task_store.py): `codepilot/tasks/task_store.py`
- [Semantic cache](https://github.com/naprila/code-pilot/blob/main/codepilot/cache/semantic_cache.py): `codepilot/cache/semantic_cache.py`

### Other components

- **Engineer**
- **LLM service**
- **MCP servers**
- **Redis cache**

## Connections

- Engineer → Command interface: enters commands
- Command interface → Session management: selects session
- Command interface → Conversation checkpoint: opens checkpoint
- Command interface → Repository indexer: initializes or reindexes
- Repository indexer → Vector store: writes index
- Command interface → Change watcher: starts watcher
- Command interface → Coding agent: builds agent
- Command interface → Query handling: dispatches /ask
- Query handling → Semantic cache: checks and stores
- Semantic cache → Redis cache: reads and writes
- Query handling → Coding agent: invokes on cache miss
- Coding agent → Model provider: uses model factory
- Model provider → LLM service: connects to model
- Command interface → Plan command: dispatches /plan
- Plan command → Plan generation: creates plan
- Plan command → Plan approval: requests approval
- Plan command → Task recovery: recovers tasks
- Plan command → Task records: persists and reads tasks
- Plan command → Task execution: runs ready tasks
- Task execution → Task records: updates task state
- Command interface → Task status: shows task status
- Task status → Task records: reads progress
- Coding agent → Agent tools: registers tools
- Agent tools → Filesystem tools: exposes filesystem
- Agent tools → Terminal tools: exposes terminal
- MCP tools client → MCP servers: loads tools