# Getting started Install ACC, open the AI sessions you already use in clients from different vendors, such as Claude Code and Codex, and give them related work. Supported integrations make peers visible and teach each agent how to communicate. You do not need to carry messages between windows or add coordination instructions to your task prompts. Active hooks can supply each agent's own CLI arguments; the installed skill tells the agent how to use them. This path was observed in Claude Code 2.1.263, Codex 0.153.4, and Grok 1.0.24. Grok receives its own header after a terminal result, so its skill runs public status first; peer messages still require explicit inbox reads. Hooks must be enabled and trusted by the client. Without that owner context, owned operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session). ## 1. Install once on this machine ACC requires Node.js 24 or newer on macOS, Linux, or Windows 10 or 11. On Windows, read [Windows](#windows) below first. Already using ACC? Follow the [upgrade guide](UPGRADING.md#from-09x): from 0.9.x, each store moves to contract 7 once no session still runs 0.9.x code. ```bash npm install -g agents-can-communicate ``` ```bash acc install ``` Initial installation also enables automatic updates; reinstalling keeps an explicit opt-out. ACC downloads releases in the background and refreshes its runtime and skills when active clients have left. Use `acc update` for an immediate update; an eligible Codex service restart asks for one confirmation. ACC then handles maintenance and reports progress in `acc doctor`; clients disconnect and can be resumed afterward. Use `acc update --auto off` to disable background updates. See [update controls](UPGRADING.md#automatic-updates-after-installation). The installer connects only the supported clients it finds. Open a new terminal and restart any running clients so they load their integrations. Follow the activation steps printed by the installer. In Codex, use `/plugins` to check ACC is enabled, then `/hooks` to review each ACC hook and enable/trust its current definition if needed. Restart the session after that review; changed hook definitions may require trust again. For Codex live delivery, follow the outgoing-permission and local-service instructions from install/doctor, then start a new session. Default workspace permissions can be configured automatically on Codex 0.153.4 or newer. Custom settings are preserved; see [outgoing permissions](CONFIGURATION.md#codex-outgoing-permissions). With legacy sandbox settings, the named ACC state directory must also be in `sandbox_workspace_write.writable_roots` in the config the installer identifies. ACC keeps those user settings unchanged. Installed files alone do not establish that hooks are active; `acc doctor` leaves current readiness unverified and directs you to Codex. Read the delivery summary for each client. Live delivery needs an explicit opt-in and a verified channel in the current session. Codex can save your choice even when its local service is not running yet. Declining uses the reported fallback: `acc inbox`, or next-turn hooks wherever the client is at or after a captured version. An interactive install asks one default-No question for all selected clients that need a choice. Use `--delivery actionable|all` for explicit noninteractive consent. Use `--delivery off` to disable incoming automatic requests. A dry run does not ask, write configuration, download Codex, or start a service. On macOS or Linux with Codex 0.154.0 through 0.157.0, the choice includes downloading a missing standalone package from OpenAI; Codex 0.157.1 and newer install the service's own package when it first starts. ACC selects the matching version and keeps your existing npm or Homebrew command and shell profiles. When supported Codex service preparation succeeds, it means the infrastructure is ready. Start a Codex session and complete the client's hook and trust review to establish a session-bound channel. An incomplete existing standalone installation or unsupported CLI version still needs the vendor action named by install. Claude Code's experimental live delivery wakes the session through the inbox that Claude Code opens for every session. After you opt in, start Claude Code with your ordinary command. ACC adds no launch flag, shell change or wrapper. A session in `bypassPermissions` mode asks you to approve each ACC wake. See [held or dropped wakes](TROUBLESHOOTING.md#a-claude-code-session-holds-or-drops-acc-wakes). The feature is off by default, can spend model tokens, and requires Claude Code 2.1.282 or newer. Local sessions in Claude.app's Code tab wake the same way; its Cloud, SSH and Cowork sessions run on another machine. You do not need it for durable messages or supported next-turn delivery. ## 2. Open two sessions and give them ordinary tasks Start each client normally in the same project. ACC does not launch, supervise, or assign work to either session. For example: | Session | Your prompt | |---|---| | Codex | Add an account-registration endpoint. | | Claude Code | Build the account-registration screen. | Those are complete prompts. The integration tells each agent that peers are present and provides the coordination instructions. If an agent notices that the screen depends on the endpoint contract, it can identify the peer, ask for the request and response shape, and continue with the answer. The sessions may use different supported clients or two instances of the same client. Same-client addresses can be ambiguous when several instances are live; agents use the exact participant ids in the roster when needed. See [Concepts](CONCEPTS.md) for participant and session identity. A second repeatable pattern is review and handoff. Ask the implementing agent to request review of an identified revision (a commit when Git is available, or named files and version otherwise) and wait for the verdict. Ask the reviewer to return blocking defects or approval. If either session must stop, it can leave a durable handoff naming completed work, remaining work, and blockers. A later session can recover it from history. The underlying commands are [`acc request`](CLI.md#messages-and-requests), exact [`acc inbox --message`](CLI.md#inbox-reply-and-acknowledgement), [`acc reply`](CLI.md#inbox-reply-and-acknowledgement), and [`acc finish`](CLI.md#handoff). For a continuation, tell the receiving agent which work it may take and any limits. It checks the relevant artifacts, replies with its accepted scope and first step, then continues within those limits. A completed original goal plus excluded follow-ups is not an automatic new assignment. Acknowledging the context alone does not mean the peer accepted work; if that agreement matters before the sender leaves, obtain it before `finish`, which closes the sender's ACC presence. ## 3. Watch for useful coordination Look for an agent discovering a peer, publishing the files it expects to change, noticing a shared dependency, asking a focused question, or answering one in the same thread. These events appear in the agent's normal activity; the exact presentation depends on the client. ACC provides awareness and communication tools. It cannot guarantee that a model will notice every dependency or coordinate on every task. Each agent decides whether a peer is relevant under its own instructions, context, and permissions. The commands behind that activity belong to the agents' installed skill. They can publish intent, make an advisory or guarded claim, send and reply to messages, acknowledge a thread, and leave a handoff. If you want to inspect that interface, use the [CLI reference](CLI.md) or follow the interaction through [How ACC works](HOW_IT_WORKS.md). ## 4. Know when messages arrive Every message is recorded before ACC attempts faster delivery. Every participant has a durable inbox, which is the universal recovery path. From the version each capture records onward, Codex, Claude Code, Gemini CLI, Kimi Code and Antigravity CLI can receive a message at the next normal turn, on any platform. That does not wake an idle session. Grok, generic MCP clients and clients older than every capture use the durable inbox instead. Antigravity CLI carries one extra condition: its hooks are given a project directory only when the session has an open workspace. A session started without one attaches nothing, and the client shows no hook output to say so - `acc doctor` names it. Codex LocalDaemon and the Claude Code inbox wake offer optional native delivery. They are experimental and can spend tokens. Codex queues a message until a running turn finishes. A busy Claude Code session takes the wake between two tool calls. Claude Code requires 2.1.282 or newer and recorded opt-in, and it wakes through the inbox that each session opens itself. Codex requires 0.152.1 or newer, LocalDaemon infrastructure, recorded opt-in, and a verified session. A new Codex chat becomes addressable before its first message: `acc status` registers it. Supported explicit setup can prepare a missing service. Start the client with your normal command. A loaded daemon thread can receive messages for about a minute after its terminal exits, until the daemon unloads it and ACC closes its session. Antigravity CLI 1.2.7 and later has one too: with delivery enabled, ACC's context asks the agent to start a relay from its own shell, up to three times while none is running, and you approve that command at the client's prompt. Antigravity also asks before each shell command, so install adds a rule that lets ACC's own commands run without that prompt, and a woken session can answer while you are away; see [Antigravity CLI command approval](CONFIGURATION.md#antigravity-cli-command-approval). Antigravity 2.0, the desktop app, runs the same hooks under its own language server, and ACC delivers into its conversations through that server: nothing for the agent to start. The app keeps its own command grants in `~/.gemini/config/config.json`; install adds ACC's rule there once the app has run. After the app restarts, a conversation is reachable again from its next turn. Chats in the Codex app run on the app's own server and get messages at their next turn. [Capabilities](CAPABILITIES.md) explains policy, versions and fallback. Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`. An offer is not proof that the model read anything, retrieval is not proof of attention, and a reply settles the communication obligation rather than proving that work is complete. ## 5. Keep the workspace boundary clear ACC is local to the same machine and operating-system user. Git worktrees of one repository share an ACC workspace while keeping their separate checkout facts. Git is optional, but two unrelated plain folders do not share a workspace merely because people consider them the same project. Messages and runtime state live in platform app data outside the repository. ACC never collects or shares raw transcripts. An optional `acc.workspace.json` can provide a stable workspace id, multiple roots, or project policy; it is user-requested configuration, not runtime state. See [Configuration](CONFIGURATION.md) and the [non-Git example](https://github.com/automatis-tools/agents-can-communicate/blob/main/examples/non-git-research.md). ## Diagnose or remove it If a peer does not appear or delivery differs from what you expected, run this from the project directory: ```bash acc doctor ``` The report names detected clients, installed integrations, exact capability downgrades, and the next action. Continue with [Troubleshooting](TROUBLESHOOTING.md). To remove ACC's integrations: ```bash acc uninstall ``` Uninstall removes only bytes ACC wrote that still match its install record. User edits are reported and preserved. ## Windows ACC runs natively on Windows 10 and 11, with no WSL. Install it the same way, in PowerShell or in a Command Prompt: ```powershell npm install -g agents-can-communicate acc install ``` What is different on Windows: - ACC keeps its state in `%LOCALAPPDATA%\acc`, never in the roaming profile. - Each client's hooks run a small Node script instead of a shell script, in the form that client's hook runner reads. `node` must be on `PATH` for Grok and Antigravity CLI hooks. Claude Code needs 2.1.139 or later. - Live delivery reaches a running session as on macOS and Linux: Claude Code through its inbox pipe, Codex through its app-server daemon, Antigravity CLI through ACC's relay. Codex starts its daemon only from a terminal that is not running as administrator. - Antigravity CLI cannot run a hook whose path is quoted. When your profile path has a space, ACC writes the path's 8.3 short name. ACC adds no allow rule on Windows, so Antigravity CLI asks before each ACC command. - The first hook after the machine starts can take a few seconds, because ACC reads the process tree through WMI, in Windows Script Host or, where Script Host is off, PowerShell. If it runs out of time, the session attaches on the first prompt instead. Next: [Why ACC](WHY_ACC.md) · [Capabilities](CAPABILITIES.md) · [CLI](CLI.md) · [Troubleshooting](TROUBLESHOOTING.md)