Autohand Code CLI

August 13, 2026 · View on GitHub

Bun Discord

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.

Autohand Code CLI running in the terminal

Features

  • 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

Why Autohand Code CLI?

  • 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

Installation

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

Homebrew

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, and agent; 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.

Manual Installation

# 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 .

Requirements

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

Shell Completion

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>.

Quick Start

# 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

Editor Extensions

Use Autohand Code CLI directly in your favorite editor:

VS Code

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

code --install-extension AutohandAI.vscode-autohand

Zed Editor

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.

Code Agent SDK

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.

Usage Modes

Interactive Mode

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)
  • 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
  • Press Enter or Shift+Enter for newlines in multi-line input

Command Mode (Non-Interactive)

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.

CLI Options

OptionShortDescription
--prompt <text>-pRun a single instruction in command mode
--output-format stream-jsonStream command lifecycle events as JSON Lines
--json <stream|local>Stream JSON Lines or write only the final JSON result (--json defaults to stream)
--yes-yAuto-confirm risky actions
--auto-commit-cAuto-commit changes after completing tasks
--dry-runPreview actions without applying mutations
--debug-dEnable debug output (verbose logging)
--model <model>Override the configured LLM model
--path <path>Workspace path to operate in
--auto-skillAuto-generate skills based on project analysis
--unrestrictedRun without approval prompts (use with caution)
--restrictedDeny all dangerous operations automatically
--no-idle-logoutDisable authenticated idle logout for long-running agent sessions
--config <path>Path to config file
--temperature <value>Sampling temperature for LLM
--thinking [level]Set thinking/reasoning depth (none, normal, extended)
--learnRun skill advisor non-interactively
--learn-updateRe-analyze project and regenerate skills
--skill-install [name]Install a community skill
--projectInstall skill to project level (with --skill-install)
--permissionsDisplay current permission settings and exit
--loginSign in to your Autohand Code account
--logoutSign out of your Autohand Code account
--sync-settings [bool]Enable/disable settings sync (default: true for logged users)
--patchGenerate git patch without applying changes
--output <file>Output file for patch (default: stdout)
--mode <mode>Run mode: interactive (default), rpc, or acp
--acpShorthand for --mode acp (Agent Client Protocol over stdio)
--teammate-mode <mode>Team display mode: auto, in-process, or tmux
--worktree [name]Run session in isolated git worktree (optional name)
--tmuxLaunch in a dedicated tmux session (implies --worktree)
--auto-mode [prompt]Enable interactive auto-mode, or start standalone loop with inline task
--max-iterations <n>Max auto-mode iterations (default: 50)
--completion-promise <text>Completion marker text (default: "DONE")
--no-worktreeDisable git worktree isolation in auto-mode
--checkpoint-interval <n>Git commit every N iterations (default: 5)
--max-runtime <m>Max runtime in minutes (default: 120)
--max-cost <d>Max API cost in dollars (default: 10)
--interactive-on-completeAfter auto-mode ends, hand off to interactive mode (TTY only)
--setupRun the setup wizard to configure or reconfigure Autohand Code CLI
--aboutShow information about Autohand Code CLI
--add-dir <path...>Add additional directories to workspace scope (can be used multiple times)
--display-language <locale>Set display language (e.g., en, id, zh-cn, fr, de, ja)
--cc, --context-compactEnable context compaction (default: on)
--no-cc, --no-context-compactDisable context compaction
--search-engine <provider>Set web search provider (browser-profile, exa, google, brave, duckduckgo, parallel)
--sys-prompt <value>Replace entire system prompt (inline string or file path)
--append-sys-prompt <value>Append to system prompt (inline string or file path)
--yolo [pattern]Auto-approve tool calls matching pattern (e.g., allow:read,write or deny:delete)
--timeout <seconds>Timeout in seconds for auto-approve mode
--settingsConfigure Autohand Code CLI settings (same as /settings in interactive mode)
--feedbackSubmit feedback
--browserEnable browser integration (same as /browser)
--no-browserDisable browser integration

Agent Skills

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

Using Skills

# 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

Auto-Skill Generation

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.

Slash Commands

CommandDescription
/helpDisplay available commands
/?Alias for /help
/quitExit the session
/exitExit the session
/modelSwitch LLM models
/newStart fresh conversation
/clearClear conversation history
/undoRevert last changes
/sessionShow current session details
/sessionsList past sessions
/resumeResume a previous session
/memoryView/manage stored memories
/initCreate AGENTS.md file
/agentsShow active Autohand CLI instances
/agents definitionsList configured sub-agents
/agents-newCreate new agent via wizard
/skillsList and manage skills
/skills newCreate a new skill
/skills useActivate a skill
/skills installInstall a community skill
/skills searchSearch for skills
/skills trendingList trending skills
/skills removeRemove an installed skill
/learnGet skill recommendations
/feedbackSend feedback
/formattersList code formatters
/lintList code linters
/completionGenerate shell completion scripts
/exportExport session to markdown/JSON/HTML
/statusShow workspace status
/usageShow token activity by day, week, or month
/loginAuthenticate with Autohand Code API
/logoutSign out
/permissionsManage tool permissions
/hooksManage git hooks
/experimentsToggle experimental feature switches
/settingsView configuration settings
/themeChange UI theme
/languageChange display language
/ccToggle context compaction
/searchSearch the web
/deep-researchRun cited research; use status for progress (/deep-search alias)
/publish-researchPreview and publish a saved research report with explicit confirmation
/automodeManage auto-mode
/autoresearchRun replayable benchmark loops with history, replay, comparison, and Pareto analysis
/goalSet a session-attached persistent goal and continue until it reaches a terminal state
/goal writerDraft one or more well-specified goals with the built-in $goal-writer skill
/squadOpen/manage the local Autohand Squad runtime
/goPair this session with the Autohand Code iOS app
/syncSync settings across devices
/add-dirAdd additional workspace directory
/planCreate a task plan
/aboutShow information about Autohand Code CLI
/whatsnewView and dismiss active CLI announcements
/ideOpen in IDE
/historyView command history
/mcpManage MCP servers
/mcp installInstall community MCP servers
/teamManage team collaboration
/tasksList team tasks
/messageSend team message
/importImport data from Claude, Codex, Gemini, Cursor, OpenCode, Kimi, and other agents
/repeatRepeat previous actions
/browserBrowser integration
/reviewCode review

Persistent goal data remains in the workspace across conversations, but execution does not silently transfer to a fresh session. Use /goal to inspect prior state and /goal resume to deliberately attach it to the current session.

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.

Mobile composer and historical sessions

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.

Tool System

Autohand Code CLI includes 40+ tools for autonomous coding:

File Operations

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

Git Operations

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

Commands & Dependencies

run_command, custom_command, add_dependency, remove_dependency

Planning & Memory

plan, todo_write, save_memory, recall_memory

Meta Tools

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.

Code Extensions

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.

Notebooks

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

Team & Collaboration

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

Agent Delegation

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

Skills & Browser

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

Configuration

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": "dark",
    "autoConfirm": false
  }
}

Supported Providers

ProviderConfig KeyNotes
Autohand AIautohandaiCloud Fantail/Moa or guided local Apple Silicon MLX
OpenRouteropenrouterAccess to Claude, GPT-4, Grok, etc.
LLMGatewayllmgatewayDirect Claude API access
OpenAIopenaiGPT-4 and other models
AWS BedrockbedrockBedrock Converse and OpenAI-compatible modes
DeepSeekdeepseekDeepSeek V4 Flash, V4 Pro, reasoning
OllamaollamaLocal models
llama.cppllamacppLocal inference
MLXmlxApple Silicon optimized
Z.aizaiHigh-performance inference

Session Management

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

# Resume via command
autohand resume <session-id>

# Or in interactive mode
/resume

Entire Integration

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.

Security & Permissions

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 *"]
  }
}

Platform Support

  • macOS
  • Linux
  • Windows

Telemetry & Feedback

Telemetry is disabled by default. Opt in to help improve Autohand Code CLI:

{
  "telemetry": {
    "enabled": true
  }
}

When enabled, Autohand Code CLI collects anonymous usage data (no PII, no code content). See Telemetry Documentation for details.

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

Development

# Install dependencies
bun install

# Development mode
bun run dev

# Build
bun run build

# Type check
bun run typecheck

# Run tests
bun run test

Docker

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

Documentation

Contributing

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

Troubleshooting

Common Issues

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.

Getting Help

Community

Security

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

License

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.

Roadmap

Upcoming Features

  • 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

Current Focus

  • 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.