# nick211908/coding-agent architecture

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

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

## Overview

1. **What this repo is**
   - `coding-agent` is an agentic coding assistant/runtime that runs a conversational loop, lets an LLM choose tools, and executes those tools against the local machine and external services.
   - The architecture is centered on a small core agent with pluggable tool execution, safety checks, and optional terminal UI.

2. **Main entry and orchestration**
   - `main.py` is the likely process entrypoint that wires together configuration, the agent, the UI, and any persistence/session setup.
   - The runtime boundary is: initialize config → create agent/session → start interaction loop → handle tool calls and model replies.

3. **Agent core**
   - `agent/agent.py` is the orchestration layer that coordinates model turns, tool invocation, and state updates.
   - `agent/session.py` holds per-run conversation/session state.
   - `agent/events.py` defines the event stream emitted during agent execution, which is useful for UI, logging, hooks, and persistence.
   - `agent/persistence.py` stores or reloads session state so runs can survive process restarts.

4. **Model/client boundary**
   - `client/llm_client.py` is the abstraction over the LLM provider. It likely sends the prompt + tool schema and receives structured responses/tool calls.
   - `client/response.py` handles normalized response parsing, likely mapping provider-specific output into internal agent events or action objects.
   - The README’s OpenAI-style tool schema snippet suggests the system follows a function/tool-call contract similar to OpenAI-compatible APIs.

5. **Context management**
   - `context/manager.py` is responsible for assembling the message/context window passed to the model.
   - `context/compaction.py` reduces or summarizes history when context grows too large.
   - `context/loop_detector.py` guards against repetitive agent behavior, such as repeatedly calling the same tool or producing the same outcome.
   - This is a key boundary: session state may be large, but the model only sees a curated, bounded context.

6. **Tools subsystem**
   - `tools/base.py` defines the common tool interface.
   - `tools/registry.py` is the central catalog of available tools and likely converts tool implementations into the schema exposed to the model.
   - `tools/discovery.py` auto-discovers tools from the codebase.
   - `tools/builtin/` contains local first-party capabilities: filesystem reads/writes, directory listing, grep/glob, shell execution, web search/fetch, todo/memory, and edit/apply workflows.
   - `apply_patch.py` and the edit/write tools indicate the system is built to make code changes directly, not just inspect files.

7. **External tool integration**
   - `tools/mcp/` integrates with MCP-style tool servers:
     - `tools/mcp/client.py` talks to an external MCP server.
     - `tools/mcp/mcp_manager.py` manages one or more MCP connections.
     - `tools/mcp/mcp_tool.py` adapts MCP-exposed capabilities into the internal tool interface.
   - This creates a clear external boundary: internal agent/tooling on one side, remote tool providers on the other.

8. **Subagent support**
   - `tools/subagents.py` suggests the system can delegate work to subordinate agents.
   - Architecturally, this is a second-level orchestration path: the main agent can spawn/coordinate specialized agent runs rather than performing everything in one loop.

9. **Safety and approval**
   - `safety/approval.py` is the control point for human confirmation before risky actions.
   - This is especially relevant for destructive or irreversible tools such as shell, write, or edit operations.
   - In the diagram, this should sit between tool request generation and actual tool execution.

10. **Hooks and extensibility**
    - `hooks/hook_system.py` provides lifecycle interception around agent events.
    - Hooks likely observe or modify behavior at key points such as before/after model calls, before/after tool execution, or on errors.
    - This is the repo’s extension seam for logging, telemetry, custom policy, or workflow automation.

11. **User interface**
    - `ui/tui.py` is a terminal UI layer for interacting with the agent.
    - It likely subscribes to the event stream and renders progress, tool calls, outputs, and approvals.
    - The UI is not the agent core; it is a presentation layer over the event/agent runtime.

12. **Configuration and environment**
    - `config/config.py` and `config/loader.py` load runtime settings such as model provider details, tool enablement, paths, approvals, and UI behavior.
    - `utils/paths.py` and related utilities support cross-platform path handling and text/error normalization.
    - `pyproject.toml` and `uv.lock` show this is a Python project managed with modern dependency locking, and `.python-version` suggests a pinned interpreter version.

13. **Operational data flow**
    - The dominant flow is: user input or task request → agent session/context assembly → LLM call → tool selection → safety check → tool execution → event emission/hook handling → context update → next turn.
    - Persistence, compaction, and loop detection all feed back into that loop to keep the agent reliable over longer tasks.

14. **What to show in an architecture diagram**
    - Draw a central agent loop surrounded by four main boundaries:
      - **Model boundary**: `client/*`
      - **Tool boundary**: `tools/*` including builtins and MCP
      - **Safety boundary**: `safety/approval.py`
      - **Presentation boundary**: `ui/tui.py`
    - Add side services for **context management**, **hooks**, and **persistence**, because they influence behavior but do not own the primary control flow.

Main entry points: [`agent/agent.py`](https://github.com/nick211908/coding-agent/blob/main/agent/agent.py) (Agent), [`tools/builtin/__init__.py`](https://github.com/nick211908/coding-agent/blob/main/tools/builtin/__init__.py) (Builtins), [`tools/registry.py`](https://github.com/nick211908/coding-agent/blob/main/tools/registry.py) (Registry), [`main.py`](https://github.com/nick211908/coding-agent/blob/main/main.py) (main.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_main["main.py<br/>entrypoint<br/>[main.py]"]
  node_agent_core["Agent<br/>orchestrator<br/>[agent.py]"]
  node_session["Session<br/>state<br/>[session.py]"]
  node_events["Events<br/>event stream<br/>[events.py]"]
  node_persistence[("Persistence<br/>session store<br/>[persistence.py]")]
  node_context_mgr["Context<br/>[manager.py]"]
  node_compaction["Compaction<br/>history reducer<br/>[compaction.py]"]
  node_loop_detector{{"Loop detector<br/>guardrail<br/>[loop_detector.py]"}}
end

subgraph group_tools["Tools"]
  node_registry["Registry<br/>tool catalog<br/>[registry.py]"]
  node_discovery["Discovery<br/>tool loader<br/>[discovery.py]"]
  node_builtin_tools["Builtins<br/>local tools<br/>[__init__.py]"]
  node_mcp_manager["MCP manager<br/>external tools<br/>[mcp_manager.py]"]
  node_mcp_client["MCP client<br/>protocol client<br/>[client.py]"]
  node_mcp_tool["MCP tool<br/>tool adapter<br/>[mcp_tool.py]"]
  node_subagents["Subagents<br/>delegation<br/>[subagents.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_llm_client["LLM client<br/>model client<br/>[llm_client.py]"]
  node_response["Response<br/>normalizer<br/>[response.py]"]
  node_approval{{"Approval<br/>safety gate<br/>[approval.py]"}}
  node_hook_system["Hooks<br/>extension seam<br/>[hook_system.py]"]
  node_tui["TUI<br/>terminal ui<br/>[tui.py]"]
end

subgraph group_support["Support"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_loader["Loader<br/>[loader.py]"]
  node_system_prompt["Prompt<br/>[system.py]"]
  node_paths["Paths<br/>path utils<br/>[paths.py]"]
  node_errors["Errors<br/>error utils<br/>[errors.py]"]
  node_text["Text<br/>[text.py]"]
end

node_main -->|"load config"| node_loader
node_main -->|"start loop"| node_agent_core
node_main -->|"attach ui"| node_tui
node_loader -->|"produce"| node_config
node_agent_core -->|"use state"| node_session
node_agent_core -->|"build context"| node_context_mgr
node_context_mgr -->|"compact"| node_compaction
node_context_mgr -->|"check loops"| node_loop_detector
node_agent_core -->|"call model"| node_llm_client
node_llm_client -->|"parse reply"| node_response
node_response -->|"actions"| node_agent_core
node_agent_core -->|"resolve tools"| node_registry
node_registry -->|"discover"| node_discovery
node_registry -->|"include"| node_builtin_tools
node_registry -->|"include"| node_mcp_manager
node_mcp_manager -->|"connect"| node_mcp_client
node_mcp_manager -->|"adapt"| node_mcp_tool
node_agent_core -->|"request approval"| node_approval
node_approval -->|"allow exec"| node_builtin_tools
node_approval -->|"allow remote"| node_mcp_tool
node_agent_core -->|"emit hooks"| node_hook_system
node_agent_core -->|"emit"| node_events
node_events -->|"render"| node_tui
node_agent_core -->|"save/load"| node_persistence
node_agent_core -->|"delegate"| node_subagents
node_agent_core -->|"prime"| node_system_prompt
node_builtin_tools -->|"use"| node_paths
node_builtin_tools -->|"report"| node_errors
node_builtin_tools -->|"normalize"| node_text

click node_main "https://github.com/nick211908/coding-agent/blob/main/main.py"
click node_agent_core "https://github.com/nick211908/coding-agent/blob/main/agent/agent.py"
click node_session "https://github.com/nick211908/coding-agent/blob/main/agent/session.py"
click node_events "https://github.com/nick211908/coding-agent/blob/main/agent/events.py"
click node_persistence "https://github.com/nick211908/coding-agent/blob/main/agent/persistence.py"
click node_context_mgr "https://github.com/nick211908/coding-agent/blob/main/context/manager.py"
click node_compaction "https://github.com/nick211908/coding-agent/blob/main/context/compaction.py"
click node_loop_detector "https://github.com/nick211908/coding-agent/blob/main/context/loop_detector.py"
click node_llm_client "https://github.com/nick211908/coding-agent/blob/main/client/llm_client.py"
click node_response "https://github.com/nick211908/coding-agent/blob/main/client/response.py"
click node_approval "https://github.com/nick211908/coding-agent/blob/main/safety/approval.py"
click node_hook_system "https://github.com/nick211908/coding-agent/blob/main/hooks/hook_system.py"
click node_tui "https://github.com/nick211908/coding-agent/blob/main/ui/tui.py"
click node_registry "https://github.com/nick211908/coding-agent/blob/main/tools/registry.py"
click node_discovery "https://github.com/nick211908/coding-agent/blob/main/tools/discovery.py"
click node_builtin_tools "https://github.com/nick211908/coding-agent/blob/main/tools/builtin/__init__.py"
click node_mcp_manager "https://github.com/nick211908/coding-agent/blob/main/tools/mcp/mcp_manager.py"
click node_mcp_client "https://github.com/nick211908/coding-agent/blob/main/tools/mcp/client.py"
click node_mcp_tool "https://github.com/nick211908/coding-agent/blob/main/tools/mcp/mcp_tool.py"
click node_subagents "https://github.com/nick211908/coding-agent/blob/main/tools/subagents.py"
click node_config "https://github.com/nick211908/coding-agent/blob/main/config/config.py"
click node_loader "https://github.com/nick211908/coding-agent/blob/main/config/loader.py"
click node_system_prompt "https://github.com/nick211908/coding-agent/blob/main/prompts/system.py"
click node_paths "https://github.com/nick211908/coding-agent/blob/main/utils/paths.py"
click node_errors "https://github.com/nick211908/coding-agent/blob/main/utils/errors.py"
click node_text "https://github.com/nick211908/coding-agent/blob/main/utils/text.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_main,node_agent_core,node_session,node_events,node_persistence,node_context_mgr,node_compaction,node_loop_detector toneBlue
class node_registry,node_discovery,node_builtin_tools,node_mcp_manager,node_mcp_client,node_mcp_tool,node_subagents toneAmber
class node_llm_client,node_response,node_approval,node_hook_system,node_tui toneMint
class node_config,node_loader,node_system_prompt,node_paths,node_errors,node_text toneRose
```

## Components

### Core runtime

Agent loop, session state, context assembly, persistence, and event flow.

- [main.py](https://github.com/nick211908/coding-agent/blob/main/main.py): entrypoint · Process entrypoint that wires config, agent runtime, UI, and persistence. · `main.py`
- [Agent](https://github.com/nick211908/coding-agent/blob/main/agent/agent.py): orchestrator · Coordinates model turns, tool calls, and state updates. · `agent/agent.py`
- [Session](https://github.com/nick211908/coding-agent/blob/main/agent/session.py): state · Per-run conversation and execution state. · `agent/session.py`
- [Events](https://github.com/nick211908/coding-agent/blob/main/agent/events.py): event stream · Execution events emitted for UI, hooks, and logging. · `agent/events.py`
- [Persistence](https://github.com/nick211908/coding-agent/blob/main/agent/persistence.py): session store · Saves and restores agent session state across runs. · `agent/persistence.py`
- [Context](https://github.com/nick211908/coding-agent/blob/main/context/manager.py): context builder · Builds bounded model context from session state and history. · `context/manager.py`
- [Compaction](https://github.com/nick211908/coding-agent/blob/main/context/compaction.py): history reducer · Summarizes or compresses context when it grows too large. · `context/compaction.py`
- [Loop detector](https://github.com/nick211908/coding-agent/blob/main/context/loop_detector.py): guardrail · Detects repetitive tool or reasoning loops. · `context/loop_detector.py`

### Tools

Local tools, external MCP tools, and subagent delegation.

- [Registry](https://github.com/nick211908/coding-agent/blob/main/tools/registry.py): tool catalog · Central catalog and schema exporter for available tools. · `tools/registry.py`
- [Discovery](https://github.com/nick211908/coding-agent/blob/main/tools/discovery.py): tool loader · Auto-discovers tool implementations from the codebase. · `tools/discovery.py`
- [Builtins](https://github.com/nick211908/coding-agent/blob/main/tools/builtin/__init__.py): local tools · First-party filesystem, shell, search, edit, memory, and todo tools. · `tools/builtin/__init__.py`
- [MCP manager](https://github.com/nick211908/coding-agent/blob/main/tools/mcp/mcp_manager.py): external tools · Manages connections to external MCP tool servers. · `tools/mcp/mcp_manager.py`
- [MCP client](https://github.com/nick211908/coding-agent/blob/main/tools/mcp/client.py): protocol client · Talks to a remote MCP server. · `tools/mcp/client.py`
- [MCP tool](https://github.com/nick211908/coding-agent/blob/main/tools/mcp/mcp_tool.py): tool adapter · Wraps MCP-exposed capabilities into the internal tool interface. · `tools/mcp/mcp_tool.py`
- [Subagents](https://github.com/nick211908/coding-agent/blob/main/tools/subagents.py): delegation · Spawns or coordinates subordinate agent runs. · `tools/subagents.py`

### Interfaces

Model client, safety, UI, and extensibility seams.

- [LLM client](https://github.com/nick211908/coding-agent/blob/main/client/llm_client.py): model client · Provider abstraction for prompt, tool schema, and structured replies. · `client/llm_client.py`
- [Response](https://github.com/nick211908/coding-agent/blob/main/client/response.py): normalizer · Parses provider output into internal actions or tool calls. · `client/response.py`
- [Approval](https://github.com/nick211908/coding-agent/blob/main/safety/approval.py): safety gate · Human confirmation boundary for risky or destructive actions. · `safety/approval.py`
- [Hooks](https://github.com/nick211908/coding-agent/blob/main/hooks/hook_system.py): extension seam · Lifecycle interception for logging, telemetry, and policy. · `hooks/hook_system.py`
- [TUI](https://github.com/nick211908/coding-agent/blob/main/ui/tui.py): terminal ui · Terminal presentation layer over the agent event stream. · `ui/tui.py`

### Support

Configuration, prompts, and shared utilities.

- [Config](https://github.com/nick211908/coding-agent/blob/main/config/config.py): settings · Loads runtime settings for models, tools, approvals, and UI. · `config/config.py`
- [Loader](https://github.com/nick211908/coding-agent/blob/main/config/loader.py): config loader · Reads and assembles configuration from files and environment. · `config/loader.py`
- [Prompt](https://github.com/nick211908/coding-agent/blob/main/prompts/system.py): system prompt · Defines the agent’s system instructions and operating policy. · `prompts/system.py`
- [Paths](https://github.com/nick211908/coding-agent/blob/main/utils/paths.py): path utils · Cross-platform path handling helpers. · `utils/paths.py`
- [Errors](https://github.com/nick211908/coding-agent/blob/main/utils/errors.py): error utils · Shared error normalization and handling helpers. · `utils/errors.py`
- [Text](https://github.com/nick211908/coding-agent/blob/main/utils/text.py): text utils · Shared text normalization helpers. · `utils/text.py`

## Connections

- main.py → Loader: load config · Initializes runtime settings before the agent starts.
- main.py → Agent: start loop · Creates and runs the primary agent loop.
- main.py → TUI: attach ui · Connects the terminal UI to runtime events.
- Loader → Config: produce · Builds effective configuration from files and environment.
- Agent → Session: use state · Reads and updates per-run session state.
- Agent → Context: build context · Requests bounded model context for each turn.
- Context → Compaction: compact · Summarizes or trims history when needed.
- Context → Loop detector: check loops · Applies repetition guardrails before model calls or tool use.
- Agent → LLM client: call model · Sends context and tool schema to the model client.
- LLM client → Response: parse reply · Normalizes provider output into internal response objects.
- Response → Agent: actions · Returns tool calls, messages, and control signals to the agent.
- Agent → Registry: resolve tools · Looks up available tools and their schemas.
- Registry → Discovery: discover · Finds tool implementations in the repository.
- Registry → Builtins: include · Registers local first-party tools.
- Registry → MCP manager: include · Registers remote MCP-backed tools.
- MCP manager → MCP client: connect · Maintains one or more server connections.
- MCP manager → MCP tool: adapt · Exposes MCP capabilities through the internal tool interface.
- Agent → Approval: request approval · Sends risky tool actions through the human approval gate.
- Approval → Builtins: allow exec · Permits execution of local tools after confirmation.
- Approval → MCP tool: allow remote · Permits execution of remote tool actions after confirmation.
- Agent → Hooks: emit hooks · Triggers lifecycle callbacks around model and tool activity.
- Agent → Events: emit · Publishes execution events for observers.
- Events → TUI: render · Streams progress and results to the terminal UI.
- Agent → Persistence: save/load · Persists session state for recovery and resumption.
- Agent → Subagents: delegate · Spawns specialized subordinate agent runs when useful.
- Agent → Prompt: prime · Uses the system prompt to shape the agent’s behavior.
- Builtins → Paths: use · Shares path handling helpers across local tools.
- Builtins → Errors: report · Normalizes tool failures and runtime errors.
- Builtins → Text: normalize · Uses shared text helpers for consistent tool output.
