compaction-trigger
Requests a session compaction when the live context passes a token threshold, so verbatim compaction plugins run near the working ceiling instead of at the…
new
Requests a session compaction when the live context passes a token threshold, so verbatim compaction plugins run near the working ceiling instead of at the…
cc-settings gives Claude Code and Codex the Darkroom engineering team's standards, task workflows, safety checks, and proof gates. One installer makes a new machine behave like the rest of the team without replacing personal configuration that cc-settings does not own.
The practical effect is simple: "fix this bug" gets a cause-first debugging workflow, "review my changes" stays read-only, and "ship it" must prove the real build and tests before anything is published.
New here? Install it (5 minutes), run one read-only task, then learn the daily loop. That is enough to get most of the value. Everything after that section is reference you can come back to.
Install and authenticate Claude Code, Codex CLI, or both. cc-settings configures those products; it does not install a subscription or account.
Any platform (Node 18+):
npx darkroom-settingsEvery installer flag works: npx darkroom-settings --light --auto-update=on. bunx darkroom-settings is equivalent. The npm package is only a downloader; the configuration always installs from this repository's pinned GitHub origin.
macOS or Linux, without Node:
curl -fsSL https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.sh | bashFlags go after -s --. Every setup.sh flag works remotely, with no clone or download needed:
curl -fsSL https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.sh | bash -s -- --light --auto-update=onWindows PowerShell:
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.ps1 | iex"To pass flags remotely on Windows, invoke the downloaded script as a script block:
powershell -ExecutionPolicy Bypass -c "& ([scriptblock]::Create((irm https://raw.githubusercontent.com/darkroomengineering/cc-settings/main/setup.ps1))) --light"The default target installs both products when codex is on PATH, and Claude Code only otherwise. --light installs a minimal beginner tier; re-run without it to get the full setup. Clone the repository only when you want a source checkout you own:
git clone https://github.com/darkroomengineering/cc-settings.git
cd cc-settings
bash setup.sh --target=both --dry-run
bash setup.sh --target=bothReview all requirements, tiers, system changes, prompts, managed paths, and undo behavior in the installation reference.
Restart every selected product. In Codex full installs, open /hooks and review the installed hooks once. Claude users can inspect the installed user-scope configuration from any directory:
bun ~/.claude/src/scripts/whats-on.tsThat report shows what is installed and shaping Claude user scope. It does not identify which skill handled a previous prompt or fully resolve project overrides.
Open a repository and say:
Explain where this project's configuration is loaded. Read only. Cite the files and lines.The result should name its read-only scope, cite evidence, and leave the working tree unchanged. Your first session shows the expected output, background behavior, follow-up, and recovery.
You do not need to memorize commands. Describe the outcome in plain language and cc-settings picks the matching workflow (a "skill"). Type the skill name only when you want to force a specific one: /name in Claude Code, $name in Codex.
Most days are some path through these steps:
| Step | Say something like | Or pin | What you get back |
|---|---|---|---|
| Understand | "how does checkout work here?" | /explore | A read-only map with file and line citations |
| Fix | "the login redirect loops on Safari" | /fix | The named cause, a reproduction, the smallest fix, and the tests that prove it |
| Build | "add a stats dashboard to the admin page" | /build | A GO/NO-GO check, a plan, the implementation, tests, and a review |
| Check | "review my changes" | /review | Findings on the current diff by severity, with no edits |
| Prove | "is this review-ready?" | /proof-of-work | The project's real typecheck, tests, lint, and a screenshot for UI work |
| Ship | "ship it" | /ship | A pushed branch, a PR in the house format, and CI watched until it settles |
| Pause | "done for today" | /handoff | Saved state; "continue where we left off" resumes it in a new session |
Claude Code also has a built-in /review. When you want the cc-settings one, say "run the cc-settings local pre-commit review" or pick it from the skill picker.
Big tasks split themselves. Work that spans several files, a long chain of tool calls, or security-sensitive code gets handed to focused agents (explore, implement, test, review, security) that run in the background and report back. You can keep talking in the main conversation while they work.
Every workflow for every situation, including audits, triage of a client repo, and adversarial verification, is in the manual. The skill guide says what each one can change and when it stops to ask.
cc-settings brings the team standards to every repository. Each project can add its own instructions on top.
/dr-init. It creates the project from the satus or novus starter. The native /init is a different command that only writes a CLAUDE.md.AGENTS.md at the project root. Claude Code and Codex both read it. Good content is what an agent cannot learn from the code: the commands to run, the environments, the traps, and the decisions that look wrong but are deliberate.CLAUDE.md: say "migrate to agents.md" or run /cc migrate. Claude Code ignores AGENTS.md while a CLAUDE.md exists, so the two drift apart. The session banner tells you when a project needs this./handoff posts progress to it, so agents read the issue and update it as they go.Small habits make the biggest difference in how well sessions go:
/clear between unrelated tasks. Long, mixed sessions get slower, cost more, and lose track of details./handoff at the end of a day or a long session; /checkpoint before a risky refactor or migration, so you can roll back./effort high or /effort xhigh for hard debugging, audits, or migrations, or add ultrathink to a single message./poke-holes) sends independent agents to find and disprove problems. Asking "what could go wrong?" before you commit to a plan gets a risk review.whats-on.ts shows what is installed and active; troubleshooting covers hook warnings and install health.cc-settings improves when people feed back what they learn. There are three levels, from quickest to most involved:
/share-learning. It lands in the shared team-knowledge repository, and every machine sees it right before the command or file edit it applies to./harvest. It proposes a skill, rule, or team note built from what actually happened./retro reports what you shipped, how sessions went, and quality trends, and shows which guardrails fired and whether they helped.To change cc-settings itself, clone it and read the maintainer docs. The short version:
config/ as fragments that the installer merges into ~/.claude/settings.json. Edit the fragments, never the installed file.evals/; see skill authoring.bun test, bun run typecheck, and bun run lint before pushing./cc update in a session, or re-run the install command. Restart the product afterwards.--auto-update=on to the install command for a daily check at 10:00 local time. --auto-update=off removes it.npx darkroom-settings --status reports installed versus packaged state.bun src/setup.ts --rollback from a checkout restores the newest backup. The installation reference covers uninstall.A fresh Claude Code or Codex install is a capable general assistant with no memory of how this team works. cc-settings installs that memory, plus the checks that make "done" mean the same thing on every machine. The same request behaves differently once it is installed:
| You say | Vanilla Claude Code or Codex | With cc-settings |
|---|---|---|
| "Fix this bug" | Edits the first plausible cause and reports done | Reproduces first, names the cause before the fix, keeps the change inside the bug's scope, runs the real tests afterwards |
| "Review my changes" | May start editing while it reviews | Stays read-only, checks the diff against the team checklist, reports by severity |
| "Ship it" | Pushes whatever is in the tree | Runs the repository's own type check, build, tests, and lint, opens the PR in the house style, watches CI |
| "Build a header component" | Writes a component its way | Uses the Darkroom starter conventions: CSS modules, no manual memoization, the accessibility and performance rules |
git push --force origin main | Runs it | A permission rule denies it; a hook blocks rm -rf and other destructive commands before they execute |
bun drizzle-kit push on a project with data | Runs it | A hook surfaces the team note that this command can truncate production tables |
| Working in a large repo | Reads files one at a time | Delegates to focused agents for exploration, implementation, testing, review, and security, on cheaper models |
| Something worth remembering for the team | Lost when the session ends | /share-learning posts it to the shared knowledge repo, and later sessions on every machine are reminded of it when it applies |
~/.claude/CLAUDE.md. Twelve topic rules (TypeScript, React, performance, accessibility, security, git, motion, style) load only for the files they cover, and six stack profiles (Next.js, React Router, React Native, Tauri, WebGL, orchestration) add the specifics of each starter./name in Claude and $name in Codex: fix, build, review, ship, audit, poke-holes, handoff, and the rest. The skill guide lists what each one changes and when it asks./hooks./share-learning and surface automatically before the command or file edit they apply to.Your login and subscription, your permission mode, your personal memory, and any setting the installer does not own. Put your own global instructions in ~/.claude/personal.md: the installed CLAUDE.md imports it, and setup never replaces it (Claude Code only). It does not grant GitHub, Figma, or browser access, and it does not make the two products identical: see Claude Code and Codex for what each host can and cannot do.
| Goal | Start here |
|---|---|
| Find the workflow for a specific outcome | Manual |
| Choose a skill and understand what it can change | Skill guide |
| Prove the setup with a harmless first task | Your first session |
| Install safely and understand every side effect | Installation |
| Compare Claude Code and Codex behavior | Host parity |
| Diagnose an installed setup | Troubleshooting |
| Understand the whole system | System overview |
| Understand why advice becomes an enforced gate | The flow |
| Browse every user, concept, maintainer, and history document | Documentation index |
Written standards, workflows, and proof gates reduce per-machine drift. They also make the codebase more legible to humans: the conventions an agent needs are the same debt the team owes its engineers.
darkroom.engineering | MIT
hooks/trigger.ts 151 lines1// compaction-trigger — a small function-hook plugin that asks Claude Code to
2// compact the session once the live context passes a token threshold, tied to
3// cc-settings' ~150K working-context ceiling rather than upstream verbatim
4// compaction plugins' percentage-of-window trigger (which fires far too often
5// on a 200K+ window model). Before requesting, it copies a rotated
6// TYPESAFE_API_KEY from settings into the process env so the verbatim plugin
7// does not 401 for the rest of the session. See docs/hooks-reference.md
8// "Function hooks (early access)".
9//
10// Deliberately has NO runtime imports: `import type` erases at compile time,
11// so this module can be unit-tested under `bun test` without resolving the
12// 'claude-code' module specifier (it exists only as ambient types, generated
13// by `/plugin-types`, never published to a registry bun could fetch).
14import type { On, PluginOptions, Register, TurnCompleteInput } from "claude-code";
15
16const DEFAULTS = {
17 compactAtTokens: 150_000,
18 minTurnsBetween: 3,
19} as const;
20
21export type TriggerConfig = {
22 compactAtTokens: number;
23 minTurnsBetween: number;
24};
25
26function optionNumber(options: PluginOptions, key: string, fallback: number): number {
27 const value = options[key];
28 return typeof value === "number" && Number.isFinite(value) ? value : fallback;
29}
30
31/** Reads the plugin's `userConfig` values; anything missing takes the defaults. */
32export function resolveTriggerConfig(options: PluginOptions): TriggerConfig {
33 return {
34 compactAtTokens: optionNumber(options, "compactAtTokens", DEFAULTS.compactAtTokens),
35 minTurnsBetween: optionNumber(options, "minTurnsBetween", DEFAULTS.minTurnsBetween),
36 };
37}
38
39export type ShouldRequestInput = {
40 /** `context.tokens` from `$.session.usage()`; absent before the first API
41 * response of a live window. */
42 tokens: number | undefined;
43 compactAtTokens: number;
44 /** Turns elapsed (inclusive of the current one) since the last compaction
45 * this plugin requested. */
46 turnsSince: number;
47 minTurnsBetween: number;
48 /** True while a compaction this plugin requested is still in flight. */
49 compacting: boolean;
50};
51
52/**
53 * Pure decision: should `turn.complete` ask `$.session.compact()` to run now?
54 * No engine access, so it is exercised directly in tests without a fake `$`.
55 */
56export function shouldRequest(input: ShouldRequestInput): boolean {
57 if (input.compacting) return false;
58 if (input.turnsSince < input.minTurnsBetween) return false;
59 if (typeof input.tokens !== "number") return false;
60 return input.tokens >= input.compactAtTokens;
61}
62
63/** The TypeSafe key the settings `env` block holds, or undefined. */
64export function settingsTypesafeKey(settings: Readonly<Record<string, unknown>>): string | undefined {
65 const env = settings.env;
66 if (!env || typeof env !== "object") return undefined;
67 const value = (env as Record<string, unknown>).TYPESAFE_API_KEY;
68 return typeof value === "string" && value.length > 0 ? value : undefined;
69}
70
71/**
72 * Copies a rotated TypeSafe key from settings into the process env before a
73 * compaction. The verbatim plugin reads `$.env.get("TYPESAFE_API_KEY")` before
74 * it reads settings, so a session started before a key rotation kept sending
75 * the stale key and fell back to the built-in summary on every 401.
76 * Returns true when the env was updated.
77 */
78export async function syncTypesafeKey($: {
79 env: { get: (name: string) => Promise<string | undefined>; set: (name: string, value: string | undefined) => Promise<void> };
80 settings: { read: () => Promise<Readonly<Record<string, unknown>>> };
81}): Promise<boolean> {
82 const fromSettings = settingsTypesafeKey(await $.settings.read());
83 if (!fromSettings) return false;
84 const fromEnv = await $.env.get("TYPESAFE_API_KEY");
85 if (fromEnv === fromSettings) return false;
86 await $.env.set("TYPESAFE_API_KEY", fromSettings);
87 return true;
88}
89
90/**
91 * True for fast-jev-compaction's per-item decision dump (`decisions: t1:Bash:
92 * drop_call/call=0.30/result=0.18 ...`, chunked as `decisions (2/3): ...`).
93 * The plugin has no option to silence it; its summary line (`kept N/M
94 * messages ...`) is the one worth the transcript row.
95 */
96export function isDecisionDump(text: string): boolean {
97 return /^decisions(?: \(\d+\/\d+\))?: /.test(text);
98}
99
100// $ is never bound to a name: `claude plugin validate` requires every call on
101// it to read as `$.noun.event(...)` at the call site, so every use below goes
102// straight through a `$` parameter.
103export const register: Register = (on: On, options: PluginOptions) => {
104 const config = resolveTriggerConfig(options);
105 let compacting = false;
106 let turnsSinceCompaction = 0;
107
108 // A `$.ui.log` from a plugin seated beneath this one is a dispatch this
109 // hook sees; rewriting `to` keeps the line in the debug log and off the
110 // transcript. Only the decision dump is touched.
111 on("ui.log", ($, event, next) => (isDecisionDump(event.text) ? next({ ...event, to: "debug" }) : next(event)));
112
113 on("turn.complete", async ($, event: TurnCompleteInput, next) => {
114 turnsSinceCompaction += 1;
115 try {
116 const { context } = await $.session.usage();
117 const request = shouldRequest({
118 tokens: context.tokens,
119 compactAtTokens: config.compactAtTokens,
120 turnsSince: turnsSinceCompaction,
121 minTurnsBetween: config.minTurnsBetween,
122 compacting,
123 });
124 if (request) {
125 compacting = true;
126 try {
127 if (await syncTypesafeKey($)) $.ui.log("compaction-trigger: refreshed TYPESAFE_API_KEY from settings");
128 } catch (error) {
129 $.ui.log(
130 `compaction-trigger: key sync skipped (${error instanceof Error ? error.message : String(error)})`,
131 );
132 }
133 const result = await $.session.compact();
134 if (result.skip) {
135 $.ui.log(`compaction-trigger: skipped: ${result.skip}`);
136 } else {
137 $.ui.log(`compaction-trigger: requested at ${context.tokens} tokens`);
138 }
139 turnsSinceCompaction = 0;
140 }
141 } catch (error) {
142 $.ui.log(
143 `compaction-trigger: skipped (${error instanceof Error ? error.message : String(error)})`,
144 );
145 } finally {
146 compacting = false;
147 }
148 return next(event);
149 });
150};
151