Zed Editor Integration

Overview

The Autohand ACP adapter bridges Autohand CLI with editors that support the Agent Client Protocol, like Zed. This gives you access to Autohand's powerful AI capabilities without leaving your editor.

What you get:

• AI-powered code generation and editing directly in Zed
• Context-aware assistance that understands your entire codebase
• Seamless integration with Autohand's tool ecosystem
• Configurable permissions and safety controls

Prerequisites

Before setting up the integration, make sure you have:

• Node.js 18.17 or newer - Download Node.js
• Autohand CLI installed and configured - See CLI Overview
• Zed editor - Download Zed

Verify your Autohand installation:

# Check Autohand is installed
autohand --version

# Verify configuration exists
ls ~/.autohand/config.json

Installation

Step 1: Install the ACP adapter

Install the Autohand ACP adapter globally:

npm install -g @autohandai/autohand-acp

Step 2: Verify the installation

# Test the adapter starts correctly
autohand-acp --version

Step 3: Configure Zed

Zed can launch the adapter via the Agent Server extension. Add the following to your Zed settings or use the extension configuration:

{
  "agent_servers": {
    "autohand": {
      "command": "autohand-acp",
      "args": []
    }
  }
}

Configuration

Environment variables control how the adapter launches Autohand. Set these in your shell profile or Zed's environment configuration.

Basic settings

Permission modes

Control how Autohand handles actions that require approval:

Set the permission mode:

export AUTOHAND_PERMISSION_MODE=restricted

Advanced settings

Using Autohand in Zed

Starting a session

Once configured, Autohand appears as an available agent in Zed's AI panel. Select it and start chatting:

You: Add error handling to the fetchUser function

Autohand: I'll analyze the fetchUser function and add proper error handling...
[Autohand reads the file, makes changes, runs tests]

Best practices

• Be specific: Describe exactly what you want. Include file paths when relevant.
• Use restricted mode for exploration: When browsing code or asking questions, restricted mode prevents accidental changes.
• Enable history for complex tasks: Set AUTOHAND_INCLUDE_HISTORY=1 for multi-turn conversations.
• Review changes: Use --dry-run to preview changes before applying them.

Example prompts

# Refactoring
"Refactor src/utils/api.ts to use async/await instead of promises"

# Bug fixing
"There's a null pointer error in handleSubmit - can you fix it?"

# Code generation
"Create a React hook for managing form state with validation"

# Code review
"Review the changes in my current git diff for potential issues"

# Documentation
"Add JSDoc comments to all exported functions in src/lib/"

Troubleshooting

Adapter doesn't start

Check: Is Node.js 18.17+ installed?

node --version  # Should be v18.17.0 or higher

Session hangs or stalls

Cause: Autohand may be waiting for interactive input.

Solution: Make sure AUTOHAND_PERMISSION_MODE is not set to ask. Use auto, restricted, or unrestricted.

export AUTOHAND_PERMISSION_MODE=auto

Missing configuration

Cause: Autohand config file doesn't exist or is incomplete.

Solution: Run Autohand interactively once to complete setup:

autohand
# Follow the prompts to configure API keys and preferences

Each prompt loses context

Cause: By default, each ACP prompt starts a fresh Autohand process.

Solution: Enable history to carry context between turns:

export AUTOHAND_INCLUDE_HISTORY=1
export AUTOHAND_HISTORY_LIMIT=10

Limitations

• Non-interactive mode: Autohand runs without interactive prompts. If it needs input (e.g., missing config), the run will stall.
• Tool permissions: ACP tool-level permission prompts are not surfaced to the editor. Use AUTOHAND_PERMISSION_MODE to control approvals.
• Fresh process per prompt: Each ACP prompt starts a new Autohand process. Enable AUTOHAND_INCLUDE_HISTORY for basic continuity.
• No streaming UI: Progress indicators and intermediate output depend on the editor's ACP implementation.

Next steps