/sitrep sessions and accounts

Install

Install just this, from a clone of the repo. Anything it needs comes with it.

./scripts/install-skills.sh --skill sitrep   # bash, Git Bash, macOS, Linux
.\scripts\install-skills.ps1 -Skill sitrep   # Windows PowerShell

Needs: handoff-auto (installed with it).

What it does

Answers "how's it going" in 10 lines or fewer. It's a live, spoken answer, not a document.

• What's running right now.
• Git state (worktrees, dirty/unpushed work).
• Open PRs and their CI.
• An asked-vs-done checklist for this conversation.
• Anything that needs you.
• A verdict on whether it's safe to close the session.

When to use

• "How's it going", "status update", "what's running", "anything for me", "can I close this".
• Named sitrep rather than /status because /status is already a built-in Claude Code command.
• Not for a written record of a long run — that's progress-report, which is scoped to everything since the last report and produces a file. sitrep never writes a report and only answers for right now.

How to invoke

/sitrep

Claude also runs it when you say one of the phrases above, so you don't have to type the slash command.

How it works

1. What's running. Collects the IDs of background tasks from the conversation, skipping any whose completion notice already arrived.
   • Sources: Bash/PowerShell with run_in_background, Monitor loops, background Agent launches.
   • Reports each one's age and its last output line (read from the task's output file, or TaskOutput, now deprecated).
   • Checks ListAgents (if available) and notes other agents that look stalled.
2. Git. For each repo this session ran git in (not only the current one):
   • git worktree list.
   • Per worktree, git status --porcelain and git status --porcelain --ignored -- skilleddocs. The second one finds handoffs in an excluded skilleddocs/, or in a handoff folder set in AGENTS.md.
   • Per worktree, unpushed commits: git log <ref>.., where <ref> is the upstream, else origin/<branch>, else origin/<default>. Never the local default branch, which would hide commits made on it.
   • No remote ref: unpushed is "unknown", and that blocks SAFE.
   • A branch with 0 commits and a clean tree has nothing to push; "never pushed" is only for commits with no origin/<branch>.
3. PRs + CI. gh pr list --author @me with checks status.
4. Asked vs. done. A short checklist built from this conversation's user messages — not the whole backlog.
5. Needs-you items. Missing keys/approvals/manual steps/unanswered questions, or "none".
6. Verdict. SAFE to close only if all of these hold:
   • Nothing's running.
   • Nothing's dirty/unpushed (or it's intentional and already handed off).
   • Any unfinished work has a handoff: committed and pushed, or saved on disk per TRACKING.md. Saved on disk means untracked (the only option on forks) or, in commit mode, a dated handoff left uncommitted on a task branch. That file doesn't count as dirty, and sitrep never suggests committing it.
   • An untracked handoff covers only the work it describes. It is lost if its worktree is removed, so the verdict is NOT SAFE when that worktree isn't the main one, was made by pair or meta-orchestrator, or when unsure.
   • Otherwise NOT SAFE, with the specific reasons.
7. On "close" / "yes, stop them": lists exactly what will be stopped and what (if anything) would be committed/pushed, and waits for an explicit yes before doing either.
   • On yes, stops background tasks with TaskStop (if available).
   • Calls handoff-auto to write the handoff if anything was unfinished, and prints its path.

Reads: background-task tools (if available), git, gh, this conversation. Writes: nothing, except a handoff document via handoff-auto when closing unfinished work, saved under skilleddocs/handoffs/.

Design principles

• Live and conversational, not a document. progress-report already covers the ledger-scoped, written case; sitrep fills the gap of "just tell me, right now, in chat."
• Read-only by default. Looking around only reads state. The one path that changes anything (stopping background work, writing a handoff) needs an explicit yes.
• Short on purpose. A status check that takes longer to read than the work itself defeats the point — hence the 10-line cap and "drop empty lines rather than padding them."

Shared context for these principles: Matt Pocock's video.

Use cases

• Mid-session, checking whether a background agent or long shell command has finished.
• Before stepping away, to see whether anything is unpushed or uncommitted across several worktrees.
• Before closing a session or terminal, to get a SAFE/NOT SAFE verdict instead of guessing.
• After a flurry of asks, to see which ones are still outstanding.

Tips

• If ListAgents isn't enabled, or a background task's output file path isn't in the transcript, sitrep still works from the transcript alone and says the last-output check was skipped.
  • TaskOutput is deprecated in favor of Read on the output file.
  • TaskList is the session to-do list, not background work; it only feeds the asked-vs-done line.
• "Can I close this?" and "close this" are different asks: the former is a read-only verdict (step 6); only the latter (or an explicit "yes, stop them") starts the stop-and-handoff flow in step 7, which waits for your yes.
• Ask again after fixing a NOT SAFE reason — it's cheap and re-checks everything, not just the item you fixed.

Example

Running: 1 background (8m, "3 tests failing") | 0 agents pending
Git: 2 worktrees, 1 dirty, 1 unpushed (fix/date-parse, 3 commits)
PRs: #21 checks passing
Asked -> done: 3/4 (in progress: fixing date parser)
Needs you: none
Verdict: NOT SAFE - background test run still failing, fix/date-parse unpushed

Running: none
Git: 2 worktrees, clean, all pushed (handoff in ../wt-issue-9 is excluded)
PRs: none
Asked -> done: 2/2
Needs you: none
Verdict: NOT SAFE - untracked handoff in worktree slated for removal: move ../wt-issue-9/skilleddocs/handoffs/2026-10-15-x.md or keep worktree

Related

• progress-report — the written, ledger-scoped counterpart; use it for "what's been done" over a whole run, not "right now".
• handoff-auto — writes the handoff document sitrep points at when it closes mid-flight work.
• session-handoff — same handoff, plus board bookkeeping, for a full end-of-session wrap-up rather than a quick check.

Prereqs

gh for the PR/CI check. TaskOutput (deprecated), TaskStop, TaskList and ListAgents are optional — used when available, skipped with a note otherwise.

Sample workflows

• Check before closing the terminal
  you → sitrep → remind → you → handoff-auto → you
  Install just this one: ./scripts/install-skills.sh --workflow safe-to-close or .\scripts\install-skills.ps1 -Workflow safe-to-close
• Coordinate with another session
  sitrep → session-bridge → you → you
  Install just this one: ./scripts/install-skills.sh --workflow two-sessions or .\scripts\install-skills.ps1 -Workflow two-sessions
• Keep going on another account
  you → switch → you → switch → sitrep → remind → you
  Install just this one: ./scripts/install-skills.sh --workflow usage-limit or .\scripts\install-skills.ps1 -Workflow usage-limit

Source

• sitrep/SKILL.md
• sitrep/README.md