Your first agent task
In this tutorial we will hand a GitHub issue to an agent. cambium will start a Claude Code worker in its own worktree, the worker will publish a pull request through graft, and once you merge it cambium will close the issue. Then we will start cambium as a service and watch a second issue go through on its own.
It takes about thirty minutes, most of it waiting for the worker.
Before you start
Section titled “Before you start”- Finish Your first Verified commit. We use the same
you/sandboxclone and App. - macOS (the services are launchd agents) with Node 22.13 or newer.
- Claude Code installed and signed in:
claude --versionprints a version. - No existing
~/.cambium/config.json.
Work from the sandbox clone throughout:
cd sandbox1. Install the stack
Section titled “1. Install the stack”npm install -g oakgreenoakgreen --versionThis installs oakgreen with cambium, canopy and the other tools.
2. Set up the queue
Section titled “2. Set up the queue”oakgreen setup --repo you/sandboxYou will see it write ~/.cambium/config.json, create the queue labels (q:intake, q:task, q:human and the rest) on the sandbox, and write a label guide for agents into the clone. It ends with a list of remaining steps; we do them next.
3. Point cambium at your App
Section titled “3. Point cambium at your App”Open ~/.cambium/config.json. Fill in the App’s slug (the name graft doctor shows in App credentials (…), here you-agents), turn off the base-health check because the sandbox has no CI, and allow one worker at a time:
{ "repos": [{ "slug": "you/sandbox", "path": "/Users/you/sandbox", "baseBranch": "main", "requiredCheck": null }], "phases": { "task": { "cap": 1, "wallClockMinutes": 60, "maxTurns": 200, "maxAttempts": 3 } }, "graft": { "command": "graft", "app": "you-agents", "botLogin": "you-agents[bot]" }, "worker": { "command": "claude", "args": [], "graftApp": "you-agents" }}Keep the path setup wrote for you.
Workers get their worktrees under .claude/worktrees in the clone. Keep them out of git locally:
echo ".claude/worktrees/" >> .git/info/exclude4. Tell workers how to check their work
Section titled “4. Tell workers how to check their work”Workers read the repository’s AGENTS.md. Give the sandbox one, published the way you learned in the first tutorial:
cat > AGENTS.md <<'EOF'# Working in this repo
Verify: `test -f haiku.txt`. There is no `pnpm verify` here.EOFgraft publish agent/agents-md "docs: add AGENTS.md" --paths AGENTS.md --pr "Add AGENTS.md"Merge that pull request on GitHub before going on: workers start from origin/main.
5. File a task
Section titled “5. File a task”cat > issue.md <<'EOF'Add `haiku.txt` with a three-line haiku about oak trees.
Acceptance: `haiku.txt` exists and has three lines.EOFgraft issue create --title "Add a haiku" --body-file issue.md --labels q:taskgraft prints the new issue as JSON. Note its number; we will say 7.
6. Run the worker
Section titled “6. Run the worker”cambium run task --issue 7cambium claims the issue (it gains the running label), creates a worktree at .claude/worktrees/7-add-a-haiku, and starts claude -p in it. The worker runs in the foreground, so this takes a few minutes.
When it finishes, cambium records the outcome. Open the issue on GitHub:
- It has lost
q:taskandrunning. - cambium has left one comment describing the issue’s state.
- A pull request from
agent/7-add-a-haikucloses it, with a Verified commit from the App.
7. Merge, and let cambium close out
Section titled “7. Merge, and let cambium close out”Merge the pull request on GitHub. Then run one tick of the scheduler:
cambium start --oncecambium sees the merged pull request, closes issue 7 and deletes its branch.
8. Run it as a service
Section titled “8. Run it as a service”oakgreen start cambium canopyoakgreen servicesBoth show as running with a pid. Open http://127.0.0.1:4317/: this is canopy. The header shows the mode and the last tick.
9. Do it again, hands off
Section titled “9. Do it again, hands off”File a second task:
cat > issue.md <<'EOF'Add a second haiku to `haiku.txt`, about acorns, after the first one.
Acceptance: `haiku.txt` has two haiku.EOFgraft issue create --title "Add an acorn haiku" --body-file issue.md --labels q:taskWatch canopy’s Queue tab. Within a tick (30 seconds) the issue moves from the q:task lane to Running, then its pull request appears. Merge it, and within another tick the issue closes.
What you did
Section titled “What you did”You turned a labelled issue into a merged pull request without touching the code. cambium kept every bit of state on GitHub, in labels and one comment, and the worker wrote only through graft.
When you are finished, stop the services:
oakgreen stop cambium canopy