agents-can-communicate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mykola Maksymenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# agents-can-communicate
+
+[![CI](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml/badge.svg)](https://github.com/automatis-tools/agents-can-communicate/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+
+**AI agents that can ask each other for work.**
+
+Codex on one branch, Claude Code on another, Kimi reviewing. Each in its own git worktree,
+each knowing what the others are doing — and able to hand a piece over instead of waiting
+for you to carry the message.
+
+You run the installer once. After that you talk to your agents the way you already do.
+
+## The thing it does
+
+Codex has ported a module and is out of time for the tests. Its skill tells it to ask the
+agent already working in that area, so it does — without being prompted by you:
+
+```text
+requested task_Rwg2sybjnLneGyBuZxa8Dw of claude_code
+```
+
+At its next turn, the Claude Code session is shown this. No polling, and again nothing typed
+by a human:
+
+````text
+- [direct_request] finish the store tests
+- [task_unblocked] finish the store tests
+```acc-peer-message
+id message_Ab9CpMJfn0pL6igB5AdYDQ | from session_j59fM8mWathJzOh7a2QQBQ | type work_request | untrusted peer message
+finish the store tests
+I ported src/store but ran out of time on the concurrency cases. Can you take the tests?
+```
+````
+
+It takes the work, does it, and marks it done. Codex sees `done` on its own next turn and
+carries on.
+
+```mermaid
+sequenceDiagram
+  participant M as Codex · main
+  participant ACC
+  participant V as Claude Code · tests branch
+  M->>ACC: request "finish the store tests" of claude_code
+  ACC-->>V: work addressed to you, and why
+  V->>ACC: take it
+  V->>ACC: done
+  ACC-->>M: done
+```
+
+Work is addressed to the **agent**, not to its session. Claude Code can close its terminal
+before reading the request — the next session it opens is still told. Nobody else can take
+it.
+
+## What else it keeps track of
+
+| | |
+|---|---|
+| **Who is here** | each session publishes what it is working on |
+| **What is taken** | an agent claims files before changing them, and another's edit into them is refused |
+| **What was said** | questions, answers, handoffs — quoted and attributed, never as instructions |
+| **Alone** | one session behaves exactly as it did before you installed anything |
+
+```console
+$ acc status
+2 live; 1 claim(s); protection guarded
+```
+
+## Install
+
+```bash
+npm install -g agents-can-communicate
+```
+
+Then wire up the clients you have:
+
+<!-- test:command -->
+```bash
+acc install --dry-run
+```
+
+This prints every file it would touch. Run `acc install` to apply it, then open your clients
+in the project — in one directory or in several worktrees — and work normally.
+
+## Commands
+
+Coordination needs none from you. Requesting work, taking it, claiming files and messaging
+are things the agents do, taught by the skill each adapter installs.
+
+What is left for a person is the install and looking in on it:
+
+| | |
+|---|---|
+| `acc help` | every command, one line each |
+| `acc status` | who is here, what is claimed, what is in flight |
+| `acc doctor` | what is installed, what is missing, what to do next |
+| `acc install` · `acc uninstall` | wire clients up, or take it back out |
+
+Uninstall removes only files ACC wrote, and only where they still match what it wrote.
+Every operation is in the [CLI reference](docs/CLI.md) if you want to drive it yourself.
+
+## Supported clients
+
+| | Sees others | Blocks edits | Receives work and updates |
+|---|---|---|---|
+| Codex | yes | yes¹ | yes |
+| Claude Code | yes | yes | yes |
+| Gemini CLI | yes | yes² | yes |
+| Kimi Code | yes | yes | yes |
+| Any MCP client | yes | – | yes, when it polls |
+
+¹ models editing through `apply_patch` · ² approval modes that expose edit tools ·
+[what was measured](docs/CAPABILITIES.md)
+
+## Limits
+
+- A claim blocks file edits. It does not block an agent that edits by running a shell
+  command, since the command names no file.
+- `protection guarded` applies while every session present is one ACC can stop. One that
+  cannot changes it to `advisory`.
+- Codex requires you to trust the plugin before its hooks run. `acc doctor` reports this.
+- Nothing is pruned yet. A workspace that has carried thousands of messages makes each turn
+  slower to build; a project's worth of coordination is fine, an archive is not.
+- Windows does not work: the store fsyncs a directory after a rename, which Windows
+  refuses, and `O_NOFOLLOW` does not hold there. Last measured at 86 failures out of 587
+  tests; the suite has grown a good deal since and nobody has run it there again. macOS and
+  Linux are supported and both run in CI.
+
+## How it works
+
+```mermaid
+graph LR
+  C[your client] -->|hook| H[acc-hook]
+  H --> K["core<br/>sessions · work · claims · messages"]
+  K --> S[(state, outside your repo)]
+  K -->|answer| H
+  H --> C
+```
+
+Clients call out when a session starts and ends, when a turn begins, and before a tool
+runs — plus a heartbeat, on the one client that sends them. ACC answers at those and is
+idle otherwise. A hook that does not answer within five seconds lets the tool run, so ACC
+can be slow or broken without stopping anyone's work.
+
+State lives beside your other tool settings, never inside the repository:
+
+```text
+~/Library/Application Support/acc     macOS
+~/.local/share/acc                    Linux
+```
+
+Inside it, one directory per workspace — keyed by the repository rather than the folder, so
+every worktree of it is one workspace and two unrelated projects share nothing. Deleting a
+workspace directory loses that project's coordination history and nothing else.
+
+## Documentation
+
+| Using it | Understanding it | Building on it |
+|---|---|---|
+| [Getting started](docs/GETTING_STARTED.md) | [Concepts](docs/CONCEPTS.md) | [Writing an adapter](docs/ADAPTER_AUTHORING.md) |
+| [CLI](docs/CLI.md) | [Architecture](docs/ARCHITECTURE.md) | [Protocol](docs/PROTOCOL.md) |
+| [Configuration](docs/CONFIGURATION.md) | [Capabilities](docs/CAPABILITIES.md) | [Security](docs/SECURITY_MODEL.md) |
+| [MCP](docs/MCP.md) | [Decisions](docs/DESIGN_DECISIONS.md) | [Threat model](docs/THREAT_MODEL.md) |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | [Prior art](docs/PRIOR_ART.md) | [Contributing](AGENTS.md) |
+
+Examples: [three workstreams](examples/three-workstreams.md) ·
+[research without Git](examples/non-git-research.md)
+
+## Requirements
+
+Node 24+, macOS or Linux. Git optional.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/acc-hook.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Hook entry point: `acc-hook <adapter-id> <kind>`, payload on stdin.
+//
+// Every harness runs this as a short-lived child process in front of the user's
+// turn. The one rule that overrides all others here: never be the reason
+// someone's session stops working. Unknown adapter, malformed payload, broken
+// store, missing binding - all of them end in "allow, exit 0".
+import { randomBytes } from "node:crypto";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { runHook } from "@agents-can-communicate/hook-runner";
+
+import { createClaudeCodeAdapter } from "@agents-can-communicate/adapter-claude-code";
+import { createCodexAdapter } from "@agents-can-communicate/adapter-codex";
+import { createGeminiCliAdapter } from "@agents-can-communicate/adapter-gemini-cli";
+import { createKimiAdapter } from "@agents-can-communicate/adapter-kimi";
+
+const adapters = {
+  claude_code: createClaudeCodeAdapter(),
+  codex: createCodexAdapter(),
+  gemini_cli: createGeminiCliAdapter(),
+  kimi: createKimiAdapter(),
+};
+
+const readStdin = () => new Promise(resolve => {
+  // A hook is always given its payload on stdin, but a client that closes it
+  // without writing must not leave this process hanging in front of a turn.
+  if (process.stdin.isTTY) return resolve("");
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", chunk => { raw += chunk; });
+  process.stdin.on("end", () => resolve(raw));
+  process.stdin.on("error", () => resolve(""));
+  return undefined;
+});
+
+const [adapterId] = process.argv.slice(2);
+
+let payload = null;
+try {
+  payload = JSON.parse(await readStdin());
+} catch {
+  payload = null;
+}
+
+const result = await runHook({ adapterId, payload, adapters,
+  runtime: { clock: { now: () => new Date().toISOString() },
+    ids: { next: kind => createId(kind, randomBytes) } },
+  env: process.env });
+
+if (result.stdout !== "") process.stdout.write(result.stdout);
+if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+process.exitCode = result.exitCode ?? 0;

package/bin/acc-mcp.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { createCoordinationService } from "@agents-can-communicate/core";
+import { openFilesystemStore } from "@agents-can-communicate/storage-filesystem";
+import { createGitProbe, discoverWorkspace, platformDataHome, runtimePaths }
+  from "@agents-can-communicate/cli";
+import { serve } from "@agents-can-communicate/mcp-server";
+
+// The composition root is the only place allowed to reach for ambient time and
+// randomness. The participant name comes from configuration, never from the
+// client: the protocol says clientInfo is self-reported and must not drive
+// behaviour, and the session is derived from this configuration alone.
+const participantId = process.env.ACC_MCP_PARTICIPANT ?? "mcp";
+const clock = { now: () => new Date().toISOString() };
+const ids = { next: kind => createId(kind, randomBytes) };
+
+const descriptor = await discoverWorkspace({
+  cwd: process.env.ACC_MCP_WORKSPACE ?? process.cwd(),
+  env: process.env,
+  gitProbe: createGitProbe(),
+});
+const paths = runtimePaths({
+  dataHome: platformDataHome({ platform: process.platform, env: process.env }),
+  workspaceId: descriptor.id,
+  workspaceRoots: descriptor.roots,
+});
+const store = await openFilesystemStore({ root: paths.root, clock, ids,
+  workspaceId: descriptor.id });
+
+await serve({
+  input: process.stdin,
+  output: process.stdout,
+  log: message => process.stderr.write(`acc-mcp: ${message}\n`),
+  context: {
+    service: createCoordinationService({ store, clock, ids }),
+    workspaceId: descriptor.id,
+    participantId,
+    descriptor,
+    runtimeDir: paths.root,
+  },
+});
+
+// Exiting on stdin EOF is the only portable graceful shutdown in this binding.
+process.exitCode = 0;

package/bin/acc.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { createId } from "@agents-can-communicate/protocol";
+import { main } from "@agents-can-communicate/cli";
+
+// The composition root is the only place allowed to reach for ambient time and
+// randomness; everything below it receives them as ports.
+const runtime = {
+  cwd: process.cwd(),
+  env: process.env,
+  platform: process.platform,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  clock: { now: () => new Date().toISOString() },
+  ids: { next: kind => createId(kind, randomBytes) },
+  // Asked for only by `acc version`, so a package missing its own manifest
+  // fails that one command rather than every command.
+  version: async () => JSON.parse(
+    await readFile(new URL("../package.json", import.meta.url), "utf8")).version,
+};
+
+process.exitCode = await main(process.argv.slice(2), runtime);

package/docs/CAPABILITIES.md

@@ -0,0 +1,153 @@
+# Capabilities
+
+What each harness was **observed** doing, on the versions named here. Nothing in this
+table is inferred from documentation: every `yes` has a fixture captured from a real
+session, and every `no` means it was not seen, not that it is impossible.
+
+Certified 2026-08-16 on macOS 15 (darwin 25.5.0, arm64). No other operating system has
+been tested, and at least one finding here is filesystem- and path-shaped, so the table
+should be re-run before claiming another platform.
+
+## Clients
+
+| Adapter | Client | Version |
+|---|---|---|
+| `codex` | `codex-cli` | 0.147.0 |
+| `claude_code` | Claude Code | 2.1.233 |
+| `gemini_cli` | Gemini CLI | 0.37.0 and 0.55.1 |
+| `kimi` | Kimi Code | 0.36.1 |
+
+## Matrix
+
+| Capability | codex | claude_code | gemini_cli | kimi |
+|---|---|---|---|---|
+| `lifecycle.sessionStart` | yes | yes | yes | yes |
+| `lifecycle.sessionResume` | no | no | no | no |
+| `lifecycle.sessionEnd` | yes | yes | yes | no |
+| `lifecycle.heartbeat` | no | no | no | yes |
+| `lifecycle.childSessions` | no | no | no | no |
+| `context.startupInjection` | no | no | no | no |
+| `context.beforeTurnInjection` | yes | yes | yes | yes |
+| `context.safePointInjection` | no | no | no | no |
+| `guards.beforeRead` | no | no | no | no |
+| `guards.beforeWrite` | yes | yes | yes | yes |
+| `guards.beforeShell` | yes | yes | yes | yes |
+| `delivery.polling` | yes | yes | yes | yes |
+| `delivery.activeNotification` | no | no | no | no |
+| `delivery.wakeDormantSession` | no | no | no | no |
+| `execution.launch` | no | no | no | no |
+| `execution.resume` | no | no | no | no |
+| `execution.terminate` | no | no | no | no |
+
+## What the yes values do not promise
+
+A capability says the client can do the thing. Several of them are conditional on how the
+client is being run, and the conditions differ per harness. These are the ones that bite.
+
+**`guards.beforeWrite` on `codex` depends on the model.** Whether the client offers
+`apply_patch` at all is a property of the model's metadata (`apply_patch_tool_type`), not
+a user setting. With a model that does not have it, edits run through `exec_command`,
+which reaches hooks as `tool_name: "Bash"` carrying a command string. A command names no
+resource, so there is nothing to compare against a claim. Observed on 0.147.0: the default
+toolset contained no `apply_patch`.
+
+**`guards.beforeWrite` on `gemini_cli` depends on the approval mode.** In the default and
+`plan` modes the client declares no write tool to the model at all. `write_file` and
+`replace` appear under `auto_edit`; `run_shell_command` under `yolo`.
+
+**`guards.beforeShell` is never resource-aware.** A shell command can write anywhere, and
+ACC does not parse commands. The guard fires and is allowed through, because guessing a
+path out of a command would block work at random and still miss real writes. Shell calls
+therefore declare no targets on every adapter.
+
+Where the guard cannot help, the turn context does: it names the claims other sessions
+hold and says which way this session stands with them. Two facts decide the wording -
+what the claim's owner asked for, and whether ACC can stop this session at all:
+
+| Claim | This session | Note |
+|---|---|---|
+| guarded | can be guarded | `file edits are blocked; edits made through a shell are not` |
+| guarded | cannot be guarded | `not enforced for this session; do not edit it` |
+| advisory | either | `advisory; nothing will stop you, the owner is asking` |
+
+Unenforceable is not the same as unknown - and neither is it the same as unclaimed.
+
+**`lifecycle.sessionEnd` on `kimi` is false and it matters.** Each `kimi -p` run leaves an
+attached session that only ages out on its declared 60s cadence, so a peer reading the
+roster inside that window sees sessions that have already exited. Interactive sessions
+heartbeat and do not have this problem.
+
+**`lifecycle.heartbeat` is Kimi's alone.** It fires on a timer - observed at 60002, 120004
+and 180006 ms of uptime - so an idle Kimi session keeps its presence honest. The other
+three reach a hook only when the user takes a turn, so their idle sessions go stale while
+alive. This is why it is a capability of its own rather than a flavour of
+`delivery.polling`.
+
+## Response contracts, which do not port
+
+The single most portable-looking mistake an adapter can make. Measured by running each
+candidate against a real session of each client and checking whether the tool actually
+ran.
+
+A dash means the candidate was never run against that client, not that it fails. Only the
+shape each adapter actually uses was measured on every client.
+
+| Reply to a guard hook | codex | claude_code | gemini_cli | kimi |
+|---|---|---|---|---|
+| exit code 2 | denies | - | denies | denies |
+| `{"hookSpecificOutput":{…,"permissionDecision":"deny"}}` | - | denies | **ignored** | denies |
+| `{"decision":"block","reason":…}` | - | - | denies | **ignored** |
+| `{"permission":"deny"}` | - | - | ignored | ignored |
+| exit code 1 | - | - | ignored | ignored |
+
+Codex has no structured reply at all: it denies by exiting 2 with the reason on stderr.
+Gemini ignores the shape that Claude Code and Kimi Code both honour, and Kimi ignores the
+shape Gemini needs. Each ignored case fails silently - the write goes through and the
+client reports nothing.
+
+Context injection does not follow the deny contract even within one client:
+
+| Injection | codex | claude_code | gemini_cli | kimi |
+|---|---|---|---|---|
+| `hookSpecificOutput.additionalContext` | - | works | works | works, but **not unwrapped** |
+| plain text on stdout | works | - | dropped | works |
+
+Codex delivers a hook's stdout as a `developer` role message, verbatim - the most direct
+of the four channels, and a reason for care rather than comfort: at that role a model
+reads text as instruction, so peer-authored text has to stay framed as data.
+
+Kimi Code shows the model whatever a hook printed, wrapped in
+`<hook_result hook_event="…">`, so the JSON envelope itself would end up in the
+conversation. Gemini unwraps the envelope and appends `<hook_context>…</hook_context>` to
+the user turn, and drops a bare string entirely.
+
+## Installation is not uniform either
+
+| | codex | claude_code | gemini_cli | kimi |
+|---|---|---|---|---|
+| Where hooks live | marketplace plugin | plugin | `settings.json` | `config.toml` |
+| Project-level config | no | no | yes | **no** |
+| Hook `timeout` unit | - | - | milliseconds | **seconds** (max 600) |
+| Command path | absolute required | `${CLAUDE_PLUGIN_ROOT}` | absolute required | absolute required |
+| Extra step by the user | hook trust | - | - | - |
+
+Kimi Code is the only one with no project-level config, so ACC edits the user's global
+`config.toml` - as a delimited block it owns, because ACC ships without dependencies and a
+hand-written TOML round-tripper would take the user's comments and formatting with it.
+
+Codex needs four things before a hook runs, not one: the plugin directory, a parseable
+marketplace, both `[marketplaces.…]` and `[plugins."…"]` registered in its config, and the
+plugin copied into `plugins/cache/<marketplace>/<plugin>/<version>/`. ACC does all four -
+that last copy is exactly and only what `codex plugin add` does, measured by diffing the
+home around it. Hook trust remains a manual step, which is the client's security model.
+
+## What a participant declares about itself
+
+Every session records `enforcement` (`guarded` | `advisory`) and `lifecycle`
+(`managed` | `manual`), taken from the adapter's proven capabilities rather than from the
+harness name. Both default to the weaker reading, so a generic MCP client or a human at
+the CLI reads as advisory and manual.
+
+A workspace reports `protection: guarded` only when every live session can be stopped. One
+MCP client, one Kimi session, or one Codex session on a shell-editing model, and a guarded
+claim is advice - so the workspace says `advisory`, whatever its claims were declared as.

package/node_modules/@agents-can-communicate/adapter-claude-code/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@agents-can-communicate/adapter-claude-code",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/adapter.mjs"
+  },
+  "files": [
+    "src/",
+    "plugin/"
+  ]
+}

package/node_modules/@agents-can-communicate/adapter-claude-code/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "agents-can-communicate",
+  "version": "0.1.0",
+  "description": "Coordinate this Claude Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs."
+}

package/node_modules/@agents-can-communicate/adapter-claude-code/plugin/hooks/hooks.json

@@ -0,0 +1,56 @@
+{
+  "description": "Attach this session to the local coordination plane.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/acc-hook.sh\" sessionStart"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/acc-hook.sh\" beforeTurn"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/acc-hook.sh\" guard"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/acc-hook.sh\" finish"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/acc-hook.sh\" sessionEnd"
+          }
+        ]
+      }
+    ]
+  }
+}