\n\nGrackle runtime that drives any agent speaking the Agent Client Protocol (ACP) over stdio.\n\n## Overview\n\nThe [Agent Client Protocol (ACP)](https://agentclientprotocol.com) is a JSON-RPC protocol, framed as newline-delimited JSON over stdio, that lets a client drive a coding agent: initialize, authenticate, create a session, send prompts, and receive streamed session updates. This runtime spawns an ACP-compatible agent CLI as a subprocess and talks to it over its stdin/stdout — so a single implementation can drive many different agents (e.g. Goose, `codex-acp`, Copilot, the Claude agent ACP bridge).\n\n`AcpRuntime` implements the `@grackle-ai/runtime-sdk` runtime interface (extending `BaseAgentRuntime` / `BaseAgentSession`) and is loaded by the Grackle PowerLine, which registers one runtime per configured ACP agent. Each session translates ACP session updates into Grackle `AgentEvent`s (text, thoughts, tool calls/results, plans, and usage), auto-approves permission requests, and forwards MCP servers to the agent.\n\n## Configuration\n\n`AcpRuntime` is constructed with an `AcpAgentConfig`, which names the runtime and describes the agent CLI to spawn:\n\n| Field | Type | Default | Description |\n| --------------------- | ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `name` | `string` | — | Runtime name used for registry lookup and the isolated install directory (e.g. `\"codex-acp\"`) |\n| `command` | `string` | — | Agent command to spawn (e.g. `\"codex-acp\"`, `\"copilot\"`, `\"goose\"`) |\n| `args` | `string[]` | — | CLI arguments passed to the command (e.g. `[\"--acp\", \"--stdio\"]`) |\n| `env` | `Record` | — | Additional environment variables for the subprocess |\n| `isolateClaudeConfig` | `boolean` | `false` | Point `CLAUDE_CONFIG_DIR` at a clean, Grackle-managed dir so the agent does not inherit the developer's personal `~/.claude/settings.json`. Set for Claude-backed bridges (e.g. `claude-code-acp`), whose headless permission-mode enum rejects interactive-only settings such as `permissions.defaultMode: \"auto\"`. Existing credentials are symlinked (or copied) into the isolated dir so auth is preserved. |\n\nThe Grackle PowerLine registers several ACP agents out of the box:\n\n| Runtime name | Command | Args |\n| ----------------- | ------------------ | --------------- |\n| `goose` | `goose` | `acp` |\n| `codex-acp` | `codex-acp` | — |\n| `copilot-acp` | `copilot` | `--acp --stdio` |\n| `claude-code-acp` | `claude-agent-acp` | — |\n\nThe ACP SDK (`@agentclientprotocol/sdk`) is installed lazily into an isolated per-runtime directory (`~/.grackle/runtimes//`) the first time a session starts; that directory's `.bin` is prepended to the subprocess `PATH`.\n\n## Credentials\n\nCredentials are passed through to the agent subprocess via the process environment (plus any `env` overrides in the config). During ACP `initialize`, the runtime inspects the agent's advertised auth methods and, if an `env_var` method is offered whose required variables are all present in the environment, calls `authenticate()` with it. This is required by some bridges (e.g. Copilot) and is a best-effort, non-fatal step for others (e.g. `codex-acp`, `claude-code-acp`). Each agent defines its own required credential variables.\n\n## Requirements\n\n- Node.js >= 22\n- An ACP-compatible agent CLI available on `PATH` (or installed into the runtime's isolated directory), e.g. `goose`, `codex-acp`, `copilot`, or `claude-agent-acp`\n- Whatever credentials the chosen agent requires, supplied via the environment\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"npm](\"https://img.shields.io/npm/v/@grackle-ai/runtime-acp.svg\")
\n ![\"CI\"](\"https://github.com/nick-pape/grackle/actions/workflows/ci.yml/badge.svg?branch=main\"){kind=icon}
\n ![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg\"){kind=icon}
\n![\"Grackle\"](\"https://raw.githubusercontent.com/nick-pape/grackle/main/apps/docs-site/static/img/grackle-logo.png\"){kind=logo}
\n