# rivaanranawat/ai-coding-agent architecture

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

- Interactive diagram: https://gitdiagram.com/rivaanranawat/ai-coding-agent
- Repository: https://github.com/rivaanranawat/ai-coding-agent

## Overview

AI Agent is a terminal-based assistant that turns user prompts into streamed model responses and, when needed, tool executions. The principal workflow runs from the CLI through agent/session orchestration, conversation context, model tool calls, and registry-mediated execution; approval and hooks surround tool use. Sessions also initialize built-in, discovered, and MCP tools and maintain usage and persistence state. The README documents additional capabilities whose detailed wiring is not fully visible in the sampled source, so uncertain call relationships are omitted.

Main entry points: [`agent/session.py`](https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/session.py) (Session setup), [`tools/registry.py`](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/registry.py) (Tool registry), [`agent/agent.py`](https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/agent.py) (Agent loop), [`main.py`](https://github.com/rivaanranawat/ai-coding-agent/blob/main/main.py) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal interface"]
  node_cli["CLI entry<br/>[main.py]"]
  node_tui["Terminal UI<br/>[tui.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent["Agent loop<br/>[agent.py]"]
  node_session["Session setup<br/>[session.py]"]
  node_persistence[("Session persistence<br/>[persistence.py]")]
  node_config["Configuration<br/>[config.py]"]
  node_hooks["Hooks<br/>[hook_system.py]"]
end

subgraph group_context["Conversation context"]
  node_context_manager["Context manager<br/>[manager.py]"]
  node_compactor["Context compression<br/>[compaction.py]"]
  node_loop_detector["Loop detection<br/>[loop_detector.py]"]
end

subgraph group_tools["Tool execution"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_builtin_tools["Built-in tools"]
  node_discovery["Tool discovery<br/>[discovery.py]"]
  node_subagents["Subagents<br/>[subagents.py]"]
  node_approval["Approval policy<br/>[approval.py]"]
end

subgraph group_integrations["External integrations"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_mcp_manager["MCP manager<br/>[mcp_manager.py]"]
  node_mcp_client["MCP client<br/>[client.py]"]
end

node_user(("User"))
node_model_service{{"Model API"}}
node_mcp_servers{{"MCP servers"}}
node_web{{"Web search"}}

node_user -->|"enters prompt"| node_cli
node_cli -->|"submits work"| node_agent
node_cli -->|"renders events"| node_tui
node_agent -->|"uses session"| node_session
node_session -->|"creates context"| node_context_manager
node_session -->|"creates client"| node_llm
node_session -->|"creates registry"| node_registry
node_session -->|"sets up discovery"| node_discovery
node_session -->|"initializes"| node_mcp_manager
node_session -->|"creates compactor"| node_compactor
node_session -->|"creates manager"| node_approval
node_session -->|"creates detector"| node_loop_detector
node_session -->|"creates hook system"| node_hooks
node_session -->|"reads settings"| node_config
node_agent -->|"manages messages"| node_context_manager
node_agent -->|"requests completions"| node_llm
node_llm -->|"sends chat request"| node_model_service
node_model_service -->|"streams events"| node_llm
node_agent -->|"dispatches tool calls"| node_registry
node_registry -->|"checks operations"| node_approval
node_registry -->|"triggers tool hooks"| node_hooks
node_registry -->|"executes tools"| node_builtin_tools
node_registry -->|"registers tools"| node_subagents
node_session -->|"registers MCP tools"| node_mcp_manager
node_mcp_manager -->|"registers tools"| node_registry
node_mcp_manager -->|"connects clients"| node_mcp_client
node_mcp_client -->|"lists and calls tools"| node_mcp_servers
node_builtin_tools -.->|"searches web"| node_web
node_cli -->|"saves and resumes"| node_persistence
node_agent -->|"updates conversation"| node_context_manager

click node_cli "https://github.com/rivaanranawat/ai-coding-agent/blob/main/main.py"
click node_tui "https://github.com/rivaanranawat/ai-coding-agent/blob/main/ui/tui.py"
click node_agent "https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/agent.py"
click node_session "https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/session.py"
click node_persistence "https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/persistence.py"
click node_config "https://github.com/rivaanranawat/ai-coding-agent/blob/main/config/config.py"
click node_context_manager "https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/manager.py"
click node_compactor "https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/compaction.py"
click node_loop_detector "https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/loop_detector.py"
click node_llm "https://github.com/rivaanranawat/ai-coding-agent/blob/main/client/llm_client.py"
click node_registry "https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/registry.py"
click node_builtin_tools "https://github.com/rivaanranawat/ai-coding-agent/tree/main/tools/builtin"
click node_discovery "https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/discovery.py"
click node_subagents "https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/subagents.py"
click node_approval "https://github.com/rivaanranawat/ai-coding-agent/blob/main/safety/approval.py"
click node_hooks "https://github.com/rivaanranawat/ai-coding-agent/blob/main/hooks/hook_system.py"
click node_mcp_manager "https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/mcp/mcp_manager.py"
click node_mcp_client "https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/mcp/client.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_user toneBlue
class node_agent,node_session,node_persistence,node_config,node_hooks toneAmber
class node_context_manager,node_compactor,node_loop_detector,node_model_service,node_mcp_servers toneMint
class node_registry,node_builtin_tools,node_discovery,node_subagents,node_approval toneRose
class node_llm,node_mcp_manager,node_mcp_client,node_web toneIndigo
```

## Components

### Terminal interface

- [CLI entry](https://github.com/rivaanranawat/ai-coding-agent/blob/main/main.py): `main.py`
- [Terminal UI](https://github.com/rivaanranawat/ai-coding-agent/blob/main/ui/tui.py): `ui/tui.py`

### Agent runtime

- [Agent loop](https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/agent.py): `agent/agent.py`
- [Session setup](https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/session.py): `agent/session.py`
- [Session persistence](https://github.com/rivaanranawat/ai-coding-agent/blob/main/agent/persistence.py): `agent/persistence.py`
- [Configuration](https://github.com/rivaanranawat/ai-coding-agent/blob/main/config/config.py): `config/config.py`
- [Hooks](https://github.com/rivaanranawat/ai-coding-agent/blob/main/hooks/hook_system.py): `hooks/hook_system.py`

### Conversation context

- [Context manager](https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/manager.py): `context/manager.py`
- [Context compression](https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/compaction.py): `context/compaction.py`
- [Loop detection](https://github.com/rivaanranawat/ai-coding-agent/blob/main/context/loop_detector.py): `context/loop_detector.py`

### Tool execution

- [Tool registry](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/registry.py): `tools/registry.py`
- [Built-in tools](https://github.com/rivaanranawat/ai-coding-agent/tree/main/tools/builtin): `tools/builtin`
- [Tool discovery](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/discovery.py): `tools/discovery.py`
- [Subagents](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/subagents.py): `tools/subagents.py`
- [Approval policy](https://github.com/rivaanranawat/ai-coding-agent/blob/main/safety/approval.py): `safety/approval.py`

### External integrations

- [LLM client](https://github.com/rivaanranawat/ai-coding-agent/blob/main/client/llm_client.py): `client/llm_client.py`
- [MCP manager](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/mcp/mcp_manager.py): `tools/mcp/mcp_manager.py`
- [MCP client](https://github.com/rivaanranawat/ai-coding-agent/blob/main/tools/mcp/client.py): `tools/mcp/client.py`

### Other components

- **User**
- **Model API**
- **MCP servers**
- **Web search**

## Connections

- User → CLI entry: enters prompt
- CLI entry → Agent loop: submits work
- CLI entry → Terminal UI: renders events
- Agent loop → Session setup: uses session
- Session setup → Context manager: creates context
- Session setup → LLM client: creates client
- Session setup → Tool registry: creates registry
- Session setup → Tool discovery: sets up discovery
- Session setup → MCP manager: initializes
- Session setup → Context compression: creates compactor
- Session setup → Approval policy: creates manager
- Session setup → Loop detection: creates detector
- Session setup → Hooks: creates hook system
- Session setup → Configuration: reads settings
- Agent loop → Context manager: manages messages
- Agent loop → LLM client: requests completions
- LLM client → Model API: sends chat request
- Model API → LLM client: streams events
- Agent loop → Tool registry: dispatches tool calls
- Tool registry → Approval policy: checks operations
- Tool registry → Hooks: triggers tool hooks
- Tool registry → Built-in tools: executes tools
- Tool registry → Subagents: registers tools
- Session setup → MCP manager: registers MCP tools
- MCP manager → Tool registry: registers tools
- MCP manager → MCP client: connects clients
- MCP client → MCP servers: lists and calls tools
- Built-in tools → Web search: searches web
- CLI entry → Session persistence: saves and resumes
- Agent loop → Context manager: updates conversation