Claude Supervisor for Pi

Supervise and manage multiple persistent interactive Claude Code sessions running inside tmux.

Features

• Polls supervised tmux panes concurrently every five seconds.
• Distinguishes active work, idle output, permission prompts, missing sessions, likely questions, and unresolved failures.
• Classifies only the live pane tail, preventing stale scrollback from controlling current state.
• Wakes Pi automatically after a stable waiting state or a managed Claude Stop hook.
• Spawns Claude Code sessions with ownership metadata and a durable Stop hook.
• Closes validated completed managed sessions and records a closure audit entry.
• Auto-closes clean, unattached managed sessions after a 30-minute idle grace period.
• Previews legacy cleanup and requires interactive confirmation before closing anything.
• Requires interactive user confirmation before sending into a detected destructive, deployment, production, credential, or security-sensitive permission prompt.
• Sends multiline prompts through a mode-0600 temporary tmux buffer.
• Restores monitored sessions after Pi reloads or resumes.

Requirements

• pi, claude, and tmux available in PATH
• Claude Code configured and authenticated

Install

pi install git:github.com/ygncode/claude-supervisor

Restart Pi or run /reload after installation.

Commands

/claude-supervise                         # add an existing tmux session
/claude-supervise <session>               # monitor a named session
/claude-supervise status                  # show lifecycle status
/claude-supervise close <session>         # close a validated managed session
/claude-supervise cleanup                 # preview and confirm legacy cleanup
/claude-supervise stop <session>          # stop one monitor without closing it
/claude-supervise stop                    # stop all monitors
/claude-send <message>                    # send when one session is watched
/claude-send <session> :: <text>          # send to a named session
/claude-spawn [-m model] [-n name] [-d dir] [-e effort]

/claude-spawn uses Claude's configured default model when -m is omitted. Supported effort values depend on the installed Claude Code version.

claude_supervisor tool

The agent-facing tool supports:

• list — list tmux sessions and mark likely Claude Code sessions
• start — start background monitoring
• status — report state, ownership, attachment, failure, and auto-close information
• capture — inspect recent output
• send — submit a multiline response; sensitive permission prompts require interactive confirmation
• spawn — start a supervisor-managed Claude Code session
• close — close one validated, idle managed session
• cleanup — preview eligible legacy sessions without deleting anything
• stop — stop one or all monitors without closing tmux sessions

Monitoring and completion

The extension polls every five seconds. A visual idle, permission, or missing state must remain stable for two polls before Pi is notified.

Managed sessions receive an additional Claude Code Stop hook through --settings. The hook writes @claude_agent_settled on the active tmux pane, giving the supervisor a durable completion signal that cannot be missed between visual polls.

After start succeeds, do not run sleep loops or repeatedly poll status. End the current turn and wait for an injected Claude Supervisor event. Use status or capture when processing that event or diagnosing a specific problem.

Lifecycle safety

Sessions created by spawn carry:

• @claude_supervisor_managed=1
• @claude_supervisor_owner=<Pi session ID>
• @claude_supervisor_created_at=<timestamp>

A managed session cannot be closed when it is:

• owned by another Pi supervisor session
• the supervisor's own tmux session
• attached to a tmux client
• active
• waiting at a permission prompt
• showing a likely unresolved failure

Automatic close additionally preserves likely questions and requires a valid Claude Stop signal older than 30 minutes.

Legacy cleanup is conservative: sessions must be unattached, look like Claude Code, be idle for at least ten minutes according to tmux activity, and show no permission prompt, likely question, sensitive request, or unresolved failure. The tool action is preview-only; the slash command shows the exact candidates, asks for confirmation, and rechecks every session before closing it.

Safety notes

• send performs a fresh pane inspection. If a sensitive permission prompt is detected, it opens an interactive confirmation. Without UI confirmation, the send is rejected.
• State and failure detection remain heuristic because Claude Code is an external TUI. Validate important completion claims before closing.
• Stopping supervision does not stop or delete tmux sessions.
• Automatic cleanup never closes unmarked legacy sessions.

Test

npx --yes tsx ~/.pi/agent/extensions/claude-supervisor/classifier.test.ts
npx --yes tsx ~/.pi/agent/extensions/claude-supervisor/lifecycle.test.ts

Run /reload after changing the extension.