CovenDocs
CLI ReferenceWorkRepo Workflow

Repo Workflow

Reference for coven wt, claim, hooks, ward, familiar-ledger, and adapter commands.

4 min read

These commands implement the Coven Parallel Work Protocol around a git repository, plus the Ward, familiar-ledger, and adapter surfaces the sessions depend on.

Worktrees

coven wt (aliases: worktree, worktrees) keeps every parallel session in its own git worktree so git operations do not race. Worktrees live in a sibling <repo>.wt/<branch> directory:

coven wt fix/output-polish   # create (or re-enter) a worktree for the branch
coven wt --list              # branch, dirty state, active claim, path
coven wt --list --json       # machine-readable
coven wt --doctor            # layout and hook check; exits 1 on problems
coven wt --prune-merged      # remove clean worktrees merged into the primary branch
coven wt --prune-stale 14    # remove clean worktrees untouched for 14 days

Exactly one action per invocation. coven wt <branch> prints the worktree path, so it composes:

cd "$(coven wt fix/output-polish)"

Claims

coven claim manages TTL-bounded branch claims — shared locks that make intent visible so parallel sessions do not duplicate work. Claims live under the repository's common git dir, so every worktree sees the same registry.

coven claim status              # active and expired claims (--json available)
coven claim acquire issue-42    # claim before touching code
coven claim heartbeat issue-42  # extend the TTL on long tasks
coven claim release issue-42    # release when the work lands or stops
coven claim canary main         # record HEAD for later hook canary checks

acquire fails while another agent's claim is active; release refuses to remove another agent's active claim. Claims expire after one hour by default.

Hooks

coven hooks install installs the pre-commit and pre-push Parallel Work Protocol hooks into the repository's hooks directory:

coven hooks install

It refuses to modify a tracked core.hooksPath hook directory and prints integration options instead.

Maintenance fence

coven maintenance coordinates exclusive repository maintenance with normal Coven writers:

coven maintenance status --json
coven maintenance acquire <owner> --wait-ms 30000 --json
coven maintenance heartbeat <owner> <generation> --json
coven maintenance release <owner> <generation>

acquire fences new writers and can wait for existing writer intents to drain. The returned generation token is required for heartbeat and release so one owner cannot accidentally release another owner's fence.

A maintenance command launched inside a Coven-managed harness automatically participates as that session's exact writer generation. This lets the caller reach held without waiting on itself while every unrelated live writer still blocks acquisition. The participant capability is internal runtime state: do not copy it into scripts or session metadata, and no extra CLI flag is needed. Malformed, stale, or mismatched participants are rejected rather than widening the drain exception.

Ward

coven ward covers the principal-facing Ward lifecycle: proposals staged for the principal's decision and config migration.

coven ward pending                    # staged proposals awaiting the principal
coven ward pending <proposal-id>      # one proposal in full
coven ward pending --json             # exact daemon body
coven ward audit-census               # bounded, read-only audit-history inventory
coven ward audit-census --json        # machine-readable audit-only census
coven ward migrate --fingerprint <FPR> --apply   # migrate v0.1 ward.toml to Phase-2 WardConfig

audit-census reads an existing Coven store without repairing state, migrating its schema, or granting authorization. It fails instead of truncating when the relevant audit history exceeds --max-audit-rows (default 10,000; range 1–100,000) or the 32 MiB decoding budget. Pending artifacts are non-atomic, unverified observations, not proof that a proposal can be applied.

migrate is a dry-run report unless --apply is passed; --familiar <id> limits it to one familiar. A familiar's declared Ward surface is read with coven familiars <id> — see Observability commands.

Familiar ledger

coven familiar-ledger records each familiar's identity in the familiar ledger: a stable root per familiar and a revision for every identity it has had. A revision keeps the familiar's roster identity fields (id, name, display_name, role, pronouns, person, coven) and the exact text of its IDENTITY.md, SOUL.md, and, when present, ward.toml.

coven familiar-ledger register <familiar>        # first identity: a new root at revision 0
coven familiar-ledger adopt <familiar>           # record changed declarations as the next revision
coven familiar-ledger history <familiar>         # every root for the familiar id, with revisions
coven familiar-ledger history <root-id>          # one root (familiar:…)
coven familiar-ledger retire <familiar>          # retire the live root; history stays readable
coven familiar-ledger restore <root-id>          # continue a retired root with a new revision
coven familiar-ledger revoke <revision-id> --reason "…"   # the revision can never be embodied

Every subcommand accepts --json to print the ledger's response. Only these commands change the ledger: editing a roster entry or declaration file records nothing until you adopt it.

Requirements:

  • The familiar appears exactly once in ~/.coven/familiars.toml.
  • Its workspace contains IDENTITY.md and SOUL.md as UTF-8 text. A ward.toml, when present, must parse.
  • The command runs as the owner, in process, against the local Coven store; it does not need a running daemon. Over the daemon API the same actions are coven.familiars.ledger.*.v1. They are owner-local IPC only, so a TCP request gets AUTHORITY_REQUIRED, and capabilities does not advertise them.

How changes are recorded:

  • register mints an opaque root (familiar:<hex>) that never reuses the familiar id. Registering an id that already has a live root is refused.
  • adopt compares the current declarations with the head revision and reports Unchanged when they match. Otherwise it records the next revision and marks the previous one superseded. Emoji, icon, description, and workspace path are not identity, so changing only those records nothing.
  • retire closes the live root and frees the familiar id; registering the id again mints a new root. restore instead continues a retired root, as long as no other root holds the id.
  • revoke is permanent and requires --reason. A revoked head can only be replaced by adopting changed declarations.

Commands that change a familiar's head read the current head first and send it as the expected revision, so a concurrent change fails with REVISION_CONFLICT instead of being overwritten. Errors print the ledger's code and message:

Error: VALIDATION_FAILED: familiar `sage` has no SOUL.md; add it before recording its identity

The ledger is groundwork for Runtime Authority, which will bind automation runs to a familiar revision. This daemon does not advertise Runtime Authority yet and refuses routine authority declarations, so no run binds to the ledger today. To read a familiar's declared Ward surface instead, use coven familiars <id> (see Observability commands).

Adapters

coven adapter (alias: adapters) lists and diagnoses the harness adapters coven run launches:

coven adapter list           # configured harness adapters (--json available)
coven adapter doctor         # diagnose all adapters; exits 1 if any is unavailable
coven adapter doctor codex   # diagnose one adapter id
coven adapter install hermes # install a trusted local adapter recipe
  • Run for launching sessions into these worktrees.
  • Sessions for the session records the protocol wraps.
  • Daemon lifecycle for the authority boundary behind launches.
Was this page helpful?No

Last updated on

On this page