Driving Claude Code Sessions

Driving Coding-Agent Sessions

Overview

You can launch coding-agent sessions — Claude Code, Codex, or Pi — as "workers" in tmux, send them prompts, wait for them to finish, read their output, and hand them off to a human. Workers run with permissions bypassed, so they execute tool calls without prompting. Each worker emits lifecycle events to a JSONL file so the controller can observe what it's doing — Claude and Codex through their hook systems, Pi through a native extension csd loads into it.

All operations go through a single CLI: csd. After launching a worker, the controller receives a shim path at /tmp/csd-workers/bin/<tmux-name> that bakes in the worker handle. Every per-worker operation goes through that path — no positional state to thread between calls, no absolute skill path to prepend. A small set of environment variables tune behavior; see Environment variables at the bottom.

(The worker dir moved from /tmp/claude-workers to /tmp/csd-workers; when the default path is in use, csd creates a back-compat symlink /tmp/claude-workers → /tmp/csd-workers, so old paths and muscle memory still resolve.)

The shim path is deterministic: if you pick a memorable tmux name at launch, you can reconstruct /tmp/csd-workers/bin/<tmux-name> whenever you need it. For agents driving via tool calls, that's the right model — shell state doesn't persist between calls, so a SHIM=...; $SHIM cmd pattern just adds noise. The examples below use the bare path.

Harnesses

Pick a harness with --harness at launch (default claude):

$SKILL/csd launch --harness codex my-task /path/to/project
$SKILL/csd launch --harness pi    my-task /path/to/project

The controller-facing command surface is identical across all three harnesses — launch, send, converse, wait-for-turn, read-turn, read-events, status, stop, and handoff behave the same regardless of harness. A few things differ:

• Auth. Each harness authenticates from its own home — Claude ~/.claude, Codex ~/.codex, Pi ~/.pi/agent. csd stages that login into the worker at launch, so to rotate credentials, relaunch.
• adopt is Claude-only. Claude takes a caller-assigned session id, so a session can be resumed by id (claude --resume). Codex and Pi mint their own ids on the first prompt and offer no resume-by-id — relaunch them instead.
• Codex isn't queryable until its first prompt. Codex mints its session id only when you send the first prompt, so between launch and the first send/converse a codex worker's status, session-id, and wait-for-turn return no worker known — it is running, it just hasn't registered yet. converse handles this internally, so the typical launch→converse path is fine; only the lower-level commands see the gap. (Claude takes its id at launch and Pi registers at launch, so both are queryable immediately.)

Prerequisites

• tmux
• 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 and its hooks are node programs. node is required, but it's already present wherever Claude Code runs.)

Setup

The CLI lives at <skill>/scripts/csd. Top-level subcommands need the skill path:

• csd launch [--harness <claude|codex|pi>] <tmux-name> <cwd> [-- harness-args...] — bootstrap a worker (harness defaults to claude)
• csd adopt <tmux-name> <cwd> <session-id> [-- claude-args...] — re-adopt an existing Claude session as a worker (claude-only; see Recovering workers)
• csd list [--all] — enumerate workers
• csd grant-consent — one-time consent for running workers with permissions bypassed

Once a worker is launched, run subsequent commands against /tmp/csd-workers/bin/<tmux-name>:

SKILL=/abs/path/to/skill/scripts
$SKILL/csd grant-consent                          # one-time per machine
$SKILL/csd launch my-task /path/to/project        # stdout: /tmp/csd-workers/bin/my-task
/tmp/csd-workers/bin/my-task status               # use the shim directly

Pick a memorable tmux name at launch; the shim path is then deterministic. (You can capture it into a shell variable in an interactive shell, but for agent-driven workflows the bare path is simpler — there's no shell state to lose between calls.)

Workflow

In examples below, $SKILL is the absolute path to skills/driving-claude-code-sessions/scripts. WORKER is the bare shim path (e.g. /tmp/csd-workers/bin/my-task) — substitute the deterministic path for your worker.

1. Launch

$SKILL/csd launch my-task /path/to/project
# stdout: /tmp/csd-workers/bin/my-task
# stderr: Worker launched. tmux/session_id/cwd/events/reproduce

csd launch:

• Writes a 3-line shim at /tmp/csd-workers/bin/my-task
• Starts tmux and the harness in it
• Blocks until the worker is ready — Claude (which takes a caller-assigned session id) waits for its session_start event; Codex and Pi mint their own ids on the first prompt, so launch settles their TUI and the worker's meta self-registers when it fires its first event
• Prints the shim path on stdout (one line)
• Prints a "Worker launched" panel on stderr — the reproduce: line is the exact command to relaunch with the same args

Pass harness CLI args after a -- separator, or pick a non-default harness with --harness:

$SKILL/csd launch my-task /path/to/project -- --model sonnet
$SKILL/csd launch --harness codex my-task /path/to/project

2. Converse (the typical case)

/tmp/csd-workers/bin/my-task converse "Refactor the auth module" 300

converse sends the prompt, waits for the worker to finish, and prints the final assistant text on stdout. For tool-heavy turns where the bare text strips the interesting part, use --with-turn to get the full markdown:

/tmp/csd-workers/bin/my-task converse --with-turn "Run the failing tests" 600

Multi-turn just works — the wait tracks turn boundaries automatically:

/tmp/csd-workers/bin/my-task converse "Write tests for the auth module" 300
/tmp/csd-workers/bin/my-task converse "Add edge cases for expired tokens" 300

3. Lower-level control

If you need to drive the worker more directly:

/tmp/csd-workers/bin/my-task send "Refactor the auth module"     # send without waiting
/tmp/csd-workers/bin/my-task wait-for-turn 300                   # block until stop or session_end
/tmp/csd-workers/bin/my-task status                              # idle | working | terminated | gone | unknown
/tmp/csd-workers/bin/my-task read-turn                           # last turn as markdown (tool results truncated to 5 lines)
/tmp/csd-workers/bin/my-task read-turn --full                    # last turn with complete tool results

4. Watching what the worker does

Every tool call emits a pre_tool_use event with the tool name and input. Tail the event stream to watch in real time:

/tmp/csd-workers/bin/my-task read-events --follow &
MONITOR_PID=$!
# ... do other work ...
kill $MONITOR_PID

Or pull events after the fact:

/tmp/csd-workers/bin/my-task read-events                       # all events
/tmp/csd-workers/bin/my-task read-events --last 5
/tmp/csd-workers/bin/my-task read-events --type pre_tool_use

--type accepts one of: session_start, user_prompt_submit, pre_tool_use, post_tool_use, stop, session_end. Unknown event names fail fast. (Claude workers emit pre_tool_use but not post_tool_use; Codex and Pi emit both.)

If you see something you don't want, stop the worker:

/tmp/csd-workers/bin/my-task stop

5. Stop and clean up

/tmp/csd-workers/bin/my-task stop

Sends /exit, waits up to 10s for session_end, kills the tmux session if still running, and removes the meta, events, and shim files.

stop is destructive: the worker is gone and the shim path stops working. If you wanted the worker around for follow-up turns or a parallel workflow, don't call stop until you're done with it. To resume work under the same name, relaunch — csd launch my-task /path/to/project again — and you'll get a fresh worker at the same shim path.

After stop, the shim no longer exists, so invoking it again surfaces a shell error along the lines of no such file or directory: /tmp/csd-workers/bin/my-task (the exact wording depends on your shell). That's expected; the worker is gone.

6. Hand off to a human

/tmp/csd-workers/bin/my-task handoff

Prints attach instructions for a human to take over the tmux session.

Finding workers

$SKILL/csd list                      # live workers (idle/working/terminated)
$SKILL/csd list --all                # include 'gone' workers (tmux already exited)
$SKILL/csd list api                  # substring filter on tmux name
$SKILL/csd prune                     # remove dead workers + orphaned sidecars/shims

Reference

csd launch [--harness <claude|codex|pi>] <tmux-name> <cwd> [-- harness-args...]
csd adopt <tmux-name> <cwd> <session-id> [-- claude-args...]   # claude-only
csd list [--all] [<pattern>]
csd prune                          # remove dead/orphaned worker state
csd grant-consent

<shim> converse [--with-turn] <prompt> [timeout=120]
<shim> send <prompt>
<shim> wait-for-turn [timeout=60] [--after-line N]
<shim> status
<shim> read-events [--last N] [--type T] [--follow]   # --last caps the --follow backlog
<shim> read-turn [--full]
<shim> stop
<shim> handoff
<shim> session-id
<shim> events-file

<shim> is /tmp/csd-workers/bin/<tmux-name>. Run csd help for the same surface.

Common Patterns

Fan-Out: Multiple Workers in Parallel

$SKILL/csd launch worker-api ~/proj
$SKILL/csd launch worker-ui ~/proj

/tmp/csd-workers/bin/worker-api send "Add pagination to /users"
/tmp/csd-workers/bin/worker-ui send "Add a loading spinner to the user list"

/tmp/csd-workers/bin/worker-api wait-for-turn 600
/tmp/csd-workers/bin/worker-ui wait-for-turn 600

/tmp/csd-workers/bin/worker-api stop
/tmp/csd-workers/bin/worker-ui stop

Pipeline: Worker A produces, Worker B consumes

$SKILL/csd launch spec ~/proj
/tmp/csd-workers/bin/spec converse "Write an OpenAPI spec for /users to /tmp/api.yaml" 300
/tmp/csd-workers/bin/spec stop

$SKILL/csd launch impl ~/proj
/tmp/csd-workers/bin/impl converse "Implement the endpoint defined in /tmp/api.yaml" 600
/tmp/csd-workers/bin/impl stop

Don't trust worker B's summary of what it did — check the produced file. A worker can report success while having written the wrong thing (see Important Notes).

Edge Cases

Worker crashes mid-turn

wait-for-turn matches stop OR session_end, so it returns when the worker dies. Call status afterward: if it's gone, the worker crashed.