Operator layer for persistent AI coding workspaces.

PanePilot turns terminal-native coding agents into durable workspaces you can operate: start once, detach/reattach, inject tasks from scripts, inspect health, and recover sessions when they drift.

It is designed for real machines, not demo shells.

PanePilot is the operator surface for long-lived AI coding workspaces.

You bring the runtime (Codex, Claude Code, OpenHands, OpenClaw, or your own agent CLI). PanePilot manages the workspace.

If tmux is the persistence layer, PanePilot is the control plane.

PanePilot is intentionally staged:

• Workspace Ops: run one or many persistent workspaces reliably.
• Goal-Driven Supervision: attach goal/criteria/verifier and keep pushing until acceptance passes.
• Team Control Plane: role-bearing workspaces with explicit handoff and team-level status.

The roadmap spells out the representative CLI surfaces, core data structures, and user stories for each stage. Details live in ROADMAP.md.

Most coding agents behave like interactive terminal apps, but real usage is closer to workspace management than one-off terminal sessions:

• keep a session alive while you disconnect
• send prompts without attaching to the pane
• keep one agent pinned to one workspace
• manage multiple workspaces across repos
• understand which workspace is healthy, starting, or broken
• recover the session if the agent exits
• schedule recurring prompts with cron
• keep logs and local state out of the repo

PanePilot is the control layer around that workflow.

Plain tmux gives you persistence, but not workspace management.

PanePilot adds:

• runtime-aware health checks
• ready detection
• conditional recovery instead of blind restarts
• runtime profiles for different agent CLIs
• goal, criteria, verifier, and role metadata for persistent workspaces
• a stable command surface for status, capture, logs, and task injection
• a path toward managing multiple workspaces as one system

If your answer is "I can already do this in tmux", that is true for the first 10 minutes. PanePilot exists for the third day of managing the same agent workspace, or the fifth workspace on the same machine.

Today, PanePilot is strongest as:

• Workspace Ops for a single long-running agent workspace
• a practical base for multi-workspace setups via --config
• an early Goal-Driven Supervision loop via brief, verify, and keepalive.sh

It is not an agent runtime, and it is not yet a full team control plane. It is the operator layer between an agent CLI and a real machine.

PanePilot is runtime-agnostic. If the agent exposes a terminal command, you can run it inside the managed tmux session.

Common examples:

• claude
• codex
• openclaw
• custom wrapper scripts such as bin/my-agent

Validated profiles currently included:

See docs/runtimes.md for runtime-specific notes.

git clone https://github.com/Galaxy-0/panepilot.git
cd panepilot
cp config/panepilot.env.example config/panepilot.env

Edit config/panepilot.env and set at least:

• PANEPILOT_AGENT_CMD, for example codex
• PANEPILOT_WORK_DIR, the workspace you want the agent to run in

If your agent needs local API credentials, also set:

• PANEPILOT_AGENT_ENV_FILE, for example "$HOME/.codex/crs_oai.env"

If you want the workspace to operate against an explicit mission, also set:

• PANEPILOT_TEAM_NAME
• PANEPILOT_WORKSPACE_ROLE
• PANEPILOT_GOAL_FILE
• PANEPILOT_CRITERIA_FILE
• PANEPILOT_VERIFY_CMD

Then start the session:

./bin/panepilot start

For named workspace configs, use explicit config selection:

./bin/panepilot --config ./examples/workspaces/builder.env start
./bin/panepilot --config ./examples/workspaces/reviewer.env start
./bin/panepilot list

This avoids manual env juggling when you operate multiple workspaces on one machine.

Common commands:

./bin/panepilot status
./bin/panepilot health
./bin/panepilot list
./bin/panepilot doctor
./bin/panepilot verify
./bin/panepilot restart-if-unhealthy
./bin/panepilot wait-ready 20
./bin/panepilot attach
./bin/panepilot capture 80
./bin/panepilot logs keepalive 50
./bin/panepilot send "Review the open TODOs in this repo."
./bin/panepilot send-file ./tasks/example-nightly.md
./bin/panepilot brief
./bin/panepilot send-brief
./bin/panepilot config

$ ./bin/panepilot start
Started session: panepilot
Attach with: ./bin/panepilot attach

$ ./bin/panepilot send "Summarize the open TODOs in this repo."
Sent task to panepilot

$ ./bin/panepilot doctor
check_tmux=ok
check_agent_command=ok
session_state=ready
doctor=ok

Local configuration lives in config/panepilot.env and is gitignored.

Example:

PANEPILOT_AGENT_CMD="codex"
PANEPILOT_AGENT_ENV_FILE="$HOME/.codex/crs_oai.env"
PANEPILOT_TEAM_NAME="core"
PANEPILOT_WORKSPACE_ROLE="builder"
PANEPILOT_GOAL_FILE="$HOME/work/my-project/tasks/goal.md"
PANEPILOT_CRITERIA_FILE="$HOME/work/my-project/tasks/criteria.md"
PANEPILOT_VERIFY_CMD="./scripts/verify-goal.sh"
PANEPILOT_PROCESS_REGEX="^(node|codex)$"
PANEPILOT_READY_REGEX="OpenAI Codex|Use /skills|100% left"
PANEPILOT_ERROR_REGEX="Missing environment variable"
PANEPILOT_WORK_DIR="$HOME/work/my-project"
PANEPILOT_SESSION="panepilot"
PANEPILOT_LOG_DIR="$HOME/.local/state/panepilot"
PANEPILOT_TASK_FILE="$HOME/work/my-project/tasks/nightly.md"

See:

• config/panepilot.env.example
• examples/codex.env
• examples/claude.env
• examples/openclaw.env
• examples/workspaces/builder.env
• examples/workspaces/reviewer.env
• docs/runtimes.md

For multi-workspace operations, pass the config file explicitly on every command:

./bin/panepilot --config ./examples/workspaces/builder.env status
./bin/panepilot --config ./examples/workspaces/reviewer.env send-brief
./bin/panepilot --config ./examples/workspaces/reviewer.env config

./bin/panepilot config and ./bin/panepilot status show the selected config_file, and ./bin/panepilot list includes a config_file column so you can distinguish managed workspaces started from different files.

Useful operational commands:

• ./bin/panepilot health for the current runtime state
• ./bin/panepilot list to inspect managed tmux sessions
• ./bin/panepilot doctor to validate config, runtime command, env file, and session state
• ./bin/panepilot verify to run the goal verifier and return pass/fail
• ./bin/panepilot brief to render the goal, criteria, and role for the current workspace
• ./bin/panepilot send-brief to inject that brief into the running workspace
• ./bin/panepilot restart-if-unhealthy to recover only when state is not healthy
• ./bin/panepilot wait-ready 20 to block until the pane becomes ready
• ./bin/panepilot capture 120 to inspect the current pane buffer
• ./bin/panepilot logs assistant 50 to tail PanePilot logs
• ./bin/panepilot logs keepalive 50 to inspect restart behavior
• ./bin/panepilot logs verify 50 to inspect verifier history and output

To evaluate whether PanePilot is actually helping a single Codex workspace, use the benchmark in docs/single-codex-benchmark.md.

The benchmark defines:

• a primary metric: OMVC (Operator Minutes Per Verified Completion)
• guardrails: VCR, MRT, and UUMR
• baseline vs PanePilot comparison rules
• event logging fields and scorecard templates

Keep the session alive and compact the context every few hours:

0 * * * * /path/to/panepilot/scripts/keepalive.sh

Send a nightly task prompt from a file (example):

0 22 * * * cd /path/to/panepilot && ./bin/panepilot --config /path/to/workspace.env send-file /path/to/nightly.md

You can use tasks/example-nightly.md as a starting point and copy it to your own tasks/nightly.md.

For goal-driven runs, use:

• tasks/example-goal.md
• tasks/example-criteria.md
• scripts/verify-example.sh

keepalive.sh now supports a verification loop:

• if the workspace is unhealthy, restart it
• if the workspace is healthy but PANEPILOT_VERIFY_CMD still fails, log the failure and periodically remind the agent to keep pushing
• if verification passes and PANEPILOT_STOP_ON_VERIFY=1, stop the session automatically

• Ctrl+b d: detach and leave the agent running
• Ctrl+b [: enter scroll mode
• q: exit scroll mode

Right now, one PanePilot config manages one primary workspace well. You can run multiple workspaces by using different config files or tmux session names, but first-class multi-workspace and team flows are still ahead on the roadmap.

No. PanePilot is intentionally focused on workspace management, not abstract workflow orchestration.

No. Subagents are short-lived task delegation. PanePilot is about persistent workspaces and, over time, persistent agent team coordination.

It means a workspace can carry explicit goal and success criteria files, plus a role inside a broader team. It can also run a verifier command that decides whether the goal has actually been met. See docs/goal-driven.md.

Not much. You still benefit from knowing basic tmux keys, but the day-to-day control surface is ./bin/panepilot, not raw tmux commands.

Tune:

• PANEPILOT_PROCESS_REGEX
• PANEPILOT_READY_REGEX
• PANEPILOT_ERROR_REGEX

Short version:

• Workspace Ops: reliable operation of one or many persistent workspaces
• Goal-Driven Supervision: acceptance-driven keepalive and recovery loops
• Team Control Plane: role-bearing workspaces with explicit handoff and supervision

Goal-driven workspace briefs are the first bridge in that direction. See ROADMAP.md and docs/goal-driven.md.

• docs/single-codex-benchmark.md
• docs/demo-script.md
• docs/launch-post.md
• docs/publish-checklist.md

See CONTRIBUTING.md.

MIT