intersession weekly downloads statistics

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:

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

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

Description from the npm listing.