ACP Runtimes

ACP Runtimes

TitanX integrates with 17 Agent Communication Protocol (ACP) runtimes out of the box. An ACP runtime is an external AI CLI that TitanX spawns as a child process and drives over stdin/stdout using a shared protocol.

---

The supported runtimes

Runtime	Vendor	Typical model	How TitanX detects it
Claude Code CLI	Anthropic	Claude Sonnet/Opus	claude on $PATH
Gemini CLI	Google	Gemini 2.5 Pro/Flash	gemini on $PATH
Codex	OpenAI	GPT-5 / o1 / o3	codex on $PATH
OpenCode	SST / OpenCode	Variable	opencode on $PATH
Goose	Block	Variable	goose on $PATH
Qwen Code	Alibaba	Qwen-Coder	qwen on $PATH
GitHub Copilot CLI	GitHub	GPT-4-ish	gh copilot
CodeBuddy	Tencent	Hunyuan / Claude	codebuddy on $PATH
Factory Droid	Factory.ai	Claude	factory on $PATH
Cursor CLI	Cursor	Variable	cursor-agent
Kiro	Kiro	Variable	kiro on $PATH
iFlow	iFlow	Variable	iflow on $PATH
Mistral Vibe	Mistral	Mistral family	vibe on $PATH
Qoder	Qoder	Variable	qoder on $PATH
Auggie	Augment Code	Variable	auggie on $PATH
Kimi	Moonshot	Kimi K2	kimi on $PATH
nanobot	(open spec)	Variable	nanobot on $PATH

Detection runs on every TitanX launch and takes ~300ms. Results surface in the hire modal as available runtime badges.

---

Why use ACP runtimes vs. direct APIs

Both work. TitanX supports both for every LLM provider that ships a CLI. The trade-offs:

Property	ACP CLI	Direct API (via provider adapter)
Auth	CLI's own (OAuth, subscription)	Your API key in TitanX's vault
Cost	Often flat-rate via subscription	Per-token metered
Features	Whatever the CLI supports (slash commands, tools, etc.)	What the provider's API exposes
Startup latency	2–5s CLI spawn on first turn	~200ms HTTP
Session caching	TitanX caches the CLI process per agent (idle 30min)	Stateless
Tools	CLI's own tool ecosystem (MCP servers it auto-loads)	TitanX's unified tool layer
Best for	Subscription users, CLI-heavy workflows, access to beta features	Pay-as-you-go, high concurrency, API-exclusive models

You can mix freely — one team can have a Claude Code teammate, a Gemini API teammate, and an OpenCode CLI teammate all coordinating via the same mailbox.

---

How the ACP adapter works

┌──────────────┐   stdin (JSON-RPC)    ┌─────────────┐
│   TitanX     │  ──────────────────→  │   ACP CLI   │
│  main proc   │  ←──────────────────  │  (child pty)│
└──────────────┘   stdout (streaming)  └─────────────┘

For each agent using an ACP runtime, TitanX:

1. Spawns the CLI with pty (node-pty) so ANSI escape codes + interactive prompts work
2. Sends the agent's system prompt + first user message as the initial turn
3. Streams output back, parsing it incrementally for:
   • Assistant text (goes to the conversation)
   • Tool calls (routed through TitanX's tool layer)
   • Status signals ([thinking], [idle], [turn_complete])
4. On turn completion, keeps the process alive in an idle pool (default 30min timeout) for the next turn
5. On agent removal or timeout, cleanly SIGTERMs the child

Session caching (performance win)

First turn: CLI spawn (2–5s) + first token latency Subsequent turns in the same agent: ~100ms — the CLI is already warm, session resumed, context preserved

This is why teams running long multi-turn flows stay snappy even with ACP runtimes.

---

Configuring a runtime

TitanX auto-configures everything it can detect. Manual adjustments live in Settings → ACP:

• Re-detect runtimes — force a rescan of $PATH after you install a new CLI
• CLI paths — override the detected binary path per-runtime (useful for multiple installations or wrappers)
• Session caching — per-runtime timeout (default 30min)
• Sandbox mode — for Codex specifically, pick workspace-write or danger-full-access depending on what you want the CLI to be able to touch

---

Installing a runtime

TitanX doesn't install runtimes for you — they're upstream tools with their own install procedures. Quick-start commands for the most common:

Claude Code CLI

npm install -g @anthropic-ai/claude-code

Gemini CLI

npm install -g @google/gemini-cli

Codex

npm install -g @openai/codex

OpenCode

npm install -g opencode

Goose

brew install block/tap/goose-cli

After installing, restart TitanX (or Settings → ACP → Re-detect) and the new runtime appears in the hire modal.

---

When a runtime isn't detected

Symptoms: runtime missing from hire modal, or "not installed" chip in Settings → ACP.

Debug checklist:

1. Confirm the binary is on PATH

   which claude  # or gemini, codex, etc.

2. Confirm TitanX's PATH matches your shell's PATH — Electron apps on macOS inherit a limited PATH; if you installed via Homebrew to /opt/homebrew/bin, TitanX may not see it. Fix by launching TitanX from terminal:

   open -a TitanX  # or use the terminal

   Or add /opt/homebrew/bin to the default PATH via Settings → Advanced.
3. Try explicit path — Settings → ACP → [Runtime] → CLI path → set absolute path

---

Per-turn behavior

When you send a message to an ACP-backed agent:

• First turn: ~2–5s CLI spawn + ~1–3s first-token latency = 3–8s to first reply
• Subsequent turns: ~100ms handshake + ~500ms–2s first-token = under 2s typically
• Long turns: no upper limit imposed by TitanX, but the team's timeoutMs (default 120s for farm teammates) will abort

Cost accounting piggybacks on the CLI's own usage output when the CLI emits it (Claude Code emits structured token counts; others vary). For CLIs that don't emit costs, TitanX estimates from output-char length × provider rate.

---

Custom runtimes

Building your own ACP-compatible CLI? TitanX can drive anything that speaks the Agent Communication Protocol. See Adding an ACP Runtime for the integration walkthrough.

---

Related pages

• Agents and Teams — how runtimes plug into agent slots
• Hiring Agents from the Gallery — the runtime picker in the hire modal
• Adding an ACP Runtime — contributing a new runtime to core
• Environment Variables — TITANX_ACP_* overrides