Autohand Code CLI（Autohand 编码命令行工具）｜终端 AI 编码代理

access：来源确认 · curl -fsSL https://autohand.ai/install.sh | bash

project_type：来源确认 · A fast, self-improving terminal-native AI coding agent for planning, reflecting, remembering, editing, testing, and automating work across your codebase.

# Autohand Code CLI

[![Bun](https://img.shields.io/badge/Bun-%23c61f33?style=flat&logo=bun&logoColor=white)](https://bun.sh)
[![Discord](https://img.shields.io/badge/Discord-Join%20Us-%235865F2?style=flat&logo=discord&logoColor=white)](https://discord.gg/ZM3TCtwCwG)

[Follow us on X](https://x.com/autohandai) | [Join Discord](https://discord.gg/ZM3TCtwCwG)

Docs: [English](docs/config-reference.md) | [日本語](docs/config-reference_ja.md) | [简体中文](docs/config-reference_zh.md) | [繁體中文](docs/config-reference_zh-tw.md) | [한국어](docs/config-reference_ko.md) | [Deutsch](docs/config-reference_de.md) | [Español](docs/config-reference_es.md) | [Français](docs/config-reference_fr.md) | [Italiano](docs/config-reference_it.md) | [Polski](docs/config-reference_pl.md) | [Русский](docs/config-reference_ru.md) | [Português (Brasil)](docs/config-reference_ptBR.md) | [Türkçe](docs/config-reference_tr.md) | [Čeština](docs/config-reference_cs.md) | [Magyar](docs/config-reference_hu.md) | [हिन्दी](docs/config-reference_hi.md) | [Bahasa Indonesia](docs/config-reference_id.md)

**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](docs/gif/autohand-intro.gif)

## Features

Interactive sessions assess repository readiness in the background while you work. A bounded, read-only scan compares `AGENTS.md` and `CLAUDE.md` history with committed and uncommitted changes, then asks your configured model for a repository map and concrete improvement candidates. It runs no project scripts and makes no edits. After your first successful turn, new findings appear once per repository; materially new findings can be offered in a later session. Use `/readiness` to review the evidence, `/readiness apply 1` to choose a finding, or `/readiness dismiss` to skip. Set `ui.repositoryReadiness` to `false` to disable this background model request. Bare, ephemeral, offline, command, RPC and ACP sessions skip it.

The shell installer includes [Zit](https://getzit.org) v0.1.2 by default on supported macOS and Linux platforms, preserving an existing installation and verifying release checksums. Use `--no-zit` or `AUTOHAND_SKIP_ZIT_INSTALL=1` to opt out. The Windows installer supports `-NoZit` and the same environment variable; it preserves an existing Zit installation and reports that native Windows binaries are currently unavailable. `autohand --zit` requires Git 2.38 or newer. Installing Zit does not initialize repositories.

On Windows, running `install.sh` from Git Bash, MSYS, or Cygwin delegates to the native PowerShell installer and preserves installation options. Autohand launched from Git Bash uses Bash for command tools; see [shell settings](docs/config-reference.md#shell-settings) to choose an executable explicitly.

The npm package includes checksum-verified Zit binaries for macOS and Linux on ARM64 and x64. `npm install -g autohand-cli` and `bun install -g autohand-cli` download them with the package, including when lifecycle scripts are disabled. Autohand uses `ZIT_BIN`, an existing `zit` on `PATH`, or its packaged binary, in that order. Rust and a separate Zit installation are not required. Native Windows Zit binaries are currently unavailable.

- **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**: Free Fantail model with an Autohand account, or 15+ providers incl. Anthropic, OpenAI, OpenRouter, Bedrock, DeepSeek, Azure, Vertex, xAI, Z.ai and local Ollama/llama.cpp/MLX
- **Git Integration**: Full version control support with automatic commits
- **Cross-Platform**: Works on macOS, Linux, and Windows
- **Coming from Claude Code?** Run `autohand import claude` to bring over your settings, skills, hooks, sessions and memory

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

### Quick Install (Recommended)

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

### Homebrew

```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](docs/traces.md) 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](https://github.com/autohandai/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](docs/computer-control.md).

### Manual Installation

```bash
# 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

- Node.js 22 or later (to run Autohand)
- Bun 1.0 or later, only to build from source (`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.

```bash
# 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

```bash
# 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" --auto-commit
```

## Editor Extensions

Use Autohand Code CLI directly in your favorite editor:

### VS Code

Install the extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=AutohandAI.vscode-autohand) or via command line:

```bash
code --install-extension AutohandAI.vscode-autohand
```

### Zed Editor

Run Autohand Code CLI as a native ACP External Agent. See the [ACP integration guide](docs/guides/ACP.md) 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](https://github.com/autohandai/code-agent-sdk-typescript). 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:

```bash
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](#viewing-and-managing-goals); 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

### Command Mode (Non-Interactive)

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

```bash
# 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

| Option                          | Short | Description                                                                      |
| ------------------------------- | ----- | -------------------------------------------------------------------------------- |
| `--prompt <text>`               | `-p`  | Run a single instruction in command mode                                         |
| `--output-format stream-json`   |       | Stream command lifecycle events as JSON Lines                                    |
| `--json <stream\|local>`        |       | Stream JSON Lines or write only the final JSON result (`--json` defaults to stream) |
| `--yes`                         | `-y`  | Auto-confirm risky actions                                                       |
| `--continue`                    | `-c`  | Resume the latest session in this folder (also with `-p`)                        |
| `--resume [id]`                 | `-r`  | Resume a saved session or open the folder picker                                 |
| `--auto-commit`                 |       | Auto-commit changes after completing tasks                                       |
| `--dry-run`                     |       | Preview actions without applying mutations                                       |
| `--debug`                       | `-d`  | Enable debug output (verbose logging)                                            |
| `--model <model>`               |       | Override the configured LLM model                                                |
| `--path <path>`                 |       | Workspace path to operate in                                                     |
| `--auto-skill`                  |       | Auto-generate skills based on project analysis                                   |
| `--unrestricted`                |       | Run without approval prompts (use with caution)                                  |
| `--restricted`                  |       | Deny all dangerous operations automatically                                      |
| `--plan`                        |       | Start in read-only plan mode before the first prompt                             |
| `--no-idle-logout`              |       | Disable 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)                            |
| `--learn`                       |       | Run skill advisor non-interactively                                              |
| `--learn-update`                |       | Re-analyze project and regenerate skills                                         |
| `--skill-install [name]`        |       | Install a community skill                                                        |
| `--project`                     |       | Install skill to project level (with --skill-install)                            |
| `--permissions`                 |       | Display current permission settings and exit                                     |
| `--login`                       |       | Sign in to your Autohand Code account                                            |
| `--logout`                      |       | Sign out of your Autohand Code account                                           |
| `--sync-settings [bool]`        |       | Enable/disable settings sync (default: true for logged users)                    |
| `--patch`                       |       | Generate git patch without applying changes                                      |
| `--output <file>`               |       | Output file for patch (default: stdout)                                          |
| `--mode <mode>`                 |       | Run mode: interactive (default), rpc, or acp                                     |
| `--acp`                         |       | Shorthand 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)                             |
| `--tmux`                        |       | Launch in a dedicated tmux session (implies --worktree)                          |
| `--zit [intent]`                |       | Run session in a disposable Zit workspace, recorded as a Zit change on exit      |
| `--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-worktree`                 |       | Disable 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-complete`     |       | After auto-mode ends, hand off to interactive mode (TTY only)                    |
| `--setup`                       |       | Run the setup wizard to configure or reconfigure Autohand Code CLI               |
| `--about`                       |       | Show 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-compact`       |       | Enable context compaction (default: on)                                          |
| `--no-cc, --no-context-compact` |       | Disable 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                                         |
| `--settings`                    |       | Configure Autohand Code CLI settings (same as /settings in interactive mode)     |
| `--feedback`                    |       | Submit feedback                                                                  |
| `--browser`                     |       | Enable browser integration (same as /browser)                                    |
| `--no-browser`                  |       | Disable browser integration                                                      |

Native computer control commands:

| Command | Description |
| --- | --- |
| `autohand computer status [--json]` | Show Autohand Computer Use and MCP readiness |
| `autohand computer install [--force]` | Install or repair the pinned, verified native driver |
| `autohand computer doctor` | Check platform support and desktop permissions |

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

```bash
# 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:

```bash
$ 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](https://skilled.autohand.ai) - Community skill registry
- Compatible with Codex and Claude skill formats

See [Agent Skills Documentation](docs/agent-skills.md) for creating custom skills.

## Automatic commits

`--auto-commit` snapshots the repository before the agent starts editing. It commits only session changes and lists pre-existing edits and untracked files as `left uncommitted (yours)`. An initially dirty file stays uncommitted even if the agent edits it again. Your existing staging is preserved. Automatic commits are disabled if a safe baseline cannot be captured.

## Proxy settings

Node installs use `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY` for requests, including provider SDK calls. Lowercase variables take precedence; Bun binaries use Bun's native proxy support. Corporate certificate bundles can be supplied with `NODE_EXTRA_CA_CERTS`.

## Slash Commands

`/undo` restores every recorded agent file change from the last turn, newest first. It stops on the first unsafe restore and keeps the turn. Shell commands are not undone; restored sessions without a file journal are kept. `/export` redacts credentials and saves bare filenames under `~/.autohand/exports/` (or `$AUTOHAND_HOME/exports/`). Use an absolute or `./`-prefixed path to choose another location.

| Command            | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `/help`            | Display available commands                                                       |
| `/?`               | Alias for /help                                                                  |
| `/quit`            | Exit the session                                                                 |
| `/exit`            | Exit the session                                                                 |
| `/model`           | Switch LLM models                                                                |
| `/new`             | Start fresh conversation                                                         |
| `/clear`           | Compact context, retaining requests, learnings, changes and final answer           |
| `/undo`            | Restore agent file changes from the last turn and remove it                      |
| `/session`         | Show current session details                                                     |
| `/sessions`        | List past sessions                                                               |
| `/resume`          | Resume a previous session                                                        |
| `/memory`          | View/manage stored memories                                                      |
| `/init`            | Create `AGENTS.md` file                                                          |
| `/agents`          | Show active Autohand CLI instances                                               |
| `/agents definitions` | List configured sub-agents                                                    |
| `/agents-new`      | Create new agent via wizard                                                      |
| `/skills`          | List and manage skills                                                           |
| `/skills new`      | Create a new skill                                                               |
| `/skills use`      | Activate a skill                                                                 |
| `/skills install`  | Install a community skill                                                        |
| `/skills search`   | Search for skills                                                                |
| `/skills trending` | List trending skills                                                             |
| `/skills remove`   | Remove an installed skill                                                        |
| `/learn`           | Get skill recommendations                                                        |
| `/feedback`        | Send feedback                                                                    |
| `/formatters`      | List code formatters                                                             |
| `/lint`            | List code linters                                                                |
| `/completion`      | Generate shell completion scripts                                                |
| `/export`          | Export a redacted session to Markdown/JSON/HTML                                             |
| `/status`          | Show workspace status                                                            |
| `/usage`           | Show token activity by day, week, or month                                       |
| `/login`           | Authenticate with Autohand Code API                                              |
| `/logout`          | Sign out                                                                         |
| `/permissions`     | Manage tool permissions                                                          |
| `/hooks`           | Manage git hooks                                                                 |
| `/experiments`     | Toggle experimental feature switches                                             |
| `/settings`        | View configuration settings                                                      |
| `/theme`           | Change UI theme                                                                  |
| `/language`        | Change display language                                                          |
| `/cc`              | Toggle context compaction                                                        |
| `/search`          | Search the web                                                                   |
| `/deep-research`   | Run cited research; use `status` for progress (`/deep-search` alias)             |
| `/publish-research`| Preview and publish a saved research report with explicit confirmation             |
| `/automode`        | Manage auto-mode                                                                 |
| `/autoresearch`    | Run replayable benchmark loops with history, replay, comparison, and Pareto analysis |
| `/goal`            | Set a session-attached persistent goal and continue until it reaches a terminal state |
| `/goal writer`     | Draft one or more well-specified goals with the built-in `$goal-writer` skill    |
| `/goals`, `/goals view` | Open the live goals view with compact summaries and statuses                  |
| `/goal view`       | Alias for `/goals view`                                                          |
| `/goals edit <id> <objective>` | Update this session's goal or a queued goal by ID                     |
| `/goals queue [objective]` | List queued goals and their IDs, or add an objective to the queue          |
| `/goals pause`     | Pause this session's current goal                                               |
| `/goals resume`    | Resume this session's goal, or start queued work when it has no current goal     |
| `/goals complete`  | Mark the current goal complete and advance queued work when completion requirements are met |
| `/goals clear`     | Clear this session's current goal while retaining queued work                   |
| `/goals templates` | List reusable goal templates                                                    |
| `/squad`           | Open/manage the local Autohand Squad runtime                                     |
| `/go`              | Pair this session with the Autohand Code iOS app                                 |
| `/sync`            | Sync settings across devices                                                     |
| `/add-dir`         | Add additional workspace directory                                               |
| `/plan`            | Create a task plan                                                               |
| `/about`           | Show information about Autohand Code CLI                                         |
| `/whatsnew`        | View and dismiss active CLI announcements                                        |
| `/ide`             | Open in IDE                                                                      |
| `/history`         | View command history                                                             |
| `/mcp`             | Manage MCP servers                                                               |
| `/mcp install`     | Install validated Official MCP Registry servers (stdio and HTTP)                |
| `/team`            | Manage team collaboration                                                        |
| `/tasks`           | List team tasks                                                                  |
| `/message`         | Send team message                                                                |
| `/import`          | Import data from Claude, Codex, Gemini, Cursor, OpenCode, Kimi, Grok hooks, and other agents |
| `/repeat`          | Repeat previous actions                                                          |
| `/browser`         | Browser integration                                                              |
| `/review`          | Code review                                                                      |

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.

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

### Viewing and managing goals

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

```text
/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.

| Control | Action |
|---------|--------|
| `Ctrl+G` (`Cmd+G` on macOS) | Open or close the goals view |
| `Up` / `Down`, with an empty composer | Select an editable goal |
| `Enter` on a selected goal, or click its row | Load the full objective into the composer |
| `Enter` while editing | Save the edited objective |
| `Esc` with a goal selected or being edited | Clear the selection or cancel the unsaved edit; the view stays open |

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](docs/features.md#viewing-and-managing-goals) and
[goals and auto mode](docs/config-reference.md#goals-and-auto-mode) for more details.

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

```sh
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](docs/guides/building-autohand-extensions.md), [Using extensions](docs/extensions.md), [Extension authoring](docs/extension-authoring.md), and the [eight working examples](examples/extensions).

### 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`:

```json
{
  "provider": "openrouter",
  "openrouter": {
    "apiKey": "<API_KEY>",
    "model": "your-modelcard-id-here"
  },
  "workspace": {
    "defaultRoot": ".",
    "allowDangerousOps": false
  },
  "ui": {
    "theme": "aurora",
    "autoConfirm": false
  }
}
```

### Supported Providers

| Provider    | Config Key    | Notes                                                |
| ----------- | ------------- | ---------------------------------------------------- |
| Autohand AI | `autohandai`  | Cloud Fantail/Moa or guided local Apple Silicon MLX. Weka is API/Console only. |
| OpenRouter  | `openrouter`  | Access to Claude, GPT-4, Grok, etc.                  |
| LLMGateway  | `llmgateway`  | Direct Claude API access                             |
| OpenAI      | `openai`      | GPT-4 and other models                               |
| AWS Bedrock | `bedrock`     | Bedrock Converse and OpenAI-compatible modes         |
| DeepSeek    | `deepseek`    | DeepSeek V4 Flash, V4 Pro, reasoning                 |
| Ollama      | `ollama`      | Local models                                         |
| llama.cpp   | `llamacpp`    | Local inference                                      |
| MLX         | `mlx`         | Apple Silicon optimized                              |
| Z.ai        | `zai`         | High-performance inference                           |
| Anthropic   | `anthropic`   | Claude models with your own API key                  |
| Azure OpenAI | `azure`       | Azure deployments via API key, Entra ID or managed identity |
| Vertex AI   | `vertexai`    | Google models on Vertex AI                           |
| xAI         | `xai`         | Grok models via API key or OAuth                     |
| Cerebras    | `cerebras`    | Hosted fast inference                                |
| NVIDIA      | `nvidia`      | NVIDIA-hosted models                                 |
| Sakana AI   | `sakana`      | Sakana AI models                                     |

## Session Management

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

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

`autohand -c` continues the most recently active session in this folder. If none exists, it starts a new one. Use `autohand -c -p "Continue the fix"` for a headless continuation, or `autohand -r <id>` to select a session directly. `autohand -r` opens the folder picker. `--ephemeral` cannot be combined with `--continue`, `--resume`, or `--fork`.

## Entire Integration

Autohand Code CLI supports [Entire](https://entire.io) 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.

```bash
# 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](docs/entire-integration.md) for setup details and troubleshooting.

## Security & Permissions

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`:

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

## Platform Support

- macOS
- Linux
- Windows

## Telemetry & Feedback

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.

```json
{
  "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](docs/telemetry.md) for exact fields, defaults, endpoints, and limits.

### Local agent Work Map

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.

```bash
# 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](docs/discovery.md#work-map) for command options.

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

## Development

```bash
# Install dependencies
bun install

# Development mode
bun run dev

# Build
bun run build

# Type check
bun run typecheck

# Run tests
bun run test

# Full proof (unit tests, build, and Tuistory)
bun run proof

# Limit local test workers on resource-constrained hosts
AUTOHAND_TEST_WORKERS=1 bun run proof
```

## Docker

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

```bash
docker build -t autohand .
docker run -it autohand
```

## Documentation

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

## Contributing

We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for details on how to get involved.

## Troubleshooting

### Common Issues

**Installation fails**: Make sure Node.js 22 or later is installed. Building from source also needs Bun.

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

- Join our [Discord community](https://discord.gg/ZM3TCtwCwG)
- Check the [documentation](docs/)
- Open an issue on [GitHub](https://github.com/autohandai/code-cli/issues)

## Community

- **Discord**: https://discord.gg/ZM3TCtwCwG
- **GitHub**: https://github.com/autohandai/code-cli
- **Website**: https://autohand.ai
- **X**: [@autohandai](https://x.com/autohandai)

## 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](LICENSE) and [COMMERCIAL.md](COMMERCIAL.md) for details.

## Links

- 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

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

Node.js 22+；从源码构建需 Bun 1.0+；Git；ripgrep 可选。使用模型需 Autohand 账号或自行配置的提供方 API Key；Desktop 控制组件在 macOS 需辅助功能与屏幕录制权限；代理可执行 Shell 命令与编辑文件，受模式与审批设置约束；其他提供方费用与是否免费待核验；境外依赖（官方安装地址、账号服务、云端轨迹）的网络可用性待核验。