# Agent Loops

An agent loop is when one agent manages other agents for you. It picks up work, creates panes, starts agents in each one, 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.

If you want the exact workflow Pane uses for issue fan-out, PR testing, and independent Codex/Claude reviews, grab the open-source orchestrator skills for [Codex](https://github.com/dcouple/skills/tree/main/parsa/.codex/skills/runpane-orchestrator) or [Claude Code](https://github.com/dcouple/skills/tree/main/parsa/.claude/skills/runpane-orchestrator).

## 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.

## Create a pane for each task

Each pane maps to one piece of work: an issue, a PR review, an implementation. Create one per task:

```bash
runpane panes create \
  --repo active \
  --name "review-pr-51" \
  --agent codex \
  --prompt "Review PR #51. Run checks, summarize findings, and stop before merging." \
  --source agent \
  --wait-ready \
  --yes \
  --json
```

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 <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 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 <panel-id> \
  --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 <panel-id> --input-file - --yes --json

runpane panels output --panel <panel-id> --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 <panel-id> --input-file - --yes
runpane panels screen --panel <panel-id> --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 <panel-id> --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. Create one background-friendly Pane per task or review stream.
5. Start the right terminal agent in each pane with a clear initial prompt.
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 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).