79002a00cb
* chore: rename npm package + bin to @opengsd/gsd-core (functional) - package.json: name @opengsd/get-shit-done-redux → @opengsd/gsd-core, bin key get-shit-done-redux → gsd-core, repository/homepage/bugs URLs - package-lock.json: regenerated (npm install --package-lock-only) - tests/**, scripts/**, bin/**, .github/**, agents/**, commands/**, get-shit-done/bin/**, get-shit-done/workflows/**: applied the 4-rule replacement (scoped npm ref, GitHub repo path, bin/clone invocations) per #505 single-source refactor Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: sweep live references to @opengsd/gsd-core Update all live documentation (README.md + translations, docs/**, CONTRIBUTING.md, VERSIONING.md, SECURITY.md, CONTEXT.md, docs/CANARY.md) to reflect the renamed package and repository. Rules applied: - @opengsd/get-shit-done-redux → @opengsd/gsd-core (scoped npm name) - open-gsd/get-shit-done-redux → open-gsd/gsd-core (GitHub repo) - GSD-redux/get-shit-done-redux → open-gsd/gsd-core (stale badge org) - bare bin/clone refs → gsd-core CHANGELOG.md, docs/adr/**, docs/RELEASE-*.md, docs/research/**, and .changeset/** are preserved byte-identical. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix: add negative lookbehind to slash-command regex in bug-2954 test The extractSlashReferences regex matched /gsd-core inside npm package URLs (@opengsd/gsd-core), producing a false /gsd:core command reference. Adding a negative lookbehind (?<![a-z]) excludes matches preceded by a letter, so only standalone /gsd-<cmd> and /gsd:<cmd> tokens are found. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * chore(#518): add changeset for package rename Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * test(#518): update package-identity expectations to the renamed coordinates The rebase regenerated the seam to @opengsd/gsd-core (bin gsd-core, repo open-gsd/gsd-core). The #498 seam tests assert deriveIdentity against the REAL package.json, so their expected literals must follow the rename. The drift-lint unit test is left as-is — its SEAM is a self-consistent fixture and its stale-literal detection cases would shift if altered; the live-repo scan in it already passes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
118 lines
3.3 KiB
Markdown
118 lines
3.3 KiB
Markdown
# 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
|
|
|
|
1. The statusline hook writes context metrics to `/tmp/claude-ctx-{session_id}.json`
|
|
2. After each tool use, the context monitor reads these metrics
|
|
3. When remaining context drops below thresholds, it injects a warning as `additionalContext`
|
|
4. 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:
|
|
|
|
```json
|
|
{
|
|
"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 automatically registered during `npx @opengsd/gsd-core` installation:
|
|
|
|
- **Statusline** (writes bridge file): Registered as `statusLine` in settings.json
|
|
- **Context Monitor** (reads bridge file): Registered as `PostToolUse` hook in settings.json (`AfterTool` for Gemini)
|
|
|
|
Manual registration should use the absolute Node executable path that ran the installer. On Windows PowerShell, prefix the command with `&` when that executable path is quoted.
|
|
|
|
Manual registration in `~/.claude/settings.json` (Claude Code):
|
|
|
|
```json
|
|
{
|
|
"statusLine": {
|
|
"type": "command",
|
|
"command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-statusline.js\""
|
|
},
|
|
"hooks": {
|
|
"PostToolUse": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "\"/usr/local/bin/node\" \"/Users/me/.claude/hooks/gsd-context-monitor.js\""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
For Gemini CLI (`~/.gemini/settings.json`), use `AfterTool` instead of `PostToolUse`:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"AfterTool": [
|
|
{
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "& \"C:/Program Files/nodejs/node.exe\" \"C:/Users/me/.gemini/hooks/gsd-context-monitor.js\""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
## 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)
|