catch-up

Per-machine state management for cross-repo session readiness briefings. Tracks which repos the user wants briefed at session start and the last time each was checked.

Why

Distributed teams across timezones hand off work overnight. When you start a session 8 hours after the previous timezone signed off, you need to know what changed before you start working — but the brief should be scoped to your task, not a generic dump of every PR. The CLI manages state; the Session Readiness & Catch-Up directive tells agents how to use it.

The CLI itself is state management only — it does not run gh queries, Linear lookups, or git mutations. Those live in the catch-up agent persona (which reads state via era-code catch-up list --json) and orchestration (which executes approved actions).

Subcommands

Subcommand	Purpose
register	Add the current repo to catch-up tracking
unregister	Remove the current repo
status	Show staleness for the current repo
list	Show all registered repos with staleness
mark-checked	Advance last_check after approved rebases land

Usage

Register the current repo

era-code catch-up register

Auto-detects the GitHub remote slug (e.g. Era-Laboratories/era-code) from git config remote.origin.url. Defaults to tracking the main branch; use --branches to specify others:

era-code catch-up register --branches main,develop

Check status

era-code catch-up status

Sample output:

Catch-Up Status
──────────────────────────────────────────────────

Path: /Users/alex/era-code
Stale threshold: 4h

Remote:        Era-Laboratories/era-code
Branches:      main
Registered:    5/6/2026, 8:00:00 AM
Last check:    5/6/2026, 6:30:00 AM  (5.0h ago)
State:         STALE — catch-up suggested

List all registered repos

era-code catch-up list

Use --json for agent consumption (this is what the catch-up persona reads):

era-code catch-up list --json

Returns a structured payload of all registered repos with last_check, is_stale, hours_since_check, etc.

Advance last_check after approved rebases

After the user approves the catch-up persona's proposed rebase actions and orchestration executes them successfully, run:

era-code catch-up mark-checked

This advances last_check to now, so the next session within the threshold won't re-prompt. Only run after a successful rebase / catch-up cycle. Failed or rejected proposals leave the timestamp stale so re-prompting works.

Storage

~/.era/catch-up-state.json (machine-global, distinct from per-repo .era/):

{
  "version": 1,
  "config": {
    "stale_threshold_hours": 4
  },
  "repos": {
    "/Users/alex/era-code": {
      "remote": "Era-Laboratories/era-code",
      "tracked_branches": ["main"],
      "last_check": "2026-05-06T19:30:00Z",
      "registered_at": "2026-04-15T10:00:00Z"
    }
  }
}

Plan-mode compliance

The catch-up flow is read-only by default in both plan mode and normal mode. All git mutations and state writes are surfaced as proposed actions for explicit user approval. The CLI commands themselves split into:

Command	Mutates state?	Plan-mode behavior
status, list	No	Always allowed
register, unregister	Yes (state file only)	Surfaced as proposed action by callers
mark-checked	Yes (state file only)	Run only after approved rebases land

The persona itself never invokes these mutating commands — orchestration (post-approval) does.

[!IMPORTANT] The catch-up persona never runs git fetch, git rebase, or any branch-mutating command. It only proposes rebase plans for user approval. Orchestration executes approved actions outside plan mode.

How it composes

era-code catch-up (CLI) → state file → catch-up persona (reads state, gathers data, synthesizes brief) → orchestration (presents proposals, executes on approval) → era-code catch-up mark-checked (advances state).

Each piece is replaceable: the CLI works standalone for humans (status / list are useful on their own), the persona is invokable for ad-hoc cross-repo briefings, and orchestration's Step 0 wires it all together for first-prompt-of-session readiness.

Use Cases

• Morning timezone handoff: Last check 14h ago. First prompt of the day triggers a scoped brief covering overnight merges relevant to the task you're picking up.
• Cross-repo coordination: Multiple registered repos surface together — see what Tokyo merged in era-code-agent while you were on era-code-manager.
• Standalone state inspection: Run era-code catch-up list anytime to see which repos are stale without launching a session.