| name | interlinked-coordination |
| description | Coordinate with other agents/humans via the optional Interlinked MCP Server, and use local checkpoints & file reservations. Load this when picking up or handing off work (`tasks`, `send`, `inbox`, `handoff`), switching workspace context (`workspace`, `attach`), when a write is blocked because a file is "reserved by" another agent, when creating/restoring a local checkpoint (`checkpoint`, `rewind`, `resume`), installing the git-hook reservation guard (`interlinked guard`), or checking CI failure rates (`ci-status`). IMPORTANT: `checkpoint`/`rewind`/`resume` MUTATE git state (stash, checkout, clean -fd) and must not be run without explicit per-turn user authorization. |
interlinked-coordination — multi-agent server surface & local checkpoints
The Interlinked CLI is a local companion; the Interlinked MCP Server is the source of
truth for coordination. Two halves:
- Server-backed (needs auth + a reachable server):
tasks, send, inbox, handoff,
workspace. These are thin wrappers that POST to the server; they do nothing useful offline
(they short-circuit with "Not authenticated. Run: interlinked login"). (cloud recent also needs
a token but via a separate cloud_governor.url. attach is not server-gated — it writes
config locally and only best-effort contacts the server, so it works offline.)
- Local-only (offline):
checkpoint, rewind, resume, guard (git-hook reservation
checks), reminder, ci-status, mcp stdio, and automatic file reservations among
sibling agents on the same machine.
The whole server half is opt-in. Auth resolution: explicit --token → access_token in
config.local.json (auto-refresh) → Claude Code credentials fallback. localhost/127.0.0.1
server_url skips auth entirely (dev mode).
Load this when
- Picking up / handing off work, messaging a peer, or checking your inbox.
- A write was blocked/warned because a file is "reserved by" another agent.
- Switching workspace context.
- Creating or restoring a local checkpoint (read the git-safety warning first).
- Installing the git-hook reservation guard, or checking CI failure rates.
⚠️ Git-safety (read before any checkpoint/rewind/resume)
checkpoint, rewind, resume, and git link-checkpoint --apply mutate git state —
git stash, git checkout <sha> (detaches HEAD), git checkout -- . && git clean -fd
(discards uncommitted changes + deletes untracked files), or commit amend. Under the standing
rule that each commit/push/reset/stash/checkout is an independent per-turn ask, an agent
must not run these autonomously — describe and recommend, don't execute, unless the user
explicitly authorizes it this turn. Also note rewind rarely restores the working tree
(the checkpoint stash is popped at creation, so the message-based lookup usually finds nothing)
— its reliable effect is detaching HEAD to the base commit with a "changes may be missing"
warning. Don't rely on it as an undo.
Server-backed commands
tasks/send/inbox/handoff/workspace are auth-gated (!isAuthenticated && !isLocalDevServer ⇒ error) with no local fallback; send + tasks create/claim/complete also
require agent_name (interlinked enable --agent <name> or INTERLINKED_AGENT_NAME).
Exceptions in this table: attach writes config locally and only best-effort contacts the
server (works offline); cloud recent gates on cloud_governor.url + a token, not isAuthenticated.
| Command | Purpose |
|---|
tasks list (default) [--status --assignee --priority --limit] | List server tasks. |
tasks create <title> [--description --assignee --priority] | Create a task. |
tasks show <id> / tasks claim <id> / tasks complete <id> | Inspect / claim / complete. |
send <to> [message] [--file --importance normal|urgent] | Message a peer (body from arg or --file). |
inbox [--all --agent --limit] | Your messages (unread-only by default). |
workspace list / workspace switch <ws_…> | List / select the registry workspace (writes workspace_id). |
handoff <from-agent> <to-agent> [--include-files] | Send an urgent message with your work-context summary. |
attach [--workspace --workspace-key --project --agent --auto] | Link identity + set internal MCP workspace_key/project_key defaults. |
cloud recent [--limit] | Recent cloud-governor events (a separate HTTP surface — reads cloud_governor.url, not /api/ui/call). |
Two workspace notions: the registry workspace_id (ws_…, set by workspace switch,
for routing/sync) vs. the internal MCP workspace_key/project_key (defaults main/main,
set by attach). Mixing them routes tool calls to the wrong context.
interlinked tasks list --status open
interlinked tasks claim 42 && interlinked tasks complete 42
interlinked send bob "rebased onto main, pull before you push" --importance urgent
interlinked inbox --all
interlinked handoff alice bob
File reservations — automatic, no reserve command
Reservations are an automatic side-effect of writing, enforced in the daemon (there is no
interlinked reserve). On a Write/Edit, over each path the call mutates:
- No conflict → optimistic local grant (5-min TTL) + async server confirm. If the server
rejects/unreachable, the local grant rolls back and a
conflict event is emitted.
- Conflict, holder is remote (not in your local cohort) → BLOCK: "File reserved by …
Coordinate via MCP messages."
- Conflict, holder is a sibling agent on this machine → default a warning (auto-releases
~30s after that agent goes idle); escalates to a block only when the coordination story is
fully known (≥2 known agents, not a parent↔child pair). Unknown → fails open to a warning.
Auto-release fires ~30s after the last edit (idle) and at session end. When you hit a
reservation conflict, coordinate via send/inbox — don't force it; leases self-heal. (Escape
hatch for the local-lease block: INTERLINKED_DISABLE_LOCAL_LEASE_BLOCK=1.) Without an API
client wired in, reservations are a purely local optimistic lease shared across sibling agents —
still useful, just no cross-machine truth.
Local checkpoints (git-mutating — see the warning above)
Metadata in .interlinked/checkpoints.json; working-tree state via a transient git stash.
A checkpoint captures HEAD SHA, changed files, and a stash ref.
| Command | Effect |
|---|
interlinked checkpoint [message] | Creates a checkpoint (runs git stash push --include-untracked then immediately git stash pop — a stash/pop; a pop conflict can leave changes stashed). |
checkpoint list / show <id> / compare <id1> <id2> | Metadata/diff-stat only — no git mutation. |
checkpoint prune [--older-than --keep-latest] / archive | Rewrite metadata only (stash cleanup deliberately skipped). |
interlinked rewind [id] [--force] | On a dirty tree refuses without --force; with --force runs git checkout -- . && git clean -fd (discards changes), then git checkout <base> (detaches HEAD). |
interlinked resume [id] | Non-destructive on a dirty tree, but still git checkout <base> (detaches HEAD) on a clean tree; then best-effort server work-context. |
interlinked git link-checkpoint --apply | Amends HEAD to link a server checkpoint (rewrites the commit). |
interlinked guard — git-hook reservation enforcement
A separate git pre-commit/pre-push hook (not the PreToolUse daemon guard):
interlinked guard install --mode warn|block [--pre-push]
interlinked guard check --files <paths…>
interlinked guard status | uninstall
guard check uses a 5-min stale cache when the server is down (warns loudly) — results can
be outdated.
ci-status, reminder, mcp
interlinked ci-status [--limit --branch] — shells out to gh run list (needs the GitHub
gh CLI, not the Interlinked server); aggregates per-workflow failure rate. "This step
failed 7 of the last 10 pushes" before you push.interlinked reminder add --glob <p> --message <t> [--ops Edit,Write,Read] [--team] /
reminder list / reminder remove — file-touch reminders that warn when a matching file is
edited.interlinked mcp stdio --server <name> -- <command…> — a local recording proxy that
spawns a real stdio MCP server and records its JSON-RPC traffic for observability. There is
no mcp serve; it does not expose Interlinked's own tools. The real MCP Server is the remote
Worker reached over HTTP by the server-backed commands above.
Common workflows
- Pick up a task:
tasks list --status open → tasks claim <id> → work → tasks complete <id>.
- Hand off:
handoff <me> <peer> (urgent message + work-context), or targeted send.
- Reservation conflict: coordinate via
send/inbox; don't force — leases self-heal.
- Local safety net before risky work: propose
interlinked checkpoint "before refactor" —
but get the user's OK first (it stashes). Restoring is git-mutating → explicit ask.
Gotchas
- Server commands have no offline fallback (unlike
status/doctor/activity) — they just
print "Not authenticated" / "Server error".
handoff --include-files and inbox --since are accepted but currently inert.- Hook activity posts and the reservation server-confirm are fire-and-forget (rejection now
rolls back, not silently).
Related skills
- interlinked-setup —
login / attach, sync modes, server config.
- interlinked-observability —
watch (server poll), activity the hooks capture.
- interlinked-harness — the PreToolUse daemon guard (distinct from
interlinked guard).
