Agent Setup

Agent Setup#

This chapter explains how to configure common ACP agents with this bot.

Use ACP_AGENT_COMMAND to define the command executed by /new.

Quick compatibility map#

Agent

ACP support

Recommended command

Gemini CLI

Native ACP support (experimental flag required)

ACP_AGENT_COMMAND="npx @google/gemini-cli --experimental-acp"

GitHub Copilot CLI

Native ACP support (--acp)

ACP_AGENT_COMMAND="copilot --acp"

Codex CLI

Via ACP adapter

ACP_AGENT_COMMAND="npx @zed-industries/codex-acp"

Claude Agent SDK / Claude Code

Via ACP adapter

ACP_AGENT_COMMAND="npx @zed-industries/claude-agent-acp"

Gemini CLI (native ACP)#

  1. Install and authenticate Gemini CLI first.

  2. Set GEMINI_API_KEY (or another auth method supported by Gemini CLI).

  3. Start the bot with Gemini as agent:

GEMINI_API_KEY=... \
ACP_AGENT_COMMAND="npx @google/gemini-cli --experimental-acp" \
uv run telegram-acp-bot

If /new does not return, set a lower ACP_CONNECT_TIMEOUT and ACP_LOG_LEVEL=DEBUG to see where handshake stops. See also Gemini CLI repository.

Codex CLI (via adapter)#

Codex CLI is an OpenAI coding agent. For ACP clients, use the Codex ACP adapter.

OPENAI_API_KEY=... \
ACP_AGENT_COMMAND="npx @zed-industries/codex-acp" \
uv run telegram-acp-bot

You can also install the adapter binary from adapter releases and use codex-acp directly.

Codex profiles, sandbox, and behavior differences#

When using Codex through Zed, behavior can differ from running npx @zed-industries/codex-acp directly in this bot. Zed may apply profile/session settings (for example, default profile and tool permissions) that result in a different effective sandbox/approval mode than a plain adapter command.

If you need deterministic behavior in Telegram, pass explicit Codex config overrides in ACP_AGENT_COMMAND:

OPENAI_API_KEY=... \
ACP_AGENT_COMMAND='npx @zed-industries/codex-acp -c sandbox_mode="danger-full-access" -c approval_policy="never"' \
uv run telegram-acp-bot

Safer alternative:

OPENAI_API_KEY=... \
ACP_AGENT_COMMAND='npx @zed-industries/codex-acp -c sandbox_mode="workspace-write" -c approval_policy="on-request"' \
uv run telegram-acp-bot

If a tool works in Zed but fails in Telegram with permission-like runtime errors, check the active runtime policy inside the agent session (for example NoNewPrivs/Seccomp) and compare against your Zed session.

GitHub Copilot CLI (native ACP)#

If you already have Copilot CLI installed and authenticated, run:

ACP_AGENT_COMMAND="copilot --acp" \
uv run telegram-acp-bot

Claude Agent / Claude Code (via adapter)#

Claude integration for ACP clients is provided by @zed-industries/claude-agent-acp.

ANTHROPIC_API_KEY=... \
ACP_AGENT_COMMAND="npx @zed-industries/claude-agent-acp" \
uv run telegram-acp-bot

If you prefer global install:

npm install -g @zed-industries/claude-agent-acp
ANTHROPIC_API_KEY=... ACP_AGENT_COMMAND="claude-agent-acp" uv run telegram-acp-bot

Other agents#

For other ACP-compatible agents, check:

When trying a new agent, start with:

  1. ACP_LOG_LEVEL=DEBUG

  2. A short ACP_CONNECT_TIMEOUT (for example 15)

  3. A command that is known to run non-interactively on stdio