Introduction & Installation
Relevant source files
The following files were used as context for generating this wiki page:
Autohand Code CLI is an autonomous, LLM-powered coding agent designed to operate directly within a developer's terminal. It utilizes the ReAct (Reason + Act) pattern to analyze codebases, plan complex multi-step modifications, and execute them across an entire project. Unlike traditional chat-based assistants, Autohand integrates deeply with local development environments, providing a suite of over 40 tools for file manipulation, Git operations, and dependency management.
Sources: README.md:1-12
The system is designed for high-velocity development, allowing users to issue natural language instructions while maintaining full control through an interactive loop or non-interactive command modes. It supports extensible "skills" and maintains persistent project knowledge to prevent repeated failures and leverage successful patterns from previous sessions.
Sources: README.md:14-25, src/core/agent.ts:182-200
Installation & Setup
Autohand requires Bun (≥1.0) and Git for its core operations. While it can function without it, ripgrep is recommended for enhanced search performance.
Sources: README.md:38-42
Installation Methods
| Method | Command |
|---|---|
| Quick Install | curl -fsSL https://autohand.ai/install.sh | bash |
| Manual (Clone/Build) | git clone https://github.com/autohandai/cli.git && cd cli && bun install && bun run build |
| Global Access | bun add -g . (within the cloned directory) |
Sources: README.md:27-36
Environment Initialization
Upon first run or through the /init command, the agent sets up its workspace environment. This involves creating an AGENTS.md file, which serves as a template for project-specific instructions, framework commands, and constraints.
# Create AGENTS.md template
autohand /init
Sources: src/core/agent.ts:1049-1057, README.md:139
The AgentsMdUpdater class handles automatic synchronization of discovered project patterns (e.g., tech stack, test commands) into this file.
Sources: src/core/AgentsMdUpdater.ts:25-45
System Architecture Overview
The Autohand CLI architecture revolves around the AutohandAgent class, which orchestrates various managers to handle conversation history, tool execution, and session state.
Core Component Interaction
The following diagram illustrates how the AutohandAgent interacts with internal managers and external LLM providers to process a user instruction:
Key Architectual Components
| Component | Responsibility |
|---|---|
| AutohandAgent | Main orchestrator managing the ReAct loop, UI state, and session lifecycle. |
| ActionExecutor | Executes technical actions (read/write/git/shell) and handles security/permissions. |
| ProjectManager | Maintains project-specific history, success/failure logs, and synthesized knowledge. |
| ToolManager | Defines tool schemas and filters available tools based on client context (CLI vs Restricted). |
| SkillsRegistry | Manages modular instruction sets ("skills") that extend agent capabilities. |
Sources: src/core/agent.ts:102-140, src/core/actionExecutor.ts:100-120, src/core/toolManager.ts:470-485
Getting Started: Operational Modes
Autohand supports multiple modes of operation tailored for interactive development or automated workflows.
Interactive Mode
Launched by running autohand without arguments. It provides a full REPL experience with:
- Slash Commands: Specialized operations like
/modelor/resume. - At-Mentions: File path autocompletion using the
@prefix. - Persistent Input: A mechanism to queue messages while the agent is currently working.
Sources: README.md:52-65, src/core/agent.ts:285-300
Command Mode
For single-turn tasks or CI/CD integration, use the --prompt (or -p) flag.
autohand -p "fix the TypeScript errors in src/core" --yes --auto-commit
Sources: README.md:67-85, src/core/agent.ts:316-335
Project Analysis & "Auto-Skill"
A core feature of the installation and setup phase is project analysis. The ProjectAnalyzer scans the workspace root for package.json, requirements.txt, Cargo.toml, and other markers to detect:
- Languages: TypeScript, Python, Rust, Go, etc.
- Frameworks: React, Next.js, Express, FastAPI, etc.
- Patterns: Testing, CI/CD, monorepos, and database migrations.
Sources: src/skills/autoSkill.ts:125-150, src/skills/autoSkill.ts:280-305
The runAutoSkillGeneration function uses this analysis to generate specialized .autohand/skills tailored to the project's specific tech stack.
Sources: src/skills/autoSkill.ts:430-475
Conclusion
Autohand Code CLI provides a robust, tool-rich environment for autonomous software engineering. By combining deep filesystem access through the ActionExecutor with project-specific memory managed by the ProjectManager, it offers a persistent and evolving assistance experience. Installation is streamlined for modern developer environments, requiring only Bun and Git to begin transforming natural language into functional code.
Sources: src/core/agent.ts:200-220, README.md:235-245