# Status

> Use when a thin client (pi extension, TUI, dashboard) needs bro's live project board in one read — active beads, fleet workers, drill frame, PR gate. `bro fleet status --json` is the contract; `--deep` adds the act gate (network). Requires `bro` (npx -y @broject/bro@0).

- Skill: `theplenkov/status` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/status`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/status/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/status

---


# /status (bro)

**All mechanics live in the `bro` CLI.** This skill is the contract
reference for thin clients rendering the board.

## The read

```bash
bro fleet status            # compact human board
bro fleet status --json     # machine form — the thin-client contract
bro fleet status --deep     # + act exit gate (gh calls — slower cadence)
```

`bro fleet status` is the answer to "what is alive in this project right
now": one call instead of `bd list` + `bro fleet agents status` +
`bro review act status` per refresh tick.

```jsonc
{
  "dir": "/repo", "branch": "feat/x", "dirty": 3,
  "worktrees": [{ "name": "repo--fix-x", "path": "/repo--fix-x",
                  "branch": "work/fix-x", "state": "dirty(2)",
                  "claim": "fix-x" },
                { "name": "repo", "path": "/repo", "branch": "main",
                  "state": "clean", "main": true, "here": true }],
  "beads": { "inProgress": [{ "id": "bro-1", "title": "…",
                              "priority": 2, "assignee": "…" }],
             "ready": [{ "id": "bro-9", "title": "…" }],
             "readyTotal": 68 },
  "fleet": { "maxConcurrent": 3,
             "agents": [{ "id": "native-abc", "backend": "native",
                          "step": "bro-mol-x", "state": "running",
                          "cause": null, "pid": 123, "worktree": "bro",
                          "provider": "orcarouter", "model": "jev" }] },
  "drill": { "frame": { "id": "bro-x.1", "title": "…", "depth": 2 } },
  "watch": { "ts": "…", "ageMs": 240000, "attention": 0 },
  "act": { "pr": 282, "url": "https://…/pull/282", "gate": "BLOCKED",
           "openThreads": 2, "ciPending": 3,                        // --deep
           "blockers": ["3 pending check(s)"] }
}
```

## Contract notes

- **Read-only, cwd-scoped.** Never mutates; safe to poll on any tick.
- **Fast path is local-only.** `bd`, the agent registry
  (`<git-common>/bro/agents.json` — shared across linked worktrees),
  the drill stack, `git status --porcelain`. No network.
- **`--deep` adds `act`** — the current branch's open PR + exit gate
  (threads, checks, blockers). This is the network part; poll it on a
  slower cadence than the local board.
- **Absent state is empty, not an error.** Bead-less checkout → empty
  arrays; no registry → `agents: []`; no open PR → `act: null`; no
  heartbeat file → `watch: null`.
- **`watch` is the rig's heartbeat freshness** — read from
  `<git-common>/bro/heartbeat.json` (rewritten by every `bro review watch`
  tick, a manual `--once` included). `ageMs` is the signal: fresh = a
  watch ran recently, stale = none did — it attests the last tick, not
  which invocation wrote it. `attention` is the last snapshot's
  open-decision count.
- **Bead rows are slim.** Only `id`, `title`, `priority`,
  `issue_type`, `assignee` cross the wire — descriptions and
  dependency graphs stay in `bd show`. `beads.ready` is capped at 10;
  `readyTotal` carries the real count.
- **fleet.agents[].state** — `running | exited | stopped | unknown`,
  derived cheaply (pidAlive + recorded exitStatus), not the full
  connector probe `bro fleet agents status` does.
- **`worktrees` is the claimed-live-work plane** — every checkout in
  `git worktree list`, each with `branch` and `claim`: the live
  in-tree marker detail `bro work enter` stamped (absent = unclaimed
  or aged out). `state` follows `bro work list`'s vocabulary
  (`clean | dirty(n) | gone | LOCKED | PRUNABLE`) but is probed only
  for live work — claimed trees, main, cwd — a parked sibling lists
  without it. `main`/`here` flag the primary checkout and the board's
  own cwd — a sibling holding work is visible even when it never
  became a bead row.

