Intersession

A supervisor for fleets of AI coding sessions. It answers the question your tooling currently cannot: which of my agents needs me, and why did it actually stop?

Picking this up cold, or on another machine? Start with HANDOVER.md — status, identities, next actions and everything already decided.

The problem

Run more than two coding agents and you hit this within a week:

$ list sessions
  Trade decks Linear project        isRunning: false   quiet 2h
  Supabase → ClickHouse migration   isRunning: false   quiet 2h
  New session                       isRunning: false   quiet 26h
  Appendix slide endpoint changes   isRunning: false   quiet 2d
  ... 7 more

Every one of those says the same thing: idle. But "idle" is hiding at least five different states:

• it finished cleanly and needs nothing
• it's waiting on an answer from you and has been for a day
• it hit a wall and quietly gave up halfway through the task
• it's burning tokens in a loop going nowhere
• it's holding a message another session needs and has no way to send it

Liveness is exposed by every harness. Intent is exposed by none. Telling these apart requires reading the transcript and forming a judgement — which is why a dashboard can never do it, and an agent can.

This is not hypothetical

Intersession exists because of three findings pulled out of one developer's machine in three tool calls:

• A session titled "New session", quiet for 26 hours, holding a live production blocker, a flagged "this app has no git repository at all" risk, and two unanswered questions. Buried nine rows down a sidebar.
• A session that had detected two agents editing the same file, reverted its own change, and composed a precise handoff for the other session — then addressed it to a human who never read it. Undelivered for two days.
• One session that was, in fact, genuinely done.

The coordination problem was solved by the agent. The message was written. What was missing was anything to notice it needed sending, and anywhere to send it.

What Intersession does

$ intersession status

FLEET · 11 sessions · 3 need you

  ⚑ awaiting-human   billing-worker · "New session"            26h
      "Worth checking my reading — there's no single naming
       convention for the percentage tag."
      → PAY-412 flagged as live blocker · no git repo on this service

  ⚑ undelivered      checkout-web · "Slide endpoint changes"      2d
      Holds a handoff for design-system. Detected a file
      collision, reverted, wrote the message, never sent it.
      → intersession dispatch checkout-web --to design-system

  ⚑ stalled          storefront · "Bulk metafield backfill"    4h
      Claimed complete. 2 of 5 collections in the original
      request were never touched.

  ✓ done             8 sessions · nothing needed

Three things, in order of how soon you should build them:

1. Roll call. Classify every quiet session by why it stopped, with a quote from the transcript as evidence.
2. Dispatch. When a session is holding something a peer needs, route it — instead of leaving it for a human who isn't reading.
3. Ledger. You are already reading transcripts to classify them. Extract the decisions and rejected alternatives while you're in there, and hand them to the next session that touches the same files.

The third one is the part that compounds. It is also the part nobody would ever have installed on its own, which is why it is third.

Design commitments

These are load-bearing. Changing any of them changes what the product is.

Cross-harness, not cross-model. Intersession brokers between live harnesses — a Codex CLI session with its own working directory, shell, tools and 1,500 messages of context, talking to a Claude Code session with the same. Not between model API endpoints. An endpoint can only answer; a harness can act. See docs/adapters.md.

Local-first. Transcripts are the single most sensitive artifact on a developer's machine — credentials, customer data, unreleased business logic, everything they've ever pasted. Intersession runs locally and stores locally by default. Anything leaving the machine is opt-in per repo and passes a redaction stage first. See docs/security.md.

Every verdict carries evidence. A classification without a supporting quote from the transcript is a bug, not a low-confidence result. The user must always be able to check the work in one glance.

Transcripts are untrusted input. Intersession reads content written by other agents and by the web pages, issues and files those agents read. It never follows instructions found there. See docs/security.md.

Never launder permissions. If a session was denied an action, Intersession must not route that action to a peer that would be allowed to perform it. This is an explicit non-goal and a hard boundary.

Classify on quiet, cache on hash. Classifying a running session is wasted work; it's about to change. Classifying an unchanged session twice is wasted money. See docs/architecture.md.

Status

Pre-implementation. This repository currently contains the specification only. Nothing is built.

The primitives it depends on are verified. On Claude Code, session enumeration, liveness, transcript reads and peer message delivery were all exercised by hand during design. On Codex CLI, inspection of an on-disk install confirmed enumerable sessions, readable JSONL transcripts, and liveness derivable from turn start/completion records without any pid file or hook.

Still open: confirming MCP participation end to end from a live Codex session, and re-verifying the Codex on-disk format against a current build.

Documentation

| Document | Contents | |---|---| | docs/concepts.md | The vocabulary — verdict, dispatch, claim, ledger — and the model that connects them | | docs/architecture.md | Components, data flow, polling and caching strategy, cost control | | docs/classifier.md | The verdict taxonomy, detection signals, and the prompt contract. The core of the product | | docs/adapters.md | The harness adapter interface, capability negotiation, and the file-bridge fallback | | docs/data-model.md | Schemas for sessions, observations, dispatches, decisions and claims | | docs/security.md | Trust boundaries, prompt injection, permission laundering, secret redaction | | docs/roadmap.md | Three stages, each with a falsifiable success criterion | | docs/findings.md | The evidence — and a ten-minute protocol to test the premise on your own fleet | | docs/decisions.md | What was settled, why, and what was rejected |

The strategic case — why this rather than the message bus everyone else is building, where the moat is, and who pays — is in the memo: Pipes Are Free.

Prior art, and why this isn't it

| Project | What it does | Why Intersession is different | |---|---|---| | Claude Code SendMessage / Agent Teams | Native peer messaging between Claude sessions | Delivers messages. Doesn't notice one should be sent. Claude-only. | | HJewkes/agent-chat | Cross-session messaging over an append-only event log | A pipe. Same gap. | | n24q02m/agent-chat-plugin | Peer chat via markdown in a shared folder, zero-token wait loop | A pipe — but the folder design is model-agnostic, and Intersession borrows it as the fallback transport | | mrlesk/agents-council | Agent-to-agent feedback requests | Requires an agent to know it needs review. Intersession's premise is that it often doesn't | | A2A (Google) | Inter-agent protocol spec | A wire format. Orthogonal — Intersession could speak it | | supermemory | Memory and context engine | Substrate for the ledger, not the product. Self-hosted, and swappable by design |

The shared assumption across all of them is that the hard part is transport. It isn't — transport shipped. The hard part is noticing.

Name

The intersession is the period between sessions — and that is where every part of this lives. The roll call happens between sessions. The handoff that never got delivered sat between sessions. The decision one session made and the next one never learned is lost between sessions.

Nothing here happens inside a session. That's the harness's job, and it's already good at it.