Autohand CLI for Zed

Use Autohand CLI from Zed and other ACP-compatible editors!

Features

• File Operations: Read, write, search, and modify files
• Terminal Commands: Execute shell commands with output streaming
• Session Management: Resume previous sessions, fork conversations
• Permission Controls: External (Zed UI), auto-approve, or restricted modes
• Dynamic Titles: Auto-generated session names from your first message
• Image Support: Paste screenshots for visual context
• Slash Commands: /help, /new, /model, /mode, /resume, /threads, /status, and more
• TODO/Planning: Visual task tracking in Zed's UI
• MCP Integration: Connect to HTTP/SSE MCP servers

Learn more about the Agent Client Protocol.

Installation

Option 1: Zed Extension (Recommended)

Once published to the Zed Extension Registry:

1. Open Zed
2. Go to Extensions (Cmd+Shift+X)
3. Search for "Autohand CLI"
4. Click Install
5. Open Agent Panel and select "Autohand CLI" from the + menu

Option 2: Manual Settings

Add to your Zed settings (~/.config/zed/settings.json):

{
  "agent_servers": {
    "Autohand CLI": {
      "command": "npx",
      "args": ["@autohandai/autohand-acp"],
      "env": {
        "AUTOHAND_PERMISSION_MODE": "external"
      }
    }
  }
}

Option 3: npm Global Install

npm install -g @autohandai/autohand-acp

Then add to Zed settings:

{
  "agent_servers": {
    "Autohand CLI": {
      "command": "autohand-acp",
      "env": {
        "AUTOHAND_PERMISSION_MODE": "external"
      }
    }
  }
}

Other ACP Clients

This adapter works with any ACP-compatible client. Submit a PR to add documentation for your editor!

Requirements

• Node.js >= 18.17
• autohand CLI installed and configured (~/.autohand/config.json)

Configuration

Environment variables control how the adapter launches Autohand:

| Variable | Description | Default | |----------|-------------|---------| | AUTOHAND_CMD | Path or command name for Autohand | autohand | | AUTOHAND_CONFIG | Path to config file | ~/.autohand/config.json | | AUTOHAND_MODEL | Override the model | - | | AUTOHAND_PERMISSION_MODE | auto, external, restricted, unrestricted, ask | auto | | AUTOHAND_DRY_RUN | Set to 1 for dry-run mode | - | | AUTOHAND_AUTO_COMMIT | Set to 1 to auto-commit changes | - | | AUTOHAND_AVAILABLE_MODELS | Comma-separated model IDs | - | | AUTOHAND_INCLUDE_HISTORY | Set to 1 to include prior turns | - |

Permission Modes

• auto: Auto-confirm risky actions (--yes)
• external: Forward permission requests to Zed via ACP (recommended for interactive use)
• restricted: Deny all dangerous operations automatically
• unrestricted: Run without any approval prompts (use with caution)
• ask: Run without flags (may hang if prompts appear)

File Mentions

File mentions work automatically in Zed. When you reference a file using @filename:

1. The adapter reads the file content
2. Embeds it in the prompt sent to Autohand CLI
3. Autohand can then analyze or modify the file

This enables context-aware assistance without manually copying file contents.

External Permission Mode

When AUTOHAND_PERMISSION_MODE=external, the adapter starts a local HTTP server that Autohand CLI calls to request permissions:

1. Adapter starts permission server on localhost
2. Passes AUTOHAND_PERMISSION_CALLBACK_URL to Autohand CLI
3. Autohand CLI calls the URL when it needs permission
4. Adapter forwards to Zed via ACP requestPermission
5. User sees Allow/Reject buttons in Zed
6. Decision is returned to Autohand CLI

This requires Autohand CLI v0.6+ with external callback support.

Slash Commands

| Command | Description | |---------|-------------| | /help | Show available commands | | /new | Start a new conversation | | /model [name] | Select or change model | | /mode [name] | Select mode (default/ask/code) | | /resume [id] | Resume a previous session | | /threads | List and switch between sessions | | /sessions | List recent sessions | | /session | Show current session info | | /status | Show Autohand status | | /init | Create AGENTS.md file | | /undo | Undo last file change |

Development

npm install
npm run build
npm run test
npm run lint

Local Testing

# Build local distribution
./scripts/build-local.sh

# Start local server (in separate terminal)
cd dist-local && python3 -m http.server 8765

# Copy dev config and install in Zed
cp extension.dev.toml extension.toml
# Then in Zed: "zed: install dev extension" -> select this folder

Publishing

One-Command Release

./scripts/release.sh patch   # 0.1.1 -> 0.1.2
./scripts/release.sh minor   # 0.1.1 -> 0.2.0
./scripts/release.sh major   # 0.1.1 -> 1.0.0
./scripts/release.sh 0.2.5   # Set specific version

This script will:

1. ✅ Bump version in package.json and extension.toml
2. ✅ Run tests
3. ✅ Commit and tag
4. ✅ Push to GitHub (triggers CI build)
5. ✅ Guide you through Zed registry submission

License

Apache-2.0