Install an agent runtime

A runtime in AACWorkflow is the daemon on your machine paired with one AI coding tool the daemon found on your PATH. If the onboarding "Connect a runtime" step shows No supported tools detected, it means the daemon scanned PATH and didn't find any of the 16 tools it knows how to drive. Install one (or several) of the tools below, then come back to the step and re-scan — the runtime will show up within a few seconds.

This page is the install-side companion to:

• Daemon and runtimes — how detection works
• AI coding tools matrix — what each tool can and can't do (session resumption, MCP, model selection)

Before you start

Two prerequisites apply to every tool below:

1. The AACWorkflow daemon must be running. Either run aacworkflow daemon start after installing the AACWorkflow CLI, or use the AACWorkflow desktop app, which launches the daemon automatically. Without a running daemon there is nothing to detect tools.
2. The tool's binary must be reachable on PATH. The daemon shells out to each tool by name (see the Daemon looks for column in each section). If which <name> doesn't find it in your terminal, the daemon won't find it either. After installing, open a fresh terminal (or restart the daemon) so the new PATH entry is picked up.

After installing a tool, restart the daemon:

aacworkflow daemon restart

Or, in the desktop app, just relaunch the app. The daemon re-scans PATH on every start.

The 16 supported tools

Listed roughly from most to least common. Pick whichever ones you already have credentials for — you don't need all 16.

Claude Code (Anthropic)

The most complete integration. Session resumption works, MCP works, and it consumes the mcp_config field on agents (see the matrix).

Codex (OpenAI)

JSON-RPC 2.0 transport with finer-grained approval gates. MCP config is written into the per-task $CODEX_HOME/config.toml. Session resumption works through Codex app-server thread/resume; stale or missing threads fall back to a fresh thread.

Cursor (Anysphere)

The CLI counterpart to the Cursor editor. Session resumption works with current Cursor Agent releases: AACWorkflow reads session_id from the stream-json events and passes it back with --resume <id>.

For authenticated MCP servers, Cursor stores OAuth state in the project data directory where the auth flow first ran. AACWorkflow isolates managed Cursor MCP runs with a per-task CURSOR_DATA_DIR, so it does not scan or copy every file under ~/.cursor/projects. To opt in for one agent, set the agent custom env key CURSOR_MCP_AUTH_SOURCE to the absolute path of the trusted mcp-auth.json file, or to the Cursor project data directory containing that file. AACWorkflow links or seeds only that mcp-auth.json into the isolated task project data directory. When symlinks are supported, Cursor token refreshes may write back to the trusted source; environments that cannot create symlinks fall back to copying the file.

GitHub Copilot

Model routing goes through your GitHub account entitlement — the tool doesn't pick a model itself; GitHub decides which model you get.

OpenCode (SST)

Commercial CLI agent. Dynamically discovers available models from its own configuration file — good fit for users who want to bring their own model catalog. Consumes the agent's mcp_config field through OPENCODE_CONFIG_CONTENT.

DevEco Code (Huawei)

DevEco Code is Huawei's independent coding agent for HarmonyOS, built on the OpenCode engine. It ships its own model catalog and Huawei-account auth. AACWorkflow drives it over deveco run --format json; models are discovered dynamically from deveco models (built-in deveco/GLM-5.1). MCP servers are configured through DevEco's native config (DEVECO_CONFIG_CONTENT); AACWorkflow-side mcp_config wiring is in progress.

Kiro CLI (Amazon)

ACP-over-stdio transport. Session resumption works through ACP session/load; MCP config is passed through ACP mcpServers; skills are copied into .kiro/skills/.

Kimi (Moonshot)

ACP-protocol agent, primarily aimed at the Chinese market. MCP config is passed through ACP mcpServers; skills live under .kimi/skills/ (native discovery).

Hermes (Nous Research)

ACP-protocol agent (shares the transport with Kimi). Session resumption works, and MCP config is passed through ACP mcpServers. Hermes discovers skills only from its home (~/.hermes/skills/), so when an agent has skills assigned AACWorkflow points HERMES_HOME at a per-task overlay of your ~/.hermes/ (real home mirrored by symlink; a derived config.yaml references your existing skills as external roots) and writes the assigned skills into its skills/ directory for native discovery. The SQLite state.db session store and its journal files remain task-local, so host conversation history is neither linked nor copied and live Windows WAL locks cannot block setup. Tasks with no assigned skills run against your real home unchanged.

OpenClaw

Commercial CLI agent orchestrator. MCP config is materialized through AACWorkflow's per-task config wrapper. Model is bound at the agent layer (openclaw agents add --model) — it can't be overridden per task, and you can't pass --model or --system-prompt from AACWorkflow.

Pi (Inflection AI)

Minimalist. Session resumption is unusual — the resume id is the path to a session file on disk, not a string id.

CodeBuddy (Tencent)

A Claude Code–compatible CLI agent. AACWorkflow drives it with the same stream-json protocol as Claude Code: session resumption works via --resume, MCP config is passed through --mcp-config. CodeBuddy ships its own native config directory rather than reusing Claude's, so skills land in .codebuddy/skills/ and the runtime brief is written to CODEBUDDY.md. Models are discovered dynamically.

Qoder (Alibaba)

Agentic coding CLI using the ACP protocol over stdio (shares the transport with Hermes, Kimi, and Kiro CLI). Session resumption works through ACP session/resume, MCP config is passed through ACP mcpServers, model selection is discovered dynamically, and skills are copied into .qoder/skills/.

Trae CLI (ByteDance)

ByteDance's official TRAE CLI (traecli, paired with the Trae IDE — not the open-source bytedance/trae-agent). It is ACP-native, so AACWorkflow drives it over stdio via traecli acp serve --yolo, sharing the transport with Hermes, Kimi, Kiro CLI, and Qoder. Session resumption works through ACP session/load, MCP config is passed through ACP mcpServers, model selection is discovered dynamically (switched per task via session/set_model), and skills are copied into .traecli/skills/.

Antigravity (Google)

Google's Antigravity CLI (agy). Pairs with Google's Antigravity service and runs Gemini-backed models. AACWorkflow launches it with agy -p, the daemon-compatible non-interactive mode; current Antigravity CLI releases can execute tools from that mode, while agy -i requires an attached TTY. Session resumption works through --conversation <id>, captured by the daemon from the CLI log file. Model selection is managed inside the Antigravity CLI itself — AACWorkflow disables the per-agent model picker for this provider. Skills are written to .agents/skills/ (the CLI inherits Gemini CLI's workspace skill layout — see Antigravity docs).

Grok (xAI)

xAI's Grok Build CLI (grok). AACWorkflow drives it over ACP via grok --no-auto-update agent --always-approve stdio, sharing the transport with Hermes, Kimi, Kiro CLI, Qoder, and Trae. It selects an auth method advertised by initialize and completes the headless authenticate handshake before any session operation. Session resumption works through ACP session/load. Models are discovered from session/new. MCP config is passed through ACP mcpServers. Skills are copied into .grok/skills/; user skills are discovered from $GROK_HOME/skills/ (default ~/.grok/skills/) and ~/.agents/skills/.

After installing

1. Confirm the binary is on PATH. Open a fresh terminal and run which <name> (for example which claude, which cursor-agent, which kiro-cli, which agy). If it prints a path, the daemon will find it. If it prints nothing, fix your shell PATH first (the typical cause is a per-shell rc file that wasn't reloaded).
2. Restart the daemon. aacworkflow daemon restart, or relaunch the desktop app. The daemon only scans PATH at startup.
3. Check the Runtimes page. In the AACWorkflow UI, the Runtimes page should now list one row per (workspace × tool) combination. If the row says "offline", see Daemon and runtimes → When a runtime is marked offline.
4. Go back to onboarding. The "Connect a runtime" step polls and will pick up the new runtime within a few seconds — no need to refresh.

Troubleshooting

• which finds the binary but the daemon doesn't. The daemon was started with an older PATH. Restart it.
• The binary exists but launching fails. Run the tool's own --version or --help once from the terminal — most failures here are missing auth, expired tokens, or a Node.js / runtime mismatch.
• The Runtimes page shows the row, but tasks fail immediately. Check aacworkflow daemon logs -f while triggering a task. The daemon surfaces the tool's own error output.

For broader symptoms, see the Troubleshooting guide.

Next

• Daemon and runtimes — how detection, heartbeats, and offline handling work
• AI coding tools matrix — capability differences once a tool is connected
• Creating and configuring agents — pick a tool for your agent and start running tasks