Produce an attention report for components, projects, fleets, rigs, or the full configured workspace. Snapshot report mode reads GitHub state and records a local observation in the Homeboy SQLite database so later runs can compare against the previous observation for the same target. Watch mode is also read-only unless --auto-merge is explicitly passed.

triage is the reference consumer of Homeboy’s shared scope model: it accepts component, project/target, fleet, rig, workspace, and direct path scopes, then normalizes each scope to component references before reading GitHub state.

Synopsis

homeboy triage [OPTIONS] [COMMAND]

When no command is provided, homeboy triage defaults to homeboy triage workspace.

Subcommands

• component — triage one registered component, or any checkout via --path
• project — triage every component attached to a project
• fleet — triage unique components used across a fleet
• rig — triage components declared in a local rig spec
• workspace — triage every configured project, rig, and registered component once per repo
• landing — summarize mergeability/check blockers for an explicit PR fleet or branch pattern

See Scope model for how these scopes relate to component-first, target-first, environment, and workspace commands.

Useful filters

• --issues / --prs — restrict which GitHub item types are included
• --mine — show work assigned to or authored by the authenticated GitHub user
• --assigned <USER> — restrict to one assignee
• --label <LABEL> — restrict to one label; repeatable
• --needs-review — restrict PRs to review-required items
• --failing-checks — restrict PRs to failing-check items
• --drilldown — include compact failing check names and URLs

Watch Mode

triage --watch observes one or more GitHub PR/issue refs until they reach a target state. Snapshot triage remains read-only; watch mode only mutates GitHub when --auto-merge is explicitly passed.

homeboy triage --watch Extra-Chill/homeboy#2238 --until merged
homeboy triage --watch Extra-Chill/homeboy#2238 --until green-mergeable --auto-merge
homeboy triage --watch https://github.com/Extra-Chill/homeboy#2238 --until closed --timeout 10m --poll-interval 30s

Supported --until states:

• default — merged for PRs and closed for issues when --until is omitted
• merged — PR is merged
• closed — issue or PR is closed, including merged PRs
• green — PR checks report success
• green-mergeable — PR checks report success, merge state is clean, and the PR is not draft
• failed — PR checks report failure
• state-changed — item state changes after the initial poll
• commit-pushed — PR head SHA changes after the initial poll

Watch output is structured JSON with command: "triage.watch", final watched target states, and an events array. Events include watch.started, item.state_changed, pr.commit.pushed, pr.ci.transitioned, pr.merged, optional pr.merge_requested, and watch.exit.

--auto-merge uses the GitHub REST merge endpoint with --merge-method squash by default. When --auto-merge is passed without --until, Homeboy watches for green-mergeable. This avoids depending on gh pr merge‘s GraphQL path for the actual merge operation.

Landing PR Fleets

homeboy triage landing is the compact holding dashboard for many PR branches. It accepts explicit PR refs, source branch patterns, issue-linked PRs, and normal Homeboy scopes. Each PR row includes the PR URL, base/head branch, mergeability, check classification, next suggested command, and matching local task worktrees when they exist.

homeboy triage landing Extra-Chill/homeboy#2238 Automattic/static-site-importer#118 --drilldown
homeboy triage landing --repo Extra-Chill/homeboy --branch 'fixture/*' --drilldown
homeboy triage landing --workspace --branch 'e2e/*' --limit 100 --output ./landing-fleet.json
homeboy triage landing --repo Extra-Chill/homeboy --ordered 2238 2239 2240

When a PR head branch matches a persisted homeboy worktree record for the same GitHub repo, the JSON row gains local_worktrees entries with the task worktree ID, local path, branch, base ref, dirty state, unpushed commit count, safety reasons, and optional task/run provenance. The summary also reports local_worktrees, local_worktrees_dirty, and local_worktrees_unpushed counts so an orchestrator can quickly see which PRs need local cleanup or pushes before landing.

Output Signals

Surfaced issues include comment activity when GitHub returns it:

• comments_count
• last_comment_at

Surfaced pull requests include the same comment activity plus review activity:

• comments_count
• reviews_count
• last_comment_at
• last_review_at

Each successful observation adds an observation block to the JSON output with the local run_id, recorded item_count, SQLite store_path, and previous_run_at when the same triage target was observed before. When previous item snapshots are available, the block also includes a comparison with previous_run_id, previous_item_count, new_items, resolved_items, and changed_items. Changed items report the fields that moved, such as next_action, checks, review_decision, comments_count, or last_comment_at. Triage item snapshots are stored in the triage_items table and linked to the existing runs table.

--path (component)

homeboy triage component --path <CHECKOUT> skips the registry entirely and resolves the GitHub remote directly from the checkout’s origin. Useful for:

• unregistered checkouts (CI runners, ad-hoc clones, worktrees)
• repos whose registry record is broken or stale (e.g. a leftover worktree pinned as local_path, or a non-URL remote_url) — the escape hatch lets you triage the checkout without first reconciling the registry
• one-off triage from a directory you do not want to register

The COMPONENT_ID positional becomes optional when --path is given. When both are supplied, they must agree: if a registry record exists for COMPONENT_ID and its local_path does not canonicalize to <CHECKOUT>, the command errors clearly rather than silently picking one side.

The checkout must exist and be a git repository, and git remote get-url origin must return a parseable GitHub URL — otherwise the command surfaces the same remote_url_is_not_github reason as the registry-driven path.

Examples

homeboy triage
homeboy triage --mine --drilldown
homeboy triage component homeboy --failing-checks --drilldown
homeboy triage component --path /Users/me/Developer/homeboy
homeboy triage component homeboy --path ./homeboy --failing-checks
homeboy triage landing --repo owner/repo 123 124 --drilldown

Related

• status
• runs
• review
• Hold a PR fleet