Interlinked Coordination

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.

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 <agent>… 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.

Codex subagents can share the root session id. When their stable subagent_id is present, Interlinked counts each sibling as a distinct local actor and targets activity/leave events by that id; root-session and thread-id aliases still resolve parent↔child lineage, so ordinary delegation keeps the lineage exemption instead of being mistaken for an unrelated conflict.

For Codex/Copilot apply_patch, "each path" means every patch-section destination plus the source of every *** Move to: operation, de-duplicated in patch order. PreToolUse acquisition and PostToolUse idle-release scheduling share that exact target list, so a multi-file patch does not strand all but one lease until its 5-minute TTL.

Multi-path acquisition preflights the whole set before making any new local grant or server request. If any conflict is blocking, none of the free paths are leased; warning-only sibling conflicts are skipped and the other free paths still lease. Reacquiring an owned path cancels its older idle timer before renewal, so an in-flight follow-up edit cannot lose its lease to the prior edit's 30-second timer.

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.