---
title: "Zed Editor Integration"
source: https://docs.autohand.ai/guides/zed-integration
---

# Zed Editor Integration

Use Autohand CLI as an AI agent directly in Zed editor through the Agent Client Protocol (ACP) adapter.

## 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](https://nodejs.org)
-   **Autohand CLI installed and configured** - See [CLI Overview](/docs/working-with-autohand-code/cli.html)
-   **Zed editor** - [Download Zed](https://zed.dev)

Verify your Autohand installation:

## Installation

### Step 1: Install the ACP adapter

Install the Autohand ACP adapter globally:

### Step 2: Verify the installation

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

**Tip:** The adapter includes an `extension.toml` that points to GitHub release assets for easy installation via Zed's extension system.

## Configuration

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

### Basic settings

| Variable | Default | Description |
|---|---|---|
| AUTOHAND_CMD | autohand | Path or command name for Autohand |
| AUTOHAND_CONFIG | ~/.autohand/config.json | Path to Autohand config file |
| AUTOHAND_MODEL | - | Override the model (--model) |
| AUTOHAND_TEMPERATURE | - | Override the temperature (--temperature) |

### Permission modes

Control how Autohand handles actions that require approval:

| Mode | CLI Flag | Behavior |
|---|---|---|
| auto (default) | --yes | Auto-confirm risky actions |
| restricted | --restricted | Deny dangerous operations |
| unrestricted | --unrestricted | Allow all operations without prompts |
| ask | none | Prompt for each action (may hang) |

Set the permission mode:

### Advanced settings

| Variable | Default | Description |
|---|---|---|
| AUTOHAND_DRY_RUN | false | Set to 1 to add --dry-run |
| AUTOHAND_AUTO_COMMIT | false | Set to 1 to add --auto-commit |
| AUTOHAND_EXTRA_ARGS | - | Extra CLI arguments (space-separated) |
| AUTOHAND_INCLUDE_HISTORY | false | Set to 1 to include prior turns |
| AUTOHAND_HISTORY_LIMIT | 6 | Max turns to include in history |
| AUTOHAND_MAX_HISTORY_CHARS | 8000 | Max history characters to include |

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

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

## Troubleshooting

### Adapter doesn't start

**Check:** Is Node.js 18.17+ installed?

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

### Missing configuration

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

**Solution:** Run Autohand interactively once to complete setup:

### Each prompt loses context

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

**Solution:** Enable history to carry context between turns:

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

[Agent Skills](/docs/working-with-autohand-code/agent-skills.html) - Create custom Skills to extend Autohand's capabilities

[Configuration](/docs/working-with-autohand-code/configuration.html) - Advanced Autohand CLI configuration options

[Headless Mode](/docs/guides/headless-mode.html) - Run Autohand in CI/CD and automation scripts

[ACP Adapter GitHub](https://github.com/autohandai/autohand-acp) - Source code and issue tracker