Runtimes & ADEs

Two global choices decide how PABLO's agents run: the agent runtime, the program that runs them (OpenCode, Claude Code or GitHub Copilot CLI), and the agent environment (ADE), where they run and where you read them (Orca, OpenChamber, or headless in the background). This page covers both: how to choose, how each one is set up, and its limits.

Choose an agent runtime#

The runtime decides what runs an agent; the ADE decides where. Every project uses the same runtime: agent_runtime is a global-only key of ~/.pablo/config.yaml, also settable with the PABLO_AGENT_RUNTIME environment variable.

The installer lists the runtimes it finds on your PATH and asks which one to use; with a single one it takes it without asking, and with none it stops. A first install picks OpenCode, Claude Code when it finds Claude Code but no OpenCode, Copilot when it finds Copilot CLI but neither. The runtime changes the command the doctor requires (opencode, claude or copilot), what the installer generates and links, and which model ids default_model accepts (see Choose the agent model).

Whatever the runtime, the agents come from the same templates, translated rather than rewritten, so they run the same prompts and the same guardrails (see Agents).

Switch runtime#

Run pablo system:install again with --runtime: it records agent_runtime, resets default_model to a model of that runtime, regenerates the agents and links them. Or change agent_runtime (and default_model) yourself and run it without options. The other runtimes' links stay in place until pablo system:uninstall; they're harmless.

pablo system:install --runtime claude-code   # or opencode, copilot
pablo system:doctor                          # checks the runtime and its generated files

OpenCode#

The default, and the only runtime OpenChamber can run. You need OpenCode set up with your usual model provider.

• What is installed. The agents, the /pablo-commit-and-pr command and the pablo-task skill, rendered into ~/.pablo/runtime/opencode/ and linked into ~/.config/opencode/.
• Guardrails. The agents' permissions are OpenCode frontmatter rules, enforced by OpenCode, and their step budget is OpenCode's own step limit (see Read-only, enforced).
• Sessions. opencode -s <session> reopens a run. Headless runs can be followed in OpenCode's web interface: see Follow headless OpenCode runs in the browser.

Claude Code#

Set it in ~/.pablo/config.yaml, with a Claude model, then regenerate and relink:

agent_runtime: claude-code
default_model: sonnet        # or opus, haiku, or a full model id

curl -fsSL https://getpablo.dev/installer | bash -s -- --runtime claude-code
                            # generates ~/.pablo/runtime/claude/agents.json, links the agents and the command
                            # (already installed: pablo system:install --runtime claude-code)
pablo system:doctor         # checks claude and the generated files

Setup#

• Prerequisite. The claude command, logged in: the doctor runs claude auth status. Install it with curl -fsSL https://claude.ai/install.sh | bash.
• What is installed. pablo system:generate-agents writes all five agents into ~/.pablo/runtime/claude/agents.json, which every launch passes with --agents. The installer links ~/.claude/commands/pablo-commit-and-pr.md and ~/.claude/skills/pablo-task.
• Your own sessions. The same agents are also rendered as pablo-<agent>.md files in ~/.pablo/runtime/claude/agents/ and linked into ~/.claude/agents/, so they show up in /agents and the @ picker. Those files only carry tool-level limits: the per-command shell denies (such as git push) are launch flags and apply only to PABLO's own launches.

How it runs, and its limits#

• Orca or headless. Agents run as claude -p in an Orca terminal, and as a Remote Control session headless. OpenChamber is not supported: it drives its own OpenCode server. pablo system:doctor reports the combination as an error and the dispatcher refuses to run with it.
• How they launch. claude -p --agents … --agent <name> --model <default_model> --session-id <id> --strict-mcp-config, plus the permission flags below.
• No permission prompts. The analysts run with --permission-mode dontAsk (anything not allowed is denied), the resolver with acceptEdits (dontAsk too in a Remote Control session, where its edit tools are explicitly allowed).
• Your account and quota. Agents run with your own Claude Code login. With a Pro or Max subscription they share its usage limits with your interactive sessions, so keep an eye on them with busy projects.
• Your settings, not your MCP servers. Agents load your Claude Code settings and hooks (Orca's, RTK's) but none of your MCP servers (--strict-mcp-config).
• Sessions you can resume. Each run gets a session id chosen by PABLO; claude --resume <id> in the worktree reopens it.
• Step budget. Claude Code has no per-agent step limit, so the budget becomes an instruction at the end of the prompt: followed, not enforced.

Permission mapping#

Whole tools are allowed or denied both in the agent definition and on the command line. Command patterns only go on the command line: in an agent definition, a Bash(…) entry removes the whole Bash tool. Claude Code matches * anywhere, so patterns such as *acli jira workitem edit* keep their meaning.

The commit command is rendered into ~/.pablo/runtime/claude/commands/ and linked into ~/.claude/commands/. Its body, the !`…` context injection and $ARGUMENTS work as in OpenCode, and its allowed commands become allowed-tools (raw and rtk forms again). One limit: a Claude Code command can't deny a tool, so “no edits” is an instruction in its hard rules rather than a permission.

Follow headless runs from claude.ai and the Claude apps#

A run with no terminal (agent_backend: headless, Orca's and OpenChamber's fallback, the rebase-conflict resolver) starts as an interactive claude --remote-control session named pablo <agent> <worktree> instead of claude -p, so it shows up live in claude.ai/code and the Claude apps while it runs. It is still a background run that ends on its own:

• A terminal from script. Interactive claude needs one; the command runs inside script (part of every Linux and macOS system). Its screen output goes to the run's log in ~/.pablo/agents/logs/.
• It stops when the agent has answered. A Stop (and StopFailure) hook passed with --settings ends the session after the agent's answer, so the run finishes like a claude -p one. You can't continue it from the app afterwards: claude --resume <id> in the worktree still reopens it.
• Same agent, same limits. Same model, session id and permission flags as claude -p, with only the launched agent passed inline in --agents (interactive claude takes no file there). Every agent, the resolver included, runs in dontAsk: nobody is there to answer a prompt.
• The worktree is trusted first. PABLO adds a hasTrustDialogAccepted entry for the worktree to ~/.claude.json just before the launch.
• Needs a claude.ai login on which your organization allows Remote Control.

To keep plain claude -p runs, switch it off in ~/.pablo/config.yaml (or export PABLO_CLAUDE_REMOTE_CONTROL=0):

claude_code:
  remote_control: false   # default: true

Without a generated agents.json or a script command, runs fall back to claude -p.

GitHub Copilot CLI experimental#

Set it in ~/.pablo/config.yaml (or export PABLO_AGENT_RUNTIME=copilot), with a Copilot model, then regenerate and relink:

agent_runtime: copilot
default_model: claude-sonnet-5.5   # or another Copilot model id, e.g. gpt-5.3-codex

curl -fsSL https://getpablo.dev/installer | bash -s -- --runtime copilot
                            # renders ~/.pablo/runtime/copilot/ and links the agents and skills into ~/.copilot/
                            # (already installed: pablo system:install --runtime copilot)
pablo system:doctor         # checks copilot and the generated files

Setup#

• Prerequisite. The copilot command (npm install -g @github/copilot), logged in once with copilot login. The doctor only runs copilot --version: Copilot has no non-interactive login check, so a run fails if you're logged out.
• What is installed. pablo system:generate-agents renders ~/.pablo/runtime/copilot/agents/pablo-<agent>.agent.md for the five agents, linked into ~/.copilot/agents/; the pablo-commit-and-pr and pablo-task skills go into ~/.copilot/skills/ (under COPILOT_HOME when set).
• Visible on purpose. The agents go where your own Copilot sessions can pick them, prefixed pablo-.
• What an agent file holds. name, description and tools (Copilot aliases: read, search, execute, web, edit), and no model: line: in Copilot an agent file's model would override --model.

How it runs, and its limits#

• Orca or headless. Agents run as copilot -p, in an Orca terminal or headless. OpenChamber is not supported, as with Claude Code: the doctor reports it and the dispatcher refuses to run.
• How they launch. copilot --agent pablo-<agent> --model <default_model> --session-id <uuid> --no-ask-user --no-auto-update --no-color --disable-builtin-mcps --available-tools … --allow-tool … --deny-tool … -p '<prompt>'. --available-tools lists exactly the built-in tools the agent may use (the analysts: view, grep, glob, web_fetch, bash; the resolver: view, bash, edit, create), which also hides your MCP tools; --disable-builtin-mcps turns off Copilot's built-in MCP servers. Your own custom instructions (AGENTS.md…) and hooks still load.
• Copilot model ids. Dotted ids such as claude-sonnet-5.5 or gpt-5.3-codex. A provider/model id (bring-your-own-model ids aren't supported) or a Claude Code name (sonnet, claude-sonnet-5-5) is refused when the project loads, with the dotted form suggested.
• Sessions you can resume. Each run gets a UUID chosen by PABLO; copilot --resume=<id> in the worktree reopens it. Its handle is recorded as copilot:<uuid>, so it can't be mistaken for a Claude Code session.
• Step budget. As under Claude Code: no per-agent limit, so it becomes an instruction at the end of the prompt.

Permission mapping#

Copilot matches a command prefix, so leading and trailing * are dropped: *acli jira workitem edit* becomes acli jira workitem edit. A pattern with a * in the middle can't be translated, and generation fails. In Copilot a deny always wins over an allow. The command patterns only exist on PABLO's launches: when you run a pablo-* agent by hand, only the visible tools from its agent file apply.

Copilot has no !`…` context injection, so the commit command becomes a skill, copilot/skills/pablo-commit-and-pr/SKILL.md, linked into ~/.copilot/skills/. Its context section tells the agent to run those commands first, and disable-model-invocation: true keeps the model from running it on its own: only you typing /pablo-commit-and-pr does. The “no code edits” rule is restated in its hard rules, and --force still works as part of your request.

Choose an agent environment (ADE)#

The agent environment (ADE) is where PABLO's agents run, and where you open them to read their analysis or keep chatting. It is the global-only key agent_backend of ~/.pablo/config.yaml (or the PABLO_AGENT_BACKEND environment variable); change it with pablo system:install --backend orca|openchamber|headless.

The installer only offers the ADEs that can run your runtime. Without a choice, a first install picks Orca, or OpenChamber when it finds OpenChamber but no Orca. When it finds neither, agents run headless but agent_backend stays orca, so Orca is used as soon as you install it; choose headless explicitly to never use one. OpenChamber with Claude Code or Copilot is refused by the installer, the doctor and the dispatcher.

Orca (default)

Agents run in Orca terminals. Orca only sees repositories registered with it, so register each project's repository once: orca repo add --path <path> (on Linux the Orca CLI is orca-ide: orca is GNOME's screen reader; Orca's ORCA_CLI_COMMAND overrides it).

OpenChamber

Set agent_backend: openchamber. PABLO drives it through OpenChamber's CLI, the npm package @openchamber/web (npm i -g @openchamber/web, Node.js 24.14+), which sends the sessions to the running desktop app when there is one. The desktop app installs an openchamber command too, which ignores the CLI's commands: put the CLI first on your PATH. OpenChamber works from directories, so there is nothing to register. OpenCode only.

Headless

No ADE: agent_backend: headless runs every agent as opencode run (or claude -p, copilot -p) in the background from the worktree, tracked with pid files in ~/.pablo/agents/. You read their output with opencode -s <session> (or claude --resume <session>, copilot --resume=<session> in the worktree). Under OpenCode, opencode pair prints a link to OpenCode's local web interface (see Follow headless OpenCode runs in the browser); under Claude Code, a headless run is a Remote Control session.

Fallback to headless#

Headless is every ADE's fallback, so agents still run when the chosen one can't take them:

• Orca unreachable, or a repository not registered with it: the agent runs headless. Orca's launch runs in the background, so when Orca refuses or doesn't know the worktree within 15 seconds, the agent runs headless and the reason goes to ~/.pablo/agents/logs/orca-fallback.log.
• OpenChamber unreachable, or sending the prompt fails: the reason goes to ~/.pablo/agents/logs/openchamber-fallback.log and the agent runs headless with the same model.
• Always headless, whatever the ADE: project startup scripts and the rebase-conflict resolver.

The exact commands each ADE runs, and how PABLO tells busy agents from those waiting for you, are in How it works.