Core Agent Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Core Agent Architecture of the Code-CLI project is built around the AutohandAgent, an autonomous software engineering entity designed for terminal-based project interaction. It utilizes a ReAct (Reason + Act) pattern to process user instructions, enabling it to reason about tasks, execute tool-based actions, and interpret results within a continuous loop. The architecture is highly modular, integrating specialized systems for session management, tool execution, memory, and multi-agent delegation.
Central to this architecture is the ability to maintain context across complex tasks through a sophisticated conversation management system and project-specific knowledge retrieval. It supports both a "Diagnostic" mode for read-only analysis and an "Implementation" mode for active file modifications, governed by safety protocols and permission management to ensure secure code generation and execution.
Sources: src/core/agent.ts:100-250, prd/historical-retrieval.md:1-20
Main Agent Components
The AutohandAgent acts as the primary orchestrator, managing several critical sub-systems to facilitate its autonomous operations.
| Component | Responsibility |
|---|---|
ConversationManager | Maintains message history and context window usage. |
ToolManager | Manages tool definitions, registration, and filtering based on client context. |
ActionExecutor | Handles the physical execution of tools, including file I/O and shell commands. |
AgentDelegator | Manages sub-agent spawning and parallel task execution. |
MemoryManager | Handles persistent fact storage at the user and project levels. |
ProjectManager | Tracks project-specific metadata, success patterns, and failures. |
PermissionManager | Governs authorization for destructive or risky tool operations. |
Sources: src/core/agent.ts:114-150, src/core/toolManager.ts:600-650
The ReAct Loop and Execution Flow
The core logic of the agent resides in the runReactLoop, which implements the Reason + Act pattern. This loop continues until the task is complete or a maximum iteration limit (defaulting to 100) is reached.
Logical Process Flow
The following diagram illustrates the iterative lifecycle of a single user instruction within the agent.
The agent first detects intent (diagnostic vs implementation) and prepares the environment. During the loop, it reasons about the next step, optionally calls multiple tools in parallel or sequence, and updates its internal state based on tool outputs.
Sources: src/core/agent.ts:983-1100, src/core/agent.ts:1105-1200
Multi-Agent Delegation
The architecture supports a hierarchical model where the Lead Agent can delegate specialized tasks to sub-agents. This is managed via the AgentDelegator and defined through the AgentRegistry.
Sub-agents are loaded from ~/.autohand-cli/agents/ and can be defined as JSON or Markdown files. They operate with a fresh context and restricted toolsets to ensure safety and token efficiency.
Sources: prd/sub_agents_architecture.md:25-70, src/core/agents/AgentRegistry.ts:35-60
Tool Management and Security
The ToolManager and ActionExecutor form the boundary between the agent's reasoning and the host system. Tools are categorized into groups such as File Operations, Git Operations, and System Commands.
Security and Permissions
Risky operations (e.g., run_command, delete_path, git_reset) are subject to the PermissionManager.
- Whitelist/Blacklist: Pre-defined rules in
config.jsoncan automatically allow or block specific command patterns. - Interactive Approval: If a tool is marked as
requiresApproval, the agent prompts the user via a unified confirmation UI. - Hook-based Decisioning: Pre-tool hooks can programmatically decide to allow, deny, or block an action before it reaches the user.
Sources: src/core/toolManager.ts:140-160, src/core/actionExecutor.ts:130-160, src/core/agent.ts:180-210
Tool Definition Schema
Tools are defined with JSON Schema for parameters, allowing LLMs to accurately generate call arguments.
export interface ToolDefinition {
name: AgentAction['type'];
description: string;
parameters?: ToolParameters;
requiresApproval?: boolean;
approvalMessage?: string;
}
Sources: src/core/toolManager.ts:47-53
Project Intelligence and Historical Retrieval
The architecture includes a "Historical Retrieval System" that enables the agent to learn from past interactions within a specific project. This prevents the repetition of "Anti-Patterns" (failed attempts) and promotes the reuse of "Best Practices" (successful patterns).
Project Metadata Storage
Project knowledge is synthesized into several files managed by the ProjectManager:
index.json: Project metadata and detected tech stack.failures.jsonl: Log of failed tool calls with errors and context.successes.jsonl: Log of successful operations and verified patterns.knowledge.json: Synthesized insights injected into the agent's system prompt at startup.
Sources: prd/historical-retrieval.md:80-130, src/session/ProjectManager.ts:50-100
Automated Documentation
The AgentsMdUpdater automatically maintains an AGENTS.md file in the project root. This file serves as a persistent "Project Autopilot" guide, documenting the detected tech stack, common build/test commands, and conventions learned over multiple sessions.
Sources: src/core/AgentsMdUpdater.ts:25-60, tests/agentsMdUpdater.spec.ts:30-60
Conclusion
The Core Agent Architecture represents a multi-layered approach to autonomous coding. By combining a robust ReAct execution loop with specialized delegation capabilities and project-specific historical memory, the system provides a persistent and evolving engineering assistant. The integration of strict permission controls and automated quality pipelines ensures that the agent's autonomy is balanced with operational safety and code reliability.
Sources: src/core/agent.ts:1200-1250, prd/sub_agents_architecture.md:120-140