# virecorenlm/pi-ai-coder architecture

> Architecture diagram of the GitHub repository virecorenlm/pi-ai-coder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/virecorenlm/pi-ai-coder
- Repository: https://github.com/virecorenlm/pi-ai-coder
- Video tour (about a minute): https://gitdiagram.com/virecorenlm/pi-ai-coder/video

## Overview

PI-AI-CODER is a local coding assistant with CLI and full-screen TUI front ends. Its primary workflow takes a user task, builds project context, sends it to a local model, optionally runs a bounded tool-use loop for code inspection and changes, then presents the result while retaining conversation state. The README also documents model switching, git and shell tools, approval for risky actions, and a workspace UI. Some provider wiring and TUI details are unsampled, so those relationships are omitted or marked unverified.

Main entry points: [`pi_ai_coder/tui/app.py`](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tui/app.py) (TUI workspace), [`pi_ai_coder/agent/tools.py`](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/tools.py) (Tool registry), [`pi_ai_coder/agent/service.py`](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/service.py) (Agent loop), [`pi_ai_coder/core/assistant_service.py`](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/assistant_service.py) (Assistant service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_cli["CLI assistant<br/>[assistant.py]"]
  node_tui["TUI workspace<br/>[app.py]"]
  node_tui_widgets["Workspace widgets"]
  node_tui_screens["TUI screens"]
end

subgraph group_orchestration["Assistant workflow"]
  node_assistant_core["Assistant service"]
  node_agent_loop["Agent loop<br/>[service.py]"]
  node_model_runtime["Model runtime<br/>[model_runner.py]"]
  node_model_backends["Local model backends<br/>[model_runner.py]"]
end

subgraph group_agent_tools["Agent and tools"]
  node_agent_protocol["Tool-call protocol<br/>[protocol.py]"]
  node_agent_tools_registry["Tool registry<br/>[tools.py]"]
  node_agent_permissions["Risk approvals<br/>[permissions.py]"]
  node_file_tools["File operations<br/>[files.py]"]
  node_search_tool["Code search<br/>[search.py]"]
  node_git_tool["Git inspection<br/>[git.py]"]
  node_shell_tool["Shell execution<br/>[shell.py]"]
end

subgraph group_project_state["Project context and state"]
  node_context_service["Context selection<br/>[manager.py]"]
  node_session_store[("Session persistence<br/>[session.py]")]
  node_project_service["Project workspace<br/>[project.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Developer"))
node_ollama["Ollama server"]
node_llama_cpp["llama.cpp runtime"]

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_tui
node_cli -->|"delegates chat"| node_assistant_core
node_cli -->|"starts agent"| node_agent_loop
node_tui -->|"uses service"| node_assistant_core
node_tui -->|"runs tasks"| node_agent_loop
node_tui -.->|"renders workspace"| node_tui_widgets
node_tui -.->|"opens screens"| node_tui_screens
node_assistant_core -->|"builds context"| node_context_service
node_assistant_core -->|"updates session"| node_session_store
node_assistant_core -->|"requests response"| node_model_runtime
node_agent_loop -->|"streams turns"| node_model_runtime
node_model_runtime -.->|"selects backend"| node_model_backends
node_model_backends -->|"connects optionally"| node_ollama
node_model_backends -->|"runs optionally"| node_llama_cpp
node_agent_loop -->|"parses calls"| node_agent_protocol
node_agent_loop -->|"dispatches tools"| node_agent_tools_registry
node_agent_loop -->|"records turns"| node_session_store
node_agent_tools_registry -->|"checks risk"| node_agent_permissions
node_agent_tools_registry -->|"dispatches file work"| node_file_tools
node_agent_tools_registry -->|"dispatches search"| node_search_tool
node_agent_tools_registry -->|"dispatches git reads"| node_git_tool
node_agent_tools_registry -->|"runs commands"| node_shell_tool
node_tui_widgets -->|"views context"| node_context_service
node_tui_widgets -->|"reads git status"| node_git_tool
node_tui -->|"opens project"| node_project_service
node_tui -->|"loads settings"| node_config

click node_cli "https://github.com/virecorenlm/pi-ai-coder/blob/main/assistant.py"
click node_tui "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tui/app.py"
click node_tui_widgets "https://github.com/virecorenlm/pi-ai-coder/tree/main/pi_ai_coder/tui/widgets"
click node_tui_screens "https://github.com/virecorenlm/pi-ai-coder/tree/main/pi_ai_coder/tui/screens"
click node_assistant_core "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/assistant_service.py"
click node_agent_loop "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/service.py"
click node_model_runtime "https://github.com/virecorenlm/pi-ai-coder/blob/main/model_runner.py"
click node_model_backends "https://github.com/virecorenlm/pi-ai-coder/blob/main/model_runner.py"
click node_agent_protocol "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/protocol.py"
click node_agent_tools_registry "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/tools.py"
click node_agent_permissions "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/permissions.py"
click node_file_tools "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/files.py"
click node_search_tool "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/search.py"
click node_git_tool "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/git.py"
click node_shell_tool "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/shell.py"
click node_context_service "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/context/manager.py"
click node_session_store "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/session.py"
click node_project_service "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/project.py"
click node_config "https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/config.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_tui,node_tui_widgets,node_tui_screens toneBlue
class node_assistant_core,node_agent_loop,node_model_runtime,node_model_backends toneAmber
class node_agent_protocol,node_agent_tools_registry,node_agent_permissions,node_file_tools,node_search_tool,node_git_tool,node_shell_tool,node_ollama toneMint
class node_context_service,node_session_store,node_project_service,node_config toneRose
class node_user,node_llama_cpp toneIndigo
```

## Components

### User interfaces

- [CLI assistant](https://github.com/virecorenlm/pi-ai-coder/blob/main/assistant.py): `assistant.py`
- [TUI workspace](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tui/app.py): `pi_ai_coder/tui/app.py`
- [Workspace widgets](https://github.com/virecorenlm/pi-ai-coder/tree/main/pi_ai_coder/tui/widgets): `pi_ai_coder/tui/widgets`
- [TUI screens](https://github.com/virecorenlm/pi-ai-coder/tree/main/pi_ai_coder/tui/screens): `pi_ai_coder/tui/screens`

### Assistant workflow

- [Assistant service](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/assistant_service.py): `pi_ai_coder/core/assistant_service.py`
- [Agent loop](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/service.py): `pi_ai_coder/agent/service.py`
- [Model runtime](https://github.com/virecorenlm/pi-ai-coder/blob/main/model_runner.py): `model_runner.py`
- [Local model backends](https://github.com/virecorenlm/pi-ai-coder/blob/main/model_runner.py): `model_runner.py`

### Agent and tools

- [Tool-call protocol](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/protocol.py): `pi_ai_coder/agent/protocol.py`
- [Tool registry](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/tools.py): `pi_ai_coder/agent/tools.py`
- [Risk approvals](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/agent/permissions.py): `pi_ai_coder/agent/permissions.py`
- [File operations](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/files.py): `pi_ai_coder/tools/files.py`
- [Code search](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/search.py): `pi_ai_coder/tools/search.py`
- [Git inspection](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/git.py): `pi_ai_coder/tools/git.py`
- [Shell execution](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/tools/shell.py): `pi_ai_coder/tools/shell.py`

### Project context and state

- [Context selection](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/context/manager.py): `pi_ai_coder/context/manager.py`
- [Session persistence](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/session.py): `pi_ai_coder/core/session.py`
- [Project workspace](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/core/project.py): `pi_ai_coder/core/project.py`
- [Runtime configuration](https://github.com/virecorenlm/pi-ai-coder/blob/main/pi_ai_coder/config.py): `pi_ai_coder/config.py`

### Other components

- **Developer**
- **Ollama server**
- **llama.cpp runtime**

## Connections

- Developer → CLI assistant: submits task (evidence: `README.md`)
- Developer → TUI workspace: submits task (evidence: `README.md`)
- CLI assistant → Assistant service: delegates chat (evidence: `assistant.py`)
- CLI assistant → Agent loop: starts agent (evidence: `assistant.py`)
- TUI workspace → Assistant service: uses service (evidence: `pi_ai_coder/tui/app.py`)
- TUI workspace → Agent loop: runs tasks (evidence: `pi_ai_coder/tui/app.py`)
- TUI workspace → Workspace widgets: renders workspace (evidence: `pi_ai_coder/tui/app.py`)
- TUI workspace → TUI screens: opens screens (evidence: `pi_ai_coder/tui/app.py`)
- Assistant service → Context selection: builds context (evidence: `pi_ai_coder/core/assistant_service.py`)
- Assistant service → Session persistence: updates session (evidence: `pi_ai_coder/core/assistant_service.py`)
- Assistant service → Model runtime: requests response (evidence: `pi_ai_coder/core/assistant_service.py`)
- Agent loop → Model runtime: streams turns (evidence: `pi_ai_coder/agent/service.py`)
- Model runtime → Local model backends: selects backend (evidence: `model_runner.py`)
- Local model backends → Ollama server: connects optionally (evidence: `README.md`)
- Local model backends → llama.cpp runtime: runs optionally (evidence: `README.md`)
- Agent loop → Tool-call protocol: parses calls (evidence: `pi_ai_coder/agent/service.py`)
- Agent loop → Tool registry: dispatches tools (evidence: `pi_ai_coder/agent/service.py`)
- Agent loop → Session persistence: records turns (evidence: `pi_ai_coder/agent/service.py`)
- Tool registry → Risk approvals: checks risk (evidence: `pi_ai_coder/agent/tools.py`)
- Tool registry → File operations: dispatches file work (evidence: `pi_ai_coder/agent/tools.py`)
- Tool registry → Code search: dispatches search (evidence: `pi_ai_coder/agent/tools.py`)
- Tool registry → Git inspection: dispatches git reads (evidence: `pi_ai_coder/agent/tools.py`)
- Tool registry → Shell execution: runs commands (evidence: `pi_ai_coder/agent/tools.py`)
- Workspace widgets → Context selection: views context (evidence: `pi_ai_coder/tui/widgets/context_panel.py`)
- Workspace widgets → Git inspection: reads git status (evidence: `pi_ai_coder/tui/widgets/git_panel.py`)
- TUI workspace → Project workspace: opens project (evidence: `pi_ai_coder/tui/app.py`)
- TUI workspace → Runtime configuration: loads settings (evidence: `pi_ai_coder/tui/app.py`)
