Your first project

A project tells PABLO about one repository: where its main checkout lives, which branch is primary, and which issue tracker holds its tickets. Set your global defaults once, then add each project with a short wizard.

1. Set your global defaults#

The installer created ~/.pablo/config.yaml with working defaults. Two settings are required before any project can load, and both come pre-filled: the AI model agents use (GLM 5.3 Flash through OpenCode Go), and the language of pull request descriptions. Change the model if you use another provider. Under Claude Code, the installer writes default_model: sonnet instead; under Copilot, default_model: claude-sonnet-5.5.

yaml

# ~/.pablo/config.yaml
default_model: opencode-go/glm-5.3-flash   # any model id OpenCode accepts (Claude Code: sonnet, opus, haiku…; Copilot: claude-sonnet-5.5…)
pr_description_locale: en

sync:
  strategy: rebase      # rebase | merge
  auto_apply: false     # false: sync only reports what it would do
  interval_minutes: 720 # every 12 hours
state_polling:
  interval_minutes: 10
ci:
  ignore_checks: ["approval"]

Every value here is a default that each project can override. The full list is in Configuration, including a different model per project type, so expensive models only run on work projects.

2. Add the project#

Run the wizard from anywhere (it detects the repository if you run it inside one):

bash

pablo project:new

It asks for the repository path, a project name, the project type (work, open-source or personal, used to filter tasks and pick models), the issue tracker and its details, whether you have a QA step, and an optional branch prefix. It shows the resulting YAML and writes it to ~/.pablo/projects/ once you confirm.

Or write it by hand#

One YAML file per project in ~/.pablo/projects/, any file name. The smallest useful configuration, for a GitHub project:

yaml

# ~/.pablo/projects/wallet-kit.yaml
name: wallet-kit
type: open-source
repo:
  path: ~/dev/wallet-kit
  primary_branch: main
issue_tracker:
  provider: github
  identity: your-github-login
  project_key: WK        # GitHub has no issue keys: this becomes the branch prefix (wk-45)

And a Jira project with a QA step and a CI gate to ignore:

yaml

# ~/.pablo/projects/acme-pim.yaml
name: acme-pim
type: work
repo:
  path: ~/Sites/acme/pim
  primary_branch: main
issue_tracker:
  provider: jira
  identity: you@acme.example
  project_key: PIM
  site: acme.atlassian.net
sync:
  auto_apply: true
testing:
  failure_signal: "A FIX"      # the Jira status QA moves the ticket to when it fails
ci:
  ignore_checks: ["approval"]  # manual deploy gates that never finish

Every key is described in Configuration. Both examples are in the repository: examples/acme-pim.yaml and examples/config.yaml.

3. Check it#

bash

pablo project:list     # your projects and their settings
pablo system:doctor    # now also checks the tracker's command-line tool

4. Register the repository with your agent backend#

With Orca (the default), register the repository once so PABLO's agents show up as Orca terminals:

bash

orca repo add ~/dev/wallet-kit

With OpenChamber there's nothing to do. If you skip this step with Orca, agents still run, headless, in the background.

Remove a project#

bash

pablo project:remove wallet-kit

It refuses while the project still has active tasks (close them first with pablo task:close). It deletes only the YAML file: worktrees and the rest of ~/.pablo/ stay. It also regenerates the agents, so a tracker no project uses any more stops being taught to them.

Next step#

Start your first task.