# autohandai/code-cli architecture

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

- Interactive diagram: https://gitdiagram.com/autohandai/code-cli
- Repository: https://github.com/autohandai/code-cli

## Overview

1. **What this repo is**
   - Autohand Code CLI is a Bun/TypeScript terminal agent that drives coding workflows end-to-end: interpret a user goal, gather context, call an LLM, execute tools, edit files, run commands, and manage approvals.
   - The architecture is centered around a long-lived session runtime rather than a simple one-shot CLI.

2. **Top-level entry and command routing**
   - `src/index.ts` is the entry point.
   - `src/commands/` contains the CLI surface: interactive session startup, one-shot prompt mode, auth, config, skills, MCP, team/squad, import/export, review, update, and operational commands like `resume`, `status`, `permissions`, and `automode`.
   - Command handlers mostly delegate into core/session/runtime services rather than doing business logic directly.

3. **Primary execution modes**
   - The repo supports multiple runtime boundaries: interactive REPL, non-interactive prompt mode, auto-mode, RPC mode, ACP mode, and pipe mode.
   - Mode adapters live under `src/modes/` and convert a transport-specific input/output shape into the shared agent runtime.
   - This is important for diagramming: the “agent core” is reused, while mode layers differ only in I/O and protocol handling.

4. **Agent runtime core**
   - `src/core/agent/` is the heart of the system.
   - It contains the turn loop, prompt building, mention resolution, tool-loop control, response classification, lifecycle orchestration, command runtime, UI runtime, dependency composition, and provider config management.
   - `src/core/agent.ts`, `src/core/actionExecutor.ts`, and related helpers form the bridge from “LLM output” to “real tool execution.”
   - The runtime is organized around repeated turns: collect context, build prompt, call provider, parse actions, execute tools, update state, and continue or stop.

5. **Tool and action layer**
   - `src/actions/` and `src/core/toolManager.ts` define the tool surface the agent can use.
   - Tools cover filesystem edits, shell commands, git, formatting, dependency changes, web access, notebook edits, project tracking, skills, and metadata.
   - The key boundary is that tools are invoked by the agent runtime but executed by specialized action modules with permission checks and output formatting.

6. **Context, memory, and session state**
   - Context is managed separately from the turn loop in `src/core/context/` and `src/contextManager.ts`.
   - `src/session/` stores session history, project/session metadata, chat logs, export logic, and workspace/session identity.
   - `src/memory/` handles longer-lived memory extraction and recall.
   - The architecture distinguishes short-term prompt context, persisted session history, and durable memory, which matters for understanding how the agent remembers across turns and across sessions.

7. **Permissions and workspace safety**
   - `src/permissions/` enforces what the agent may do, including risky shell commands, directory access, and yolo/restricted modes.
   - `src/startup/workspaceSafety.ts` and `src/startup/checks.ts` guard startup behavior and workspace assumptions.
   - This subsystem is a hard boundary between agent intent and side effects: tools are available only after permission evaluation.

8. **UI and terminal presentation**
   - `src/ui/` contains two main presentation stacks: Ink-based rich TUI and plain terminal output.
   - `src/ui/InkUIManager.ts` and `src/ui/PlainUIManager.ts` select the active renderer.
   - The Ink UI includes input handling, completion dropdowns, status line, team panel, modals, theming, and terminal region management.
   - UI is a consumer of runtime events; it does not own agent logic.

9. **Provider and model abstraction**
   - `src/providers/` implements the LLM backends: OpenAI, OpenRouter, Azure, Bedrock, DeepSeek, Ollama, llama.cpp, MLX, Vertex AI, NVIDIA, Z.ai, and others.
   - `src/providers/ProviderFactory.ts` and provider config classes normalize these into a shared provider interface.
   - This layer is the network boundary to model APIs and local inference backends; it is isolated from the rest of the agent so the runtime can switch models/providers without changing core logic.

10. **Integrations: auth, sync, telemetry, feedback, sharing**
   - `src/auth/`, `src/sync/`, `src/telemetry/`, `src/reporting/`, `src/feedback/`, and `src/share/` connect the CLI to the Autohand backend services.
   - These services handle login, settings sync, usage reporting, error/report submission, share links/session serialization, and related account lifecycle flows.
   - In an architecture diagram, these should appear as optional external service boundaries, not as part of the local agent loop.

11. **Skills, agents, MCP, and extensibility**
   - `src/skills/` manages built-in and community skill packages, parsing, security scanning, installation, and “learn” recommendations.
   - `src/agents/` and `src/core/agents/` provide sub-agent definitions, registration, and delegation.
   - `src/mcp/` supports Model Context Protocol clients and registry discovery.
   - `src/core/metaTools/` adds self-describing tools for discovering and creating reusable tools.
   - These are extension systems: they enrich the agent’s capability surface without changing the base runtime contract.

12. **Team, browser, mobile, and collaboration features**
   - `src/core/teams/` and `src/modes/teammate.ts` support local multi-agent/team workflows, including task routing and process coordination.
   - `src/browser/` wraps Chrome integration for browser-driven actions.
   - `src/mobile/` supports handoff/relay flows to mobile.
   - These are auxiliary execution channels that hang off the same agent/tool architecture but introduce their own transport or coordination layers.

13. **Project setup and onboarding**
   - `src/onboarding/` analyzes a repository and generates setup artifacts or skills.
   - `src/import/` migrates data from other coding agents and editors.
   - `src/goals/`, `src/modes/planMode/`, and `src/core/AutomodeManager.ts` support task planning, goal tracking, and autonomous iteration.
   - This is the “bootstrapping and workflow shaping” area: it prepares the agent to operate effectively in a new workspace.

14. **Cross-cutting utilities and support code**
   - `src/utils/`, `src/constants.ts`, `src/config.ts`, `src/i18n/`, and `src/features/` provide shared configuration, localization, feature flags, and low-level helpers.
   - `src/runtime/` contains bare/runtime helpers for special execution environments.
   - These are support layers that feed the higher-level subsystems rather than forming independent product boundaries.

15. **Repository shape and evidence of architecture**
   - The large `tests/` tree mirrors the runtime structure closely, which suggests the codebase is organized by capability and boundary rather than by deployment unit.
   - The presence of workflows, homebrew packaging, install scripts, and `tsup`/Bun tooling indicates this is a distributable CLI product, not a service-only backend.
   - For a diagram, the key box is a local terminal agent runtime with pluggable integrations to model providers, external services, and optional collaboration/extension channels.

Main entry points: [`src/core/agent`](https://github.com/autohandai/code-cli/tree/main/src/core/agent) (Agent core), [`src/commands`](https://github.com/autohandai/code-cli/tree/main/src/commands) (Commands), [`src/core/actionExecutor.ts`](https://github.com/autohandai/code-cli/blob/main/src/core/actionExecutor.ts) (Action exec), [`src/actions`](https://github.com/autohandai/code-cli/tree/main/src/actions) (Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_entry["CLI surface"]
  node_n_index["Main<br/>entrypoint<br/>[index.ts]"]
  node_n_commands["Commands"]
end

subgraph group_group_runtime["Agent runtime"]
  node_n_agent["Agent core<br/>turn loop"]
  node_n_action_exec["Action exec<br/>tool bridge<br/>[actionExecutor.ts]"]
  node_n_tools["Tools<br/>tool surface"]
  node_n_tool_mgr["Tool manager<br/>tool registry<br/>[toolManager.ts]"]
  node_n_context["Context<br/>prompt state"]
  node_n_session["Session state<br/>persistence"]
  node_n_memory["Memory<br/>long-term recall"]
  node_n_permissions["Permissions<br/>safety gate"]
  node_n_startup["Startup safety<br/>guard rails"]
end

subgraph group_group_io["I/O and modes"]
  node_n_modes["Modes<br/>transport adapters"]
  node_n_ui["Terminal UI<br/>presentation"]
end

subgraph group_group_integrations["Integrations"]
  node_n_providers["Providers<br/>llm backends"]
  node_n_auth_sync["Account services<br/>backend integrations"]
end

subgraph group_group_ext["Extensions"]
  node_n_skills["Skills<br/>extensibility"]
  node_n_agents["Sub-agents<br/>delegation"]
  node_n_mcp["MCP<br/>protocol client"]
  node_n_onboard["Onboarding<br/>workspace bootstrap"]
  node_n_goals["Goals<br/>planning"]
  node_n_teams["Teams<br/>coordination"]
  node_n_browser_mobile["Browser/Mobile<br/>auxiliary channels"]
end

node_n_index -->|"routes"| node_n_commands
node_n_commands -->|"starts"| node_n_modes
node_n_modes -->|"adapts to"| node_n_agent
node_n_ui -->|"renders"| node_n_agent
node_n_agent -->|"builds prompt"| node_n_context
node_n_agent -->|"calls"| node_n_providers
node_n_agent -->|"executes actions"| node_n_action_exec
node_n_action_exec -->|"invokes"| node_n_tools
node_n_tools -->|"checks"| node_n_permissions
node_n_permissions -->|"is informed by"| node_n_startup
node_n_agent -->|"persists"| node_n_session
node_n_session -->|"feeds"| node_n_memory
node_n_agent -->|"plans tools"| node_n_tool_mgr
node_n_commands -->|"manages account"| node_n_auth_sync
node_n_commands -->|"installs/manages"| node_n_skills
node_n_agent -->|"delegates"| node_n_agents
node_n_agent -->|"starts clients"| node_n_mcp
node_n_agent -->|"bootstraps"| node_n_onboard
node_n_agent -->|"tracks goals"| node_n_goals
node_n_agent -->|"coordinates"| node_n_teams
node_n_agent -->|"extends to"| node_n_browser_mobile
node_n_commands -.->|"launches"| node_n_agent

click node_n_index "https://github.com/autohandai/code-cli/blob/main/src/index.ts"
click node_n_commands "https://github.com/autohandai/code-cli/tree/main/src/commands"
click node_n_modes "https://github.com/autohandai/code-cli/tree/main/src/modes"
click node_n_ui "https://github.com/autohandai/code-cli/tree/main/src/ui"
click node_n_agent "https://github.com/autohandai/code-cli/tree/main/src/core/agent"
click node_n_action_exec "https://github.com/autohandai/code-cli/blob/main/src/core/actionExecutor.ts"
click node_n_tools "https://github.com/autohandai/code-cli/tree/main/src/actions"
click node_n_tool_mgr "https://github.com/autohandai/code-cli/blob/main/src/core/toolManager.ts"
click node_n_context "https://github.com/autohandai/code-cli/tree/main/src/core/context"
click node_n_session "https://github.com/autohandai/code-cli/tree/main/src/session"
click node_n_memory "https://github.com/autohandai/code-cli/tree/main/src/memory"
click node_n_permissions "https://github.com/autohandai/code-cli/tree/main/src/permissions"
click node_n_startup "https://github.com/autohandai/code-cli/tree/main/src/startup"
click node_n_providers "https://github.com/autohandai/code-cli/tree/main/src/providers"
click node_n_auth_sync "https://github.com/autohandai/code-cli/tree/main/src/auth"
click node_n_skills "https://github.com/autohandai/code-cli/tree/main/src/skills"
click node_n_agents "https://github.com/autohandai/code-cli/tree/main/src/core/agents"
click node_n_mcp "https://github.com/autohandai/code-cli/tree/main/src/mcp"
click node_n_onboard "https://github.com/autohandai/code-cli/tree/main/src/onboarding"
click node_n_goals "https://github.com/autohandai/code-cli/tree/main/src/goals"
click node_n_teams "https://github.com/autohandai/code-cli/tree/main/src/core/teams"
click node_n_browser_mobile "https://github.com/autohandai/code-cli/tree/main/src/browser"

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_n_index,node_n_commands toneBlue
class node_n_agent,node_n_action_exec,node_n_tools,node_n_tool_mgr,node_n_context,node_n_session,node_n_memory,node_n_permissions,node_n_startup toneAmber
class node_n_modes,node_n_ui toneMint
class node_n_providers,node_n_auth_sync toneRose
class node_n_skills,node_n_agents,node_n_mcp,node_n_onboard,node_n_goals,node_n_teams,node_n_browser_mobile toneIndigo
```

## Components

### CLI surface

Entry points and command routing for interactive and one-shot usage.

- [Main](https://github.com/autohandai/code-cli/blob/main/src/index.ts): entrypoint · Bun/TypeScript CLI entry that starts command routing and runtime setup. · `src/index.ts`
- [Commands](https://github.com/autohandai/code-cli/tree/main/src/commands): cli commands · Top-level command handlers for session control, auth, config, review, import/export, and operational commands. · `src/commands`

### Agent runtime

Core loop, context, session state, permissions, and tool execution.

- [Agent core](https://github.com/autohandai/code-cli/tree/main/src/core/agent): turn loop · The long-lived orchestration loop that builds prompts, calls providers, parses actions, and advances turns. · `src/core/agent`
- [Action exec](https://github.com/autohandai/code-cli/blob/main/src/core/actionExecutor.ts): tool bridge · Bridges model-produced actions into concrete tool and command execution. · `src/core/actionExecutor.ts`
- [Tools](https://github.com/autohandai/code-cli/tree/main/src/actions): tool surface · Filesystem, shell, git, formatting, dependency, web, notebook, metadata, and project-tracker actions. · `src/actions`
- [Tool manager](https://github.com/autohandai/code-cli/blob/main/src/core/toolManager.ts): tool registry · Defines, filters, and dispatches available tools to the agent runtime. · `src/core/toolManager.ts`
- [Context](https://github.com/autohandai/code-cli/tree/main/src/core/context): prompt state · Context collection, compaction, serialization, and prioritization for each turn. · `src/core/context`
- [Session state](https://github.com/autohandai/code-cli/tree/main/src/session): persistence · Session history, project identity, chat logs, export, and workspace/session metadata. · `src/session`
- [Memory](https://github.com/autohandai/code-cli/tree/main/src/memory): long-term recall · Persistent memory extraction and recall across turns and sessions. · `src/memory`
- [Permissions](https://github.com/autohandai/code-cli/tree/main/src/permissions): safety gate · Permission policy for shell, directory, and risky actions; includes yolo and restricted modes. · `src/permissions`
- [Startup safety](https://github.com/autohandai/code-cli/tree/main/src/startup): guard rails · Workspace checks and startup validation before the agent begins acting. · `src/startup`

### I/O and modes

Runtime adapters, terminal UI, and alternate transport modes.

- [Modes](https://github.com/autohandai/code-cli/tree/main/src/modes): transport adapters · Interactive, prompt, RPC, ACP, pipe, teammate, and plan-mode adapters that wrap the shared agent runtime. · `src/modes`
- [Terminal UI](https://github.com/autohandai/code-cli/tree/main/src/ui): presentation · Ink and plain-terminal rendering, input handling, status display, and modals. · `src/ui`

### Integrations

Model providers and external service connections.

- [Providers](https://github.com/autohandai/code-cli/tree/main/src/providers): llm backends · Provider factory and model adapters for hosted and local inference backends. · `src/providers`
- [Account services](https://github.com/autohandai/code-cli/tree/main/src/auth): backend integrations · Login, settings sync, telemetry, reporting, feedback, and sharing clients. · `src/auth`

### Extensions

Skills, agents, MCP, onboarding, goals, and collaboration features.

- [Skills](https://github.com/autohandai/code-cli/tree/main/src/skills): extensibility · Builtin/community skills, parsing, security scanning, installation, and learn recommendations. · `src/skills`
- [Sub-agents](https://github.com/autohandai/code-cli/tree/main/src/core/agents): delegation · Registry and delegation support for specialized agent roles. · `src/core/agents`
- [MCP](https://github.com/autohandai/code-cli/tree/main/src/mcp): protocol client · Model Context Protocol registry and client discovery for external tool servers. · `src/mcp`
- [Onboarding](https://github.com/autohandai/code-cli/tree/main/src/onboarding): workspace bootstrap · Repository analysis, setup wizard, and generated bootstrap artifacts for a new workspace. · `src/onboarding`
- [Goals](https://github.com/autohandai/code-cli/tree/main/src/goals): planning · Goal tracking and autonomous planning support for shaping long-running work. · `src/goals`
- [Teams](https://github.com/autohandai/code-cli/tree/main/src/core/teams): coordination · Local multi-agent coordination, task routing, and teammate process management. · `src/core/teams`
- [Browser/Mobile](https://github.com/autohandai/code-cli/tree/main/src/browser): auxiliary channels · Browser integration and mobile handoff/relay flows that reuse the same agent/tool core. · `src/browser`

## Connections

- Main → Commands: routes · Entry point dispatches CLI commands and startup flows.
- Commands → Modes: starts · Commands launch interactive, prompt, RPC, ACP, pipe, and teammate execution modes.
- Modes → Agent core: adapts to · Mode adapters feed a shared agent runtime with transport-specific I/O.
- Terminal UI → Agent core: renders · UI consumes runtime events and displays turn state, tool output, and prompts.
- Agent core → Context: builds prompt · Agent assembles turn context before calling a provider.
- Agent core → Providers: calls · Agent invokes LLM backends through the provider abstraction.
- Agent core → Action exec: executes actions · Parsed model actions are turned into real operations.
- Action exec → Tools: invokes · Action executor dispatches into specialized tool implementations.
- Tools → Permissions: checks · Tools are gated by permission policy before side effects occur.
- Permissions → Startup safety: is informed by · Startup checks establish workspace assumptions and safety constraints.
- Agent core → Session state: persists · Runtime updates session history and project metadata.
- Session state → Memory: feeds · Session activity can be distilled into longer-lived memory.
- Agent core → Tool manager: plans tools · The core runtime consults the tool registry and filtering layer.
- Commands → Account services: manages account · Auth and operational commands coordinate backend-connected services.
- Commands → Skills: installs/manages · Command surface exposes skill lifecycle operations.
- Agent core → Sub-agents: delegates · The runtime can route work to specialized sub-agents.
- Agent core → MCP: starts clients · Agent startup can connect to MCP servers and registry state.
- Agent core → Onboarding: bootstraps · Onboarding prepares a repository for effective agent operation.
- Agent core → Goals: tracks goals · Planning and autonomous iteration are managed alongside the turn loop.
- Agent core → Teams: coordinates · Team workflows introduce local multi-agent task routing.
- Agent core → Browser/Mobile: extends to · Auxiliary channels reuse the agent/tool architecture for browser and mobile flows.
- Commands → Agent core: launches · Most commands hand off into the central runtime rather than implement business logic themselves.