Skip to content

concord

Cross-agent coordination client: principals, a run wrapper, and a mailbox. Use it when more than one agent works in one repository — it names each agent, records which shared files it has claimed, and gives the others a way to send it a message and find out whether it is still alive.

A principal is one running agent identity. A principal owns a process group, a heartbeat, a mailbox and — when run through a worktree — a set of --owns file claims.

Usage

mini-ork concord run --name <name> [--kind loop] [--heartbeat-secs N] -- <cmd...>
mini-ork concord ps [--all] [--json]
mini-ork concord stop <principal> [--signal TERM|KILL] [--yes]
mini-ork concord send <principal> <message...> [--from <sender>]
mini-ork concord inbox [--principal <id>] [--format text|json|prompt] [--ack]
mini-ork concord ack <principal> <msg_id>
mini-ork concord admit [--db <path>]
mini-ork concord claims [--json]
mini-ork concord violations [--since <seq>] [--json]

run

mini-ork concord run --name implementer-1 --kind loop -- \
  mini-ork run code-fix ./kickoff.md

Runs a command bound to a principal. The wrapper:

  • registers the principal and its process group;
  • emits a heartbeat every --heartbeat-secs (default 30);
  • records the exit and unregisters on the way out.

--name is required unless CONCORD_PRINCIPAL is already set. --kind is a free label (default loop) used by ps and the mailbox views. The command goes after --; run without a command is an error.

ps and stop

mini-ork concord ps            # live principals
mini-ork concord ps --all      # include ended ones
mini-ork concord stop agent-b  # SIGTERM its process group

stop signals the whole process group, then escalates to SIGKILL after a grace period. On a non-TTY it refuses without --yes, so a script cannot kill an agent by accident.

send, inbox, ack

The mailbox is durable: a message waits until the recipient acknowledges it.

mini-ork concord send agent-b "claims includes pyproject.toml" --from agent-a
mini-ork concord inbox --principal agent-b --format prompt
mini-ork concord inbox --principal agent-b --ack
mini-ork concord ack agent-b msg-0007

inbox defaults the principal from CONCORD_PRINCIPAL. --format prompt renders the messages as a block suitable for pasting into an agent prompt; --ack acknowledges everything shown. ack is the single-message form.

Deliver a message only after the recipient is idle; a busy agent reads it on its next turn.

claims and violations

mini-ork concord claims          # live claims on hot shared files
mini-ork concord violations      # recorded --owns scope violations
mini-ork concord violations --since 128 --json

claims answers "who is allowed to touch this file right now" — worktrees register their --owns surface here. violations lists edits made outside a worktree's claim, in sequence order; --since pages from a sequence number. Both are read-only.

admit

mini-ork concord admit admits or defers an epic whose scope overlaps one already in progress. It reads the project state DB (override with --db) and reports the decision, so the caller does not launch a second epic over the same files.

Examples

# Two agents, one repo: name them, then exchange one message.
mini-ork concord run -n agent-a -- mini-ork run code-fix ./a.md &
mini-ork concord run -n agent-b -- mini-ork run docs ./b.md &
mini-ork concord ps --json
mini-ork concord send agent-b "I own docs/architecture/*" --from agent-a
mini-ork concord inbox -p agent-b --ack
mini-ork concord stop agent-a --yes

Exit codes

Code Meaning
0 Command succeeded; no message waiting, or the action completed
1 The wrapped command failed, or a principal/message was not found
2 Usage error (missing principal, no command after --)