context-loop

context-loop

Auto-checkpoint and /compact your Claude Code session before context fill kills response quality.

Once a Claude Code conversation crosses ~35–40% of the model's context window, response quality, tool-call accuracy, and per-token cost all degrade. context-loop watches the live transcript on every assistant turn and, when fill crosses a threshold, nudges the agent to:

1. dispatch a clean-context summarizer subagent that produces a structured Live State brief,
2. write the brief to durable storage (Obsidian + a checkpoint file claude-mem can pick up),
3. run /compact, and
4. re-post the brief as a user message so the post-compact agent sees it intact.

The live conversation stays under the degradation cliff. Nothing important is lost — claude-mem and Obsidian hold the long arc; the brief carries the active task across compaction.

Why

Claude Code has built-in auto-compact at ~95% fill, but by then quality is already wrecked. There is no "keep me below 40% perpetually" mechanism. Manual /compact works but you have to remember to run it, and you have to trust the summary to preserve the file paths, branches, and error strings you were actually working on.

context-loop makes the boundary automatic and the summary structured. It composes with the durable layer you (probably) already have:

• claude-mem stores cross-session observations.
• Obsidian stores session notes and daily logs.
• context-loop keeps the live conversation under the cliff by handing off cleanly to those two.

How it works

              ┌────────────── Stop event ──────────────┐
Claude Code ──┤                                        │
              │  ~/.claude/hooks/context-loop-gate.sh  │
              │      │                                 │
              │      ▼                                 │
              │  bun worker reads transcript JSONL,    │
              │  computes fill % from last `usage`     │
              │  block, applies cooldown + mid-chain   │
              │  safety, writes state.                 │
              │      │                                 │
              │      ▼ (if threshold crossed)          │
              │  emit additionalContext nudging the    │
              │  agent to invoke the `checkpoint`      │
              │  skill on its next turn.               │
              └────────────────────────────────────────┘
                                │
                                ▼
              ┌─────────── checkpoint skill ───────────┐
              │  1. dispatch clean-context subagent    │
              │  2. subagent runs `jq` projection on   │
              │     the transcript, writes Live State  │
              │  3. main agent appends brief to        │
              │     today's Obsidian daily note +      │
              │     state/checkpoints/ for claude-mem  │
              │  4. /compact (with optional steering)  │
              │  5. re-post the brief as a user        │
              │     message so it survives compaction  │
              └────────────────────────────────────────┘

Trigger: Stop hook, not PostToolUse

PostToolUse fires dozens of times per turn — too chatty, and tool chains are unsafe compaction boundaries. Stop fires exactly once per assistant yield, which is the only moment compaction is safe.

Threshold: hybrid, two-tier

• Advisory at 35% fill — the agent is encouraged to checkpoint between major tasks.
• Escalated advisory at 50% fill — louder copy; cooldown is bypassed.

Both tiers emit hookSpecificOutput.additionalContext — purely advisory text injection. The harness cannot force the agent to act; it can only make the next-turn context include the nudge. (See ~/.claude/rules/claude-code-hook-output-semantics.md if you're tempted to dress this as "blocking" — it isn't.)

A 15-turn cooldown after a fire prevents thrash. Cooldown is keyed on the assistant message UUID at fire time, not turn count — when /compact rewrites the transcript and the marker UUID disappears, cooldown resets automatically.

Mid-chain safety

If the final assistant turn emitted tool_use blocks without matching tool_result, the gate exits silently — never advise mid-chain.

Window detection

The divisor is a dynamic variable. CONTEXT_LOOP_WINDOW, if set to a positive integer, is used verbatim — this is the authoritative override for sessions whose real window the hook can't infer (1M-beta [1m], fast-mode, model aliases, future models). With no override, it falls back to a model-name heuristic: opus → 1,000,000, everything else → 200,000.

The heuristic is a guess, not ground truth — the transcript's model field carries no window size, and a misjudged divisor produces nonsense fill (e.g. a too-small divisor reporting >100%). When in doubt, set CONTEXT_LOOP_WINDOW explicitly.

The subagent doesn't Read the JSONL