agent-panel

Launch multiple AI coding agents in parallel terminal splits.

Ask a panel of agents to review your PR, fix an issue, or explain a codebase -- all at once, side by side.

Supported terminals

• Ghostty 1.3+ -- macOS only, via AppleScript
• cmux -- full support

Install

npm install -g agent-panel

This installs the panel binary (alias for agent-panel)

Quick start

Run panel on its own to open an interactive prompt where you can type (or paste) any text and send it to every configured agent at once:

panel

The prompt is multi-line: Enter submits, Shift+Enter (or Alt+Enter as a fallback) inserts a newline. The list of agents the prompt will be sent to is shown above the input.

Or run configured commands directly:

# Review a PR (uses the "review" command from your config)
panel review 123

# Review current branch vs main (including unstaged changes)
panel review

# Fix an issue
panel fix ISSUE-456

# Explain something in the codebase
panel explain "the auth flow"

Send a one-off prompt to all agents without opening the TUI:

# -m / --message sends the text directly to every configured agent
panel -m "what are some ways to improve the error handling here"

# "ask" works the same way via a positional argument
panel ask "what are some ways to improve the error handling here"

# Read prompt from a file (works with any command)
panel ask --file prompt.md
panel review --file ./review-instructions.md

In non-interactive contexts (piped stdin, CI, scripts) a bare panel prints its usage text instead of trying to open the TUI. Use -m in scripts.

The agent-panel command also works as an alias for panel.

How it works

1. Detects your terminal (cmux or Ghostty)
2. Loads commands and agents from ~/.config/agent-panel/config.jsonc
3. Opens N terminal splits (one per agent)
4. Sends each agent the same prompt

The first agent runs in your current pane. Each additional agent gets a new split to the right.

Configuration

Run panel config create to create ~/.config/agent-panel/config.jsonc:

{
  "$schema": "https://raw.githubusercontent.com/venables/agent-panel/main/config.schema.json",

  // Each agent needs a {{prompt}} placeholder in its command
  "agents": [
    { "name": "claude", "command": "claude {{prompt}}" },
    { "name": "codex", "command": "codex {{prompt}}" },
    { "name": "opencode", "command": "opencode --prompt {{prompt}}" }
  ],

  // Commands use {{arg}} for the optional argument
  "commands": {
    "review": {
      "prompt": "Review PR {{arg}}. Leave comments in this session and not on the PR itself.",
      "promptNoArg": "Review all changes between this branch and main, including dirty or unstaged files. Leave comments in this session and not on the PR itself."
    },
    "fix": {
      "prompt": "Fix issue {{arg}}. Implement the fix and show me what you changed.",
      "requiresArg": true
    },
    "explain": {
      "prompt": "Explain {{arg}} in this codebase. Be thorough.",
      "requiresArg": true
    }
  }
}

The $schema field enables autocompletion and validation in editors that support JSON Schema (VS Code, Zed, JetBrains, etc.).

Editing your config

Open the config in your editor:

panel config edit

This launches $EDITOR (or $VISUAL, or vi as a fallback) with the config file.

Adding a command

Add a new key to commands:

"refactor": {
  "prompt": "Refactor {{arg}}. Explain your reasoning.",
  "requiresArg": true
}

Then run it: panel refactor "the database layer"

Command options

| Field | Type | Description | | ------------- | ---------- | ---------------------------------------------------------------------- | | prompt | string | Prompt template. {{arg}} is replaced with the CLI argument. | | promptNoArg | string? | Fallback prompt when no argument is given. | | requiresArg | boolean? | If true, the command fails without an argument. Defaults to false. |

Options

Add an options object to configure panel behavior:

"options": {
  "layout": "tabs",
  "preserveActivePane": true
}

| Field | Type | Description | | -------------------- | ---------------------- | --------------------------------------------------------------------------------------------- | | layout | "splits" | "tabs" | How to arrange agents: side-by-side splits or separate tabs. Defaults to "splits". | | preserveActivePane | boolean? | If true, all agents get new panes and your current pane is left alone. Defaults to false. |

Adding an agent

Add a new entry to agents. The command field is the shell command to run, with {{prompt}} as the placeholder:

{ "name": "aider", "command": "aider --message \"{{prompt}}\"" }

CLI reference

panel                          Open the interactive prompt (or print usage
                                 in non-interactive contexts)
panel <command> [arg]          Run a configured command
panel config create            Create config (interactive)
panel config edit              Open config in $EDITOR
panel config delete            Delete config file

Flags:

-m, --message <prompt>         Send a prompt to every agent and skip the TUI
-f, --file <path>              Read the command argument from a file
-t, --tabs                     Use tabs instead of splits for this run
-p, --preserve                 Keep the current pane; give every agent a new one
-h, --help                     Show help
-v, --version                  Show version

panel does not accept a bare -- as an argument-forwarding escape. Prompts are dispatched through config-defined commands (one shell invocation per agent), so there is no single child process to forward to. Use panel ask <prompt> or panel --message <prompt> for raw prompts.

Development

# Install dependencies
bun install

# Run locally
bun run cli review 123

# Build for production
bun run build

# Run all checks (format, lint, typecheck, test)
bun check

# Auto-fix format and lint issues
bun fix

Project structure

src/
  index.ts                CLI entry point
  cli/
    main.ts               Root command, flow orchestration
    route.ts              Route resolution (pure function)
    args.ts               Positional word extraction
    options.ts            Flag definitions, option merging
  commands/
    command-list.ts       Usage/help display
    config-create.ts      Interactive config wizard
    config-edit.ts        Open config in $EDITOR
    config-delete.ts      Confirm and delete config
    launch.ts             Agent orchestration
  agents/
    known-agents.ts       Registry of supported agent CLIs
    known-commands.ts     Registry of pre-configured commands
  config/
    config.ts             Schema, loading, validation (zod)
  terminal/
    terminal.ts           Terminal interface
    cmux.ts               cmux backend
    ghostty.ts            Ghostty AppleScript backend
    detect.ts             Auto-detection logic
    index.ts              Barrel exports
  utils/
    exec.ts               Process execution utilities

License

MIT