ContenoxContenox

Use Contenox from Zed

Contenox speaks the Agent Client Protocol (ACP) over stdio. Zed can launch it as a custom agent server and drive your chain from inside the editor — tool calls render as cards, HITL prompts route through Zed's permission UI, and session history replays when you reopen the project.

This page assumes you already have contenox on PATH. If not, do the Quickstart first.

Setup

Add Contenox to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "Contenox": {
      "type": "custom",
      "command": "contenox",
      "args": ["acp"]
    }
  }
}

Restart Zed (or reload the window). Open the agent panel — Contenox now appears in the agent picker. Start a new session and prompt as usual.

What you get

Tool cards with real context. When the chain runs acp_terminal.exec, the card shows acp_terminal.exec: git status --short — the actual command, not just the tool name. Same for acp_fs.read_file, grep, sed, and other built-in tools.

Native editor surfaces. Built-in tools route through Zed: acp_fs.read_file/acp_fs.write_file use Zed's filesystem capability; acp_terminal.exec runs in a real Zed terminal you can interact with. These ACP-routed tools have Zed's own permission prompts — outside of Contenox's HITL policy.

HITL through the editor (for non-ACP tools). If your chain uses local_fs/local_shell/webtools, Contenox's HITL policy still applies — and the approval dialog is routed to Zed's permission UI instead of a terminal prompt. The default policy gates local_fs.write_file, local_fs.sed, local_shell.*, and mutating webtools calls.

Session history that replays. Close Zed mid-conversation and reopen the project — your prompts, the agent's responses, and every tool call (with its output) come back. State lives in ~/.contenox/local.db.

Choosing the chain

ACP sessions use a dedicated chain file separate from the CLI's default chain:

  • Default location: ~/.contenox/default-acp-chain.json
  • Override path with the CONTENOX_ACP_CHAIN_PATH environment variable (set it in the shell that launches Zed).

The ACP chain looks like any other Contenox chain. The default chain uses "tools": ["*"], which exposes everything the engine has registered — acp_fs, acp_terminal, webtools, plus any MCP servers you've added via contenox mcp add.

Choosing the model

ACP reads from your global model/provider config — the same one the CLI uses:

contenox config set default-model qwen2.5:7b
contenox config set default-provider ollama

Models are global; chains are local. Switching the model for ACP also switches it for contenox chat.

HITL approval flow

There are two distinct approval paths in a Zed session:

ACP-routed tools (acp_fs.*, acp_terminal.exec). Contenox forwards these to Zed as protocol-level filesystem/terminal calls. Whether and how Zed prompts the user before executing them is Zed's own UX — Contenox HITL does not gate them.

Contenox HITL (everything else). When the chain calls a non-ACP tool that's listed in your active HITL policy (default: local_fs.write_file, local_fs.sed, local_shell.*, mutating webtools), Contenox emits an ACP permission request which Zed renders as an approval dialog.

To skip Contenox HITL entirely (trusted/scripted contexts), launch with --auto:

{
  "agent_servers": {
    "Contenox": {
      "type": "custom",
      "command": "contenox",
      "args": ["acp", "--auto"]
    }
  }
}

--auto disables Contenox HITL only. Whatever permission UX Zed renders for ACP-routed filesystem/terminal calls is unaffected. Use --auto deliberately.

Troubleshooting

Nothing happens when I select Contenox. Make sure contenox is on Zed's PATH. Zed inherits the shell environment of the GUI process — on Linux that's usually your login shell's PATH. Test with which contenox in a shell launched from the same desktop session.

The default-model error. ACP needs a configured default model. Run contenox config set default-model <name> and contenox config set default-provider <type> before launching from Zed.

I want to see what's happening. Enable file logging:

contenox config set telemetry-enabled true

Subsequent ACP sessions write structured operation traces to ~/.contenox/telemetry.log (chain steps, tool calls, model requests, session updates sent to Zed). Stderr from the agent process also lands in Zed's Zed.log.

Limitations

  • Assistant text is not yet streamed incrementally with tool-using chains — it appears at the end of each generation step. Streaming-with-tools is on the roadmap; the synchronous chain shape works fine in the meantime.
  • No mid-turn cancel inside Zed propagates to the chain. Cancelling in Zed stops the UI from displaying further updates; the chain finishes in the background and its results are persisted.

Where to next

  • Author your first chain — the chain file is what defines the agent's behavior, regardless of which client drives it.
  • HITL policies — choose what requires approval and what doesn't.
  • MCP — register MCP servers once globally; ACP sessions pick them up automatically.
HITL PoliciesCLI Reference