Follow us on X | Join Discord

Docs: English | 日本語 | 简体中文 | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Polski | Русский | Português (Brasil) | Türkçe | Čeština | Magyar | हिन्दी | Bahasa Indonesia

A fast, self-improving terminal-native AI coding agent for planning, reflecting, remembering, editing, testing, and automating work across your codebase.

Autohand Code CLI is a fast, terminal-native AI coding agent that lives where you already work. It reads project context, plans changes, edits files, runs tools, and asks for approval before risky operations.

The interface is built for focused interactive sessions: minimal chrome, smooth Ink rendering, file mentions, slash commands, skills, permissions, provider switching, and session history all available from one prompt.

Install it, run autohand, and describe the outcome you want in natural language. Use Autohand Code CLI locally, with your editor, or in CI/CD to automate repetitive engineering work without giving up control.

• Terminal-Native Agent: Understands your codebase and executes approved changes from the CLI
• Planning + Tools: Combines reasoning, file edits, shell commands, and web context in one loop
• Interactive REPL: Smooth terminal experience with file mentions, slash commands, and keyboard shortcuts
• Modular Skills: Extends workflows with specialized instruction packages
• Multi-Provider Support: Works with OpenRouter, LLMGateway, OpenAI, AWS Bedrock, DeepSeek, Azure Foundry Models, Z.ai, and local models
• Git Integration: Full version control support with automatic commits
• Cross-Platform: Works on macOS, Linux, and Windows

• No Context Switching: Stay in your terminal, no copy-paste needed
• Intelligent Planning: Understands your codebase before making changes
• Safe Execution: Prompts before risky operations unless you choose a different permission mode
• Extensible: Add skills, hooks, and provider configuration as your workflow grows
• Fast: Optimized for responsive interactive sessions and efficient tool execution

curl -fsSL https://autohand.ai/install.sh | bash

brew install autohandai/code/autohand-code

The fully qualified command installs and trusts only the Autohand formula. Every supported installation exposes the same CLI as autohand, autohand-code, agent, and the short ah; autohand remains the canonical name. Because agent is a generic name other AI CLIs also use, every Autohand installer (Unix script, Windows script, and Homebrew) scans every writable directory on your PATH and replaces any existing agent command it finds — not only the one in Autohand's own install directory — so agent reliably resolves to Autohand. This happens automatically with no prompt; if another tool's agent command stops working after installing Autohand, this is why.

The npm package, release archives, Unix/Windows installers, and Homebrew formula also install ahtraces, the managed local trace-monitor companion. npm downloads the matching release binary during postinstall and verifies its SHA-256 checksum; --ignore-scripts or AUTOHAND_SKIP_AHTRACES_INSTALL=1 intentionally omits it. Its private source is built independently from a pinned revision during the Autohand release. It remains idle until the user answers the trace-consent step. New users see that step in onboarding; existing users see it once after upgrading to the consent-aware release. Cloud trace ingestion does not count against Autohand API usage.

Use autohand --traces-on, autohand traces on, or ahtraces on to enable local monitoring with metadata sync. Use the matching --traces-off, autohand traces off, or ahtraces off control to stop it. Uploaded traces are visible at https://console.autohand.ai/traces and can be deleted from the Console Account page. See the agent traces setup guide for consent modes, supported agents, Team use, and deletion controls.

The Unix and Windows installers and npm postinstall also install Autohand Computer Use, built independently in the public Autohand computer-use repository from the MIT-licensed Cua engine. Autohand reuses an existing compatible engine and connects it as a runtime-only MCP server. On macOS, Privacy & Security lists Autohand Computer Use, and the installer opens its Accessibility and Screen Recording requests. Ask “open my browser” or “go to Spotify and play X” to activate the built-in computer-control skill. Run autohand computer status, autohand computer install, or autohand computer doctor to inspect, repair, or verify desktop permissions. See the native computer control guide.

# Clone and build
git clone https://github.com/autohandai/code-cli.git
cd code-cli
bun install
bun run build

# Install globally
bun add -g .

• Bun ≥1.0 (curl -fsSL https://bun.sh/install | bash)
• Git (for version control features)
• ripgrep (optional, for faster search)

Completion scripts are generated from the current CLI command tree, including nested commands and options, and register all three executable names.

# Zsh: enable now, then add the same line to ~/.zshrc
source <(autohand completion zsh)

# Bash: enable now, then add the same line to ~/.bashrc
source <(autohand completion bash)

# Fish: install persistently
autohand completion fish > ~/.config/fish/completions/autohand.fish

After loading the script, type an executable name followed by a partial command or option and press Tab, for example agent --off<Tab> or autohand exp<Tab>.

# Interactive mode - start a coding session
autohand

# Command mode - run a single instruction
autohand -p "add a dark mode toggle to the settings page"

# With auto-confirmation
autohand -p "fix the TypeScript errors" -y

# Auto-commit changes after task completion
autohand -p "refactor the auth module" -c

Use Autohand Code CLI directly in your favorite editor:

Install the extension from the VS Code Marketplace or via command line:

code --install-extension AutohandAI.vscode-autohand

Run Autohand Code CLI as a native ACP External Agent. See the ACP integration guide for Zed, JetBrains IDEs, JetBrains Air, and other ACP-compatible development environments.

Developers can also build on the same CLI-backed agent runtime through the Code Agent SDK. Use it when you want Autohand Code CLI capabilities inside your own tools, services, workflows, or editor integrations.

The Agent SDK is available in multiple beta language packages. Use the same CLI-backed SDK model from another programming language:

• TypeScript - this package, with Agent, Run, streaming, and JSON helpers.
• Go - idiomatic Go package with context.Context, typed events, and channel-based streaming.
• Python - async Python package with async for event streams and typed Pydantic models.
• Java - Java 21 records, sealed events, and virtual-thread-ready APIs.
• Swift - SwiftPM package with Agent, Runner, async streams, tools, hooks, and permissions.

Launch without arguments for a full REPL experience:

autohand

Features:

• Type / for slash command suggestions
• Type @ for file autocomplete (e.g., @src/index.ts)
• Type $ for skill autocomplete (e.g., $frontend-design)
• Type ! to run terminal commands (e.g., ! git status, ! ls -la)
• Large command results retain the first and last portions of each output stream, up to 1,048,576 characters, with an omission marker. The same limit applies to individual displayed lines; redirect output to a file when you need the complete result.
• Smart Paste: Paste any amount of code (5+ lines shows compact indicator, full content sent to LLM)
• Press ESC to cancel in-flight requests
• Press Ctrl+C twice to exit
• Press Shift+Tab to cycle edit, plan, YOLO, and auto modes
• Press ? to toggle keyboard shortcuts panel
• Use /goals to open the goals view; press Ctrl+G (Cmd+G on macOS) to toggle it open or closed
• Press Up to recall older typed messages and Down for newer messages or your unfinished draft. In multiline drafts, Up moves the cursor until it reaches the first visual row.
• Use /whatityped to select a message from any working directory and load it into the composer for editing. The latest 200 submissions are saved locally in ~/.autohand/typed-message-history.json (or your AUTOHAND_HOME), starting when you use this feature.
• Press Enter or Shift+Enter for newlines in multi-line input

Run single instructions for CI/CD, scripts, or quick tasks:

# Basic usage
autohand --prompt "add tests for the user service"

# Short form
autohand -p "fix linting errors"

# With options
autohand -p "update dependencies" --yes --auto-commit

# Dry run (preview changes without applying)
autohand -p "refactor database queries" --dry-run

# Stream lifecycle events as JSON Lines
autohand -p "review this diff" --output-format stream-json

# Equivalent stream alias, or write only the final result object
autohand -p "review this diff" --json stream
autohand -p "review this diff" --json local

--output-format stream-json and --json stream write one JSON object per agent event to stdout. Events include thinking, tool_start, tool_end, file_modified, result, and error. --json local suppresses intermediate events and writes exactly one final result or error object to stdout.

Native computer control commands:

Skills are modular instruction packages that extend Autohand Code CLI with specialized workflows. They work like on-demand AGENTS.md files for specific tasks.

# List available skills
/skills

# Activate a skill
/skills use changelog-generator

# Create a new skill interactively
/skills new

# Auto-generate project-specific skills
autohand --auto-skill

Analyze your project and generate tailored skills automatically:

$ autohand --auto-skill
Analyzing project structure...
Detected: typescript, react, nextjs, testing
Platform: darwin
Generating skills...
  ✓ nextjs-component-creator
  ✓ typescript-test-generator
  ✓ changelog-generator

✓ Generated 3 skills in .autohand/skills

Skills are discovered from:

• ~/.autohand/skills/ - User-level skills
• <project>/.autohand/skills/ - Project-level skills
• skilled.autohand.ai - Community skill registry
• Compatible with Codex and Claude skill formats

See Agent Skills Documentation for creating custom skills.

Persistent goal data remains in the workspace across conversations, but execution does not silently transfer work owned by another live session. Bare /goal inspects prior state and starts the next queued item when this session has no goal and no live peer owns the backlog. Use /goal resume to resume this session's paused goal or explicitly start queued work.

Published CLI announcements appear as a cached launch block and a persistent line above the composer. Press Ctrl+X to dismiss the visible item, or use /whatsnew to review and dismiss all active announcements. Dismissal is per announcement; --offline keeps cached announcements visible without making announcement requests.

/go --steer and /handoff session --steer keep the paired iOS app updated with permission/change requests and read-only GitHub delivery metadata. While a relay is active, the CLI publishes the current pull request, checks, and GitHub deployment records when available; missing gh authentication does not stop the coding session. On macOS, steer handoff also keeps the computer awake with a CLI-owned caffeinate process; the paired phone can turn that assertion on or off, and it is always released when the relay stops or the CLI exits. Ready pull requests can be squash merged from the paired phone after a second explicit confirmation. The relay re-fetches the current PR and rejects the action unless its reviewed number and head branch still match, it remains open and mergeable, and all reported checks pass. Only then does it run the fixed gh pr merge <number> --squash command and publish the result to mobile. For mobile-originated completed work, explicitly referenced PNG/JPEG, MP4, and text/JSON artifacts inside the active workspace can be uploaded to the authenticated mobile session. Real-path confinement prevents symlink escapes, and uploads are capped at 12 files and 15 MB per file.

The paired app builds its composer command suggestions from the CLI's live catalog, so canonical command names, descriptions, and availability come from the current session instead of a hard-coded phone list. Only commands marked available can run. Availability updates with the session: /goal is runnable only when goals are enabled, while /plan status returns the current plan-mode details to the phone.

Phone commands and prompts share the same ordered work stream as prompts typed in the terminal composer. Autohand runs them one at a time in submission order, including when the phone and terminal both submit while another turn is active.

When a mobile task explicitly resumes history, it must name an exact session that is stored locally for the current workspace. Autohand restores that session before running the prompt; a missing or different-workspace target fails the task instead of silently starting fresh or continuing another session. The phone remains paired to the existing live CLI connection while the resumed session is identified in task progress and results.

Enable the experimental goals feature, then open the live view:

/experiments enable slash_goal
/goals view

/goals and /goal view also open this view. It groups the current goal, queued goals, and goals from other sessions into short, single-line previews with statuses. The full objectives remain available for editing. Other-session rows are informational; editing applies to this session's goal and the shared queue.

The footer shows Ctrl+G close beside the editing controls. Closing the view hides the panel; use /goals pause to pause the current goal. All goal subcommands accept either /goal or /goals. Bare /goals opens the view, while bare /goal can start the goal writer or queued work, depending on the current session state.

See goal commands and examples and goals and auto mode for more details.

Autohand Code CLI includes 40+ tools for autonomous coding:

read_file, write_file, append_file, apply_patch, search, search_replace, semantic_search, list_tree, create_directory, delete_path, rename_path, copy_path

git_status, git_diff, git_commit, git_add, git_branch, git_switch, git_merge, git_rebase, git_cherry_pick, git_stash, git_fetch, git_pull, git_push, auto_commit

run_command, custom_command, add_dependency, remove_dependency

plan, todo_write, save_memory, recall_memory

tools_registry - List all available tools with descriptions. tool_search - Search tools by capability, name, or description. create_meta_tool - Create reusable user- or project-scoped shell-backed tools that load in future sessions.

Package reusable tools and agents in a strict declarative manifest, then validate and install them without changing CLI source:

autohand extensions validate ./examples/extensions/autohand.code-health
autohand extensions install ./examples/extensions/autohand.code-health
autohand extensions list

Declarative extensions contribute tools, focused agents, and portable Agent Skills without package-code execution. Reviewed runtime extensions installed with --trust can also register slash commands, Ink UI, status/help segments, keybindings, CLI flags, hooks, providers, and permission policy. Mention $extension-builder to create, extend, or adapt an extension from a description or Pi package. See the extension-builder guide and terminal demo, Using extensions, Extension authoring, and the seven working examples.

notebook_cell_edit - Edit Jupyter notebook cells (code/markdown insert, delete, replace).

team_create, team_list, task_create, task_list, task_update, task_set_owner - Multi-agent team coordination.

spawn_subagent - Delegate tasks to focused agents to keep the main context window clean.

use_skill, sleep - Activate skills or pause execution. screenshot, navigate, get_page_content, click, type_input, select_dropdown - Browser integration.

Create ~/.autohand/config.json or use config.toml, config.yaml, or config.yml:

{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "sk-or-...",
    "model": "your-modelcard-id-here"
  },
  "workspace": {
    "defaultRoot": ".",
    "allowDangerousOps": false
  },
  "ui": {
    "theme": "aurora",
    "autoConfirm": false
  }
}

Sessions are auto-saved to ~/.autohand/sessions/:

# Pick a session from the current project
autohand resume

# Resume the most recently active session in this project
autohand resume --last

# Browse all projects, or resume the most recently active session across them
autohand resume --all
autohand resume --last --all

# Resume by full ID, unique ID prefix, or saved session directory/file
autohand resume <reference>

# Select sessions for a different workspace
autohand resume --path /path/to/project

# Or in interactive mode
/resume

The picker supports arrow keys, Enter, and page navigation for older sessions. Escape or Ctrl+C cancels without starting a session. --last uses the last activity time, falling back to creation time for older session metadata. Without a terminal, provide --last or an explicit reference. References cannot be combined with --last or --all; -c remains auto-commit.

Autohand Code CLI supports Entire for session checkpointing. Entire captures your coding sessions -- prompts, file changes, and token usage -- as git-backed checkpoints that you can rewind to, review, and share.

# Install hooks in this repository
entire enable --agent autohand-code

# Check status
entire status

# Remove hooks
entire disable --agent autohand-code

Once enabled, Entire works automatically through the Autohand Code CLI hooks system. No changes to your workflow are needed. See the Entire Integration Guide for setup details and troubleshooting.

Start with autohand --plan to investigate and plan before editing. For a one-shot plan, use autohand --plan --prompt "Plan a refactor of the authentication module". The first model request receives the plan instructions and read-only tools; mutating tool calls are blocked.

Interactive plans require an explicit acceptance decision, including with --yes or --unrestricted. One-shot and unattended plans remain pending review. Shift+Tab and /plan on|off still change the interaction mode. --plan cannot be combined with --yolo, --auto-mode, or --auto-commit.

Autohand Code CLI includes a permission system for sensitive operations:

• Interactive (default): Prompts for confirmation on risky actions
• Unrestricted (--unrestricted): No approval prompts
• Restricted (--restricted): Denies all dangerous operations

Configure granular permissions in ~/.autohand/config.toml/yaml/json:

{
  "permissions": {
    "whitelist": ["run_command:npm *", "run_command:bun *"],
    "blacklist": ["run_command:rm -rf *", "run_command:sudo *"]
  }
}

• macOS
• Linux
• Windows

Product telemetry and full session sync are disabled by default. They are separate choices: session sync includes conversation content and requires both an authenticated account and its own explicit switch.

{
  "telemetry": {
    "enabled": false,
    "enableSessionSync": false
  }
}

The ordinary version check and automatic diagnostic reports are separate data paths with separate controls. Error strings can contain sensitive text even after path sanitization. See Data collection, telemetry, and agent traces for exact fields, defaults, endpoints, and limits.

Autohand can normalize local session records from 19 coding-agent harnesses into an aggregate-only Work Map. Local collection, cloud metadata sync, and cloud full content are independent consent levels; all are off by default except Work Map availability after local collection has been enabled.

# Choose local-only or cloud collection during onboarding or in /settings
autohand --traces-on
autohand discovery map --since 30d
autohand discovery map --agent autohand,codex --json
ahtraces status
ahtraces off

The map includes session/tool/workflow/outcome and verification aggregates. It excludes prompts, responses, reasoning, commands, source code, paths, repository identities, session IDs, and credentials. See Repository discovery for command options.

The backend API is available at: https://github.com/autohandai/api

# Install dependencies
bun install

# Development mode
bun run dev

# Build
bun run build

# Type check
bun run typecheck

# Run tests
bun run test

FROM oven/bun:1
WORKDIR /app
COPY . .
RUN bun install && bun run build
CMD ["node", "dist/index.js"]

docker build -t autohand .
docker run -it autohand

• Playbook - 20 use cases for the software development lifecycle
• Features - Complete feature and experiment list
• Agent Skills - Skills system guide
• Autohand Computer Use - Install native computer control and operate local apps conversationally
• ACP integration guide - Use the native ACP agent in compatible editors, IDEs, and ADEs
• Extending Autohand Code CLI - Build tools, skills, hooks, MCP servers, and integrations
• Autohand Code extensions - Validate, install, inspect, and manage declarative extension packages
• Extension authoring - Package tools and agents for the public extension ecosystem
• Model catalog updates - Automatic refresh, offline fallback, Pi-compatible publication, and admin PR workflow
• Local peer communication - Colon composer, exact recipients, inbox and replies
• Build resource coordination - Controllers, grants and process ownership
• Peer protocol and runtime - Security, storage, worker adapters and limits
• Two-session peer lab - Verify the complete terminal workflow
• Configuration Reference - All config options
  • English
  • 日本語
  • 简体中文
  • 繁體中文
  • 한국어
  • Deutsch
  • Español
  • Français
  • Italiano
  • Polski
  • Русский
  • Português (Brasil)
  • Türkçe
  • Čeština
  • Magyar
  • हिन्दी
  • Bahasa Indonesia
• Entire Integration - Session checkpointing with Entire

We welcome contributions! Please read our Contributing Guide for details on how to get involved.

Installation fails: Make sure you have Bun installed and up to date.

Permission denied: Check your file permissions and try running with appropriate privileges.

Model not working: Verify your API key and model configuration in ~/.autohand/config.toml/yaml/json.

• Join our Discord community
• Check the documentation
• Open an issue on GitHub

• Discord: https://discord.gg/ZM3TCtwCwG
• GitHub: https://github.com/autohandai/code-cli
• Website: https://autohand.ai
• X: @autohandai

Autohand Code CLI is designed with security in mind:

• User-Controlled Execution: Risky operations require approval unless you opt into a broader permission mode
• Permission System: Fine-grained control over what operations are allowed
• Local Processing: Your code never leaves your machine unless you choose
• Open Source: Transparent code that can be audited

Apache License 2.0 - Free for individuals, non-profits, educational institutions, open source projects, and companies with ARR under $5M. See LICENSE and COMMERCIAL.md for details.

• Website: https://autohand.ai
• CLI Install: https://autohand.ai/cli/
• GitHub: https://github.com/autohandai/code-cli
• API Backend: https://github.com/autohandai/api
• Discord: https://discord.gg/ZM3TCtwCwG

• Enhanced AI Models: Support for newer models and improved reasoning
• Plugin System: Easier way to extend Autohand Code CLI with custom functionality
• Team Collaboration: Features for team-based development workflows
• Advanced Testing: Automated test generation and execution
• Code Review: AI-powered code review and quality checks

• Improving response times and accuracy
• Expanding skill library with more specialized workflows
• Enhancing the interactive experience with better UI/UX
• Adding more provider integrations
• Strengthening security and permission systems

Ready to get started? Run autohand in your terminal and start a coding session.