Guides
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
- Autohand CLI installed and configured - See CLI Overview
- Zed editor - Download Zed
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,
restrictedmode prevents accidental changes. - Enable history for complex tasks: Set
AUTOHAND_INCLUDE_HISTORY=1for multi-turn conversations. - Review changes: Use
--dry-runto 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_MODEto control approvals. - Fresh process per prompt: Each ACP prompt starts a new Autohand process. Enable
AUTOHAND_INCLUDE_HISTORYfor basic continuity. - No streaming UI: Progress indicators and intermediate output depend on the editor's ACP implementation.