agent-team-foundation/breeze

Breeze — Operational Skill

This skill is the operational handbook for the breeze product. If you have not yet loaded the first-tree entry-point skill, load that first — it explains the toolkit layout and how the four skills relate. This skill covers how to drive the first-tree breeze CLI.

When To Use This Skill

Load this skill when the task involves any of:

• Running or inspecting the breeze daemon
• Viewing the GitHub notification inbox or the live activity feed
• Triggering a one-off notification poll
• Configuring, starting, or stopping the background daemon (launchd on macOS)
• Installing the breeze statusline hook into Claude Code
• Diagnosing a broken breeze install or a stuck claim

Breeze is designed for agents, not humans — most commands are idempotent and safe to re-run.

Core Concepts

• Inbox — the local store of explicit GitHub mentions and review requests, under ~/.breeze/.
• Daemon — a long-running broker process that polls GitHub, keeps the inbox fresh, dispatches work to per-task agent runners, and serves a local HTTP/SSE endpoint on 127.0.0.1:7878 for the dashboard.
• Runner — a per-task worker spawned by the daemon for a single claim.
• Claim — exclusive lease on a notification so only one runner acts on it.
• Statusline — a sub-30 ms Claude Code statusline hook that prints a one-line summary of the inbox state.

CLI Commands

Primary (start here)

| Command | Purpose | |---|---| | first-tree breeze install --allow-repo owner/repo | First-run setup — checks gh/jq/gh auth, creates ~/.breeze/config.yaml with defaults, and starts the daemon. The repo scope is required so breeze never falls back to scanning the whole account. (Wiring the Claude Code statusline is a separate manual step — see the Statusline section.) | | first-tree breeze start --allow-repo owner/repo | Launch the daemon in the background (launchd on macOS, detached spawn elsewhere) | | first-tree breeze stop | Stop the daemon and remove its lock | | first-tree breeze status | Print the daemon lock + runtime/status.env | | first-tree breeze doctor | One-screen diagnostic of the local install | | first-tree breeze watch | Live TUI: status board + activity feed | | first-tree breeze poll | Poll explicit GitHub mentions and review requests once (no daemon required) |

Advanced (agents, debugging)

These are the daemon's foreground entrypoints and manual-cleanup helpers. Humans normally only need the primary set above; reach for these when debugging the pipeline or when doctor directs you to.

| Command | Purpose | |---|---| | first-tree breeze run --allow-repo owner/repo / first-tree breeze daemon --allow-repo owner/repo | Run the broker loop in the foreground. start is preferred for humans; daemon is invoked by launchd. | | first-tree breeze run-once --allow-repo owner/repo | Run one poll cycle, wait for drain, then exit. Useful for debugging the daemon pipeline. | | first-tree breeze cleanup | Remove stale workspaces and expired claims. Only run if doctor suggests it. |

Hook / internal entry points (do not invoke directly)

These exist for compatibility or to be called by other code. Never invoke them manually from a shell or from an agent action — they are listed here only so you recognize what they are when you encounter them in ps, config files, or log lines.

| Command | Why it exists | |---|---| | first-tree breeze statusline | Claude Code statusline hook. Claude Code should be pointed at the pre-bundled dist/breeze-statusline.js directly for sub-30 ms cold start (see the Statusline section below). The CLI shim exists for parity. | | first-tree breeze status-manager | Internal helper used by the breeze runner to manage per-session status entries. Runners call it programmatically; no direct human or agent use. | | first-tree breeze poll-inbox | Legacy alias for poll. Kept so existing scripts keep working; new callers should use poll. |

For full options on any command, run first-tree breeze <command> --help.

Any command that starts the daemon now requires an explicit --allow-repo scope. Use exact repos (owner/repo) and/or owner globs (owner/*).

Recommended Invocation

npx -p first-tree first-tree breeze <command>

This always runs the latest published version.

For the statusline hook (called many times per Claude Code session), use the pre-bundled minimal entry point for sub-30 ms cold starts:

node /path/to/first-tree/dist/breeze-statusline.js

first-tree breeze install does not wire this up into Claude Code for you. Configure the statusline hook manually after install if you want the live inbox summary in your session UI.

Environment

• BREEZE_DIR — override the default store root (~/.breeze/)
• BREEZE_HOME — override the default daemon private state dir (~/.breeze/runner/)

Typical Flows

First-time setup on a fresh machine:

npx -p first-tree first-tree breeze install --allow-repo owner/repo
npx -p first-tree first-tree breeze start --allow-repo owner/repo
npx -p first-tree first-tree breeze status

If the daemon did not come up during install, run:

npx -p first-tree first-tree breeze start --allow-repo owner/repo

Something looks wrong:

npx -p first-tree first-tree breeze doctor
npx -p first-tree first-tree breeze status
npx -p first-tree first-tree breeze cleanup   # only if doctor suggests it

Peek at activity without starting a daemon:

npx -p first-tree first-tree breeze poll
npx -p first-tree first-tree breeze watch

Related Skills

• first-tree — entry-point skill: methodology, references, routing. Load this first.
• tree — load if the task involves the Context Tree repo itself.
• gardener — load if the task involves automated responses to sync PR feedback on tree repos.