ACP Agents¶

Agent Client Protocol (ACP) mode connects SuperQode to full-featured coding agents.

Overview¶

ACP agents provide:

• Full capabilities: File editing, shell execution, MCP tools
• Structured prompting: Optimized for coding tasks
• Tool integration: Access to development environment
• Persistent context: Maintains state across operations

Quick Start¶

# Connect to OpenCode
superqode connect acp opencode

Supported Agents¶

Use superqode agents list --protocol acp to see the current list (it’s driven by the built‑in agent registry and any local agent definitions).

OpenCode¶

OpenCode is the primary ACP agent:

# Install OpenCode
npm i -g opencode-ai

# Verify installation
opencode --version

# Connect via SuperQode
superqode connect acp opencode

Capabilities¶

Web Fetch and MCP Tools¶

ACP agents do not automatically receive SuperQode's built-in Python tools such as fetch and web_fetch. To make web fetch available to OpenCode or another ACP agent, configure an enabled MCP fetch server. SuperQode passes enabled MCP servers from .superqode/mcp.json, ~/.superqode/mcp.json, or ~/.config/superqode/mcp.json into each ACP session/new request.

{
  "mcpServers": {
    "fetch": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"],
      "enabled": true
    }
  }
}

Restart the ACP session after changing MCP configuration so the agent receives the updated server list.

OpenClaw (Enterprise Integration, Experimental)¶

OpenClaw provides an ACP bridge backed by the OpenClaw Gateway. This integration is available in Enterprise.

# Install OpenClaw
npm install -g moltbot@latest

# Start the gateway (in a separate terminal)
moltbot gateway --port 18789 --verbose

# Connect via SuperQode
superqode connect acp moltbot

If your gateway requires auth, pass --token or --password in the agent command configuration.

Note: OpenClaw integration is experimental and intended for self-hosted environments with secure, private local models.

Amp¶

Amp is an AI coding agent by Ampcode with full ACP support:

# Install Amp CLI
curl -fsSL https://ampcode.com/install.sh | bash
amp login

# Install ACP adapter (Python - recommended)
uv tool install acp-amp

# Alternative: Node.js
npm install -g @superagenticai/acp-amp

# Connect via SuperQode
superqode connect acp amp

Capabilities¶

Other ACP-Compatible Agents¶

SuperQode includes registry entries for these ACP agents (availability depends on local installation):

• Amp (ACP adapter: acp-amp via acp-amp)
• Claude Code (ACP adapter: claude-code-acp)
• Codex (ACP adapter: npx @openai/codex-acp or codex-acp)
• OpenHands (openhands acp)
• Gemini CLI (gemini --experimental-acp): enterprise/API-key ACP route. Individual Google AI users should prefer :connect antigravity
• Goose (goose)
• Kimi CLI (kimi --acp)
• Augment Code / Auggie (auggie --acp)
• Stakpak (stakpak)
• VT Code (vtcode-acp)
• fast-agent (ACP entrypoint: fast-agent-acp -x)
• LLMling-Agent (llmling-agent)
• cagent (cagent)
• Code Assistant (see its agent card for the ACP command)

If an agent requires an ACP adapter, install it first using the setup instructions from superqode agents show <agent>.

Configuration¶

In superqode.yaml¶

agents:
  opencode:
    description: "OpenCode coding agent"
    protocol: acp
    command: opencode
    auth_file: ~/.local/share/opencode/auth.json
    capabilities:
      - file_editing
      - shell_execution
      - mcp_tools

  amp:
    description: "Amp Code agent"
    protocol: acp
    command: acp-amp
    capabilities:
      - file_editing
      - shell_execution
      - mcp_tools
      - multi_turn

Agent Properties¶

ACP Protocol¶

How It Works¶

1. SuperQode spawns the agent process
2. Communicates via ACP (JSON over stdin/stdout)
3. Agent has access to file system and shell
4. Results streamed back to SuperQode

Message Format¶

{
  "type": "request",
  "id": "req-001",
  "method": "analyze",
  "params": {
    "path": "/src/api/users.py",
    "focus": "security"
  }
}

Compared to BYOK¶

When to Use ACP¶

• Complex multi-step tasks
• Tasks requiring file manipulation
• Tasks requiring shell commands
• Integration with other tools

When to Use BYOK¶

• Simple analysis tasks
• Quick scans
• Cost-sensitive workloads
• Team environments

Custom Agents¶

Define a Custom Agent¶

agents:
  custom_agent:
    description: "My custom ACP agent"
    protocol: acp
    command: /path/to/my-agent
    args:
      - --mode
      - interactive
      - --workspace
      - .
    capabilities:
      - file_editing
      - shell_execution

Requirements¶

Custom agents must:

1. Accept ACP messages on stdin
2. Return ACP responses on stdout
3. Support the ACP protocol methods defined in the spec (initialize, session/new, session/prompt, session/update, fs/, terminal/)
4. Handle graceful shutdown

Troubleshooting¶

Agent Not Found¶

[INCORRECT] Agent 'opencode' not found

Solution: Install the agent:

npm i -g opencode-ai

Connection Failed¶

[INCORRECT] Failed to connect to agent

Solutions: - Verify agent is installed: which opencode - Check agent version: opencode --version - Run agent manually to check for errors

Permission Denied¶

[INCORRECT] Permission denied: auth_file

Solution: Check auth file permissions:

ls -la ~/.local/share/opencode/auth.json

Agent Timeout¶

[INCORRECT] Agent response timeout

Solutions: - Increase timeout in configuration - Check if agent is busy - Restart the agent

Best Practices¶

1. Use for Complex Tasks¶

ACP excels at multi-step tasks. Use it when you need file editing, shell access, and tool integration.

2. Combine with BYOK¶

Use ACP for complex automation, BYOK for simpler analysis tasks. Switch between them with :connect.

3. Monitor Resource Usage¶

ACP agents may use significant resources. Monitor: - Memory usage - CPU usage - Disk I/O

Next Steps¶

• BYOK Providers - Cloud provider setup
• Local Providers - Self-hosted models