Agent status hub: repository context across sessions

Every agent session starts empty. The usual fix — "read status.md first, update it as you go" — works for a month and then the file is 200–370 lines of mixed plans, research dumps and completed-phase history, loaded in full at every start and edited in half of all commits. This skill replaces the single file with three files of different lifetimes, puts a hard cap on the only one that is loaded every session, and makes loading and write-back mechanical instead of an instruction the agent may or may not follow.

First applied to kokemusu on 2026-08-23 (PR #6). The measurements below come from the author's own repositories.

When to use this skill

• A repo has a status.md / PROGRESS.md / docs/project-status.md that keeps growing, or a CLAUDE.md that has become a progress file (strikethrough history, "next actions" with dates)
• A sandboxed / autonomous agent (see claude-code-docker-sandbox) must pick up where the last session stopped without a human re-explaining
• You are asked "how should Claude remember where this project stands between sessions?"
• NOT for: team task tracking with assignees and due dates (use the issue tracker; this skill is the agent's orientation layer on top of it), or per-file coding conventions (those belong in CLAUDE.md / .claude/rules/)

The problem, measured (2026-08-23)

Root cause: three kinds of information with different lifetimes share one file, and a "read it first" rule loads all of it every session.

Design

CLAUDE.md               conventions and pointers only — no progress, no history, no "next actions"
docs/status.md          the NOW hub. Hard cap 40 lines / 3 KB. Four fixed H2 headings:
                        phase / next 3 moves / blockers & waiting-on-human / open PRs
docs/log.md             append-only, newest first, one line per milestone (date, what, #PR / ADR / skill).
                        Never loaded in full (the hook injects the latest 5 entries); `head -20 docs/log.md` on demand
docs/plans/<topic>.md   created when work on a topic starts; deleted when done (the conclusion lives in an ADR or one log line)
docs/adr/, CONTEXT.md   decisions and vocabulary (unchanged; see `grill-with-docs`)
docs/roadmap.md         phases and checkboxes only; no narratives of how things got done

Three rules keep it from regrowing:

1. A finished item in status.md is deleted and moved to the top of log.md as one line. Strikethrough is forbidden — it is the first symptom of bloat.
2. A status.md section longer than 8 lines becomes docs/plans/<topic>.md plus a one-line pointer.
3. "Done" is recorded in exactly three places: git, PRs, log.md. Never in status.md or CLAUDE.md.

The cap is enforced by a script (check-status.sh: ≤ 40 lines, ≤ 3,000 bytes, no ~~, exactly the four headings) that both the write-back skill and CI run. 40 lines is enough for a solo project's "now"; 3 KB keeps Japanese text (3 bytes/char) honest.

Mechanisms (Claude Code)

All four live in the repository, so a sandboxed container session (bind-mounted repo, committed .claude/settings.json) behaves exactly like the host. Templates for every file: references/templates.md. Doc-verified facts behind the choices: references/claude-code-facts.md.

1. SessionStart hook injects the hub. .claude/hooks/session-start.sh prints docs/status.md, the latest 5 entries of docs/log.md and git log --oneline -5; registered in the committed .claude/settings.json under hooks.SessionStart (no matcher → fires on every source: startup, resume, clear, compact, fork). A SessionStart hook's stdout is added to Claude's context; the compact source means the "next 3 moves" survive compaction without relying on the summary. This replaces "read status.md first" (advisory) with something that always happens (deterministic).
2. /handoff skill writes it back. .claude/skills/handoff/SKILL.md with disable-model-invocation: true (only the human triggers it, at the end of a session). Steps: gather state → add finished milestones to the top of log.md → rewrite status.md (never append) → delete finished plans, tick roadmap boxes → run check-status.sh until OK → commit on the working branch (branch off if on main) → report the first "next move" as the next session's starting point.
3. CI gate. bash .claude/hooks/check-status.sh docs/status.md as the first step of the required CI job: a PR that pushes the hub over the cap cannot merge. Cheap, and the only enforcement that survives an agent ignoring instructions.
4. CLAUDE.md diet. Move "next actions" to status.md, completion notes to log.md, long decision bullets to one-line pointers at the ADR / docs. Add two lines: the hub rules and "update via /handoff". No compaction-steering line: compaction is automatic, the SessionStart hook re-injects the hub on compact, and current best practices list aggressive context management under "What you can stop doing" (removed in 0.2.0). kokemusu went from 69 lines / 14.4 KB to 45 lines / 7.8 KB; the official target is under 200 lines, and /doctor proposes trims.

Install (≈ 15 minutes)

1. Copy the templates: docs/status.md, docs/log.md (seed it with the last few milestones from git log), .claude/hooks/session-start.sh, .claude/hooks/check-status.sh (chmod +x both — git keeps the bit), .claude/skills/handoff/SKILL.md.
2. Add the hooks.SessionStart block to the committed .claude/settings.json (not settings.local.json, or the container won't get it). Use ${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh as the command with "args": [] (exec form, so the path placeholder needs no quoting).
3. Add the CI step before dependency install.
4. Diet CLAUDE.md and point roadmap.md / any "current state" section at status.md.
5. Verify: bash .claude/hooks/check-status.sh prints OK; CLAUDE_PROJECT_DIR=$PWD bash .claude/hooks/session-start.sh prints the hub; in a new session /hooks lists SessionStart and the first message shows the injected hub; /context shows CLAUDE.md shrank.

If the headings are translated, change them in both status.md and check-status.sh — the script pins them literally.

Inside a Docker sandbox

• The repo is bind-mounted at /workspace and CLAUDE_PROJECT_DIR resolves there, so the hook, the skill and the check script need no rebuild and no extra mount.
• Auto memory does not cross the boundary. The container's CLAUDE_CONFIG_DIR (/home/node/.claude, a named volume) holds its own projects/<repo>/memory/; the host has another. Anything both sides must know goes in the repo — the hub — never in memory. Keep auto memory for preferences and corrections.
• Session transcripts are per machine too: claude --continue inside the container resumes container sessions only. The hub is what makes a host session and a container session interchangeable.
• Hooks run under bypassPermissions (the container default from claude-code-docker-sandbox) like anywhere else; deny rules are unaffected.

Alternatives considered

• GitHub Issues / Projects as the primary store — fine for a human backlog, but a sandbox token scoped to Contents + Pull requests cannot write issues, and gh api is typically denied. Public repos can still be read unauthenticated. Use issues for backlog items that don't need to be in context; keep the agent's "now" in the repo.
• @docs/status.md import in CLAUDE.md — imports load at launch, so it costs the same context, and there is no re-injection after /compact beyond CLAUDE.md's own reload; the hook is explicit about when it fires.
• Sharing auto memory between host and container (autoMemoryDirectory) — absolute paths differ per environment and a repo-relative path isn't allowed; the value doesn't cover the friction.
• A Stop / PreCompact hook that forces a status update — blocking every turn end is heavy-handed; a manual /handoff plus the CI gate is enough. (A PreCompact hook's stdout becomes instructions for the compaction summary, and a Stop hook can return additionalContext since 2.1.163; the hub needs neither.)

Verified on kokemusu (2026-08-23) — and what is still open

• Hub 23 lines / 1.5 KB; CLAUDE.md 69 → 45 lines, 14.4 → 7.8 KB; check-status.sh green locally and as the first CI step of PR #6 (ci passed in 27 s with the step).
• The hook invoked through the exact settings command string (${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh) prints hub + log + git on the host.
• UNVERIFIED: the hook firing inside the sandbox container on the next claude start (settings.json is bind-mounted; nothing suggests otherwise, but it has not been observed yet).
• UNVERIFIED: the first real /handoff run end to end (the skill text was written with the deployment, not exercised).
• UNVERIFIED: whether SessionStart output on the compact source alone keeps the agent on track in a long autonomous loop. 0.2.0 dropped the CLAUDE.md compaction instruction because current best practices no longer recommend compaction-steering lines. If an agent repeatedly loses the first next move after compaction, add a PreCompact hook that prints that line (its stdout becomes instructions for the compaction summary) rather than a CLAUDE.md line.