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`](DESIGN.md) explains the isolation and
threat model. [`CLAUDE.md`](CLAUDE.md) is the complete maintainer and agent guide; [`AGENTS.md`](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:

```sh
./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:

```sh
./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:

```sh
./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:

```sh
.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:

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

Compose low-risk coordinator actions with `:` separators:

```sh
.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:

```sh
.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:

```sh
.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>
```

Each managed clone has a unique jj workspace name, a namespaced `agent/...` bookmark, and a
described working-copy change. Agents may rewrite their own change but must not move shared
bookmarks such as `master`; one integration owner acquires `integration/<bookmark>`, handles the
frozen candidate commit, and records the exact target.

Separate checkouts isolate repository files and build trees, not external services. Assign
workspace-specific ports, database/schema names, containers, and temporary/output directories
when concurrent agents run mutable services. Share dependency caches only when the cache itself is
safe for concurrent writers.

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:

```text
$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`](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:

```sh
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.