Inter-session agent communication — documentation package¶

A portable, reusable protocol that lets 2–3 Claude Code orchestrator sessions work the same repository at the same time without stepping on each other — and, when they must coordinate, gives them a durable channel to hand off work, claim ownership, and pass along human instructions.

The protocol was developed and battle-tested on po-platform across a dozen parallel-session cycles (May 2026). It is deliberately project-local in its canonical form, but the mechanics generalise: this package is the on-ramp for adopting it on any repo.

One-line summary: sessions never share a working tree (each gets its own git worktree), they coordinate through a durable git blackboard (committed queue files + a claim scoreboard) complemented by a task tracker (Riff / tasks-prod), with Telegram as a human bridge, never the bus.

Which document do I want?¶

This package follows the Diátaxis framework — four documents, each answering a different question.

If you want to…	Read	Diátaxis quadrant
Understand what this is and why it exists (the failure modes, the design choices)	`explanation.md`	Explanation (understanding)
Learn by doing — spin up two coordinating sessions and watch the protocol work end-to-end	`tutorial.md`	Tutorial (learning)
Onboard the protocol onto a new project — the concrete install procedure	`how-to-onboard.md`	How-to (a goal)
Broadcast to all sessions and read replies (as the human) — the Telegram alternative when you don't need real-time	`how-to-broadcast.md`	How-to (a goal)
Look up an exact detail — message grammar, row schema, ack states, verbs, file inventory	`reference.md`	Reference (information)

New to the protocol? Read explanation.md, then do tutorial.md. Bringing it to your own repo? Go straight to how-to-onboard.md (it links back to the explanation where you need the "why"). An AI agent onboarding a repo autonomously? Use the paste-ready CSF snapshot instead — it is written for agent consumption.

The canonical sources (on po-platform)¶

This package is the teaching layer. The authoritative, normative definitions live in:

ADR-010 — the architecture decision: the three-tier model, identity & addressing, the message schema, the ack state machine, ownership invariants, and the rejected alternatives (RabbitMQ, A2A, Postgres bus). This is the contract.
docs/ai/parallel-sessions.md — the operational doctrine (Layers 0–11): worktree isolation, naming, the scoreboard, broken-main ownership, shared-doc partition, anti-patterns, and the full Layer 6 messaging spec. This is the playbook a session reads at start.
The three scripts in infrastructure/scripts/: start-session.sh, session-heartbeat.sh, check-worktree-prefix.sh.
lefthook.yml — the commit-msg and post-commit hook registrations.

If anything in this package disagrees with ADR-010, ADR-010 wins — open an issue or fix the doc.

At a glance — the moving parts¶

  Tier 1  git blackboard (durable, the spine)
          ├── docs/ai/sessions/active.md            ← claim scoreboard + presence
          └── docs/ai/sessions/queue/to-<sX>.md     ← addressed messages + ack chain

  Tier 2  Riff / tasks-prod (task-coupled coordination; complements, never replaces Tier 1)
          assignee = owner · labels = lane · comments = ack log · deps = handoff order

  Tier 3  Telegram (human↔agent bridge ONLY — single-holder, relayed into Tier 1)

  Mechanics
          start-session.sh        → worktree isolation + claim row (Layer 0)
          check-worktree-prefix.sh → commit-msg backstop ([sX] must match -sX worktree)
          session-heartbeat.sh    → post-commit presence beacon (bumps last_seen)

The whole thing degrades gracefully: a session with no Telegram and no tracker access can still read and write the bus with git pull / git commit / git push.