context-loop

context-loop

Nudge /compact on 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 Stop, computes fill % from the last usage block, and when fill crosses a threshold injects an advisory additionalContext line nudging the agent to run /compact on its next turn. Every fire and the compaction that follows are recorded to a local SQLite DB for savings analytics.

That's the whole mechanism: a fill-aware, cooldown-gated, mid-chain-safe reminder to compact. It is advisory only — a Stop hook cannot force the agent to act (see ~/.claude/rules/claude-code-hook-output-semantics.md). Durable state across the compaction boundary is left to the tools that already do it well — claude-mem (cross-session observations) and the Obsidian plugin (session notes) — which context-loop does not write to; it only keeps the live conversation under the cliff.

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 timing automatic — it reminds you to compact at the right moment instead of at 95% when quality is already gone. It sits alongside the durable layer you (probably) already have, without writing to it:

• claude-mem stores cross-session observations (its own Stop summarizer).
• Obsidian stores session notes and daily logs (its own session-end save).
• context-loop keeps the live conversation under the cliff by nudging /compact; the other two independently capture the long arc.

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 + records the    │
              │  fire to SQLite.                       │
              │      │                                 │
              │      ▼ (if threshold crossed)          │
              │  emit additionalContext:               │
              │  "context at N% — run /compact"        │
              └────────────────────────────────────────┘
                                │
                                ▼
              agent runs /compact on its next turn;
              the next Stop detects the token drop and
              records the compaction outcome.

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.

/compact is best-effort