Claude Supervision

Claude Supervision

Hand work to the local claude CLI (Anthropic's Claude Code) and supervise the result — read what Claude actually did, inspect artifacts, verify claims, only then answer the user.

Supervision, not blind delegation.

This is the Claude-Code analog of kimi-supervision and codex-supervision. Use it when you (Codex, another Claude session, a CI script, etc.) want to delegate to Claude Code non-interactively and need the answer + artifacts in a structured place.

Requirements

• PowerShell 7+ (pwsh.exe). claude-setup.ps1 refuses to mark ready=true on PS 5.1.
• Claude Code CLI (claude from @anthropic-ai/claude-code). Install: npm install -g @anthropic-ai/claude-code.
• Authentication: claude auth login (interactive once), OR $env:ANTHROPIC_API_KEY / $env:ANTHROPIC_AUTH_TOKEN. Verified by claude auth status (JSON output, exit 0=in / 1=out).

What this skill provides

Scripts under scripts/:

• common.ps1 — claude path resolution, env hygiene, async I/O, timeout, artifact capture, secret-redacted CLI arg recording, native session JSONL recovery (reads ~/.claude/projects//.jsonl when stdout is unexpectedly empty)
• claude-setup.ps1 — claude auth status JSON probe + PS 7+ + writable state dir
• claude-task.ps1 — delegate a task via claude --print (foreground, blocking)
• claude-review.ps1 — multi-agent cloud-hosted review via claude ultrareview
• claude-bg.ps1 — manage background sessions: --bg / agents / logs / stop / respawn / rm / daemon status
• claude-list-sessions.ps1 — inspect this wrapper's own session artifacts

These scripts:

• prefer the native claude.exe at $USERPROFILE\.local\bin\ (no .cmd shim chain → no Windows stdio race like codex)
• read/write UTF-8 throughout; set Console.OutputEncoding to UTF-8
• pass the prompt via stdin (no argv length limits, no quoting hell on multi-line/unicode text)
• async stdout/stderr reads with ReadToEndAsync (no pipe-buffer deadlock)
• -TimeoutSec with hard kill (Process.Kill($true) with Kill() fallback for older runtimes) and classification='timeout'
• always write last-prompt.txt, last-response.txt, stderr.log, session.json to the session dir
• session ID format YYYYMMDD-HHmmss-fff--- (no same-millisecond collisions)
• redact secrets in --settings / --mcp-config / --agents / --json-schema / --*-system-prompt inline JSON before serializing to session.json
• truncate long inline JSON args in session.json for readability

State layout

State root resolution order:

1. $env:CLAUDE_SUPERVISION_HOME (override)
2. %LOCALAPPDATA%\claude-supervision\ (Windows default)
3. %USERPROFILE%\.claude-supervision\ (fallback)
4. C:\claude-supervision\ (last resort)

Per session:

• sessions//last-prompt.txt
• sessions//last-response.txt — claude stdout (or recovered from JSONL — see below)
• sessions//stderr.log
• sessions//session.json

Claude's own session JSONL lives at ~/.claude/projects//.jsonl. The wrapper attempts native recovery from there when --print stdout is empty but the process exited 0 (i.e., Claude ran but we didn't capture output via the pipe). session.json.recovered_from_jsonl: true records that recovery fired.

Authoritative CLI flag matrix (Claude Code 2.1.146)

Verified empirically — claude --help doesn't list every flag; the docs at are authoritative. Key categories:

| Category | Flags (wrapper exposure) | |---|---| | Subcommands | claude --print (task) / claude --bg "" (background) / claude ultrareview [target] (multi-agent review) / claude auth status (used by setup) / claude agents/logs/stop/respawn/rm/daemon (used by claude-bg.ps1) | | Sessions | --continue / -c / --resume / -r / --fork-session / --session-id / --no-session-persistence / --from-pr | | Model & effort | --model / --effort low\|medium\|high\|xhigh\|max / --fallback-model | | Budget | --max-budget-usd / --max-turns | | Permissions | --permission-mode default\|acceptEdits\|auto\|bypassPermissions\|dontAsk\|plan / --dangerously-skip-permissions / --allow-dangerously-skip-permissions / --permission-prompt-tool / --allowedTools / --disallowedTools / --tools / --add-dir | | Output formats | --output-format text\|json\|stream-json / --input-format text\|stream-json / --include-hook-events / --include-partial-messages / --json-schema '' / --verbose | | System prompt | --system-prompt / --system-prompt-file / --append-system-prompt / --append-system-prompt-file | | Agents | --agent / --agents '' | | MCP / settings / plugins | --mcp-config / --strict-mcp-config / --settings / --setting-sources user,project,local / --plugin-dir (repeatable) / --plugin-url (repeatable) | | Hooks lifecycle | --init (Setup hooks before session) / --init-only (Setup + SessionStart, then exit) / --maintenance | | Cleanliness | --bare (skip hooks/plugins/CLAUDE.md/auto-memory) / --disable-slash-commands / --exclude-dynamic-system-prompt-sections | | Diagnostics | --debug [filter] / --debug-file / --verbose | | Misc | --name / --betas / --file (file resources) | | Skipped (interactive-only) | --ide / --chrome / --remote-control / --tmux / --worktree / --teleport / --remote |

When to use which script

| Goal | Script | Key flags | |------|--------|-----------| | First-time check | claude-setup.ps1 | (none) | | Fresh task | claude-task.ps1 -Message '...' | -Model / -Effort / -PermissionMode | | Task with edits | claude-task.ps1 -AcceptEdits -Message '...' | shortcut for -PermissionMode acceptEdits | | Continue most recent | claude-task.ps1 -Continue -Message '...' | reuses session in -Workspace | | Resume specific session | claude-task.ps1 -Resume -Message '...' | optionally -ForkSession | | Cap cost / turns | claude-task.ps1 -MaxBudgetUsd 0.50 -MaxTurns 5 -Message '...' | hard limits | | Custom system prompt | claude-task.ps1 -AppendSystemPrompt 'TypeScript only' -Message '...' | also -SystemPromptFile, -AppendSystemPromptFile | | Custom agent | claude-task.ps1 -Agent code-reviewer -Message '...' OR -AgentsFile agents.json | configure subagents per-run | | Per-run MCP | claude-task.ps1 -McpConfig ./linear.json -StrictMcpConfig -Message '...' | clean MCP scope | | Per-run plugin | claude-task.ps1 -PluginDirs ./local-plugin -Message '...' | load just this plugin | | Structured JSON output | claude-task.ps1 -JsonSchemaFile triage.json -OutputFormat json -Message '...' | enforces schema | | Live progress stream | claude-task.ps1 -OutputFormat stream-json -IncludeHookEvents -Message '...' | JSONL events | | Clean-room run | claude-task.ps1 -Bare -Message '...' | skip hooks/plugins/CLAUDE.md | | Ephemeral (no rollout) | claude-task.ps1 -NoSessionPersistence -Message '...' | don't record to ~/.claude/projects | | Background dispatch | claude-bg.ps1 -Submit '' -Workspace . | returns session ID; daemon does the work | | Poll background | claude-bg.ps1 -Logs | recent output | | List background sessions | claude-bg.ps1 -List -Workspace . | JSON table | | Stop/restart/remove background | claude-bg.ps1 -Stop\|-Respawn\|-Remove | lifecycle ops | | Multi-agent cloud review | claude-review.ps1 -Workspace . [-Target ] [-Json] | wraps claude ultrareview | | Inspect wrapper sessions | claude-list-sessions.ps1 | local artifact browser |

Standard recipes

Set $skillDir to wherever you installed this skill. A common location is $env:USERPROFILE\.agents\skills\claude-supervision.

Setup

$skillDir = Join-Path $env:USERPROFILE ".agents\skills\claude-supervision"
& (Join-Path $skillDir "scripts\claude-setup.ps1")

ready: true means: CLI found, claude auth status returned loggedIn:true, state dir writable, PS 7+. Setup output also includes auth_method, auth_email, subscription.

Fresh task (read-only by default)

& '...\claude-task.ps1' -Workspace '.' -Message 'Diagnose why test_login_redirect fails intermittently.'

Task with file edits

& '...\claude-task.ps1' -Workspace '.' -AcceptEdits -Message 'Patch the off-by-one in src/foo.py and add a regression test.'

Continue / resume

# Continue most recent session in this workspace
& '...\claude-task.ps1' -Workspace '.' -Continue -Message 'Apply the fix you proposed.'

# Resume a specific session UUID
& '...\claude-task.ps1' -Workspace '.' -Resume 'a1b2c3d4-...' -Message 'Add the tests we discussed.'

# Fork: continue from a known-good state without overwriting the original session id
& '...\claude-task.ps1' -Workspace '.' -Resume 'a1b2...' -ForkSession -Message 'Try a different approach.'

System prompt override

# Append per-task instructions (preserves default tool guidance + safety rules)
& '...\claude-task.ps1' -Workspace '.' -AppendSystemPrompt 'Always use TypeScript; never use any.' -Message '...'

# Append from file (long rule sets)
& '...\claude-task.ps1' -Workspace '.' -AppendSystemPromptFile './rules/typescript.md' -Message '...'

# Replace entire system prompt (drops default tool guidance — use only for non-coding agents)
& '...\claude-task.ps1' -Workspace '.' -SystemPromptFile './prompts/legal-reviewer.txt' -Message '...'

Subagents

# Use a project-defined agent
& '...\claude-task.ps1' -Workspace '.' -Agent code-reviewer -Message 'Review the diff.'

# Define agents inline per-run
$agents = '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer","tools":["Read","Grep","Glob"]}}'
& '...\claude-task.ps1' -Workspace '.' -AgentsInline $agents -Message '...'

# Or from a file
& '...\claude-task.ps1' -Workspace '.' -AgentsFile ./team/agents.json -Message '...'

Per-run MCP / settings / plugins

# Bring in just the Linear MCP for this task
& '...\claude-task.ps1' -Workspace '.' -McpConfig ./mcp/linear.json -StrictMcpConfig -Message 'Triage open Linear issues.'

# Override settings for this session only
& '...\claude-task.ps1' -Workspace '.' -SettingsFile ./session-settings.json -Message '...'

# Load only user + project settings (skip local overrides)
& '...\claude-task.ps1' -Workspace '.' -SettingSources 'user,project' -Message '...'

# Side-load a plugin without installing it permanently
& '...\claude-task.ps1' -Workspace '.' -PluginDirs './local-plugin','./another-plugin' -Message '...'

Budget control

# Cap spend AND turns simultaneously
& '...\claude-task.ps1' -Workspace '.' -MaxBudgetUsd 0.50 -MaxTurns 5 -Model haiku -Message 'Cheap one-shot.'

# Auto-fallback if default model is overloaded
& '...\claude-task.ps1' -Workspace '.' -Model opus -FallbackModel sonnet -Message '...'

Structured JSON output

# Schema in a file (wrapper reads it and inlines into --json-schema)
& '...\claude-task.ps1' -Workspace '.' -JsonSchemaFile './triage.json' -OutputFormat json -Message 'Triage this stack trace.'

# Inline schema
& '...\claude-task.ps1' -Workspace '.' -JsonSchemaInline '{"type":"object","required":["verdict"]}' -OutputFormat json -Message '...'

Live progress (stream-json)

# Get JSONL events as Claude works (includes assistant turns, tool uses, hook events, partial deltas)
& '...\claude-task.ps1' -Workspace '.' `
    -OutputFormat stream-json -IncludeHookEvents -IncludePartialMessages `
    -Message 'Long-running task with progress updates.'

Clean-room / ephemeral

# Skip hooks / plugins / CLAUDE.md / auto-memory (when one of those is suspected of breaking the run)
& '...\claude-task.ps1' -Workspace '.' -Bare -Message 'Repro WITHOUT my custom config.'

# Don't record to ~/.claude/projects
& '...\claude-task.ps1' -Workspace '.' -NoSessionPersistence -Message 'Sensitive content.'

# Disable all skills/commands for this run
& '...\claude-task.ps1' -Workspace '.' -DisableSlashCommands -Message '...'

# Improve prompt-cache reuse across users (moves per-machine fields out of system prompt)
& '...\claude-task.ps1' -Workspace '.' -ExcludeDynamicSystemPromptSections -Message '...'

Diagnostics

# Full debug stream
& '...\claude-task.ps1' -Workspace '.' -DebugFilter 'api,hooks' -VerboseOutput -Message '...'

# Write debug log to a file (implicitly enables debug)
& '...\claude-task.ps1' -Workspace '.' -DebugFile 'C:\tmp\claude-debug.log' -Message '...'

Note: PowerShell auto-adds -Verbose and -Debug as common parameters on advanced functions (anything with [CmdletBinding()] or [Parameter()]). The wrapper uses -VerboseOutput and -DebugFilter to dodge the collision while still mapping to claude CLI's --verbose / --debug [filter].

Background dispatch (the big one — async delegation)

# 1. Submit — returns session ID immediately, daemon handles the work
& '...\claude-bg.ps1' -Submit 'Investigate the flaky test_login_redirect across the codebase and propose a fix.' `
    -Workspace . -Agent code-reviewer -Model sonnet -PermissionMode plan -Name 'flaky-login-investigation'
# Output:
# backgrounded · 7c5dcf5d
#   claude agents             list sessions
#   claude attach 7c5dcf5d    open in this terminal
#   claude logs 7c5dcf5d      show recent output
#   claude stop 7c5dcf5d      stop this session

# 2. Poll for progress (non-blocking — returns recent stdout)
& '...\claude-bg.ps1' -Logs 7c5dcf5d

# 3. List all background sessions in this workspace
& '...\claude-bg.ps1' -List -Workspace .

# 4. Daemon health check
& '...\claude-bg.ps1' -DaemonStatus

# 5. Lifecycle
& '...\claude-bg.ps1' -Stop 7c5dcf5d       # gracefully stop
& '...\claude-bg.ps1' -Respawn 7c5dcf5d    # restart with conversation intact
& '...\claude-bg.ps1' -Remove 7c5dcf5d     # remove from list (transcript stays for resume)

Multi-agent cloud review (ultrareview)

# Review the current branch
& '...\claude-review.ps1' -Workspace .

# Review a specific PR
& '...\claude-review.ps1' -Workspace . -Target 1234

# Review against a base branch
& '...\claude-review.ps1' -Workspace . -Target 'origin/main'

# Raw bugs.json payload (machine-readable)
& '...\claude-review.ps1' -Workspace . -Target 1234 -Json -TimeoutMin 45

Inspect prior wrapper runs

& '...\claude-list-sessions.ps1' -Last 10
& '...\claude-list-sessions.ps1' -Session '20260522-110000-000-1234-5678-task' -View response

Views: meta / prompt / response / stderr.

Native session JSONL recovery

The wrapper attempts recovery in this exact case: exit code 0 + non-timeout + stdout empty. It:

1. Computes ~/.claude/projects// from -Workspace
2. Scans .jsonl files; picks the most recently modified within the run window
3. Walks the JSONL backwards, finds the last entry with type:'assistant' + message.content[].type:'text'
4. Writes the recovered text to last-response.txt and sets session.json.recovered_from_jsonl: true

The header banner emits (stdout was empty — answer recovered from ~/.claude/projects//*.jsonl) when recovery fires.

When recovery fails (no matching JSONL, or no assistant text), classification stays empty and you'll need to inspect ~/.claude/projects//*.jsonl manually.

How to interpret artifacts

last-response.txt

Claude's stdout under --output-format text, OR text recovered from JSONL.

For --output-format json / --output-format stream-json, this file contains structured records — parse before displaying.

session.json

Records supervision state. Key fields:

• mode — task / task-continue / task-resume / ultrareview
• exec_mode — plain / continue / resume
• claude_version, cli_args (secrets redacted, long values truncated)
• permission_mode, skip_permissions
• `mo

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ltczding-gif
• Source: ltczding-gif/agent-supervision-skills
• License: MIT
• Homepage: https://github.com/ltczding-gif/agent-supervision-skills#readme

Install and usage instructions live in the source repository linked above.