How autohandai/code-cli works
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: agent Agent core · commands Commands · actionExecutor.ts Action exec · actions Tools
Components 22
CLI surface
Entry points and command routing for interactive and one-shot usage.
Agent runtime
Core loop, context, session state, permissions, and tool execution.
- Agent core · The long-lived orchestration loop that builds prompts, calls providers, parses actions, and advances turns.
src/core/agent - Action exec · Bridges model-produced actions into concrete tool and command execution.
src/core/actionExecutor.ts - Tools · Filesystem, shell, git, formatting, dependency, web, notebook, metadata, and project-tracker actions.
src/actions - Tool manager · Defines, filters, and dispatches available tools to the agent runtime.
src/core/toolManager.ts - Context · Context collection, compaction, serialization, and prioritization for each turn.
src/core/context - Session state · Session history, project identity, chat logs, export, and workspace/session metadata.
src/session - Memory · Persistent memory extraction and recall across turns and sessions.
src/memory - Permissions · Permission policy for shell, directory, and risky actions; includes yolo and restricted modes.
src/permissions - Startup safety · 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 · Interactive, prompt, RPC, ACP, pipe, teammate, and plan-mode adapters that wrap the shared agent runtime.
src/modes - Terminal UI · Ink and plain-terminal rendering, input handling, status display, and modals.
src/ui
Integrations
Model providers and external service connections.
- Providers · Provider factory and model adapters for hosted and local inference backends.
src/providers - Account services · Login, settings sync, telemetry, reporting, feedback, and sharing clients.
src/auth
Extensions
Skills, agents, MCP, onboarding, goals, and collaboration features.
- Skills · Builtin/community skills, parsing, security scanning, installation, and learn recommendations.
src/skills - Sub-agents · Registry and delegation support for specialized agent roles.
src/core/agents - MCP · Model Context Protocol registry and client discovery for external tool servers.
src/mcp - Onboarding · Repository analysis, setup wizard, and generated bootstrap artifacts for a new workspace.
src/onboarding - Goals · Goal tracking and autonomous planning support for shaping long-running work.
src/goals - Teams · Local multi-agent coordination, task routing, and teammate process management.
src/core/teams - Browser/Mobile · Browser integration and mobile handoff/relay flows that reuse the same agent/tool core.
src/browser
Connections 22
- 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.