# Sessions import { Callout } from "nextra/components"; A Session is a chat with one agent whose job is to run your other agents. You talk to it about what you want. It splits the work into features, starts a pane for each, opens review and QA tabs in that pane, keeps an eye on them, and tells you when something needs you. **1 feature = 1 worktree = 1 branch = 1 Pane; reviews, audits, fixes and QA for it are tabs in that Pane.** Think of it as the person at the whiteboard. The panes are where the work happens. The Session is where you and the agent decide what work to do. ## What you get - **A chat that remembers.** Each Session has a name, its own agent, and its own folder for notes, plans and files. Close Pane, reboot, come back. The chat is still there. - **Panes it owns.** Every pane a Session starts is listed under it in the sidebar. Click the Session to expand them. - **A watcher.** The Session hears when a pane finishes, gets stuck, needs your input, or its PR changes. You don't have to keep checking. - **Any agent.** Run a Session with Claude Code, Codex, Cursor, or your own command. ## Create a Session 1. Click **+** next to **Sessions** in the sidebar. 2. Pick the agent. Pane remembers it as your default for next time. 3. Give it a name, or leave it blank and Pane names it `New chat`. 4. Start talking. Nothing runs until you send a message. Want the agent to behave a certain way? Use **Edit behavior…** when you create the Session, or later in its settings. You can also launch it with a custom command and arguments, like a wrapper script. ## What a Session can do Ask for something like: > Add this repo, make three panes for these features, start Codex in each, and tell me when the PRs are ready to test. The Session then: 1. Creates the panes, each in its own worktree (its own branch, safely isolated). 2. Starts an agent in each one with its task. 3. Watches them. When a worker finishes, it reports back with `runpane report`, including its PR and a summary. 4. Tells you what's done, what's stuck, and what needs your call. It drives all of this through the same [`runpane` CLI](/docs/runpane-cli) and [MCP tools](/docs/mcp) you can use yourself. ### It watches your PRs About every 3 minutes, Pane checks the open PRs from a Session's panes with the GitHub CLI. The Session hears when a PR gets a conflict, when checks pass or fail, and when it merges. You need `gh` installed and signed in. ### It can share things that only one worker should use Say several workers need the same test account. The Session can tell them to take a named lock first, so only one uses it at a time. Pane releases the lock when the worker finishes, closes, or its time runs out. ## Work on several Sessions at once Drag a Session from the sidebar onto the edge of the one you have open. Now both are side by side, and both are fully live. Drag onto the middle to swap one for the other. Each Session also has a sidebar on the right with three tabs: - **Overview**: its panes and recent activity - **Files**: the Session's own folder - **Changes**: what its panes have changed, with a link to review each one ## Run a Session in WSL On Windows, the create dialog has a **Run agent in** option when you have WSL installed. Windows is the default. Pick a distro to run the agent there instead. Install the agent inside that distro first. Cursor shows up as an option once you pick WSL. The Session remembers its distro across restarts. Its `runpane` commands still reach the Windows app, so it can manage all your panes. ## Manage Sessions from the CLI Everything above works from `runpane` too, so a script or another agent can drive it: ```bash runpane sessions list --json runpane sessions create --from-json session.json --json runpane sessions overview --session --json runpane sessions pin --session --json runpane sessions unpin --session --json runpane sessions set-agent --session --agent codex --json runpane sessions associate --session --pane --json runpane sessions detach --session --pane --json ``` A pane created from inside a Session is attached to that Session automatically. Pass `--no-associate` if you don't want that. `sessions overview` shows each pane's live state, branch, PR and its latest worker report. Workers hand back their results with `runpane report --state `, plus a PR number, commit and summary. When the work is merged, `runpane panes archive --session --merged --yes` archives every pane whose work is merged or pushed. It skips the rest with a reason, including any pane whose PR is still open (`pr-open`), so its review, fix and QA tabs keep their worktree. This needs Pane 2.4.175 or later. ## Pin, archive and restore - Right-click a Session to **pin** it to the top of the sidebar. - Right-click and **archive** it to hide it. Its chat, history and panes stay put. Restore it from the **Archived** section any time. - Archiving a Session doesn't touch its panes or their worktrees. ## Where Sessions live Each Session has a folder at `~/.pane/sessions//` for notes, plans and anything the agent writes. It survives renames, restarts and archiving. It isn't a git worktree. Real code changes happen in panes. Already used Pane Chat? It moved into Sessions automatically, with its name and history. See [Pane Chat](/docs/pane-chat) for what it can do. ## Related - [Pane Chat](/docs/pane-chat): what the coordinating agent can do, with examples - [runpane CLI](/docs/runpane-cli): the commands Sessions use, including `runpane sessions` and `runpane watch` - [Loops](/docs/loops): run a Session's agent on a schedule - [Agent Loops](/docs/agent-loops): one agent managing other agents, from a Session, a script or CI