agents-can-communicate 0.1.2 → 0.1.4

package/README.md

@@ -4,197 +4,166 @@
 [![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.**
+**Give every agent session a shared room for coordination. Keep your attention on the
+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.
+ACC is a local-first coordination layer for the AI agent sessions you already opened. It
+gives them shared presence, intent, claims, messages, and work requests while every
+session keeps its own authority.
 
-You run the installer once. After that you talk to your agents the way you already do.
+Coordination runs locally on your machine. Raw transcripts stay private. The runtime is
+built entirely on Node's standard library.
 
-## 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
+```mermaid
+flowchart TB
+  Y["You<br/>set direction"]
+  A["Agent session A"]
+  B["Agent session B"]
+  C["Agent session C"]
+  R["ACC shared room<br/>presence · intent · claims<br/>messages · work requests"]
+  O["Coordinated work<br/>with shared context"]
+
+  Y --> A
+  Y --> B
+  Y --> C
+  A <--> R
+  B <--> R
+  C <--> R
+  R --> O
 ```
 
-At its next turn, the Claude Code session is shown this. No polling, and again nothing typed
-by a human:
+## You opened more agents. You became the coordinator.
 
-````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?
-```
-````
+One session implements. Another writes tests. A third reviews. At first, more agents means
+more work gets done.
 
-It takes the work, does it, and marks it done. Codex sees `done` on its own next turn and
-carries on.
+Then you start copying context between windows. You warn two agents away from the same
+file. You relay a question, return with the answer, and try to remember which terminal was
+waiting for what. The agents are capable; they need a room they can share.
 
-```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
-```
+ACC gives them that room. Each session stays in its original client, checkout, and trust
+boundary. You still decide when it starts and stops. ACC only supplies the coordination
+that was previously passing through you.
 
-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.
+## A handoff the agents carry themselves
 
-## What else it keeps track of
+One agent finishes building a feature and sees that its final tests still need work. It
+asks the testing agent to take over, including a short summary of what is ready and what
+remains.
 
-| | |
-|---|---|
-| **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
+```mermaid
+flowchart LR
+  A["Feature agent<br/>finishes its part"] --> B["Requests tests<br/>from the testing agent"]
+  B --> C["ACC keeps the handoff<br/>ready for that agent"]
+  C --> D["Testing agent<br/>completes the work"]
+  D --> E["Result returns<br/>to the feature agent"]
 ```
 
+The request stays with the testing agent across terminal restarts. When that agent returns,
+it receives the handoff, completes the tests, and sends the result back. You choose the
+direction and review the outcome; the agents carry the context between them.
+
 ## Install
 
+Run these commands in a terminal on each macOS or Linux machine where your agent clients
+run:
+
 ```bash
 npm install -g agents-can-communicate
+acc install
 ```
 
-Then wire up the clients you have:
+The first command makes `acc` available across the machine. The second finds Codex,
+Claude Code, Gemini CLI, and Kimi Code installations and activates the integrations that
+are available. Codex completes activation after you trust the plugin; `acc doctor` shows
+the current state.
 
-```bash
-acc install
-```
+`acc install` names every client setting it activated and how to undo it.
 
-It names every file it wrote, in your own home-relative paths, and how to undo it. Open your
-clients in the project afterwards — in one directory or in several worktrees — and work
-normally.
+Open or restart your agent client inside a project. Each new session joins that project's
+room automatically. Open another session in the same project and the two can coordinate;
+run `acc status` from the project directory whenever you want to see the room yourself.
 
-If you would rather look before it writes, `acc install --dry-run` prints the same list and
-changes nothing. `acc uninstall` takes it all back out.
+ACC stores coordination data in the standard application-data location for your system.
+The defaults are `~/Library/Application Support/acc` on macOS and `~/.local/share/acc` on
+Linux. `XDG_DATA_HOME` relocates the Linux default; `ACC_DATA_HOME` overrides either
+platform, as described in [configuration](docs/CONFIGURATION.md). Project files stay
+unchanged. Git worktrees from one repository share a room, and plain folders receive the
+same coordination experience.
 
-<!-- test:command -->
-```bash
-acc install --dry-run
-```
+Keep ACC current with `acc update --apply`. It installs the latest release and refreshes
+the client integrations together. `acc doctor` points to that action when their versions
+drift.
 
-## Keeping it current
+Run `acc uninstall` to remove ACC's client integrations. Settings you changed remain
+yours.
 
-```bash
-acc update            # asks npm; --apply installs it and re-wires the clients
-```
+## What changes after installation
 
-An upgrade is two steps, because it lands in two places. `npm install -g` replaces the CLI
-and the hook runtime — a client runs the runtime out of the npm directory rather than a copy
-— and leaves the bundle written into that client alone, including the skills the agents
-read. `acc install` refreshes it, and `acc doctor` says so when the two disagree:
+**Agents know who is around.** Each session can see the other participants, their current
+focus, and the files they have claimed.
 
-```console
-$ acc doctor
-store healthy; 2 live session(s); protection guarded; 3 of 4 adapter(s) installed
-  acc install --adapter claude_code  # plugin is 0.1.1, acc is 0.2.0
-```
+**Parallel work becomes deliberate.** Agents claim shared files before editing. Supported
+client edits respect those claims and identify the participant already working there.
 
-`acc update` is the only command that reaches the network. `acc doctor` reads what it
-remembered and asks at most once a day; nothing on the hook path ever asks, since a hook
-runs on every turn inside a five-second budget. `ACC_NO_UPDATE_CHECK=1` turns both off.
+**Questions and work find their way back.** Requests, decisions, and handoffs stay with
+the intended agent across session restarts, and results return to the agent that asked.
 
-## Commands
+**Human authority stays clear.** Peer messages arrive with attribution and remain peer
+context. Your instructions and approved policy continue to set the boundaries.
 
-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.
+**Solo work stays quiet.** A single session receives the familiar client experience.
+Shared context appears when another participant or pending handoff makes it useful.
 
-What is left for a person is the install and looking in on it:
+## Fits the workflow you already have
 
-| | |
-|---|---|
-| `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
+Your agent client remains the place where sessions start, permissions are granted, and
+work happens. ACC joins at natural moments, shares the relevant context, and returns
+control to the client. Forward progress stays the priority during any coordination delay.
 
-```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
-```
+ACC currently connects directly to Codex, Claude Code, Gemini CLI, and Kimi Code. Other
+clients that support MCP can join the same room, see its activity, and exchange work when
+they sync.
 
-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.
+When a client exposes supported file edits, ACC can protect a claimed file before another
+agent changes it. Shell commands and separate local applications rely on visible claims
+instead. `acc status` explains the protection available in the current room.
 
-State lives beside your other tool settings, never inside the repository:
+Current support focuses on multiple sessions working in one project on one machine, on
+macOS or Linux. Each client retains its session lifecycle and full conversation history.
+The [capability evidence](docs/CAPABILITIES.md) records exactly what each integration has
+demonstrated in a real client.
 
-```text
-~/Library/Application Support/acc     macOS
-~/.local/share/acc                    Linux
-```
+ACC currently retains every coordination record. It is sized for an active project's
+history; thousands of messages make each turn slower to assemble, so use your project
+documentation for long-term archives.
+
+## Everyday controls
+
+The installed guidance teaches agents how to claim files, ask questions, request work,
+and complete handoffs. These commands give you a direct view and control when you want it:
+
+| Command | What it is for |
+|---|---|
+| `acc status` | See active sessions, claimed work, and the room's protection level |
+| `acc doctor` | Confirm which client integrations are active |
+| `acc update --apply` | Install the latest release and refresh integrations |
+| `acc uninstall` | Remove ACC's client integrations safely |
 
-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.
+Every operation is documented in the [CLI reference](docs/CLI.md).
 
-## Documentation
+## Keep exploring
 
-| 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) |
+- **Start using ACC:** [getting started](docs/GETTING_STARTED.md) ·
+  [configuration](docs/CONFIGURATION.md) · [troubleshooting](docs/TROUBLESHOOTING.md)
+- **Understand the promise:** [why ACC](docs/WHY_ACC.md) · [concepts](docs/CONCEPTS.md) ·
+  [capabilities](docs/CAPABILITIES.md) · [security](docs/SECURITY_MODEL.md)
+- **Build on ACC:** [MCP](docs/MCP.md) · [writing an adapter](docs/ADAPTER_AUTHORING.md) ·
+  [protocol](docs/PROTOCOL.md)
 
-Examples: [three workstreams](examples/three-workstreams.md) ·
-[research without Git](examples/non-git-research.md)
+See it in action: [three workstreams](examples/three-workstreams.md) ·
+[research in a plain directory](examples/non-git-research.md). Contributions start with
+[Repository Guidelines](AGENTS.md).
 
 ## Requirements
 
@@ -202,4 +171,4 @@ Node 24+, macOS or Linux. Git optional.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+Free and MIT-licensed. Use it, fork it, keep it — see [LICENSE](LICENSE).

package/bin/acc-mcp.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { randomBytes } from "node:crypto";
 
-import { createId } from "@agents-can-communicate/protocol";
+import { EXIT, 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 }
@@ -12,6 +12,18 @@ import { serve } from "@agents-can-communicate/mcp-server";
 // 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.
+// Nothing is read from the command line, so nothing may be passed on it. It
+// used to accept and ignore anything: writing `acc-mcp --cwd <project>` - the
+// habit `acc` teaches - started a server rooted wherever the client happened to
+// launch it, alone in a workspace nobody else was in, with no warning at all.
+if (process.argv.length > 2) {
+  process.stderr.write("acc-mcp takes no arguments. It is configured by environment:\n"
+    + "  ACC_MCP_PARTICIPANT   who this server takes part as (default: mcp)\n"
+    + "  ACC_MCP_WORKSPACE     the project it joins (default: the working directory)\n"
+    + `refusing: ${process.argv.slice(2).join(" ")}\n`);
+  process.exit(EXIT.USAGE);
+}
+
 const participantId = process.env.ACC_MCP_PARTICIPANT ?? "mcp";
 const clock = { now: () => new Date().toISOString() };
 const ids = { next: kind => createId(kind, randomBytes) };

package/docs/CAPABILITIES.md

@@ -1,5 +1,10 @@
 # Capabilities
 
+Capability honesty is part of the product, not an implementation footnote. ACC coordinates
+sessions it does not own, so the workspace can promise only what every session actually
+exposes. One weaker participant lowers the reported protection level instead of inheriting
+a stronger label from its peers.
+
 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.

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

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-claude-code",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,5 +1,5 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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-codex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-codex",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Coordinate this Codex session with other AI agent sessions working in the same workspace.",
   "license": "UNLICENSED",
   "keywords": ["coordination", "multi-agent", "claims", "handoff"],

package/node_modules/@agents-can-communicate/adapter-codex/src/install.mjs

@@ -1,4 +1,4 @@
-import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -11,22 +11,35 @@ import { AccError, EXIT } from "@agents-can-communicate/protocol";
 const bundle = fileURLToPath(new URL("../plugin", import.meta.url));
 const PLUGIN_NAME = "agents-can-communicate";
 
-// The marketplace ACC owns. Registering a separate one rather than editing the
-// user's keeps the two apart: uninstall removes a marketplace ACC created and
-// never touches entries someone else put in theirs.
+// The marketplace ACC owns, and its own root inside the agents home.
+//
+// Registering a separate one rather than joining the user's keeps the two
+// apart. ACC used to write into `<home>/.agents/plugins/marketplace.json` -
+// which is the marketplace this client discovers by itself, with no config
+// entry at all, under whatever that manifest calls itself. So ACC merged its
+// entry into someone else's marketplace and then enabled `…@acc-local`, an id
+// this client never forms: `acc install` reported success and `codex plugin
+// list` said `not installed`. Measured against Codex 0.147.0, then measured
+// again to confirm a root of ACC's own is accepted and reported enabled.
 const MARKETPLACE = "acc-local";
 const QUALIFIED = `${PLUGIN_NAME}@${MARKETPLACE}`;
 
-// A marketplace is a directory whose manifest sits at
-// `<root>/.agents/plugins/marketplace.json`, and every `source.path` in that
-// manifest is relative to the manifest's own directory - `./plugins/<name>`,
-// as the client's own entries are written. Resolving the plugin from `root`
-// instead put the files two levels above where the manifest pointed, so the
-// entry named a directory that did not exist and the client loaded nothing.
-const marketplaceDir = root => path.join(root, ".agents", "plugins");
-const marketplacePath = root => path.join(marketplaceDir(root), "marketplace.json");
-const pluginPath = (root, name = PLUGIN_NAME) =>
-  path.join(marketplaceDir(root), "plugins", name);
+// A marketplace is a root holding `.agents/plugins/marketplace.json`, and every
+// `source.path` in that manifest - `./plugins/<name>` - is resolved by this
+// client against the *root*, not against the manifest's directory. Measured:
+// `codex plugin list` prints the path it resolved, and for a plugin the user
+// installed themselves it printed `<root>/plugins/x` from an entry spelled
+// `./plugins/x`. The comment that used to be here said the opposite, and ACC
+// wrote its tree two directories below where the client then looked.
+//
+// The root is under `.agents/` rather than the home itself: `<home>/plugins/`
+// is where this client would put it, and nothing of ACC's belongs at the top of
+// somebody's home.
+const marketplaceRoot = agentsHome => path.join(agentsHome, ".agents", MARKETPLACE);
+const marketplacePath = agentsHome =>
+  path.join(marketplaceRoot(agentsHome), ".agents", "plugins", "marketplace.json");
+const pluginPath = (agentsHome, name = PLUGIN_NAME) =>
+  path.join(marketplaceRoot(agentsHome), "plugins", name);
 const configPath = codexHome => path.join(codexHome, "config.toml");
 // Where `codex plugin add` leaves the copy it actually runs. All three
 // components are ACC's own - the marketplace it created, the plugin name it
@@ -111,6 +124,11 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // plugin tree is laid down that nothing will then be able to remove.
   const existing = await readJson(marketplacePath(agentsHome), { name: MARKETPLACE,
     interface: { displayName: "Agents Can Communicate" }, plugins: [] });
+  // The name in the manifest, which is the one this client forms plugin ids
+  // from. ACC used its own regardless, so on a machine that already had a
+  // marketplace at this root - discovered without any config entry, under
+  // whatever its manifest calls itself - the id ACC enabled was one the client
+  // never forms, and the plugin sat there listed and not installed.
   const before = await readFile(configPath(codexHome), "utf8").catch(() => "");
 
   const target = pluginPath(agentsHome);
@@ -142,7 +160,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
   await writeTomlBlock(config, [
     `[marketplaces.${MARKETPLACE}]`,
     `source_type = "local"`,
-    `source = ${tomlString(agentsHome)}`,
+    `source = ${tomlString(marketplaceRoot(agentsHome))}`,
     "",
     `[plugins.${tomlString(QUALIFIED)}]`,
     "enabled = true",
@@ -156,13 +174,26 @@ export async function installCodexPlugin({ home, agentsHome = home,
   await rm(cached, { recursive: true, force: true });
   await cp(target, cached, { recursive: true });
 
-  // The cache *root* rather than the versioned directory inside it: that is
-  // what ACC owns and what uninstall removes, and reporting the version would
+  // The plugin's own directory in the cache. Not the versioned one inside it,
+  // which goes stale the moment the version changes - and not the marketplace
+  // cache root above it, which belongs to whoever's marketplace this is: that
+  // root holds every plugin installed from it, and removing it took a plugin
+  // the user had installed themselves. Measured, on a real machine.
+  //
+  // The old comment here said the root was "what ACC owns", which was true only
+  // while ACC invented its own marketplace name and so had a root to itself.
   // make the record stale the moment the plugin version changes.
-  return { ok: true, changes: [target, file, config, cacheRoot(codexHome)],
+  return { ok: true, changes: [target, file, config, cachePath(codexHome)],
     diagnostics: ["hooks require explicit trust in Codex before they run"] };
 }
 
+/** Remove each directory that is empty, in the order given. */
+async function removeEmptyDirs(directories) {
+  for (const directory of directories) {
+    await rmdir(directory).catch(() => {});
+  }
+}
+
 export async function uninstallCodexPlugin({ home, agentsHome = home,
   codexHome = path.join(home, ".codex"), keep = [] }) {
   const file = marketplacePath(agentsHome);
@@ -190,8 +221,20 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
       return value?.name === MARKETPLACE && (value.plugins ?? []).length === 0;
     } });
 
-  await removeInstalledTree(cacheRoot(codexHome), keep);
+  await removeInstalledTree(cachePath(codexHome), keep);
   await removeInstalledTree(pluginPath(agentsHome), keep);
+  // The directories ACC made to hold those, once nothing is in them. They are
+  // ACC's own - a marketplace root it created and the cache directory named
+  // after it - and an empty one left behind is litter in a home that did not
+  // have it. Anything the user put inside stops this: the directory is not
+  // empty, and it stays.
+  await removeEmptyDirs([
+    path.join(marketplaceRoot(agentsHome), "plugins"),
+    path.dirname(marketplacePath(agentsHome)),
+    path.dirname(path.dirname(marketplacePath(agentsHome))),
+    marketplaceRoot(agentsHome),
+    cacheRoot(codexHome),
+  ]);
   return { ok: true, changes, diagnostics: [] };
 }
 
@@ -202,7 +245,8 @@ export async function detectCodex({ home, agentsHome = home,
   const config = await readFile(configPath(codexHome), "utf8").catch(() => "");
   const registered = config.includes(`[marketplaces.${MARKETPLACE}]`);
   const enabled = config.includes(`[plugins."${QUALIFIED}"]`);
-  const cached = await stat(cachePath(codexHome)).then(() => true).catch(() => false);
+  const cached = await stat(cachePath(codexHome))
+    .then(() => true).catch(() => false);
   return { ok: true, changes: [], diagnostics: [
     published ? "acc plugin published in the marketplace" : "acc plugin not registered",
     registered && enabled
@@ -228,7 +272,7 @@ export function planCodexInstall({ home, agentsHome = home,
   codexHome = path.join(home, ".codex") }) {
   return [
     { path: pluginPath(agentsHome), kind: "tree" },
-    { path: cacheRoot(codexHome), kind: "tree" },
+    { path: cachePath(codexHome), kind: "tree" },
     { path: marketplacePath(agentsHome), kind: "merge" },
     { path: configPath(codexHome), kind: "merge" },
   ];

package/node_modules/@agents-can-communicate/adapter-gemini-cli/extension/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Coordinate this Gemini CLI session with other AI agent sessions working in the same workspace.",
   "contextFileName": "skills/acc/SKILL.md"
 }

package/node_modules/@agents-can-communicate/adapter-gemini-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-gemini-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/adapter-kimi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-kimi",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Coordinate this Kimi Code session with other AI agent sessions working in the same workspace: shared presence, resource claims, typed messages, and handoffs.",
   "skills": "./skills/",
   "sessionStart": {

package/node_modules/@agents-can-communicate/adapter-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/adapter-sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/cli/src/help.mjs

@@ -62,7 +62,7 @@ const DOCS = "https://github.com/automatis-tools/agents-can-communicate"
 
 export function helpText() {
   const width = Math.max(...Object.keys(COMMANDS).map(name => name.length)) + 4;
-  const lines = ["acc - several agents in one workspace, none of them in charge", ""];
+  const lines = ["acc - coordinate the agent sessions you already opened", ""];
   for (const { heading, commands } of describeCommands()) {
     lines.push(heading);
     for (const { name, summary } of commands) {

package/node_modules/@agents-can-communicate/cli/src/runtime-paths.mjs

@@ -23,11 +23,24 @@ export function runtimePaths({ dataHome, workspaceId, workspaceRoots = [] }) {
   // Enforced here rather than only asserted in a test, because "just put it in
   // .agents next to the project" is the exact regression this design exists to
   // prevent, and it would otherwise look like it works.
+  //
+  // The message names both paths and what to do, because the case a person
+  // actually meets is not the one this was written for. Running `acc` in a home
+  // directory makes that directory the workspace - it is no checkout, so
+  // discovery falls back to where you are - and the platform's own state
+  // directory is inside a home by definition. So `acc status` in `~` answered
+  // "runtime state must not live inside the workspace", which reads as a
+  // misconfiguration and tells the reader nothing they can act on.
   for (const workspaceRoot of workspaceRoots) {
     const relative = path.relative(workspaceRoot, root);
     if (relative === "" || (!path.isAbsolute(relative) && !relative.startsWith(".."))) {
-      throw new AccError(EXIT.USAGE, "runtime state must not live inside the workspace",
-        { root, workspaceRoot });
+      throw new AccError(EXIT.USAGE,
+        // The data home rather than the workspace's own directory inside it:
+        // that is the one a reader can move, and the one the remedy names.
+        `${workspaceRoot} holds ACC's own state at ${path.join(dataHome, "acc")}, `
+        + "so it cannot be a workspace. Run acc inside a project, or point "
+        + "ACC_DATA_HOME outside this directory.",
+        { root, dataHome, workspaceRoot });
     }
   }
   return Object.freeze(Object.fromEntries([["root", root],

package/node_modules/@agents-can-communicate/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/hook-runner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/hook-runner",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/installer",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": { ".": "./src/index.mjs" },

package/node_modules/@agents-can-communicate/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/protocol",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/node_modules/@agents-can-communicate/storage-filesystem/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agents-can-communicate/storage-filesystem",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": true,
   "type": "module",
   "exports": {

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "agents-can-communicate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
-  "description": "Model- and harness-agnostic coordination for independent AI agent sessions.",
+  "description": "Local-first coordination for independently opened AI agent sessions.",
   "keywords": [
     "agents",
     "coordination",
+    "local-first",
+    "agent-handoff",
     "mcp",
     "hooks",
     "codex",