Session Supervisor — Durable Coding Sessions for OpenClaw

Stop losing terminal state

Session Supervisor is a skill that turns ordinary tmux sessions into managed workcells for your coding agents. Each session gets a stable socket, a run directory, an operator brief, a handoff file, and a status record you can inspect without attaching live.

Long-running coding work should not die when your laptop sleeps, your SSH drops, or a provider rate-limits you mid-task. Session Supervisor treats each agent run like infrastructure: it survives disconnects, recovers cleanly from failures, and leaves behind artifacts the next pass can pick up immediately.

What Session Supervisor handles

• Durable workcells — each coding session runs inside tmux with a stable socket that survives machine quirks and disconnects.
• Run directories with full artifact trail — every session produces a brief, agent log, status record, verification script, and human-readable handoff.
• Watchdog checks — detect idle or stuck sessions by inspecting log freshness and pane output without attaching live.
• Recovery playbook — structured responses for auth failures, rate limits, partial completions, vanished sessions, and dirty repos.
• Resume protocol — restart from artifacts instead of memory. Read the handoff, inspect the diff, rewrite the brief for remaining scope, and relaunch.
• Notifier adapters — get notified on completion via OpenClaw events, Telegram, Slack, or local desktop notifications.

How it works

1. Create the control directories and pick a stable tmux socket path.
2. Write a brief with the specific objective, constraints, and definition of done.
3. Launch the agent inside tmux using the provided launch recipe.
4. The session streams output to a log, writes a machine-readable status on exit, and leaves a human-readable handoff for the next pass.

What's included

• SKILL.md runbook — the complete operating pattern for durable coding sessions, from setup through recovery.
• Launch recipes — copy-paste commands for single-repo and multi-repo session launches.
• Runtime layout — a lightweight control directory structure outside the repo with sockets, run directories, and templates.
• Recovery playbook — five documented failure modes with exact diagnosis steps and response actions.
• Resume protocol — a step-by-step process for restarting interrupted work from artifacts.
• Handoff format template — a standard format so every session leaves context the next agent (or human) can act on immediately.
• Notifier adapter examples — ready-made snippets for OpenClaw, Telegram, Slack, and macOS desktop notifications.

Best for

• Developers running long coding sessions that outlast a single terminal window
• Multi-repo operators juggling parallel agent tasks across separate codebases
• Anyone tired of losing terminal state to SSH drops, laptop sleep, or provider rate limits
• Teams that need every agent run to leave an inspectable trail and a clean handoff

Under the hood

Session Supervisor follows a strict operating contract: one repo, one objective, one session. Every run is artifact-first — the session is not the source of truth, the files it produces are.

• Artifact-first contract — brief.md defines the task, verify.sh defines the check, agent.log keeps raw output, status.json records the exit, handoff.md carries the next-step context.
• Stable socket path — uses a persistent socket instead of the default temp location so sessions survive system quirks.
• Repo-local add-ons — drop a SUPERVISOR.md into any repo for custom test commands, deployment rules, and forbidden directories.

Get started

What you'll download

session-supervisor/
├── SKILL.md        — orchestration runbook
├── recipes/        — launch templates
├── recovery/       — 5 failure mode playbooks
└── adapters/       — notifier configs (Telegram, Slack, Desktop)

Before vs After

What operators are saying