# zgjdev/code-agent architecture

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

- Interactive diagram: https://gitdiagram.com/zgjdev/code-agent
- Repository: https://github.com/zgjdev/code-agent

## Overview

CodeAgent is a Java coding-agent CLI for understanding and changing real codebases. A user submits a task through the terminal; the CLI selects ReAct or Plan-and-Execute, invokes model-backed agents and guarded tools, and presents the result. Plan execution adds DAG planning, approval, conflict-aware batching, worker execution, evidence checks, review, and recovery. Other documented capabilities include code retrieval, persistent sessions and memory, integrations, and alternate channels. The README documents the major workflows; sampled source confirms selected retrieval, search, provider, memory, snapshot, and entry-point behavior, but not every connection shown.

Main entry points: [`src/main/java/com/codeagent/cli/Main.java`](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/cli/Main.java) (CLI entry), [`src/main/java/com/codeagent/tool/ToolRegistry.java`](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/tool/ToolRegistry.java) (Tool registry), [`src/main/java/com/codeagent/agent/PlanExecuteAgent.java`](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/PlanExecuteAgent.java) (Plan executor), [`src/main/java/com/codeagent/agent/Agent.java`](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/Agent.java) (ReAct agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Task workflow"]
  node_cli["CLI entry<br/>[Main.java]"]
  node_router["Mode router"]
  node_react["ReAct agent<br/>[Agent.java]"]
  node_plan["Plan executor"]
  node_planner["Task planner<br/>[Planner.java]"]
  node_review["Step reviewer<br/>[StepReviewer.java]"]
  node_llm["LLM clients"]
end

subgraph group_safety["Tool safety"]
  node_toolpolicy["Turn policy"]
  node_hitl["Approval handler"]
  node_tools["Tool registry<br/>[ToolRegistry.java]"]
  node_guards["Path and command guards<br/>[PathGuard.java]"]
end

subgraph group_knowledge["Code and memory"]
  node_retrieval["Code retrieval"]
  node_search["Live code search"]
  node_index[("Retrieval index")]
  node_memory["Memory manager<br/>[MemoryManager.java]"]
end

subgraph group_state["Persistence"]
  node_history[("Session history")]
  node_planstate[("Plan checkpoints")]
  node_snapshots["Turn snapshots"]
end

subgraph group_integrations["Channels and integrations"]
  node_renderer["Terminal renderer<br/>[Renderer.java]"]
  node_mcp["MCP manager"]
  node_web["Web tools"]
  node_browser["Browser connector"]
  node_runtime["Runtime API"]
  node_wechat["WeChat channel"]
end

node_user(("User"))
node_modelservice(("LLM provider"))
node_project["Project files"]
node_approval(("Human approver"))

node_user -->|"submits task"| node_cli
node_cli -->|"routes input"| node_router
node_cli -->|"runs ReAct"| node_react
node_cli -->|"runs plan"| node_plan
node_router -->|"classifies task"| node_llm
node_router -->|"selects mode"| node_react
node_router -->|"selects mode"| node_plan
node_react -->|"requests response"| node_llm
node_plan -->|"creates task DAG"| node_planner
node_plan -->|"reviews steps"| node_review
node_plan -->|"runs workers"| node_llm
node_plan -->|"checkpoints plan"| node_planstate
node_plan -->|"records events"| node_history
node_llm -->|"sends requests"| node_modelservice
node_react -->|"dispatches tools"| node_toolpolicy
node_toolpolicy -->|"checks approval"| node_hitl
node_hitl -->|"requests decision"| node_approval
node_hitl -->|"dispatches approved"| node_tools
node_tools -->|"checks operations"| node_guards
node_guards -->|"reads or writes"| node_project
node_tools -->|"invokes search"| node_retrieval
node_tools -->|"invokes grep"| node_search
node_retrieval -->|"queries and refreshes"| node_index
node_search -->|"searches live files"| node_project
node_react -->|"uses memory"| node_memory
node_memory -.->|"classifies writes"| node_llm
node_cli -->|"manages sessions"| node_history
node_cli -->|"manages snapshots"| node_snapshots
node_cli -->|"renders interaction"| node_renderer
node_cli -->|"manages servers"| node_mcp
node_tools -->|"calls MCP tools"| node_mcp
node_tools -->|"dispatches web tools"| node_web
node_tools -->|"dispatches browser tools"| node_browser
node_runtime -->|"runs turns"| node_react
node_wechat -->|"submits messages"| node_react

click node_cli "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/cli/Main.java"
click node_router "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/ExecutionModeRouter.java"
click node_react "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/Agent.java"
click node_plan "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/PlanExecuteAgent.java"
click node_planner "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/plan/Planner.java"
click node_review "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/StepReviewer.java"
click node_llm "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/llm/LlmClientFactory.java"
click node_toolpolicy "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/tool/TurnToolPolicy.java"
click node_hitl "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/hitl/HitlToolRegistry.java"
click node_tools "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/tool/ToolRegistry.java"
click node_guards "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/policy/PathGuard.java"
click node_retrieval "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/rag/DefaultCodeRetrievalService.java"
click node_search "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/search/RipgrepCodeSearchService.java"
click node_index "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/rag/SqliteRetrievalIndex.java"
click node_memory "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/memory/MemoryManager.java"
click node_history "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/history/ConversationLedger.java"
click node_planstate "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/plan/PlanStateStore.java"
click node_snapshots "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/snapshot/SnapshotService.java"
click node_renderer "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/render/Renderer.java"
click node_mcp "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/mcp/McpServerManager.java"
click node_web "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/web/WebToolBackendRouter.java"
click node_browser "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/browser/BrowserConnector.java"
click node_runtime "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/runtime/api/RuntimeApiServer.java"
click node_wechat "https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/wechat/WechatMessageLoop.java"

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_router,node_react,node_plan,node_planner,node_review,node_llm,node_user toneBlue
class node_toolpolicy,node_hitl,node_tools,node_guards toneAmber
class node_retrieval,node_search,node_index,node_memory toneMint
class node_history,node_planstate,node_snapshots toneRose
class node_renderer,node_mcp,node_web,node_browser,node_runtime,node_wechat,node_modelservice,node_project,node_approval toneIndigo
```

## Components

### Task workflow

- [CLI entry](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/cli/Main.java): `src/main/java/com/codeagent/cli/Main.java`
- [Mode router](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/ExecutionModeRouter.java): `src/main/java/com/codeagent/agent/ExecutionModeRouter.java`
- [ReAct agent](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/Agent.java): `src/main/java/com/codeagent/agent/Agent.java`
- [Plan executor](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/PlanExecuteAgent.java): `src/main/java/com/codeagent/agent/PlanExecuteAgent.java`
- [Task planner](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/plan/Planner.java): `src/main/java/com/codeagent/plan/Planner.java`
- [Step reviewer](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/agent/StepReviewer.java): `src/main/java/com/codeagent/agent/StepReviewer.java`
- [LLM clients](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/llm/LlmClientFactory.java): `src/main/java/com/codeagent/llm/LlmClientFactory.java`

### Tool safety

- [Turn policy](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/tool/TurnToolPolicy.java): `src/main/java/com/codeagent/tool/TurnToolPolicy.java`
- [Approval handler](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/hitl/HitlToolRegistry.java): `src/main/java/com/codeagent/hitl/HitlToolRegistry.java`
- [Tool registry](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/tool/ToolRegistry.java): `src/main/java/com/codeagent/tool/ToolRegistry.java`
- [Path and command guards](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/policy/PathGuard.java): `src/main/java/com/codeagent/policy/PathGuard.java`

### Code and memory

- [Code retrieval](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/rag/DefaultCodeRetrievalService.java): `src/main/java/com/codeagent/rag/DefaultCodeRetrievalService.java`
- [Live code search](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/search/RipgrepCodeSearchService.java): `src/main/java/com/codeagent/search/RipgrepCodeSearchService.java`
- [Retrieval index](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/rag/SqliteRetrievalIndex.java): `src/main/java/com/codeagent/rag/SqliteRetrievalIndex.java`
- [Memory manager](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/memory/MemoryManager.java): `src/main/java/com/codeagent/memory/MemoryManager.java`

### Persistence

- [Session history](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/history/ConversationLedger.java): `src/main/java/com/codeagent/history/ConversationLedger.java`
- [Plan checkpoints](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/plan/PlanStateStore.java): `src/main/java/com/codeagent/plan/PlanStateStore.java`
- [Turn snapshots](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/snapshot/SnapshotService.java): `src/main/java/com/codeagent/snapshot/SnapshotService.java`

### Channels and integrations

- [Terminal renderer](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/render/Renderer.java): `src/main/java/com/codeagent/render/Renderer.java`
- [MCP manager](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/mcp/McpServerManager.java): `src/main/java/com/codeagent/mcp/McpServerManager.java`
- [Web tools](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/web/WebToolBackendRouter.java): `src/main/java/com/codeagent/web/WebToolBackendRouter.java`
- [Browser connector](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/browser/BrowserConnector.java): `src/main/java/com/codeagent/browser/BrowserConnector.java`
- [Runtime API](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/runtime/api/RuntimeApiServer.java): `src/main/java/com/codeagent/runtime/api/RuntimeApiServer.java`
- [WeChat channel](https://github.com/zgjdev/code-agent/blob/main/src/main/java/com/codeagent/wechat/WechatMessageLoop.java): `src/main/java/com/codeagent/wechat/WechatMessageLoop.java`

### Other components

- **User**
- **LLM provider**
- **Project files**
- **Human approver**

## Connections

- User → CLI entry: submits task
- CLI entry → Mode router: routes input
- CLI entry → ReAct agent: runs ReAct
- CLI entry → Plan executor: runs plan
- Mode router → LLM clients: classifies task
- Mode router → ReAct agent: selects mode
- Mode router → Plan executor: selects mode
- ReAct agent → LLM clients: requests response
- Plan executor → Task planner: creates task DAG
- Plan executor → Step reviewer: reviews steps
- Plan executor → LLM clients: runs workers
- Plan executor → Plan checkpoints: checkpoints plan
- Plan executor → Session history: records events
- LLM clients → LLM provider: sends requests
- ReAct agent → Turn policy: dispatches tools
- Turn policy → Approval handler: checks approval
- Approval handler → Human approver: requests decision
- Approval handler → Tool registry: dispatches approved
- Tool registry → Path and command guards: checks operations
- Path and command guards → Project files: reads or writes
- Tool registry → Code retrieval: invokes search
- Tool registry → Live code search: invokes grep
- Code retrieval → Retrieval index: queries and refreshes
- Live code search → Project files: searches live files
- ReAct agent → Memory manager: uses memory
- Memory manager → LLM clients: classifies writes
- CLI entry → Session history: manages sessions
- CLI entry → Turn snapshots: manages snapshots
- CLI entry → Terminal renderer: renders interaction
- CLI entry → MCP manager: manages servers
- Tool registry → MCP manager: calls MCP tools
- Tool registry → Web tools: dispatches web tools
- Tool registry → Browser connector: dispatches browser tools
- Runtime API → ReAct agent: runs turns
- WeChat channel → ReAct agent: submits messages