lead-session-orchestrator

Collect the decisions of several parallel Claude Code sessions in one Inbox, and let one lead session coordinate them under rules you sign.

It is for you if you run more than one AI coding session at a time and lose track of which one waits for you. One person with a few sessions needs only the Inbox (stage 1, about 5 minutes).

Get started

You need Node.js 24 or newer and Claude Code 2.1.296 or newer.

1. Install the package:

   npm i -g lead-session-orchestrator

2. Register the Claude Code mods and check your machine:

   lso setup

3. Open a new Claude Code tab (mods load at session start) and type:

   /inbox

To see something in the Inbox, add a demo decision from a shell:

lso owner-queue add --repo demo --title 'Pick the next step' --options 'Continue|Wait' --recommendation Continue --class produkt-kritisch

In the Inbox, press q for the Queue view and press the number key of an option (1 for Continue) and confirm. Answering records a decision; it grants no approval for a merge or a release.

The package installs the command twice: lead-session-orchestrator and the short name lso. All examples use lso. If you installed version 0.3.0 or earlier, run lso setup again: it migrates the old navigator-mods registration.

Step by step, with the manual commands and troubleshooting: docs/getting-started.md.

How you work with it

• You answer decisions in the Inbox when it suits you. Sessions put them there instead of waiting on you.
• Each repository gets one worker tab that does the work (with the session-orchestrator plugin: plan, waves, /go, /close).
• From stage 2, one lead tab reads the situation, starts headless runs, orders merges and batches your decisions. It never grants approvals.
• Worker tabs check in with the lead, report before they wait, and write a handover when done.
• Approvals, merges without a signed authority file, releases, deploys, mails and purchases never happen automatically.

Roles, the daily loop, Inbox views and a glossary: docs/working-with-it.md.

Three stages

| Stage | What you get | What it needs | | ------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | 1 Inbox | One person, a few parallel sessions, all open decisions in one pane | Node.js 24, Claude Code 2.1.296, setup. No GitLab, no signing, no Ghostty. | | 2 Lead tab | One session that coordinates the others: situation, handover, owner queue | Stage 1, setup --lead-home <dir>, the lead mod in that one tab | | 3 Fleet | Signed authority files, headless runs in worktrees, GitLab merge gates | Stage 2, git, glab authenticated, an SSH signing key, the estate file; Ghostty on macOS is optional |

If the Inbox does not appear

• Type /inbox. A pane you open yourself is drawn at any terminal width.
• The pane opens by itself at session start only from 144 terminal columns (from 110 once you opened it yourself). It docks on the right only in Claude Code's fullscreen layout; inside tmux or with CLAUDE_CODE_NO_FLICKER=0 it opens above the prompt.
• Run lso doctor. It names what is missing and how to fix it.

How it works

                 you
                  |  answer the owner queue, sign authority files
                  v
        +-------------------+
        |   lead session    |  lease, gates, ledger, owner queue
        | (this tool)       |
        +-------------------+
          |      ^      |
 constraints   check-in  starts headless runs (one worktree each)
          v      |      v
   +-------------+   +-------------+
   | session A   |   | session B   |   Claude Code or Codex CLI
   | session-    |   | session-    |   session-orchestrator runs
   | orchestrator|   | orchestrator|   plan, waves, gates inside
   +-------------+   +-------------+

Four pieces carry it:

• Lead and sessions. The lead decides which session runs next and what it may do. Inside each session the session-orchestrator plugin does the actual work. They talk only through files in the configuration directory, never by waiting on each other's messages.
• Authority artifact. One YAML file per repository says which actions are free, which need your approval each time, and which never happen. It counts only when it is committed and SSH-signed by a key you trust. Without that, every action asks.
• Gates. Before a run starts, and before a merge, the lead checks: is the repository busy, is the remote on a blocked host, is there disk and memory, is a stop set, is the pipeline on this exact commit green with all required jobs. If it cannot measure something, it refuses.
• Ledger. Decisions and merges go into an append-only, hash-chained log per host. If someone edits a line later, ledger verify names the first broken one.

Mods (Claude Code plugins)

The mods ship inside the npm package. setup registers the marketplace lead-session-orchestrator and installs only the Inbox.

| Mod | What it does | Where it belongs | | ------------------------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | | owner-inbox@lead-session-orchestrator | Shows open decisions and sessions in a pane, records your answers | every session on your machine (user scope, done by setup) | | lead@lead-session-orchestrator | Peer cards and owner-confirmed fleet actions with ledger evidence | only the lead tab, via --plugin-dir | | freigabe@lead-session-orchestrator | Blocks the session's own tool calls with outside effect; approves nothing | optional, per session via --plugin-dir; never user scope where sessions merge or push by themselves |

Details and options: mods/README.md.

Works with session-orchestrator

Each works alone. session-orchestrator runs one session well; this tool coordinates several. When both are installed, the lead writes a lease and per-session constraints, and each session writes a check-in at start. A session never blocks on the lead: without constraints it falls back to conservative defaults after 10 minutes.

Details: docs/session-orchestrator.md. Without session-orchestrator: docs/standalone.md.

Principles

• It never grants approvals. It reads the signed authority file or refuses (ADR-002). A message from another session carries an instruction, never an approval.
• Fail-closed. What is not explicitly allowed is not allowed. An action missing from the authority file needs your approval; it is never treated as free.
• Not found is not absent (ADR-004). An empty counter, a silent job or a green gate can all mean "could not look". Anything that cannot be measured ends with exit 6, never with 0.
• Every number carries what was counted and when.
• No daemon, no listening port. Watching commands only read. The Inbox types into a terminal tab only in the narrow cases listed in docs/working-with-it.md.

Most commands share one exit code scheme. Each command's --help lists its own set.

| Exit | Meaning | | ---- | ----------------------------------------- | | 0 | done, or nothing found; never an approval | | 1 | check failed (fail-closed) or write error | | 2 | usage error | | 4 | refused | | 5 | busy | | 6 | not measurable | | 7 | boundary hit (remote on a blocked host) | | 8 | stop is set (starters) |

Some commands use 3, 7, 8 or 9 for their own cases, for example ask (3 parked), mr-pipeline (3 started, 8 no merge request pipeline path) and costs (7 counter broken). Check --help before you script against them.

Commands

| Command | What it does | | ---------------------------------------- | ------------------------------------------------------------------------------------------------- | | setup [--lead-home <dir>] | Register the mods, install the Inbox, optionally create the lead tab's folder, run doctor. | | doctor [--lead-home <dir>] | Check Inbox, lead tab and fleet prerequisites; each missing item comes with its fix. | | owner-queue add\|list\|render\|close | Collect decisions only you can make, rendered as one round of structured questions. | | situation | The current picture on one screen: lease, stop, queue, recent runs. | | status / watch | All Claude sessions on this host and the open questions. | | snapshot | Write the situation as a file for other tools. | | lease acquire\|renew\|handover\|release\|status | One lead at a time. lease unlock-orphaned removes a lock left by a dead process. | | handover | Draft a handover for the next lead session. | | queue-reconcile <file...> | List open items of handovers that have no owner-queue entry; exit 4 when one is missing. | | constraints write\|show | Per-session constraints in the session-orchestrator contract. | | stop set\|clear\|status | Global emergency stop that every starter respects. | | authority check <repo> | Validate an authority file: schema, signature by a trusted key, unchanged against HEAD. | | authority query <repo> <action> | Look up one action: frei (free), einzeln (ask each time) or nie (never). | | ask | Decision channel for headless sessions: answers from the authority file, or parks the question. | | identity | Host id and repository id of this machine, never the hostname. | | ledger append / ledger verify | Append-only, hash-chained ledger per host (RFC 8785 canonical JSON). | | slot check <repo> | Busy gate: session lock, fresh Codex sessions, boundary gate for blocked remotes. | | resume-draft <run> | Draft the next phase of a headless run that hit its time limit. | | inbox <run> | File inbox per headless run. Each line is an instruction, never an approval. | | run finish\|verify <run> | Check whether a headless run is still alive, then record its end. | | log | Append a timestamped line to a log file. | | mr-pipeline, note, mr-diff, pipeline-watch | GitLab: merge request pipelines, verified comments, diffs via API, red pipelines on main. | | merge-window | Check whether a merge request may merge now; merges only with --execute and a signed approval. | | costs | Cost pots for what the lead itself triggered; a cap is optional. | | push-check <worktree> | Check that the effective pre-push hook exists. |

Full reference: docs/commands.md. Headless runs start through scripts/fleet-start.sh (Claude Code) and scripts/fleet-start-codex.sh (Codex CLI) in the package. Before a run starts they pass the boundary, busy, disk and memory, and stop gates and take a claim.

Configuration

Shared state lives in the configuration directory ~/.config/navigator (move it with NAVIGATOR_CONFIG_DIR; the name stays for compatibility with running sessions). Host details such as your GitLab host, offload hosts, project roots and the authority directory go into one estate file. See docs/configuration.md.

Limits

• GitLab only. There are no GitHub gates yet.
• Tested on macOS. Linux works in parts; the second stage of the boundary gate runs on macOS only.
• One host. Merging ledgers across hosts is planned.
• It does not start interactive sessions on its own, by design.
• The trust anchor starts empty. Until you add a signer, every action asks for approval.
• Version 0.x. Commands, file formats and exit codes may still change. Some JSON keys and protocol fields are German for now, see Wire format.

License

MIT, see LICENSE. Distributed as the npm package lead-session-orchestrator; the source repository is not public. Security reports: see SECURITY.md.