# Custom Agents

<a id="any-cli-works"></a>

Any CLI tool you can run in a terminal, you can run as a custom command. Claude Code, Codex, Cursor and OpenCode are built in and don't need one.

<TerminalPreview
  title="Terminal"
  lines={[
    { type: "command", text: "your-agent --flag" },
    { type: "output", text: "Agent started..." },
    { type: "output", text: "Reading project files..." },
    { type: "success", text: "✓ Task complete" },
  ]}
/>

## Add a Custom Command

1. Click the **+** in the tab bar to open **Add Tool**.
2. Choose **Add custom command…**.
3. Type any command in **Command to run**, like `aider`, `gh copilot`, or `npm run dev`. The **Name** is optional.
4. Press **Enter** or click **Save & launch**. Pane saves the command and launches it right away.

Without a name, Pane names the tab from the first few words of your command. The first four custom commands you add each get a hotkey, <KeyCombo keys={["⌘", "⌥", "7"]} /> through <KeyCombo keys={["⌘", "⌥", "0"]} /> on macOS, and <KeyCombo keys={["Ctrl", "Alt", "7"]} /> through <KeyCombo keys={["Ctrl", "Alt", "0"]} /> on Windows and Linux. Click the X next to a saved command to delete it.

> **Note:** Commands run exactly as typed, in a real terminal, inside the pane's [worktree](/docs/panes-and-worktrees).

## Resume a custom agent's conversation

To have a custom agent pick up its conversation after a restart, tick **Enable custom command resume** in the same form:

1. Pick a **Session ID source**:
   - **CLI reports its ID**: your CLI prints a line `PANE_AGENT_SESSION_ID=<id>`.
   - **Pane allocates an ID**: also put `{sessionId}` in the **First launch template**.
   - **Claude**, **Codex** or **Cursor**: for wrappers around those agents.
2. Set the **Resume template**, like `{command} --resume {sessionId}`. Pane fills in the ID and quotes it, so leave `{sessionId}` unquoted.

## Windows and PATH

On a Windows machine with a WSL project, Pane detects `\\wsl$\` paths automatically and runs your custom command inside that WSL distro. Install the CLI there first.

If the tab says the command isn't found, add its folder in **Settings → Advanced → Additional PATH**. See [Troubleshooting](/docs/troubleshooting) for more on PATH issues.

## Automating From the CLI

Agents and scripts can create a [pane](/docs/panes-and-worktrees) for a new feature with a custom command:

```bash
runpane panes create --repo active --name <feature> --tool-command '<cmd>' --yes
```

To run a custom command as a tab in a feature's existing pane:

```bash
runpane panels create --pane <id> --tool-command '<cmd>' --no-focus --wait-ready --yes --json
```

For multi-step setups, wrap them in a shell:

```bash
runpane panes create --repo active --name dev-server --tool-command "bash -lc 'npm install && npm run dev'" --yes
```

See the [`runpane` CLI](/docs/runpane-cli) for the rest of the command set.

## Is There a Plugin API?

No. Pane doesn't have a plugin or extension system today. What you get instead: custom commands (this page), terminal shortcuts, the `runpane` CLI, and project scripts in [`pane.json`](/docs/configuration).

Pane is AGPL-3.0 open source, so you can fork it and build deeper integrations yourself. See the [Troubleshooting & FAQ](/docs/troubleshooting) page for what that license requires. File extension requests at [github.com/greenfield-inc/Pane/issues](https://github.com/greenfield-inc/Pane/issues).

## Custom Shortcuts

Custom Shortcuts are a different feature: a keyboard shortcut that pastes a saved command into the terminal without running it automatically. See [Keyboard Shortcuts](/docs/keyboard-shortcuts#terminal-shortcuts) for setup steps.
