Get Your Briefing

Get Your Briefing

bob brief builds one briefing for every project, covering the time since the previous briefing. It has four lists: Needs you, Done, Doing and Will do, and every item has a link. It is where to start after time away. The document contract, its sources and the page are described in the Briefing reference.

Terminal only.

1. Read it

bob brief

briefing 2026-09-18T02:23:31Z on farm-01 — window since 2026-09-16T05:12:24Z (previous-briefing)

Needs you (0)
Done (2)
  [tick] farm-01/bigbrain: bob tick 2026-09-17 (dry-run) — blocked — 1 step(s) failed: run
Doing (1)
  [warp-session] farm-01/bigbrain: coding — feature/issue-2553-howto-coverage (73,575 tokens)
Will do (0)

sources: gh:merged-prs ok (3), gh:closed-reqs ok (7), …, snapshots ok (0), warp ok (1), ticks ok (2), rituals ok (22), rotations ok (0)
gaps (2):
  snapshots:macbook-air: never — no snapshot published

Start with Needs you: open todos, non-draft PRs waiting for review, blocked warp runs, open harness defects, overdue credential rotations and overdue rituals. It lists everything still open, however old. The window applies only to Done. It starts at the previous stored briefing, or 24 hours back if there is none; use --since <ISO> to choose a different start.

2. Read the gaps line

A source that cannot be read becomes one named gap. The briefing is still built. The exit code tells you whether anything was skipped:

Exit	Meaning
0	Every source was read.
3	Built, but at least one source is a gap. Read gaps (N): at the bottom.

A gap such as snapshots:<machine>: never — no snapshot published means that machine’s projects are missing from Doing. Fix the gap before you conclude nothing is running there. With --offline, every forge-backed source is deliberately a gap, and only local files are read.

3. Store it for the page

bob brief --write

--write saves the document under $BOB_HOME/briefings/ — or the dir this machine declares in machines.json bob_workload.brief. The next briefing’s window starts from it, and the Project Monitor’s /briefings page lists it. When the machine declares a retention_days (90 when its brief block omits it), each write also prunes stored briefings older than that; --retain-days N sets it for one run. That page is the dashboard server bob dash serve runs, reached over the tailnet.

4. Send the headline to your phone

bob brief --send                      # store it, then post at most 5 lines + the page link
bob brief --send --on-quiet skip      # send nothing when nothing needs you and nothing got done

--send stores the briefing, then posts the counts, the top Needs-you item and a link to the stored page through bob notify. It uses that command’s exit codes: 0 delivered, 3 no bridge configured (the message is printed instead), 4 transport error. If the link points at the wrong host, pass --url http://<host>:<port>.

5. Have it arrive on a schedule

Declare the cadence once, in this machine’s entry in the operator repo’s machines.json, beside the farm tick:

"bob_workload": {
  "source": "~/projects/bigbrain",
  "bob_home_channel": "nightly",
  "tick":  { "schedule": "daily 02:30 America/Los_Angeles" },
  "brief": { "schedule": "daily 07:00 America/Los_Angeles", "quiet_hours": "22:00-07:00", "retention_days": 90 }
}

Then install the timer (Linux):

bob brief --install-timer --dry-run   # the units it would write
bob brief --install-timer             # write them and enable bob-brief.timer
bob brief --timer-status              # expect: installed (…), timer active

The timer runs bob brief --send --scheduled every day at 07:00. bob tick does the same at the end of each tick. Neither makes a briefing inside the quiet hours. Stored briefings older than retention_days are pruned on each write. A machine with no brief block has no schedule. bob brief still works there when you run it.

Verify

ls "$BOB_HOME/briefings/" | tail -1   # the briefing you just stored
systemctl --user list-timers bob-brief.timer   # the next scheduled briefing (after step 5)
bob brief --json | jq .counts         # the same counts the headline sent

Related

• Briefing reference: briefing/1, the sources, gap semantics, the page and the message format.
• Farm Tick: the unattended work a briefing reports on.