coord/README.md

coord

coord is a small, harness-neutral coordinator for concurrent Claude Code, Codex, and other repository agents. It combines:

• exact five-word agent and workspace handles;
• transactional resource leases and durable messages in host-local SQLite;
• isolated Jujutsu clones with recorded lifecycle, integration, and cleanup evidence;
• tmux launch, resume, attach, and safe-close operations using immutable tmux object IDs;
• shared lifecycle and write-conflict hooks for Claude Code and Codex; and
• a concise coord skill installed for both harnesses.

The standalone project is the source of truth. DESIGN.md explains the isolation and threat model. CLAUDE.md is the complete maintainer and agent guide; AGENTS.md front-loads its most important rules.

Requirements

• Python 3 with the standard-library sqlite3 module
• Jujutsu (jj) and Git for managed independent clones
• tmux plus codex-direct and/or claude-direct for managed interactive sessions

The coordinator itself has no third-party Python dependencies.

Install or upgrade a repository

Choose a stable project ID shared by every clone of the same logical project:

./install /path/to/repository --project-id my-logical-project

On later upgrades, omit --project-id; the installer preserves the existing value and refuses a conflicting one:

./install /path/to/repository
./install /path/to/repository --check

--check is read-only and exits nonzero on drift. Installation preflights all source files, identity, wrappers, and hook JSON before replacing any target file.

For a version-aware diagnosis and an explicit repair workflow, use:

./install /path/to/repository --doctor
./install /path/to/repository --repair
.coord/coord --version

--doctor reports the source and installed versions, lists every stale or missing managed file, and prints the exact repair command. An older installation without a version marker is reported as unversioned. --repair uses the same fully preflighted, atomic replacement path as an ordinary upgrade and preserves unrelated hooks, settings, skills, and repository content. Run these commands from the authoritative standalone coord checkout whose release you want to compare. A vendored .coord/install . --doctor can detect damage within its own installed release, but it cannot discover a newer standalone release by itself.

An installation provides:

Path	Purpose
.coord/	Canonical CLI, hook/runtime modules, installer, docs, skill source, and project ID
.agents/skills/coord/	Codex/project skill, including UI metadata
.claude/skills/coord/	Claude Code copy of the same skill
.claude/coord/	Compatibility shims for older sessions and instructions
.codex/hooks.json	Merged Codex lifecycle and write-conflict hooks
.claude/settings.json	Merged Claude lifecycle and write-conflict hooks

The installer replaces only hooks that invoke known coord endpoints. It preserves unrelated hooks and unrelated settings. It does not alter the target repository’s AGENTS.md, CLAUDE.md, VCS history, or runtime database.

Codex pins hook source hashes and may prompt to trust a changed hook after an upgrade. Review and approve it with /hooks; that prompt is an intentional harness security boundary.

The source release is recorded in VERSION using semantic MAJOR.MINOR.PATCH form and is vendored as .coord/VERSION. Maintainers bump it whenever installed behavior or packaging changes: major for incompatible changes, minor for backward-compatible functionality, and patch for compatible fixes. Version equality is informational; byte-for-byte doctor checks remain authoritative for detecting drift within a release.

Everyday use

Hooks normally register the current runtime and export enough identity for commands to infer it. Use the canonical entry point from the repository root:

.coord/coord list
.coord/coord claim tests/checks.nix -p "add cache checks"
.coord/coord send "I am changing the cache schema" --to '*'
.coord/coord release tests/checks.nix

Use append only when simultaneous additions cannot overwrite one another:

.coord/coord claim tests/checks.nix --mode append -p "append one independent check"

Compose low-risk coordinator actions with : separators:

.coord/coord batch claim docs/plan.md -p "revise plan" : send "plan claimed" --to '*'

The batch stops at the first failure and is deliberately not atomic. Destructive workspace and external publication actions are excluded.

Create an isolated Jujutsu clone before writable concurrent work:

.coord/coord work create cache-audit
.coord/coord work list
.coord/coord work gc

work create prints the exact five-word work handle and path. Then use that handle for lifecycle operations:

.coord/coord work start <work-handle> --harness codex
.coord/coord work attach <work-handle> --execute
.coord/coord work park <work-handle> --reason "waiting for review"
.coord/coord work resume <work-handle>
.coord/coord work inspect <work-handle>

Managed windows have short human-readable names, while mutations target immutable tmux IDs. work close safely closes the recorded window without dropping the operator to an outer shell. work remove is conservative: inspect its refusal, integration, gate, and confirmation requirements before cleanup.

Run coord COMMAND --help or coord work COMMAND --help for the complete option surface. Legacy --sid, --paths, and similar spellings remain accepted for compatibility but are hidden; new instructions should rely on inferred identity, positional operands, and readable optional flags.

Command map

Command	Role
coord hello	Register a live runtime; normally called by lifecycle hooks
coord heartbeat	Renew runtime presence and held leases
coord bye	End a runtime attachment without ending its durable conversation
coord claim / coord renew / coord release	Manage transactional resource leases
coord list	Show live agents, leases, and optionally work records
coord send / coord inbox / coord ack	Deliver and acknowledge durable messages
coord check	Ask whether a resource is blocked; used by write hooks
coord audit	Export deterministic audit events
coord batch	Compose guarded low-risk actions separated by :
coord remote verify	Read and verify an authoritative remote bookmark
coord work …	Create, inspect, run, integrate, recover, and clean managed work

State, identity, and portability

Runtime state defaults to:

$XDG_STATE_HOME/fleet-agent-coord/<project-id>.sqlite3

or ~/.local/state/fleet-agent-coord/… when XDG_STATE_HOME is unset. The directory and SQLite files are private to the user. COORD_DB selects a different database, and COORD_PROJECT_ID overrides project discovery for controlled testing. The historical fleet-agent-coord directory name is retained so existing deployments do not silently split their state.

The managed-clone default is /var/tmp/fleet-audit, retained for compatibility with the original deployment. Use work create --scratch-root /safe/local/path when that directory is inappropriate. The cleanup registry never scans arbitrary directories or guesses ownership.

Five-word handles are collision-checked aliases. Full UUIDs and full VCS object IDs remain the authoritative stored evidence; prefixes and shortened IDs never authorize mutations.

Skills

The canonical repository skill source is skills/coord/SKILL.md. An installation retains it at .coord/skills/coord/ and puts identical discovery copies under both supported harness paths. Invoke it explicitly as $coord, or let its description trigger when coordinating agents, claiming shared resources, creating isolated work, handling messages, managing tmux sessions, or cleaning up managed work.

The skill is intentionally concise. Detailed architecture stays in .coord/DESIGN.md, while repository-specific policies belong in the target repository’s own agent instructions.

Develop and validate

This repository is a colocated Jujutsu repository. Use jj, not Git, for status and history:

jj st
jj diff
python3 -m unittest discover -s tests -v
python3 -m py_compile coord hook.py install session.py store.py workspace.py
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/coord

For an installer change, test both a fresh install and an in-place legacy upgrade. Do not publish or force-update a remote without explicit authorization. No remote is configured by default.