3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
2.8 KiB
Context Window Monitor
A post-tool hook (PostToolUse for Claude Code, AfterTool for Gemini CLI) that warns the agent when context window usage is high.
Problem
The statusline shows context usage to the user, but the agent has no awareness of context limits. When context runs low, the agent continues working until it hits the wall — potentially mid-task with no state saved.
How It Works
- The statusline hook writes context metrics to
/tmp/claude-ctx-{session_id}.json - After each tool use, the context monitor reads these metrics
- When remaining context drops below thresholds, it injects a warning as
additionalContext - The agent receives the warning in its conversation and can act accordingly
Thresholds
| Level | Remaining | Agent Behavior |
|---|---|---|
| Normal | > 35% | No warning |
| WARNING | <= 35% | Wrap up current task, avoid starting new complex work |
| CRITICAL | <= 25% | Stop immediately, save state (/gsd-pause-work) |
Debounce
To avoid spamming the agent with repeated warnings:
- First warning always fires immediately
- Subsequent warnings require 5 tool uses between them
- Severity escalation (WARNING -> CRITICAL) bypasses debounce
Architecture
Statusline Hook (gsd-statusline.js)
| writes
v
/tmp/claude-ctx-{session_id}.json
^ reads
|
Context Monitor (gsd-context-monitor.js, PostToolUse/AfterTool)
| injects
v
additionalContext -> Agent sees warning
The bridge file is a simple JSON object:
{
"session_id": "abc123",
"remaining_percentage": 28.5,
"used_pct": 71,
"timestamp": 1708200000
}
Integration with GSD
GSD's /gsd-pause-work command saves execution state. The WARNING message suggests using it. The CRITICAL message instructs immediate state save.
Setup
Both hooks are registered automatically during npx @opengsd/gsd-core installation — no manual steps are needed under normal circumstances. For hook configuration details, threshold overrides, and manual registration examples, see Configuration.
As a brief reference: the statusline hook registers as statusLine in settings.json; the context monitor (gsd-context-monitor.js) registers as a PostToolUse hook (or AfterTool for Gemini CLI). Both entries use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix quoted executable paths with &.
Safety
- The hook wraps everything in try/catch and exits silently on error
- It never blocks tool execution — a broken monitor should not break the agent's workflow
- Stale metrics (older than 60s) are ignored
- Missing bridge files are handled gracefully (subagents, fresh sessions)