Dev and Test: install Phillip and pick up your first task
This page takes about 15 minutes. When you finish, Phillip runs on your machine, is connected to Tara and to GitHub or GitLab, and you know the commands you use every day. A BA who wants to test on their own machine can follow this page too.
If you don't know what Phillip, Bandum, and Tara are, read the Introduction first. If you only use a browser, see BA, PO, PM.
Prerequisites
Your machine needs Node 22 or later (check with node --version), git, and VS Code or a terminal. This documentation writes the Tara address as https://tara.phillipcli.cloud. Tara and Ryoma run online, so you don't set anything up for them. You also need a GitHub or GitLab account with Developer access or higher on the project repo, and an organization on Tara as a Member or higher (Viewers can't use Phillip). If you don't have one yet, follow Create or join an organization first: create your own, or ask an Owner or Admin to invite you.
Install Phillip
The install script checks Node, downloads the latest Phillip from Tara, verifies the sha256, and installs it with npm install -g. The script doesn't use sudo, and it writes the Tara address and the public key into your configuration.
curl -fsSL https://tara.phillipcli.cloud/install.sh | shAfter installing, verify with this command:
ph --versionThe command prints the Phillip version, then the version of the bundled Claude Code. ph is short for phillip, and the two names behave the same.
If the terminal doesn't recognize the ph command, open a new terminal. If that doesn't help, npm's bin directory isn't on your PATH. See Installation or Troubleshooting. If you installed directly with npm, Phillip doesn't know the Tara address yet, so in the next step run ph setup --tara https://tara.phillipcli.cloud.
ph --versionphillip 0.1.6Claude Code 2.1.308Set up with ph setup
Go to your project's repo directory (already cloned, with an origin) and run:
cd your-project
ph setupThe command does five things in order and prints one status line for each.
- Get the Tara address and public key. If the machine has no key yet, Phillip fetches it from Tara, prints the fingerprint, and asks "Trust this key? [y/N]". Compare the fingerprint with your Owner or Admin before you answer
y. - Sign in to Tara: Phillip opens the browser, and you click Allow.
- Choose a project: Phillip lists the harnesses on Tara, you pick one, and Phillip runs
ph initfor you. - Connect GitHub or GitLab: Phillip reads the host from
origin, looks for tokens already on your machine (gh,glab, git credential), and asks before using one. If there isn't one, it opens the browser so you can click Authorize, or opens the token creation page with permissions already filled in. - Check the environment with
ph forge doctor.
You can run it as many times as you like. A step that's already done prints ✓ … (already done) and is skipped. If you run it outside a repo, the command stops after step 2, says the folder is not a git repository and lists git clone … && cd … commands for your organization's project repos; clone one, then run ph setup again inside the folder. When you see Next: ph bandum start <issue number>, then run ph to work with the agent., setup is complete. Ryoma only counts sessions that go through ph, so start the agent with ph after ph bandum start. At this point, commit phillip.lock, CLAUDE.md, and .claude/settings.json, which step 3 just created.
| Option | Meaning |
|---|---|
--tara <address> | The Tara address. Not needed if the install script already wrote it |
--harness <name> | Apply this harness to the project and skip the selection prompt |
--yes | Ask nothing: trust the Tara key, accept community resources during init, and use existing tokens. Use only after you've verified the key fingerprint |
Run the steps by hand
If ph setup stops partway, or you prefer to do it yourself, these commands correspond to each step:
# sign in (add --no-browser if the machine has no browser)
# a login belongs to one organization: add --org <slug> to choose, or pick from the list it prints
ph login --url https://tara.phillipcli.cloud
# later: ph org list, ph org switch <slug>
# apply a harness to the project; your organization decides the harness name
ph init harness-rnd-sdlc
# connect GitHub/GitLab, detecting the host from origin
ph connect
# check the environment
ph forge doctorOn another machine that clones a project that already ran init, you only need ph tara install to install the exact versions locked in phillip.lock.
ph connect takes your own token, because commits and reviews are made in your name. Phillip stores the token in the machine's secret store and doesn't write it to the repo.
| Platform | Token permissions needed |
|---|---|
| GitHub | Classic: the repo scope. Or fine-grained: Issues, Pull requests, and Contents all set to Read and write on the project repo |
| GitLab | The api scope, and you're a Developer or higher in the project (GitLab 15.0 or later) |
Step-by-step instructions, with screenshots, for joining the organization, letting Phillip connect, and creating a token are in Connect GitHub or GitLab.
Reading the ph forge doctor result
ph forge doctor passes when no ✗ line remains. Node, Claude Code, git, and Tara are required. The ⚠ lines, such as Ryoma, Collector, or Guardrails, are optional. The command suggests how to fix them, but ph setup still doesn't fail.
ph forge doctorNode v24.22.0Claude Code 2.1.308 (Claude Code)git git version 2.50.1 (Apple Git-155)Tara maya.chen @ https://tara.phillipcli.cloudphillip.lock 17 resources locked (lock ba8972f416dd)Ryoma https://ryoma.phillipcli.cloud: metrics receivedCollector data received through RyomaGuardrails not installed on this machine (the Guardrails dashboard will be empty). Install: sudo "$(command -v ph)" guardrails install --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:<public key>Daily work
A task code looks like GH-12, which is the issue number. On GitLab you still use the GH- prefix with the issue number in the project.
For devs
| Command | When to use it |
|---|---|
ph bandum start GH-12 | Pick up a task: assigns it to you, sets the label "status: in progress", and creates the feature/GH-12-... branch and the testcases.md scaffold |
ph bandum check | Before you commit test files: checks testcases.md, acceptance.md, and .bandum.json |
ph bandum pr GH-12 | When you finish and have pushed the branch: opens a PR (an MR on GitLab) with "Closes #12" |
ph bandum review GH-12 | Move to testing: checks the PR and test cases and sets the label "status: review" |
ph bandum verify GH-12 | Runs the automated acceptance tests on the PR branch |
ph bandum pull GH-12 | View the comments when the task is sent back |
ph bandum fix GH-12 | The task was sent back: has the agent fix it according to the comments, then pushes |
ph bandum board | View the sprint's tasks by status |
A typical work cycle goes like this:
ph bandum start GH-12 # pick up the task, get a branch and test case scaffold
# ... work with the agent, commit, push the branch ...
ph bandum check # check the test files
ph bandum pr GH-12 # open the PR
ph bandum verify GH-12 # run the acceptance tests
ph bandum review GH-12 # move to testingph bandum verify exits with code 0 on pass and 2 when the task is sent back, so you can use it in scripts and CI.
ph bandum boardOpen tasks: 15Todo (6) GH-107 Export the order list to CSV for admins GH-102 Buy now without signing in GH-101 Paginated order history … and 3 moreIn progress (4) GH-111 Discount code applied twice @sam.patel [PR #112] GH-110 Remove unused environment variables @sam.patel [PR #113] GH-108 Filter products by price and brand @maya.chen [PR #114] GH-92 Promotions admin page @sam.patel [PR #96]Review (waiting for testing) (3) GH-98 Search suggestions while typing @maya.chen [PR #106] GH-91 500 error when searching special characters @maya.chen [PR #103] GH-90 Product images fail to load on Safari @maya.chen [PR #105]Rejected (being fixed) (1) GH-78 Risk: address data is not normalized @sam.patel [PR #82]Approved (1) GH-99 Pagination returns an empty page @sam.patel [PR #109]Bandum local is running: ph bandum ui opens the board on the web.For Testers, and BAs who test on their machine
| Command | When to use it |
|---|---|
ph bandum test GH-12 | Manual testing: fetches the PR branch, runs the app, and opens the task page so you can mark Pass or Fail |
ph bandum test GH-12 --cli | Mark right in the terminal, with no Bandum website needed |
ph bandum test GH-12 --pass TC-1,TC-2 --fail "TC-3=reason" | Mark with command flags: records the results, then approves or sends back |
ph bandum verify GH-12 | Runs the automated tests and records the results |
ph bandum bug "<title>" | Reports a bug outside the scope of the task under test and creates a new issue with the type: bug label |
If the bug is inside the task you're testing, mark that test case Fail and don't create a new issue. See also Report bugs.
Each issue needs exactly one type: feature | bug | debt | risk label, next to a level: S|M|L label, so that Ryoma can report on the workflow. If a label is missing, ph bandum start reminds you and ph bandum check warns with missing_type, but neither blocks you. To see your own AI cost, run ph ryoma.
Run Bandum locally to see the task board
The ph bandum ... commands above don't need Bandum running on your machine. You need it only when you want to see the task board and mark test cases on the web:
cd your-project
ph bandum uiThe first time, Phillip downloads the signed Bandum from Tara, verifies the sha256 and signature, configures it, runs it in the background on 127.0.0.1, and opens the browser. Only you can use it, and your GitHub or GitLab token isn't written to disk.
By default, Bandum uses SQLite and doesn't need Docker. That suits Devs, Testers, and BAs who work alone on a few repos. If you're comfortable with Docker, track many repos, or want to match the online version, add --docker to run with PostgreSQL.
| Command | What it does |
|---|---|
ph bandum ui stop | Stops Bandum (and PostgreSQL if you used --docker) |
ph bandum ui status | Lists local Bandum instances: host, repo, port, version, database, status |
ph bandum ui logs [-f] | Shows the log. Use -f to follow it continuously |
ph bandum ui reset [--yes] | Deletes local data. The data is only a copy, so you can sync it again |
ph bandum ui upgrade | Downloads the latest Bandum and restarts |
Three more flags: --port <n> (the default is the first free port from 8070), --repo <owner/repo> to add a repo on the same host, and --no-open to not open the browser.