# Pane Chat

Pane Chat is one conversation that controls your whole workspace.

You can have as many as you like. Each one is a [Session](/docs/sessions), with its own name, agent, folder and list of panes it owns. Find them under **Sessions** in the sidebar.

Normal agent tabs sit inside a pane. They work on one repo, one branch. Pane Chat sits above all of that. It's an <Term id="orchestrator">orchestrator</Term>: it can see every repo you've added, every pane you've created, and every agent that's running.

Use it when you want to say something like:

> Add this repo, create three panes for these features, start Codex in each one, keep a review tab ready, and tell me when the PRs are ready to test.

## What it can do

Pane Chat uses the `runpane` CLI to control your workspace:

```bash
runpane repos list --json
runpane panes list --json
runpane panes create ...
runpane panels create --pane <pane-id> ...
runpane panels list --pane <pane-id> --json
runpane panels output --panel <panel-id> --limit 200 --json
```

That means it can:

- See which repos you've added
- See all your panes and their worktrees
- Read recent terminal output from any tab
- Create a pane for each new feature and start an agent in it
- Open review, fix and QA tabs in a feature's existing pane
- Check what's running and what's waiting for input

It's all terminal commands. Agents that prefer tools can use Pane's <Term id="mcp">MCP</Term> server instead, which does the same things.

## How it knows when a pane needs it

A Session doesn't start anything on its own. Creating, opening or restarting one sends no prompt and runs no checks. Nothing happens until you send your first message.

Once you hand it work, it watches the panes it owns with one command:

```bash
runpane watch --session <session-id> --follow --quiet --json
```

That's a stream of one line per event from Pane: an agent finished a turn, an agent is waiting on you, a pane went idle, a worker sent its report, a PR got a conflict, its checks passed or failed, or it merged. The Session reads a pane only when a line says something changed. It doesn't poll.

Every line wakes the Session and replays its whole conversation, so it uses cadence flags that batch quiet events and report a stuck pane fast. Every flag, its default and the reasoning are in [runpane watch](/docs/runpane-cli#runpane-watch).

## Ask what you worked on

Pane Chat is also useful after the work is over. It can look across active
panes, recently archived panes, branches, pull requests, and agent logs, then
tell you what actually happened.

Try prompts like:

> What did I finish yesterday?

> What have I been working on this week?

> Summarize active panes and recently archived work.

> Which PRs came out of my Pane sessions today?

Ask for the actual workstream, not just the pane name. A pane can get reused,
so you want the branch, PRs, and agent logs in the answer before you count
something as shipped.

If Pane has archived the worktree, Pane Chat can still use RunPane state, git
branches, GitHub PRs, and local Codex or Claude transcript history when those
are available. If a source is missing, ask it to say that instead of guessing.

## Ask what to work on next

Pane Chat can also help when your queue is too wide. Ask it to look at your
active panes, recently active repos, open pull requests, review requests,
assigned issues, checks, labels, and recent agent work, then rank what deserves
attention.

Try prompts like:

> What should I work on next?

> What PRs are closest to shipping?

> Which issues are real priority and which ones are just backlog noise?

> Look across my last 10 active repos and tell me what I shouldn't start yet.

You get more than a list of repo names. Ask for the reason behind each ranking:
the blocker, the next action, and the evidence Pane Chat used. That makes the
answer useful for deciding whether to review a teammate's PR, finish one of
your own drafts, fix a deploy, or leave a stale backlog wave alone.

Pane installs a set of skills the Session can use, so it can also name the
right next move: investigate a bug, plan a crisp issue, run PR test
automation, prepare a PR, review a page, or write a teach-back after
something ships.

## Unattended resilience

Leaving agents to work overnight? Ask the Session to turn on unattended mode. It only does this when you ask. Then it:

- Keeps a Mac awake with `caffeinate` while the lid is open.
- Resumes panes whose agent turn died from sleep or a dropped network, instead of waiting for you to say "continue."

Say no and it stops. Pane also has its own setting, **Settings → General → Keep computer awake while sessions are active**, which is on by default. See [Remote Control → Keep the machine awake](/docs/remote-control#keep-the-machine-awake) for the full sleep/wake story.

## Claude, Codex or Cursor

You can run Pane Chat with Claude Code, Codex or Cursor, or with your own command. Pick the agent when you create a [Session](/docs/sessions). Cursor works on macOS, Linux and in WSL on Windows.

They all use the same `runpane` commands. The only difference is which agent runs in the terminal.

## How it stays lightweight

A Session doesn't load a giant prompt. Pane writes a short `AGENTS.md` into the Session's folder that points to a runtime context file: who this Session is, how to reach Pane, and the rules for coordinating panes. The agent reads it when it needs it.

Pane installs its skills locally, so a Session starts from files on disk instead of fetching anything.

## How the workflow works

A Session coordinates. Real code changes happen in panes.

**1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane.**

By default it's set up for discussion, investigation, decisions, and handing work to panes when you've said to go ahead. It doesn't force a pipeline on you. Want a plan, then implementation, then a review in a fresh tab? Ask for that. Want it to just do a small fix? Say so. You can also give each Session its own behavior with **Edit behavior…**.

A typical bigger task looks like this:

1. You tell the Session what you want.
2. It talks it through with you and nails down what "done" looks like.
3. If the feature's branch has no pane yet, it creates one and starts an agent with the task. Otherwise it opens a tab in the existing pane.
4. It watches the pane, and the worker reports back when it's done or stuck.
5. If you ask, it opens a fresh review or test tab in the same pane before telling you it's ready.

This keeps your conversation in one place while each agent works in a clean context.

## Example flow

1. Add a repository in Pane.
2. Create a Session from the sidebar and pick its agent.
3. Ask it to create a feature pane.
4. It runs `runpane panes create` to set up a worktree pane with your chosen agent.
5. The agent does the work inside that pane and reports back with `runpane report`.
6. The Session follows the PR and tells you when checks pass.
7. It checks the result itself before telling you it's done.

## Why this matters

Most orchestration tools are tied to one agent or one hosted runtime. Pane Chat works with anything that runs in a terminal because it's just shell commands underneath.

If a new CLI agent ships tomorrow, Pane can still run it. Pane Chat can still coordinate around it with `runpane`.

Related docs:

- [runpane CLI](/docs/runpane-cli)
- [Remote Control from your phone](/docs/remote-control)
- [Agent Loops](/docs/agent-loops)
- [Panes & Worktrees](/docs/panes-and-worktrees)
- [Running Agents in Parallel](/docs/parallel-agents)