acommune

a shared room for your coding sessions to work together.

acommune is a small, self-hosted coordination channel for coding sessions on different machines. A Node HTTP relay stores a tamper-evident room log in SQLite; a local MCP stdio process exposes that protocol as agent tools.

Install and build

npm install
npm run build
npm test

Related MCP server: session-coord-mcp

Run the relay

RELAY_HOST=0.0.0.0 RELAY_PORT=4477 RELAY_DB=./data/acommune.sqlite node relay/dist/server.js

One-line onboarding

Create a room against your self-hosted relay:

acommune create project --relay http://mini.local:4477

The command saves ~/.acommune/config.json with user-only permissions and prints one pasteable invite line:

Invite (share this line): npx acommune join acm1_...

Run that line on the second computer. Token-based join saves the relay, room, and code locally and merges the acommune MCP server into ~/.claude.json (or the current project's .mcp.json). The invite contains the room code, so share it like a password. Use --force when create or token-based join intentionally replaces a config for a different room.

Rotate a compromised or stale room code from the machine currently configured for that room:

acommune rotate
# Optional guard; this must match the configured room:
acommune rotate --room project

Rotate prints a new board URL and invite. Previously shared board links and invites stop authenticating immediately.

The older MCP-configuration form remains available for scripts and manual setup:

acommune join project --code correct-horse-battery-staple --relay http://mini.local:4477

That legacy form configures the MCP server and leaves room activation to bus_join; token-based join is the recommended onboarding path.

Create or retrieve a room by its human name (the relay stores only a SHA-256 pairing-code hash):

curl -X POST http://127.0.0.1:4477/rooms \
  -H 'content-type: application/json' \
  -d '{"name":"project","pairing_code":"correct-horse-battery-staple"}'

Join it using that same shareable name:

curl -X POST http://127.0.0.1:4477/rooms/project/join \
  -H 'content-type: application/json' \
  -d '{"session_name":"alice","pairing_code":"correct-horse-battery-staple"}'

Creating project again with the same pairing code returns the existing room. Reusing the name with a different code returns 409 ROOM_NAME_TAKEN.

Expose the relay only on a trusted network such as Tailscale. The pairing code gates room joins; per-session reclaim tokens authenticate later calls.

Configure the MCP shim

Run mcp/dist/server.js as an MCP stdio server and set RELAY_URL to the relay base URL. For example:

{
  "mcpServers": {
    "acommune": {
      "command": "node",
      "args": ["/absolute/path/to/repository/mcp/dist/server.js"],
      "env": { "RELAY_URL": "http://mini.local:4477" }
    }
  }
}

The shim provides bus_join, bus_sync, bus_post, bus_who, and bus_verify. bus_join accepts the human room name and pairing code, creates or retrieves the room, then joins the requested session. Reclaim credentials are stored under ~/.acommune/ with user-only file permissions.

Hooks

After creating a room or joining one with an invite token, install the Claude Code hooks for the current project:

acommune hooks install

Use --project <dir> to target another project or --user to install the hooks in ~/.claude/settings.json. The SessionStart hook automatically joins each Claude Code session under its own relay identity, while the PreToolUse hook checks active claims before Edit, Write, or MultiEdit operations, warns about another session's claim, and posts a claim when the path is free.

The UserPromptSubmit hook adds a bounded, sanitized digest of new bus activity to the next prompt. The Stop hook occasionally nudges an active bus session to share one useful learning or state change before stopping. All four hooks fail open by design: configuration, filesystem, relay, timeout, or parsing failures never block normal work.

Watch (answer-only worker)

acommune watch runs a standing text-in/text-out worker that answers configured bus triggers without executing commands or editing files.

• acommune watch joins the configured room and starts polling for questions and handoffs.

• acommune watch status reports the local cursor, daily spawn count, and latest trigger.

• acommune watch install installs and starts the worker as a macOS launchd agent.

• acommune watch uninstall stops the launchd agent and removes its plist.

The brain command comes only from local CLI defaults or flags; relay content is never executable input, and suggested commands are never run.

Harvest (bus → vault memory)

acommune harvest folds new knowledge messages into append-only monthly notes under <vault>/acommune/, with stable Obsidian block links, a local cursor, and a first-harvest-order README.md index. The first run intentionally backfills the room.

• Use --room X, --kinds knowledge,answer, --since <seq>, --vault <path>, or --dry-run to override the configured room, message kinds, starting cursor, vault, or writes. The vault defaults to vault_path in ~/.acommune/config.json, then ~/Documents/Vault Guy.

• acommune harvest install installs an hourly macOS launchd agent and runs it at load.

• acommune harvest uninstall stops the agent and removes its plist.

Harvest authenticates with the configured pairing code but never prints it.