How nick211908/coding-agent works
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.py Agent · __init__.py Builtins · registry.py Registry · main.py main.py
Components 26
Core runtime
Agent loop, session state, context assembly, persistence, and event flow.
- main.py · Process entrypoint that wires config, agent runtime, UI, and persistence.
main.py - Agent · Coordinates model turns, tool calls, and state updates.
agent/agent.py - Session · Per-run conversation and execution state.
agent/session.py - Events · Execution events emitted for UI, hooks, and logging.
agent/events.py - Persistence · Saves and restores agent session state across runs.
agent/persistence.py - Context · Builds bounded model context from session state and history.
context/manager.py - Compaction · Summarizes or compresses context when it grows too large.
context/compaction.py - Loop detector · Detects repetitive tool or reasoning loops.
context/loop_detector.py
Tools
Local tools, external MCP tools, and subagent delegation.
- Registry · Central catalog and schema exporter for available tools.
tools/registry.py - Discovery · Auto-discovers tool implementations from the codebase.
tools/discovery.py - Builtins · First-party filesystem, shell, search, edit, memory, and todo tools.
tools/builtin/__init__.py - MCP manager · Manages connections to external MCP tool servers.
tools/mcp/mcp_manager.py - MCP client · Talks to a remote MCP server.
tools/mcp/client.py - MCP tool · Wraps MCP-exposed capabilities into the internal tool interface.
tools/mcp/mcp_tool.py - Subagents · Spawns or coordinates subordinate agent runs.
tools/subagents.py
Interfaces
Model client, safety, UI, and extensibility seams.
- LLM client · Provider abstraction for prompt, tool schema, and structured replies.
client/llm_client.py - Response · Parses provider output into internal actions or tool calls.
client/response.py - Approval · Human confirmation boundary for risky or destructive actions.
safety/approval.py - Hooks · Lifecycle interception for logging, telemetry, and policy.
hooks/hook_system.py - TUI · Terminal presentation layer over the agent event stream.
ui/tui.py
Support
Configuration, prompts, and shared utilities.
- Config · Loads runtime settings for models, tools, approvals, and UI.
config/config.py - Loader · Reads and assembles configuration from files and environment.
config/loader.py - Prompt · Defines the agent’s system instructions and operating policy.
prompts/system.py - Paths · Cross-platform path handling helpers.
utils/paths.py - Errors · Shared error normalization and handling helpers.
utils/errors.py - Text · Shared text normalization helpers.
utils/text.py
Connections 29
- 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.