# Agent Loops An agent loop is when one agent manages other agents for you. It picks up work, creates a pane for each feature, opens tabs in that pane for review and QA, checks on their progress, sends follow-up input, and tells you what needs your attention. Pane gives that loop the commands it needs to work. Your loop runner can be Codex, Claude Code, a shell script, cron, or anything else that can run terminal commands. To start a loop on a schedule, like every morning at 9, use [Loops](/docs/loops). If you want the exact workflow Pane uses for issue fan-out, PR testing, and independent Codex/Claude reviews, use the orchestrator skill that ships with Pane. It's built into [Pane Chat](/docs/pane-chat). ## Getting started First, check that Pane is healthy and see what commands are available: ```bash runpane doctor --json runpane agent-context ``` Need details on a specific command? Load them one at a time: ```bash runpane agent-context --command "panes create" --json runpane agent-context --command "panels wait" --json runpane agent-context --command "panels submit" --json ``` Agents can also read the command list before installing anything: [`/runpane-cli-contract.json`](/runpane-cli-contract.json). ## Add the repo Don't assume Pane already knows about the repo. Check first, then add it: ```bash runpane repos list --json runpane repos add --path "$PWD" --yes --json runpane agents doctor --agent codex --repo active --json ``` `repos add` needs an existing git repo. It won't create directories or run `git init` for you. ## One pane per feature **1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane.** A pane is a git worktree. Creating one checks out the repo, installs dependencies and often builds, so creating several at once can freeze the machine. Create a pane only when the work's branch has no pane yet. That covers new work and an existing PR that has no pane. To find the pane for a PR, get its head branch, then check each pane's `worktreePath` from `panes list`: ```bash gh pr view --json headRefName runpane panes list --repo active --json git -C branch --show-current ``` If no pane owns the branch, create one: ```bash runpane panes create \ --repo active \ --name "issue-51-login" \ --agent codex \ --prompt "Implement issue #51. Open a PR when checks pass." \ --source agent \ --wait-ready \ --yes \ --json ``` Every later agent for that feature opens as a new tab in its pane. It's a fresh agent with its own context, sharing the pane's worktree and branch: ```bash runpane panels create \ --pane \ --agent codex \ --initial-input "Review the PR from this branch. Run checks, summarize findings, and stop before merging." \ --source agent \ --no-focus \ --wait-ready \ --yes \ --json ``` Tabs share one checkout. Only the implementer changes the branch or HEAD. Review, audit and QA tabs never run `git checkout`, `reset` or `stash`. Keep the pane until its PR merges or closes, so review, fix and QA tabs still have its worktree. For agents that aren't built in, use a custom terminal command: ```bash runpane panes create \ --repo active \ --name "custom-agent-loop" \ --tool-command "bash -lc 'my-agent --flag'" \ --initial-input-file prompt.txt \ --source agent \ --wait-ready \ --yes \ --json ``` Use `--source agent` or `--no-focus` so the pane opens in the background without stealing your active view. Only use `--focus` when the user asked to be moved there. ## Check what happened After creating a pane, find its terminal tab and read recent output: ```bash runpane panes list --repo active --json runpane panels list --pane --json runpane panels wait --panel --for ready --timeout-ms 30000 --json runpane panels screen --panel --limit 80 --json runpane panels output --panel --limit 200 --json ``` Use `panels screen` for a quick look at what's on screen right now. Use `panels output` when you need scrollback history. Only increase `--limit` when the response says there's more to read. ## Send input For normal text plus Enter: ```bash runpane panels submit \ --panel \ --text "Continue with the review pass." \ --yes \ --json ``` For prompts with newlines, quotes, Ctrl-C, or anything shell-sensitive, pipe it in: ```bash printf 'Continue with the review pass.\n' | \ runpane panels input --panel --input-file - --yes --json runpane panels output --panel --limit 200 --json ``` If you need to interrupt a running command, send Ctrl-C first, check the output, then send the next command separately: ```bash printf '\003' | runpane panels input --panel --input-file - --yes runpane panels screen --panel --json ``` If text is already in an agent composer, let Pane submit it instead of guessing whether it's Enter or Ctrl+Enter: ```bash runpane panels submit-composer --panel --strategy auto --yes --json ``` ## WSL and Windows If your agent runs inside WSL but Pane is installed as a Windows app, call the Windows wrapper through PowerShell: ```bash powershell.exe -NoProfile -Command \ 'Set-Location $env:TEMP; runpane repos list --json' ``` Create panes the same way, selecting the saved WSL repo by name or id: ```bash 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' ``` ## Starter prompt Copy this into Codex, Claude Code, or any agent that can run shell commands: ```text You are running an agent loop for this repo. Every cycle: 1. Inspect GitHub issues and PRs that need action. 2. Fetch the public contract if needed, then run runpane doctor --json and runpane agent-context. 3. Make sure this repository is saved in Pane and the requested agent is runnable. 4. 1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane. Create a Pane only when the work's branch has no Pane yet. Find an existing Pane with runpane panes list --repo --json by matching the PR's head branch against git -C branch --show-current. 5. Start the right terminal agent with a clear initial prompt. For a new Pane use runpane panes create. For a tab use runpane panels create --pane --agent --initial-input "" --source agent --no-focus --wait-ready --yes --json. Tabs share one checkout: only the implementer moves HEAD, and review, audit and QA tabs never git checkout, reset or stash. 6. Use --source agent or --no-focus for background work unless the user asked to be moved. 7. Wait for readiness and read compact screen state before claiming a pane started correctly. 8. Send follow-up input with panels submit or submit-composer; use panels input only for exact bytes. 9. Report the panes and tabs created, what each is doing, and what needs human review. Keep output brief. Do not merge without explicit human approval. ``` For the product-level walkthrough, see [How to Set Up Your First AI Agent Loop with Pane](/agent-loops).