worktree-agent-coordination

Shared, untracked Markdown status files and personal lifecycle hooks for coding agents working in parallel across Git worktrees.

This package is a lightweight collaboration blackboard, not an agent launcher or task orchestrator. Each agent owns one concise status file, while every worktree sees the same statuses through Git's shared common directory.

Install and initialize

Install once for your user:

npm install --global worktree-agent-coordination

Then run one command in every repository where you want coordination:

cd your-repository
agent-coord init

That is the complete onboarding flow. init automatically:

• enables coordination under <git-common-dir>/agent-coordination/;
• registers personal activation rules and lifecycle hooks for detected Claude Code, Codex, Cursor, and Grok Build installations;
• adds /.worktrees/ to the user's global Git ignore;
• preserves existing personal instructions and ignore rules;
• makes no changes to the repository working tree.

It is safe to run init repeatedly.

What gets registered

| Agent | Personal registration | Automatic lifecycle | | --- | --- | --- | | Claude Code | Marked block in ~/.claude/CLAUDE.md | Hooks merged into ~/.claude/settings.json | | Codex | Marked block in ~/.codex/AGENTS.md | Hooks merged into ~/.codex/hooks.json | | Cursor | Local plugin under ~/.cursor/plugins/local/worktree-agent-coordination/ | Hooks bundled with the local plugin | | Grok Build | Dedicated rule at ~/.grok/rules/worktree-agent-coordination.md | Dedicated file under ~/.grok/hooks/ |

Only installations whose personal configuration directory already exists are registered. Restart or reload an agent application after its first registration.

No repository AGENTS.md, CLAUDE.md, Cursor rule, or .gitignore is created or edited. Teammates who do not install the package are unaffected.

Codex requires users to review new or changed personal command hooks. After initialization, open /hooks once in Codex and trust the agent-coord hooks. Other supported agents may also display their normal hook-registration notice.

Upgrading

Update an existing global installation to the latest release:

npm install --global worktree-agent-coordination@latest
agent-coord --version

After upgrading, run init once inside any repository where coordination is already enabled:

agent-coord init

This refreshes personal rules and lifecycle hooks, including support added in newer releases, without removing active statuses or changing repository files.

How agents coordinate

In an initialized repository, supported agents now follow this automatic lifecycle:

1. SessionStart creates one deterministic, session-owned status file. The raw session ID is hashed and is not stored.
2. The first matching shell, edit, write, patch, or MCP tool is paused once. The agent receives its ID, active peer summaries, and a required status-update command.
3. Later matching tool calls refresh the status lease and record file paths exposed by tool input.
4. The agent is instructed to remove its status after its last relevant tool and before its final response.
5. SessionEnd removes any remaining status automatically. A 24-hour hook lease prunes records left by crashes or forced termination.

The first-tool pause does not ask the user for approval. It denies that single tool invocation with a coordination message; the agent records its task, reviews peers, and retries. This closes the gap where an agent loads a personal rule but silently ignores it.

Personal rules also require the agent to run:

agent-coord context

The command is silent in repositories that have not been initialized. In an initialized repository, it returns the strict beginning-and-end policy and active statuses.

Hooks are a reliability layer, not a full task tracker. Agents still keep the concise task, files, decisions, and concerns current:

agent-coord read --exclude "agent-a1b2c3d4"

agent-coord update "agent-a1b2c3d4" \
  --task "Add ACH retry handling" \
  --status "testing" \
  --file "src/payments/retry.js" \
  --decision "Retry eligibility remains on Payment"

When finished or abandoned:

agent-coord remove "agent-a1b2c3d4"

For agents without native hook support, the manual lifecycle remains available:

agent-coord start --task "Add ACH retry handling" --file "src/payments/retry.js"
agent-coord remove "agent-a1b2c3d4"

The policy explicitly tells agents not to investigate neighboring worktrees to infer another agent's plans. Peer status files are the coordination interface.

Storage

Every worktree resolves the same directory with:

git rev-parse --path-format=absolute --git-common-dir

The resulting layout is:

<git-common-dir>/agent-coordination/
├── enabled.json
├── agent-a1b2c3d4.md
└── agent-e5f6a7b8.md

Because this directory is inside Git metadata, it is untracked, is not committed, and cannot create merge conflicts between worktrees.

CLI

agent-coord init [--json]
agent-coord context
agent-coord hook --provider <agent> --event <event>
agent-coord start --task <description> [options]
agent-coord update <agent-id> [options]
agent-coord read [--exclude <agent-id>] [--json]
agent-coord remove <agent-id> [--json]
agent-coord path [--json]
agent-coord instructions [agents|claude|both]

Run agent-coord --help for the complete option list.

The instructions command remains available for users who want paste-ready repository instructions, but init does not use or modify repository instruction files.

hook is the internal, stdin-driven adapter used by installed lifecycle hooks. It is public for debugging and integration but normally should not be run by hand.

JavaScript API

import {
  initializeRepository,
  isRepositoryInitialized,
  readStatuses,
  removeStatus,
  startStatus,
  updateStatus,
} from "worktree-agent-coordination";

await initializeRepository();

if (await isRepositoryInitialized()) {
  const mine = await startStatus({
    task: "Refactor account authorization",
    files: ["src/auth/account.js"],
  });

  const peers = await readStatuses({
    excludeAgentId: mine.agentId,
  });

  await updateStatus(mine.agentId, {
    status: "testing",
    decisions: ["Preserve the existing policy interface"],
  });

  await removeStatus(mine.agentId);
  console.log(peers);
}

All repository-aware methods accept an optional { cwd }. The small JS API also exports handleHookEvent, normalizeHookInput, createSessionIdentity, and DEFAULT_HOOK_LEASE_MS for custom integrations.

Status format and safety

Each status is concise Markdown with structured metadata:

# Agent: agent-a1b2c3d4

**Task:** Add ACH retry handling

**Status:** testing

## Files and areas

- src/payments/retry.js

## Decisions

- Retry eligibility remains on Payment

Writes use a temporary file followed by an atomic filesystem operation. Agent IDs are validated before becoming filenames, and creating an already-active ID fails instead of overwriting its owner. Hook-owned IDs are derived from a SHA-256 hash of provider plus session ID, so the same session can update and remove exactly its own file without writing the raw session ID to disk.

Ownership is instruction-enforced rather than operating-system-enforced because coding agents normally run as the same user. Normal SessionEnd cleanup is best-effort because an application cannot fire a hook after a hard kill or machine crash; the hook-only lease handles those leftovers on the next status read. Manual statuses do not expire automatically. There are no hard locks, remote state, background services, or databases.

Development

npm install
npm test
npm run test:coverage
npm run pack:dry-run

See PUBLISHING.md for GitHub and npm release instructions.

License

MIT