System health check: binary availability + summary of all known sessions.

Returns tmux_available / claude_available (are the binaries on PATH), session_count, and sessions (SessionInfo dicts).

Pre-create a Claude Code session. Usually unnecessary — session_send creates one on demand — but useful to fix launch options up front.

• An existing tmux session called name is returned as-is.

• A fresh session is minted a UUID (--session-id) so claude_run can address the same conversation later; a stored or supplied claude_session_id triggers --resume instead.

• permission_mode: one of acceptEdits, auto, bypassPermissions, manual, dontAsk, plan. Defaults to bypassPermissions so unattended runs are not blocked by approval prompts — restrict with allowed_tools instead.

• worktree: run in an isolated git worktree at .claude/worktrees/<name>.

• effort: low, medium, high, xhigh, max.

• Launch options are stored and reused if the session is recreated.

Send prompt to a session and return immediately (non-blocking).

Creates the session if it does not exist — no session_start needed. Call session_wait to collect the answer, or session_tail to watch progress.

Sending while Claude is working is supported and is how you steer a run mid-flight; the input is queued and the pending result still spans the whole run. The returned steered field says which happened.

Launch options apply only when the session is created. Set working_dir on the first send.

Returns {dispatched, name, created, steered, state}.

Block until the session finishes its pending work, then return the answer.

This is the completion trigger: it returns Claude's final response as the tool result.

Resumable. If timeout (seconds, max 3600) elapses while Claude is still working, this returns timed_out: true with the partial transcript and keeps the pending dispatch — just call it again. Nothing is lost.

Set auto_compact_at (e.g. 70) to run /compact automatically when context usage crosses that percentage after the turn completes.

Returns {response, state, timed_out, baseline, elapsed_s, steers}. baseline: "lost" means this server restarted since the prompt was sent, so response is a plain tail of the pane rather than an exact diff. A question field appears when the session stopped on a prompt.

Peek at the last lines of pane output without blocking.

Use this to check on a long-running task instead of assuming it is stuck. Returns {name, state, output}.

Answer an on-screen prompt when state is awaiting_input.

choice is an option number ("1", "2", ...) or a navigation key: up, down, enter, escape. Read the question first via session_status.

Launch dialogs (workspace trust, bypass-permissions, effort) are handled automatically — this is only for questions Claude itself asks.

Stop the current turn without killing the session.

Sends Escape (Claude Code's own interrupt), verifies the session left the busy state, and only falls back to Ctrl-C if Escape did not take. Follow up with session_send to redirect.

Return state info for one session.

state is one of: missing, starting, busy, awaiting_input, idle. When it is awaiting_input, question holds the on-screen question and its options. pending means a dispatched prompt has not been collected by session_wait yet. context_pct is null unless /context output happens to be on screen.

List all managed sessions (metadata) plus any live tmux sessions.

Compress the session's context via /compact to recover headroom.

Optionally pass focus to bias what is retained, e.g. "the auth refactor". Output quality degrades above ~70% context usage, so compact before then.

Run /context and report context usage as a percentage.

Returns {name, context_pct}. context_pct is null when the TUI output cannot be parsed — treat that as unknown, not as zero.

Kill the tmux session and remove its stored metadata.

Do this when a task is finished — tmux sessions outlive this server. Do not use it to stop a slow run; use session_interrupt for that.

Kill the tmux session but keep the conversation.

Use this to free a session's transcript — so claude_run can address it without contention — while keeping the ability to resume it later with session_start. Use session_destroy to forget it entirely.

Bind an existing Claude conversation ID to name for future --resume.

Only needed to adopt a session this server did not create — new sessions are assigned an ID automatically.

Run a one-shot claude -p task and return structured JSON.

Best for work that needs no conversation: review a diff, answer a question, make one contained change. Cheaper and faster than a tmux session.

Pass session_name to resume a managed session's conversation, so one-shot and interactive work share history. A live, busy session is refused (two writers would corrupt the transcript); a live idle one is allowed but the running TUI will not show the turn until restarted. fork=True branches to a new session ID instead, avoiding both issues.

Returns {result, session_id, num_turns, total_cost_usd, duration_ms}. Always set max_turns to bound cost.