From 94cd9b8e181964fc2bd472c872075e0475da736a Mon Sep 17 00:00:00 2001 From: Gabriel Tavares Date: Sat, 23 May 2026 20:46:23 +0100 Subject: [PATCH 1/2] =?UTF-8?q?claude-code-hermit:=20less=20aggressive=20c?= =?UTF-8?q?ompact=20defaults=20(CLAUDE=5FAUTOCOMPACT=5FPCT=5FOVERRIDE=2050?= =?UTF-8?q?=E2=86=9265,=20COMPACT=5FTHRESHOLD=2050=E2=86=9275)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Default auto-compact was firing at 50% context — well before the quality-degradation zone (~73%) — discarding usable context without benefit. Bumps the trigger to 65%, conservative move that stays well under the upstream ~83% clamp ceiling. COMPACT_THRESHOLD was firing the tool-call-based /compact nudge mid- session for any non-trivial work. Bumps to 75; the real signal (context_usage > 60% in suggest-compact.js) continues to drive substantive nudges. CHANGELOG [Unreleased] adds executable Upgrade Instructions for hermit-evolve with an only-if-still-50 guard so operators who tuned to a custom value keep their choice. --- plugins/claude-code-hermit/CHANGELOG.md | 18 ++++++++++++++++++ plugins/claude-code-hermit/docs/always-on.md | 2 +- .../claude-code-hermit/docs/architecture.md | 4 ++-- .../docs/config-reference.md | 8 ++++---- .../claude-code-hermit/docs/troubleshooting.md | 2 +- .../claude-code-hermit/scripts/hermit-start.py | 4 ++-- .../scripts/suggest-compact.js | 2 +- .../skills/hermit-evolve/SKILL.md | 2 +- .../skills/hermit-settings/SKILL.md | 8 ++++---- .../state-templates/config.json.template | 4 ++-- 10 files changed, 36 insertions(+), 18 deletions(-) diff --git a/plugins/claude-code-hermit/CHANGELOG.md b/plugins/claude-code-hermit/CHANGELOG.md index c17c009c..8ef80c78 100644 --- a/plugins/claude-code-hermit/CHANGELOG.md +++ b/plugins/claude-code-hermit/CHANGELOG.md @@ -1,5 +1,23 @@ # Changelog +## [Unreleased] + +### Changed + +- **env defaults: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` bumped 50 → 65** — auto-compact was firing well before the quality-degradation zone (~73%); 65 reduces premature context loss while staying conservative. +- **env defaults: `COMPACT_THRESHOLD` bumped 50 → 75** — the tool-call-based nudge was firing mid-session for any non-trivial work; 75 quiets the fallback path while `context_usage > 60%` continues to drive real nudges in `suggest-compact.js`. + +### Upgrade Instructions + +1. Read `.claude-code-hermit/config.json`. + - If `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE == "50"`, set it to `"65"`. If absent or any other value, leave it alone. + - If `env.COMPACT_THRESHOLD == "50"`, set it to `"75"`. If absent or any other value, leave it alone. + - Write the file back only if either key changed. +2. Read `.claude/settings.local.json` (or `.claude/settings.json` per `hatch_target`). Apply the same only-if-still-50 guard for both keys; update to `"65"` / `"75"` respectively. Otherwise leave them alone. +3. Report to the operator, one line per key: + - "Bumped `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 50 → 65 — auto-compact triggers later." or "Left `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` at `` (custom override preserved)." + - "Bumped `COMPACT_THRESHOLD` 50 → 75 — fewer mid-session nudges." or "Left `COMPACT_THRESHOLD` at `` (custom override preserved)." + ## [1.1.3] - 2026-05-23 ### Fixed diff --git a/plugins/claude-code-hermit/docs/always-on.md b/plugins/claude-code-hermit/docs/always-on.md index c80f1f54..84b56676 100644 --- a/plugins/claude-code-hermit/docs/always-on.md +++ b/plugins/claude-code-hermit/docs/always-on.md @@ -218,7 +218,7 @@ Container restarts trigger recovery automatically: | Setting | Value | Effect | | ---------------------------------- | ------- | -------------------------------- | -| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `50` | Compacts at 50% context | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `65` | Compacts at 65% context | | `MAX_THINKING_TOKENS` | `10000` | Prevents runaway reasoning costs | Adjust with `/hermit-settings env`. diff --git a/plugins/claude-code-hermit/docs/architecture.md b/plugins/claude-code-hermit/docs/architecture.md index dc9914df..44054976 100644 --- a/plugins/claude-code-hermit/docs/architecture.md +++ b/plugins/claude-code-hermit/docs/architecture.md @@ -311,10 +311,10 @@ config.json "env" → hermit-start.py → .claude/settings.local.json "env" | Field | Value | Purpose | | --------------------------------- | ---------- | -------------------------------------------------- | -| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `50` | Auto-compact at 50% context | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `65` | Auto-compact at 65% context | | `MAX_THINKING_TOKENS` | `10000` | Cap thinking budget | | `AGENT_HOOK_PROFILE` | `standard` | Active hook profile | -| `COMPACT_THRESHOLD` | `50` | Compaction suggestion threshold | +| `COMPACT_THRESHOLD` | `75` | Compaction suggestion threshold | | `DISCORD_STATE_DIR` | (derived) | Derived from `channels.discord.state_dir` at boot | | `TELEGRAM_STATE_DIR` | (derived) | Derived from `channels.telegram.state_dir` at boot | diff --git a/plugins/claude-code-hermit/docs/config-reference.md b/plugins/claude-code-hermit/docs/config-reference.md index e9733615..3d65b216 100644 --- a/plugins/claude-code-hermit/docs/config-reference.md +++ b/plugins/claude-code-hermit/docs/config-reference.md @@ -35,8 +35,8 @@ Written to `.claude/settings.local.json` at boot by `hermit-start`. Exported to | Key | Default | Purpose | |-----|---------|---------| | `AGENT_HOOK_PROFILE` | `"standard"` | Hook profile: `minimal`, `standard`, `strict`. Protected in always-on mode. | -| `COMPACT_THRESHOLD` | `"50"` | Context % threshold for compact suggestion. | -| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `"50"` | Auto-compact at this % of context window. | +| `COMPACT_THRESHOLD` | `"75"` | Tool-call-count threshold for compact suggestion (fallback when `context_usage` is unavailable). | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `"65"` | Auto-compact at this % of context window. | | `MAX_THINKING_TOKENS` | `"10000"` | Cap on thinking tokens per turn. | Modify with `/hermit-settings env`. @@ -280,8 +280,8 @@ A realistic `config.json` for an always-on Docker hermit with Discord: ], "env": { "AGENT_HOOK_PROFILE": "strict", - "COMPACT_THRESHOLD": "50", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", + "COMPACT_THRESHOLD": "75", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "65", "MAX_THINKING_TOKENS": "10000" }, "scheduled_checks": [ diff --git a/plugins/claude-code-hermit/docs/troubleshooting.md b/plugins/claude-code-hermit/docs/troubleshooting.md index cccbbb85..01618470 100644 --- a/plugins/claude-code-hermit/docs/troubleshooting.md +++ b/plugins/claude-code-hermit/docs/troubleshooting.md @@ -63,7 +63,7 @@ Scheduled checks run during idle reflection via `reflect`. If configured checks ## Costs Unexpectedly High -- Check `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` in `config.json` `env` (default 50). Adjust with `/hermit-settings env`. +- Check `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` in `config.json` `env` (default 65). Adjust with `/hermit-settings env`. - Check heartbeat interval — 5m with Opus is expensive. Default is 2h; use 15m-30m only if you need faster monitoring. - Check if watches are running with short intervals (`/claude-code-hermit:watch stop`). - Review SHELL.md size — bloated files cost tokens on every read. diff --git a/plugins/claude-code-hermit/scripts/hermit-start.py b/plugins/claude-code-hermit/scripts/hermit-start.py index bcc16d88..44af01fe 100755 --- a/plugins/claude-code-hermit/scripts/hermit-start.py +++ b/plugins/claude-code-hermit/scripts/hermit-start.py @@ -54,8 +54,8 @@ 'monitors': [], 'env': { 'AGENT_HOOK_PROFILE': 'standard', - 'COMPACT_THRESHOLD': '50', - 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE': '50', + 'COMPACT_THRESHOLD': '75', + 'CLAUDE_AUTOCOMPACT_PCT_OVERRIDE': '65', 'MAX_THINKING_TOKENS': '10000', }, 'boot_skill': None, diff --git a/plugins/claude-code-hermit/scripts/suggest-compact.js b/plugins/claude-code-hermit/scripts/suggest-compact.js index a268a9b3..7d7e29fc 100644 --- a/plugins/claude-code-hermit/scripts/suggest-compact.js +++ b/plugins/claude-code-hermit/scripts/suggest-compact.js @@ -10,7 +10,7 @@ const path = require('path'); const os = require('os'); const MAX_STDIN = 1024 * 1024; // 1MB safety limit -const COMPACT_THRESHOLD = parseInt(process.env.COMPACT_THRESHOLD || '50', 10) || 50; +const COMPACT_THRESHOLD = parseInt(process.env.COMPACT_THRESHOLD || '75', 10) || 75; const SUBSEQUENT_INTERVAL = 25; const MAX_COUNTER = 1_000_000; const CONTEXT_USAGE_THRESHOLD = 0.6; // 60% diff --git a/plugins/claude-code-hermit/skills/hermit-evolve/SKILL.md b/plugins/claude-code-hermit/skills/hermit-evolve/SKILL.md index 52bf927a..c216c4e2 100644 --- a/plugins/claude-code-hermit/skills/hermit-evolve/SKILL.md +++ b/plugins/claude-code-hermit/skills/hermit-evolve/SKILL.md @@ -93,7 +93,7 @@ For each new key, check the table below. If the key is interactive, ask the oper - `heartbeat.waiting_timeout` (0.3.0): `null` | `heartbeat.stale_threshold` (0.0.9): `"2h"` - `idle_budget` (0.0.9): `"$0.50"` | `routines` (0.0.9): `[]` - `scheduled_checks` (0.3.1): `[]` -- `env` (0.0.7): `{"AGENT_HOOK_PROFILE":"standard","COMPACT_THRESHOLD":"50","CLAUDE_AUTOCOMPACT_PCT_OVERRIDE":"50","MAX_THINKING_TOKENS":"10000"}` +- `env` (0.0.7): `{"AGENT_HOOK_PROFILE":"standard","COMPACT_THRESHOLD":"75","CLAUDE_AUTOCOMPACT_PCT_OVERRIDE":"65","MAX_THINKING_TOKENS":"10000"}` - `docker` (0.0.7): `{"packages":[],"recommended_plugins":[]}` - `compact` (0.0.7): `{"monitoring_threshold":30,"monitoring_keep":20,"summary_threshold":30,"summary_keep":15}` - `knowledge` (0.4.0): `{"raw_retention_days":14,"compiled_budget_chars":1000,"working_set_warn":20}` diff --git a/plugins/claude-code-hermit/skills/hermit-settings/SKILL.md b/plugins/claude-code-hermit/skills/hermit-settings/SKILL.md index e8b20696..e6a500e8 100644 --- a/plugins/claude-code-hermit/skills/hermit-settings/SKILL.md +++ b/plugins/claude-code-hermit/skills/hermit-settings/SKILL.md @@ -79,8 +79,8 @@ Compaction: Environment (env): AGENT_HOOK_PROFILE standard - COMPACT_THRESHOLD 50 - CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 50 + COMPACT_THRESHOLD 75 + CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 65 MAX_THINKING_TOKENS 10000 → run: /claude-code-hermit:hermit-settings env @@ -258,8 +258,8 @@ Update `permission_mode` in config.json. Environment Variables (config.json env → .claude/settings.local.json) AGENT_HOOK_PROFILE standard - COMPACT_THRESHOLD 50 - CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 50 + COMPACT_THRESHOLD 75 + CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 65 MAX_THINKING_TOKENS 10000 ``` - **Protected keys** that cannot be changed via this command: `AGENT_HOOK_PROFILE`. These are managed by the boot script and docker-setup. If the operator tries to set one, respond: "AGENT_HOOK_PROFILE is managed by the boot script (standard for interactive, strict for Docker). To change it, edit config.json directly — the boot script validates on next start." diff --git a/plugins/claude-code-hermit/state-templates/config.json.template b/plugins/claude-code-hermit/state-templates/config.json.template index 0dd4c134..41f9aee6 100644 --- a/plugins/claude-code-hermit/state-templates/config.json.template +++ b/plugins/claude-code-hermit/state-templates/config.json.template @@ -26,8 +26,8 @@ "monitors": [], "env": { "AGENT_HOOK_PROFILE": "standard", - "COMPACT_THRESHOLD": "50", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", + "COMPACT_THRESHOLD": "75", + "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "65", "MAX_THINKING_TOKENS": "10000" }, "boot_skill": null, From 6db8f3a1884fd846c88a1c08d283db13500c6884 Mon Sep 17 00:00:00 2001 From: Gabriel Tavares Date: Sat, 23 May 2026 21:03:33 +0100 Subject: [PATCH 2/2] claude-code-hermit: surface COMPACT_THRESHOLD doc-fix in CHANGELOG, tighten architecture.md cell MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR review pointed out the `config-reference.md` description correction from the previous commit was unmentioned in CHANGELOG, and architecture.md still called the threshold a generic "Compaction suggestion threshold." Adds a third `### Changed` bullet flagging the description correction, and tightens the architecture.md env-defaults table cell to "Tool-call-count fallback for compact suggestion" — matching the now-corrected config-reference entry. --- plugins/claude-code-hermit/CHANGELOG.md | 1 + plugins/claude-code-hermit/docs/architecture.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/claude-code-hermit/CHANGELOG.md b/plugins/claude-code-hermit/CHANGELOG.md index 8ef80c78..1a37be23 100644 --- a/plugins/claude-code-hermit/CHANGELOG.md +++ b/plugins/claude-code-hermit/CHANGELOG.md @@ -6,6 +6,7 @@ - **env defaults: `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` bumped 50 → 65** — auto-compact was firing well before the quality-degradation zone (~73%); 65 reduces premature context loss while staying conservative. - **env defaults: `COMPACT_THRESHOLD` bumped 50 → 75** — the tool-call-based nudge was firing mid-session for any non-trivial work; 75 quiets the fallback path while `context_usage > 60%` continues to drive real nudges in `suggest-compact.js`. +- **docs: `COMPACT_THRESHOLD` description corrected to tool-call-count fallback** — config-reference previously called it a "context % threshold," which contradicted `suggest-compact.js`. Now matches the code: tool-call counter consulted only when `context_usage` is unavailable. ### Upgrade Instructions diff --git a/plugins/claude-code-hermit/docs/architecture.md b/plugins/claude-code-hermit/docs/architecture.md index 44054976..60cc5763 100644 --- a/plugins/claude-code-hermit/docs/architecture.md +++ b/plugins/claude-code-hermit/docs/architecture.md @@ -314,7 +314,7 @@ config.json "env" → hermit-start.py → .claude/settings.local.json "env" | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | `65` | Auto-compact at 65% context | | `MAX_THINKING_TOKENS` | `10000` | Cap thinking budget | | `AGENT_HOOK_PROFILE` | `standard` | Active hook profile | -| `COMPACT_THRESHOLD` | `75` | Compaction suggestion threshold | +| `COMPACT_THRESHOLD` | `75` | Tool-call-count fallback for compact suggestion | | `DISCORD_STATE_DIR` | (derived) | Derived from `channels.discord.state_dir` at boot | | `TELEGRAM_STATE_DIR` | (derived) | Derived from `channels.telegram.state_dir` at boot |