Installation

Install PABLO with one script, then let pablo system:doctor tell you which tool is missing or logged out. It takes a few minutes on Linux or macOS.

Prerequisites#

Start with the minimum below. Everything else depends on where your projects live, and you can add it later, when you add the project that needs it.

The minimum#

• git: every task is a branch and a worktree.
• An agent runtime that runs the agents: OpenCode set up with your usual model provider (the default), Claude Code logged in to your Claude account, or GitHub Copilot CLI logged in to your GitHub account. See With Claude Code and With GitHub Copilot CLI.
• An agent development environment, Orca or OpenChamber: where agents run and where you chat with them. Optional in theory (without one, agents run headless in the background), but that's where you'll read their work. See Choose an agent backend.
• PHP 8.4.1+ and Composer, to run PABLO itself.

Then, for your projects#

PABLO talks to each service through its own command-line tool, logged in once on your machine. Install the ones your projects use:

GitHub Issues need nothing more than gh. More details on what each tool is used for in Providers.

Install#

curl -fsSL https://getpablo.dev/installer | bash

The script is interactive, on Linux and macOS. It:

1. checks that git, PHP 8.4.1+ and Composer are there;
2. asks where to install PABLO (~/.local/share/pablo by default) and clones it there;
3. looks for the agent runtimes you have (OpenCode, Claude Code, GitHub Copilot CLI) and asks which one to use;
4. looks for the agent development environments you have (Orca, OpenChamber) and asks which one to use. It only offers the ones that can run your runtime;
5. asks whether to install the dashboard service, shows a summary, then runs bin/install.sh from the checkout with your answers (see below).

If it finds no agent runtime, it stops and sends you back to the prerequisites. If it finds no agent development environment, it says so with the same pointer and offers to carry on headless (the agents then run in the background) or to stop so you can install one first. Without a terminal, it carries on headless.

Every question has an option, so you can script it. Pass options after bash -s --:

curl -fsSL https://getpablo.dev/installer | bash -s -- --install-dir ~/pablo --runtime claude-code --backend orca --no-interaction

Running it again updates the checkout (git pull --ff-only) and re-applies the install, so it is also how you update. It refuses a directory that is not empty and is not a PABLO checkout.

From a clone#

Contributing, or want to read the code first? Clone the repository anywhere and run the installer it contains; it is the same bin/install.sh the script above hands over to.

git clone https://github.com/Korbeil/pablo
cd pablo
./bin/install.sh              # add --without-web to skip the dashboard service

Without options it keeps the choices already in ~/.pablo/config.yaml, or on a first install picks the tools it finds. Two options record a choice there instead: --runtime opencode|claude-code|copilot and --backend orca|openchamber|headless. Changing the runtime also resets default_model to a model of that runtime. bin/install.sh is safe to run again. It:

1. creates ~/.pablo/ and, if you don't have one yet, a default global config in ~/.pablo/config.yaml, set to the tools you have installed (Claude Code when it finds Claude Code but no OpenCode, Copilot when it finds Copilot CLI but neither, OpenChamber when it finds OpenChamber but no Orca);
2. installs PHP dependencies and warms PABLO's cache;
3. generates the agents for your agent runtime;
4. writes the pablo command to ~/.local/bin/pablo and, if that directory isn't on your PATH yet, adds it (see below);
5. links the agents, the /pablo-commit-and-pr command and the pablo-task skill into ~/.config/opencode/ (OpenCode), the command and the skill into ~/.claude/ (Claude Code), or the agents and both skills into ~/.copilot/ (Copilot);
6. starts the background scheduler, which runs PABLO every 5 minutes, and the dashboard on http://127.0.0.1:8321;
7. runs pablo system:doctor and prints your next steps.

The pablo command on your PATH#

When ~/.local/bin isn't on your PATH already, the installer appends a short block, between # >>> pablo >>> and # <<< pablo <<< markers, to ~/.zshrc (zsh) or ~/.bashrc (bash; ~/.bash_profile on macOS). For fish it writes ~/.config/fish/conf.d/pablo.fish instead. Open a new terminal afterwards. Running the installer again never adds the block twice, and ./bin/uninstall.sh removes it. With another shell, the installer prints the line to add yourself.

Check your setup#

pablo system:doctor   # one line per check: ✅ ready, ❌ missing or logged out
pablo system:setup    # the same checks as a wizard, one fix at a time

system:setup stops at the first problem and prints the exact command to install or log in to the tool. Fix it, run pablo system:setup again, and it moves on to the next check. Tracker tools (acli, linear) are only checked once a project uses them.

The doctor also checks that the installed agents are up to date: ~/.config/opencode/agents/ under OpenCode; ~/.pablo/claude/agents.json, the ~/.claude/agents/pablo-*.md files, the command and the skill under Claude Code; the agent files and skills in ~/.copilot/ under Copilot. If one is reported stale, run pablo system:generate-agents.

With Claude Code#

Set agent_runtime: claude-code and a Claude model in ~/.pablo/config.yaml (a first install does it when it finds claude but no opencode), then run the installer again, or let it set both for you with --runtime claude-code:

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

• 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/claude/agents.json holds the five agents; the installer links ~/.claude/commands/pablo-commit-and-pr.md and ~/.claude/skills/pablo-task.
• Your own sessions. The installer also links the agents into ~/.claude/agents/ as pablo-<agent>, so they appear in /agents and the @ picker. PABLO's own launches still pass agents.json with --agents; only those enforce the per-command shell denies.
• Backend. Use Orca, or no backend (headless). OpenChamber can't run Claude Code; the doctor reports it.

With GitHub Copilot CLI#

Set agent_runtime: copilot and a Copilot model in ~/.pablo/config.yaml (a first install does it when it finds copilot but neither opencode nor claude), then run the installer again, or let it set both for you with --runtime copilot:

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

• 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. The five pablo-<agent>.agent.md files, rendered into the git-ignored copilot/, are linked into ~/.copilot/agents/; the pablo-commit-and-pr and pablo-task skills into ~/.copilot/skills/ (under COPILOT_HOME when set).
• Visible on purpose. Unlike Claude Code, the agents go where your own Copilot sessions can pick them, prefixed pablo-.
• Backend. Use Orca, or no backend (headless). OpenChamber can't run Copilot; the doctor reports it.

Switching runtime later works the same way: run the installer again with --runtime (or change agent_runtime and run it without). The other runtimes' links stay in place until ./bin/uninstall.sh; they're harmless.

Choose an agent runtime#

The runtime is the program that runs the agents: OpenCode, Claude Code or GitHub Copilot CLI. The installer lists the ones it finds on your PATH and asks which to use. With a single one it takes it without asking, and with none it stops. To change it later, see With Claude Code and With GitHub Copilot CLI, or run the installer again with --runtime.

Choose an agent backend#

The agent backend is where PABLO's agents run, and where you open them to read their analysis or keep chatting. The installer only offers what matches your runtime: Orca, or headless, with any runtime; OpenChamber too, with OpenCode only. Run again with --backend to change it. Without a choice, a first install picks Orca by default, OpenChamber when it finds OpenChamber but no Orca. The doctor only checks the backend you use. Both run OpenCode; with Claude Code or Copilot, use Orca or headless.

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>.

OpenChamber

Set agent_backend: openchamber in ~/.pablo/config.yaml (or export PABLO_AGENT_BACKEND=openchamber). OpenChamber works from directories, so there is nothing to register. OpenCode only: not available with agent_runtime: claude-code or copilot.

Headless

When the backend is unavailable, or doesn't know a repository, PABLO falls back to opencode run (or claude -p, copilot -p) in the background, so agents still run. You read their output with opencode -s <session> (or claude --resume <session>, copilot --resume=<session> in the worktree).

More details in How it works.

The dashboard service#

The installer keeps the dashboard running as a background service that restarts on its own, on http://127.0.0.1:8321. See Dashboard.

Don't want it? Answer no when the installer asks, or install (or re-install) with --without-web; this also removes a dashboard service installed before. You can still start the dashboard by hand with pablo web.

curl -fsSL https://getpablo.dev/installer | bash -s -- --without-web
# or, from your clone: ./bin/install.sh --without-web

To only stop it for now: systemctl --user stop pablo-web.service on Linux, launchctl bootout gui/$UID/com.pablo.web on macOS.

Platform notes#

PABLO itself is portable. Only the scheduler and the dashboard service differ:

On Linux the installer enables lingering for your user (loginctl enable-linger), so the scheduler also starts after a reboot without you logging in.

First install on macOS#

1. Install the prerequisites, including acli auth login if you use Jira or Confluence.
2. Run the installer and look for “com.pablo.dispatch loaded”.
3. Run pablo system:doctor: everything should be ✅.
4. Watch one 5-minute run: tail -f ~/.pablo/logs/dispatch.log.
5. Try a round trip on a real project: pablo task:start …, then pablo task:list.

Update#

curl -fsSL https://getpablo.dev/installer | bash
# or, from your clone:
cd pablo
git pull
./bin/install.sh

Re-running the installer picks up new dependencies, new agents and new links. Your data in ~/.pablo/ is never touched.

Uninstall#

~/.local/share/pablo/bin/uninstall.sh   # or ./bin/uninstall.sh in your clone

It removes what the installer created (the shim, the links under ~/.config/opencode/, ~/.claude/ and ~/.copilot/, the generated ~/.pablo/claude/, the PATH block, the scheduler and dashboard services) and keeps your data in ~/.pablo/. The checkout itself stays: delete it yourself once you are done. Delete ~/.pablo/ as well if you want a clean slate, or back it up first.

Next step#

Add your first project.