runpane CLI

runpane is a CLI that does two things: it installs Pane, and it lets agents control Pane.

For the landing page overview, see runpane CLI: Agent Control for Pane. For the full issue-to-PR workflow, check the open-source orchestrator skills for Codex  and Claude Code .

Pane Chat is the built-in orchestrator that uses these same commands from inside Pane. It can run Claude or Codex, load local workflow skills, and coordinate repos, panes, agents, reviews, and PR tests.

How agents find Pane

Start by checking that Pane is set up and healthy:

# Before installing anything:
curl -fsSL https://runpane.com/runpane-cli-contract.json
 
# After runpane is installed:
runpane doctor --json
runpane agent-context --json
runpane agent-context --command "panes create" --json

runpane agent-context prints a short summary by default. It works without Pane running. Use --command to get full details for one specific command when you need them. The command name is flexible: panes create, panes.create, and runpane panes create all work.

runpane version just prints the package version. It doesn’t launch or focus Pane. runpane doctor checks the app and daemon, but on macOS and Windows it reads app metadata instead of launching Pane.

Install

For a one-time install or update:

npx --yes runpane@latest
pnpm dlx runpane@latest
pipx run runpane
uvx runpane@latest

For agents or scripts that call runpane repeatedly, install it permanently:

npm i -g runpane
runpane setup
 
python -m pip install runpane
python -m runpane setup

The packages don’t install or configure Pane during package install. Nothing happens until you actually run a runpane command.

Setup wizard

Run runpane with no arguments (or runpane setup) in a terminal. The wizard can:

• Install the Pane desktop app
• Set up this machine as a remote host
• Update an existing install
• Run diagnostics

In CI or non-interactive shells, it prints help instead of waiting for input.

Command reference

Commands that change things require --yes for automation.

Typical agent workflow

Here’s what an agent does to get started:

runpane doctor --json
runpane agent-context --json
runpane repos list --json
runpane repos add --path "$PWD" --yes --json
runpane agents doctor --agent codex --repo active --json

Create a pane with an agent:

runpane panes create \
  --repo active \
  --name "issue-252" \
  --agent codex \
  --prompt "Plan issue 252. Stop before editing." \
  --source agent \
  --wait-ready \
  --yes \
  --json

Use a custom terminal command when the agent isn’t built in:

runpane panes create \
  --repo active \
  --name "custom-loop" \
  --tool-command "bash -lc 'my-agent --flag'" \
  --initial-input-file prompt.txt \
  --source agent \
  --wait-ready \
  --yes \
  --json

After creation, check what actually happened before pulling more history:

runpane panels list --pane <pane-id> --json
runpane panels wait --panel <panel-id> --for ready --timeout-ms 30000 --json
runpane panels screen --panel <panel-id> --limit 80 --json
runpane panels output --panel <panel-id> --limit 200 --json

Use panels submit for normal text:

runpane panels submit \
  --panel <panel-id> \
  --text "Continue with the review pass." \
  --yes \
  --json

Use panels input for raw bytes, Ctrl-C, escape sequences, or anything shell-sensitive:

printf '\003' | runpane panels input --panel <panel-id> --input-file - --yes --json
runpane panels screen --panel <panel-id> --json

If text is sitting in a Codex or Claude composer, let Pane submit it instead of guessing whether it’s Enter or Ctrl+Enter:

runpane panels submit-composer --panel <panel-id> --strategy auto --yes --json

Background panes

When agents create panes, they shouldn’t steal your active view.

• Use --source agent so the pane opens in the background by default.
• Use --no-focus if you want an explicit background guarantee.
• Use --focus only when the user asked to be moved to the new pane.

Adding review tabs to the same pane

After a PR exists, keep reviewers in the same pane instead of creating more top-level panes:

runpane panels create \
  --pane <pane-id> \
  --agent claude \
  --source agent \
  --no-focus \
  --wait-ready \
  --yes \
  --json
 
runpane panels create \
  --pane <pane-id> \
  --agent codex \
  --source agent \
  --no-focus \
  --wait-ready \
  --yes \
  --json

Send each reviewer /review, wait for them to finish, copy their findings into the implementation tab, and ask the implementation agent to fix the real issues. Repeat until only non-blocking edge cases remain.

The reusable version of this workflow lives in dcouple/skills: Codex  and Claude Code .

Creating multiple panes at once

panes create --from-json <path|-> accepts a JSON payload. It’s cleaner than shell-escaping a bunch of prompts.

{
  "repo": "active",
  "source": "agent",
  "waitReady": true,
  "panes": [
    {
      "name": "issue-252-discussion",
      "agent": "codex",
      "initialInput": "Run the discussion skill for issue 252."
    },
    {
      "name": "issue-253-discussion",
      "agent": "codex",
      "initialInput": "Run the discussion skill for issue 253."
    }
  ]
}

runpane panes create --from-json panes.json --yes --json

WSL and Windows

If your agent runs inside WSL but Pane is installed as a Windows app, the Linux shell might not see the Windows daemon. Call the Windows wrapper through PowerShell from a Windows directory:

powershell.exe -NoProfile -Command \
  'Set-Location $env:TEMP; runpane doctor --json'

Create panes the same way, selecting the saved repo by name or id:

powershell.exe -NoProfile -Command \
  'Set-Location $env:TEMP; runpane panes create --repo "Pane" --name "loop-smoke" --agent codex --prompt "Say hello from this loop and wait." --source agent --wait-ready --yes --json'

Run runpane agents doctor --agent codex --repo <selector> --json to check the environment Pane will actually use, not just the shell where the wrapper is running.

Wrapper commands

runpane install [client|daemon] [options]
runpane update [options]
runpane version
runpane doctor [--json]
runpane help [command]

Wrapper flags:

--version <latest|vX.Y.Z>
--download-dir <path>
--pane-path <path>
--format <auto|appimage|deb|dmg|zip|exe>
--dry-run
--yes
--verbose

runpane install is shorthand for runpane install client. runpane install daemon forwards remote-host setup flags to Pane’s --remote-setup path.

Remote host setup flags:

--label <name>
--prefer-tunnel <tailscale|ssh|manual|auto>
--channel <stable|nightly>
--base-url <url>
--pane-dir <path>
--listen-port <port>
--port <port>
--repo-ref <ref>
--auto-listen-port
--interactive-tailscale-setup
--no-install-service
--no-tailscale-serve
--print-only

Unknown daemon flags get forwarded so newer Pane versions can extend remote setup without needing a wrapper update first. Unknown flags for other commands fail clearly.

Local flags

These flags are used by commands that talk to the Pane daemon:

--pane-dir <path>
--repo <selector>
--pane <pane-id>
--panel <panel-id>
--path <path>
--name <name>
--worktree-name <name>
--base-branch <branch>
--agent <codex|claude>
--tool-command <command>
--title <title>
--initial-input <text>
--prompt <text>
--initial-input-file <path|->
--from-json <path|->
--timeout-ms <milliseconds>
--ready-timeout-ms <milliseconds>
--concurrency <count>
--limit <count>
--for <initialized|ready|idle|text>
--contains <text>
--interval-ms <milliseconds>
--text <text>
--input-file <path|->
--source <user|agent>
--strategy <auto|codex-ctrl-enter|enter>
--json
--wait-ready
--no-focus
--focus

--prompt is an alias for --initial-input. In JSON payloads, use initialInput.

JSON schemas

The --json request and response schemas live in one place:

curl -fsSL https://runpane.com/runpane-cli-contract.json

This is the single source of truth for the npm wrapper, PyPI wrapper, help text, and package tests.

Shell installers

Shell installers are still available if you don’t have Node or Python:

Remote host shell installers: