IDE Integration

Zeph can act as a first-class coding assistant inside Zed and VS Code through the Agent Client Protocol. The editor spawns Zeph as a stdio subprocess and communicates over JSON-RPC; no daemon or network port is required.

For a full reference on ACP capabilities, transports, and configuration options, see ACP (Agent Client Protocol).

Prerequisites

• Zeph installed and configured (zeph init completed, at least one LLM provider active).
• ACP feature enabled in the binary (included in the default release build).
• Zed 1.0+ with the official ACP extension, or VS Code with the ACP extension.

Verify that ACP is available in your binary:

zeph --acp-manifest

Expected output:

{
  "name": "zeph",
  "version": "0.12.1",
  "transport": "stdio",
  "command": ["zeph", "--acp"],
  "capabilities": ["prompt", "cancel", "load_session", "set_session_mode", "config_options", "ext_methods"],
  "description": "Zeph AI Agent"
}

If the command is not found, ensure the Zeph binary directory is on your PATH (see Troubleshooting).

Enabling ACP in config.toml

Add the following section to your config.toml if it is not already present:

[acp]
enabled = true
# Optional: restrict which skills are exposed over ACP
# allowed_skills = ["code-review", "refactor"]

The enabled flag activates the ACP command-line flags (--acp, --acp-http, --acp-manifest). No network configuration is needed for the stdio transport used by IDE extensions.

Launching Zeph as an ACP stdio server

The editor extension manages the process lifecycle. When the user opens the assistant panel, the extension runs:

zeph --acp

Zeph reads JSON-RPC messages from stdin and writes responses to stdout. You can test the connection manually:

echo '{"jsonrpc":"2.0","id":1,"method":"acp/manifest"}' | zeph --acp

IDE setup

Zed

1. Open Settings (Cmd+, on macOS, Ctrl+, on Linux).
2. Add the agent configuration under "agent":

{
  "agent": {
    "profiles": {
      "zeph": {
        "provider": "acp",
        "binary": "zeph",
        "args": ["--acp"]
      }
    },
    "default_profile": "zeph"
  }
}

3. Reload the window. The Zeph entry appears in the assistant model selector.

VS Code

Install the ACP extension from the marketplace, then add to settings.json:

{
  "acp.agents": [
    {
      "name": "Zeph",
      "command": "zeph",
      "args": ["--acp"]
    }
  ]
}

Subagent visibility features

When Zeph orchestrates subagents internally, the IDE extension surfaces the execution hierarchy directly in the chat view.

Subagent nesting

Every session_update message carries a _meta.claudeCode.parentToolUseId field that identifies which parent tool call spawned the update. ACP-aware extensions (Zed, VS Code) use this field to nest subagent output under the originating tool call card in the chat panel, giving a clear visual tree of agent activity.

Live terminal streaming

AcpShellExecutor streams bash output in real time. Each chunk is delivered as a session_update with a _meta.terminal_output payload. The extension appends these chunks to the tool call card as they arrive, so you see command output line by line without waiting for the process to finish.

Agent following

When Zeph reads or writes a file, the ToolCall.location field carries the filePath of the target. The IDE extension receives this location and moves the editor cursor to the active file, keeping the viewport synchronized with what the agent is working on.

Troubleshooting

zeph: command not found

The binary is not on your PATH. Add the installation directory:

# Cargo install default
export PATH="$HOME/.cargo/bin:$PATH"

Add the export to your shell profile (~/.zshrc, ~/.bashrc) to make it permanent.

--acp flag not recognized

Your binary was built without the ACP feature. Rebuild with:

cargo install zeph --features acp

Or use the official release binary, which includes ACP by default.

Extension connects but returns no responses

Run zeph --acp-manifest in the terminal to confirm the process starts and outputs valid JSON. If it hangs or errors, check your config.toml for syntax errors and verify that [acp] enabled = true is present.

Verifying the manifest

zeph --acp-manifest

The capabilities array must include "prompt" for basic chat to work. If any capability is missing, ensure you are running the latest release.