claude-session-driver

claude-session-driver

Turn one coding-agent session into a project manager that delegates tasks to other coding-agent sessions — Claude Code, Codex, or Pi.

Why

A single coding-agent session works on one task at a time. With this plugin, a controller session launches worker sessions in tmux, assigns each a task, monitors their progress, and collects results. Workers run in parallel. The controller decides what to do with their output.

How It Works

Workers run with permissions bypassed and execute tool calls without prompting. Each worker writes lifecycle events to a JSONL file — session start, prompt submitted, each tool call (with name and input), stop, and session end — so a controller can watch what each worker is doing. The events are observation-only; the plugin does not gate tool calls.

The controller drives three harnesses through one CLI (csd), chosen at launch with --harness <claude|codex|pi> (default claude):

• Claude Code and Codex emit events through their hook systems (node hook programs).
• Pi emits events through a native TypeScript extension csd loads into it.

Whichever harness you launch, the controller-facing command surface is identical — launch, send, converse, wait-for-turn, read-turn, read-events, status, stop, and handoff all behave the same. (adopt is the one exception: it's Claude-only, since Codex and Pi mint their own session ids and offer no resume-by-id.) The CLI manages tmux sessions, polls events, reads conversation logs, and cleans up.

Installation

claude plugin install claude-session-driver@superpowers-marketplace

If your marketplace cache predates this plugin, update it first:

claude plugin marketplace update superpowers-marketplace

Requires tmux and a harness CLI — at least the one you launch: claude (default), codex, or pi. No jq and no bash hooks: csd is a TypeScript/node tool whose hooks are node programs (node is required, but it ships wherever Claude Code runs). Codex stages the operator's ~/.codex auth into each worker; Pi stages ~/.pi/agent.

Usage

Install the plugin and ask Claude to manage a project. The driving-claude-code-sessions skill provides orchestration patterns:

• Delegate and wait: Launch a worker, assign a task, read the result.
• Fan out: Launch several workers on independent tasks, wait for all to finish.
• Pipeline: Chain workers so each builds on the previous worker's output.
• Supervise: Hold a multi-turn conversation with a worker, reviewing each response.
• Hand off: Pass a running worker session to a human operator in tmux.

See skills/driving-claude-code-sessions/SKILL.md for detailed usage patterns.

CLI

All operations go through a single binary at skills/driving-claude-code-sessions/scripts/csd.

Top-level subcommands

Subcommand	Purpose
csd launch [--harness <claude|codex|pi>] <name> <cwd> [-- harness-args...]	Bootstrap a worker (harness defaults to claude); prints a shim path to stdout
csd adopt <name> <cwd> <session-id> [-- claude-args...]	Re-adopt an existing Claude session as a worker (claude-only)
csd list [--all]	List active (or all) workers
csd grant-consent	One-time consent flow (required before first launch)

csd launch prints the shim path to stdout (deterministic at /tmp/csd-workers/bin/<name>) and a human-readable panel to stderr. Capture it:

WORKER=$(csd launch my-worker /path/to/project)

The worker dir defaults to /tmp/csd-workers (renamed from /tmp/claude-workers; a back-compat symlink /tmp/claude-workers → /tmp/csd-workers is created when the default is in use). Override it with CSD_WORKER_DIR.

Per-worker subcommands

Once you have a shim path, invoke it directly or use csd --worker <name> <sub>:

Subcommand	Purpose
$WORKER converse [--with-turn] <prompt> [timeout]	Send a prompt, wait, return the response
$WORKER send <prompt>	Send a prompt without waiting
$WORKER wait-for-turn [timeout]	Block until the worker finishes a turn
$WORKER read-turn [--full]	Format the last turn as markdown
$WORKER read-events [--last N] [--type T] [--follow]	Read and filter the event stream
$WORKER status	Print worker status (idle/working/terminated/gone)
$WORKER stop	Stop the worker and clean up
$WORKER handoff	Print tmux attach instructions for a human takeover
$WORKER session-id	Print the worker's session id
$WORKER events-file	Print the path to the JSONL event file

Environment variables

All optional. csd help shows the full list.