Skip to content

canopy

canopy is a local, read-only page over cambium’s heartbeat, the GitHub queues and cambium’s traces. It holds no credentials and writes nothing.

Package: @oakgreencc/canopy. Node ≥ 22, no runtime dependencies. GitHub is read through graft graphql; graft must be on PATH.

Command Behaviour
canopy [flags] Serves the page in the foreground.
canopy install [flags] [--dry-run] Writes ~/Library/LaunchAgents/com.oakgreencc.canopy.plist, serving with the given flags. --dry-run prints it. Log: ~/.canopy/logs/canopy.log.
Flag Default
--port <n> 4317
--host <addr> 127.0.0.1
--state <file> cambium config’s paths.heartbeat (or <paths.home>/state.json), else ~/.cambium/state.json
--traces <file> <paths.home>/otel/traces.jsonl from the cambium config, else ~/.cambium/otel/traces.jsonl
--config <file> $CAMBIUM_CONFIG, else ~/.cambium/config.json
--repo <owner/name> Repeatable. Else the config’s repos[].slug, else the heartbeat’s repos.
--cache <seconds> 15, also the minimum
--graft <cmd> graft

The header always shows mode and last tick. The tab is kept in the URL hash.

Tab Hash Shows
Inbox #inbox, #inbox/<owner>/<name>/<n> q:human items, stranded issues and session candidates, grouped, in a list beside a reading pane.
Queue #queue Triage, Running and Pull requests; the q:intake, q:task and q:promote lanes; a band of every issue by stage; cost per day by phase.
Graphs #graphs, #graphs/<name> Each cambium graph drawn, with the last 24 hours of moves replayed.
Traces #traces, #traces/<trace id> One row per traced run; a span waterfall per run.
Health #health Last tick, workers, events.

Each item sits in the first group it matches. Empty groups are hidden; the sort applies within each group.

Group Labels
Needs a session why:budget, ask:decide with ask:session, or a session candidate (see Cost)
Answer in a comment any other ask:decide
Offline chores ask:verify, ask:chore
Approvals why:approve, ask:approve
Other no ask:* label to go by
PR closed stranded issues

Approvals are matched before the other groups.

Key Action
j / k, arrow keys Move
Enter Read
o Open on GitHub
Escape Back to the list (narrow screens)

A q:human item cambium wrote a session brief for (<home>/briefs/<owner>__<name>/issue-<n>.md, currently why:budget only) shows Interactive session in the reading pane: the command cd <repo path> && claude "$(cat <brief>)" and a Copy button. The repo path comes from repos[].path in the cambium config; without one the command has no cd. Items without a brief show nothing.

Labels on an open issue Column
running with q:intake Triage
running with q:task Running
q:intake with wait:deferred or wait:blocked Deferred / Blocked (waiting)
q:intake Intake
q:task Task
q:promote (open, or closed and not yet promoted) Promote
q:human Inbox

A stranded issue is open, carries no queue label, and its agent/* PR closed unmerged with no open agent PR closing it. Read from the 50 most recently updated closed PRs per repository.

From the heartbeat’s repos[].cost.

Where Shows
Inbox rows, reading pane, lane and Triage/Running cards What the issue has cost so far; per phase on hover. Red when flagged.
Queue figures The last 7 UTC days, each a column stacked by phase (triage, task, rescue), summed over repositories.
Inbox A flagged issue (task spend over cambium’s costFlagUsd, no merged PR) is a session candidate: tagged flag:cost (filter “Flag”, “over budget”), and listed with kind “session candidate” if it is not already in q:human or stranded, and grouped under “Needs a session” (unless it awaits an approval). Its reading pane says so.

Only GET and HEAD are answered, and only for a loopback Host (or the --host given).

Endpoint Returns
GET / One self-contained HTML page; polls /api/state every 5 s.
GET /api/state { now, pollMs, cacheMs, notes, heartbeat, github, traces, cost }
GET /api/traces Trace file fields plus traces: the newest 200 runs.
GET /api/traces/<trace id> { summary, spans }, spans in tree order with depth. 404 for an unknown id.
GET /api/issue/<owner>/<name>/<n> { issue, fetchedAt, error } for an issue in a watched repository. 404 otherwise.
Field Shape
heartbeat { status, path, message, stale, ageMs, staleAfterMs, data }. status: ok, missing, unreadable, unknown-version. stale after 3 × tickSeconds.
github { repos, columns: { intake, waiting, task, running, human, promote }, prs, stranded, flagged, fetchedAt, cached }. A human item with a session brief carries brief: { path, command }. Each column and stranded item has cost: { usd, triage, task, rescue, runs, flagged }, or null. flagged: session candidates not in q:human or stranded.
traces { status, path, message, files, malformed, total, errored, byIssue, progress, recent, flow }. status: ok, missing, unreadable.
cost { days, flagUsd }. days: the last 7 UTC days, oldest first, each { day, triage, task, rescue, total } in US dollars. flagUsd: the heartbeat’s costFlagUsd, or null.
Input Source
Heartbeat cambium’s state.json, schema version: 1. Any other version is reported, not parsed.
Traces The local collector’s OTLP/JSON file and rotated backups (traces-<time>.jsonl), newest first, up to 64 MB. Re-parsed only when size or mtime changes.
Session briefs <paths.home>/briefs/ from the cambium config, else ~/.cambium/briefs/. Checked for each q:human item on every /api/state.
Queues GitHub labels, through graft graphql. Each repository’s answer is cached for --cache seconds; a failed refresh keeps the last good answer.