Content
# acp-install
> **Control the tool call, control the agent.**
> See and stop what your coding agent actually does — every command, edit, and fetch — with one control layer that works the same across Claude Code, Cursor, and Codex. Free, on your machine, no account.
<p align="center">
<img src="demo/acp-local-demo.gif" width="820" alt="Real terminal recording: one command installs ACP local mode with no signup; a coding agent's force-push to main is blocked by the safety floor, a network call has to ask, normal work runs and is logged — and the same policy stops Codex too. tail ~/.acp/audit.jsonl shows every call and its decision.">
</p>
<p align="center"><sub>Real recording, nothing mocked — <a href="demo/README.md">how it's made / re-record it yourself</a>. 60 seconds: install → agent blocked → asked → allowed → the audit log.</sub></p>
```bash
curl -sf https://agenticcontrolplane.com/install.sh | bash -s -- --local
```
One command. It detects whichever agents you run and puts the same guardrails in front of all of them:
- **A safety floor nothing can cross** — `rm -rf /`, `mkfs`, `dd` to a disk, a fork bomb, a force-push to `main` are blocked regardless of your policy (and regardless of how the command is spelled).
- **Your rules, one file** — `~/.acp/policy.json`: `allow` / `ask` / `deny` per tool, applied identically to every agent.
- **A log of what actually happened** — `tail -f ~/.acp/audit.jsonl` and watch the calls your agent made, on-device. Nothing leaves your machine.
The same policy that stops Claude Code stops Codex. You configure control once, not once per vendor. Outgrow on-device? Re-run without `--local` to connect a workspace — team control, cost X-ray, and a shared console across everyone's agents. The local runtime is the free individual on-ramp; the cloud is the team upgrade.
Works on macOS + Linux. Requires Node 18+ and one of: Claude Code, Cursor, OpenAI Codex CLI, OpenClaw.
Want the long version first? [Every file the installer writes, in plain language](https://agenticcontrolplane.com/install-explained) · [getting started](https://agenticcontrolplane.com/getting-started) · per-client guides for [Claude Code](https://agenticcontrolplane.com/integrations/claude-code) and [Codex CLI](https://agenticcontrolplane.com/integrations/codex)
## What the installer does
For whichever AI clients it detects:
1. **Writes `~/.acp/govern.mjs`** — a shared hook dispatcher script that sends every tool call to the ACP governance API and enforces allow/deny decisions locally.
2. **Registers PreToolUse + PostToolUse hooks** in the client's config:
- Claude Code: `~/.claude/settings.json`
- Cursor: `~/.cursor/hooks.json`
- Codex: `~/.codex/hooks.json`
3. **For Codex only** — wires three layers:
- Enables `[features].codex_hooks = true` in `~/.codex/config.toml`
- Adds `[mcp_servers.acp]` for non-Bash tool governance via MCP (with runtime credential substitution — no API key in your dotfiles)
- Writes an ACP section in `~/.codex/AGENTS.md` instructing Codex to call `acp_check` before non-Bash tool invocations
4. **Opens a browser** for OAuth to provision an ACP workspace and mint an API key
5. **Saves the key to `~/.acp/credentials`** (mode 0600)
6. **Installs the `claude-acp` cost-X-ray wrapper** (`~/.acp/bin`) and adds one marked PATH line (`# acp-installer`) to your shell rc
In **`--local` mode**, steps 4–6 and every other piece of cloud wiring are skipped entirely: no OAuth, no MCP server, no cost wrapper, no shell-rc edits. Hooks + the on-device engine only. (Codex note: its hooks cover shell commands today; non-Bash Codex tools aren't hookable yet — in cloud mode the MCP connector covers them.)
The installer is **idempotent**: running it again upgrades existing entries in place without duplicating them or touching unrelated hooks/policies you've configured.
## Trust signals
- **Source**: [`install.sh`](install.sh) — one self-contained script, read it top-to-bottom
- **SHA-256**: [`https://agenticcontrolplane.com/install.sh.sha256`](https://agenticcontrolplane.com/install.sh.sha256) — auto-updates on every Agentic Control Plane release
- **License**: MIT
- **Dry read**: `curl -sf https://agenticcontrolplane.com/install.sh | less`
- **Commit history**: every change is here in this repo
The canonical install URL is `agenticcontrolplane.com/install.sh` (served from the marketing site). This repo is the auditable mirror.
## What this script will NOT do
- Run any non-interactive commands without prompting if creds already exist (it asks "Reconfigure? (y/N)")
- Install to directories you don't own (`$HOME/.acp/`, `$HOME/.codex/`, `$HOME/.claude/`, `$HOME/.cursor/` only)
- Phone home to any server other than `api.agenticcontrolplane.com` and (during auth) `cloud.agenticcontrolplane.com` — **and in `--local` mode, nothing leaves your machine at all** (decisions run on-device from `~/.acp/decide.mjs` + `~/.acp/policy.json`; no network calls)
- Modify anything outside the client config files documented above (cloud mode adds exactly one marked PATH line to your shell rc for `claude-acp`; local mode touches no rc files)
- Install binaries or compile anything — it's a pure shell + Node.js script
## Uninstall
```bash
# Remove the ACP directory (credentials + govern.mjs)
rm -rf ~/.acp
# Remove the hooks from each detected client's config:
# - ~/.claude/settings.json remove the "govern.mjs" entries under hooks.PreToolUse[] and hooks.PostToolUse[]
# - ~/.cursor/hooks.json remove the "govern.mjs" entries under hooks.preToolUse[] and hooks.postToolUse[]
# - ~/.codex/hooks.json remove the "govern.mjs" entries under hooks.PreToolUse[] and hooks.PostToolUse[]
# - ~/.codex/config.toml remove the [mcp_servers.acp] block and [features].codex_hooks line
# - ~/.codex/AGENTS.md remove the block between <!-- acp:begin --> and <!-- acp:end --> markers
# - ~/.zshrc / ~/.bashrc remove the PATH line marked "# acp-installer" (cloud mode only)
```
A one-line `uninstall.sh` is planned. Until then, the blocks above are small enough to remove by hand.
## Reporting issues
- **Install broke something**: open an issue here → [github.com/agentic-control-plane/acp-install/issues](https://github.com/agentic-control-plane/acp-install/issues)
- **Governance behavior questions**: [agenticcontrolplane.com/faq](https://agenticcontrolplane.com/faq)
- **Integration details per client**: [agenticcontrolplane.com/integrations](https://agenticcontrolplane.com/integrations)
## License
MIT — see [LICENSE](LICENSE).
Not a coding-agent CLI? Framework agents use [acp-governance-sdks](https://github.com/agentic-control-plane/acp-governance-sdks); Hermes Agent uses [hermes-acp-plugin](https://github.com/agentic-control-plane/hermes-acp-plugin) (`pip install hermes-acp`).
