opinionated-defaults

# Opinionated Defaults

A fixed, portable bundle of four `settings.json` tweaks — no homelab paths, no
personal branding, safe to hand to anyone running Claude Code. Applying it is
a **merge**, never a replace: read the target file first, keep everything
already there, and only touch the four keys below.

## The bundle

| Key | Value | Why |
| --- | --- | --- |
| `autoCompactEnabled` | `true` | Turns on auto-compact at all. |
| `autoCompactWindow` | computed — see below | Compact fires once conversation tokens reach this count. Default Claude Code behavior waits until the context is nearly full (~97% on some models); this bundle triggers around 30% instead, trading more compaction for a session that never feels close to the edge. |
| `fileCheckpointingEnabled` | `true` | Snapshots files before edits so `/rewind` can restore them. Pure safety net, no downside. |
| `precomputeCompactionEnabled` | `true` | Computes the compaction summary in the background before it's needed, so hitting the threshold doesn't stall the session. Only has an effect when `autoCompactEnabled` is on. |
| `terminalProgressBarEnabled` | `true` | Emits OSC 9;4 taskbar/dock progress during long operations. Harmless where the terminal doesn't support it. |

## Computing `autoCompactWindow`

This is the one value that isn't a flat constant — it's a token count, not a
percentage, and `settings.json` clamps it to `[100000, 1000000]`. To hit
"~30% of context":

1. Figure out the target's actual context window. In order of preference:
   - Ask the user directly if it's not obvious ("Are you on the 1M-token
     context, or the standard 200K window?"). Direct Anthropic API access on
     Sonnet 5 defaults to the native 1M window; most other setups (Console,
     third-party providers, older/other models) are 200K unless the user has
     explicitly enabled extended context.
   - If genuinely unknown, default to the 1M assumption (see step 2) and say
     so explicitly rather than silently guessing 200K.
2. Compute `round(context_window * 0.3)`, then clamp to `[100000, 1000000]`.
   - 1M window → 300000 (clean, no clamping).
   - 200K window → raw value is 60000, below the floor, so the clamped
     result is 100000 (~50%, not 30%). Tell the user this explicitly — don't
     silently write a number that doesn't match what they asked for.
3. Write the clamped integer to `autoCompactWindow`.

## Applying it

1. **Ask which file** — global (`~/.claude/settings.json`, applies to every
   project) or project (`.claude/settings.json`, this repo only). Default to
   global unless the user says otherwise; that's what this bundle is for.
2. **Read the target file first.** If it doesn't exist, create it fresh with
   just this bundle. If it exists, merge — do not touch any other key,
   including if the user has already customized `autoCompactWindow` to
   something else (ask before overwriting a value that looks intentional
   rather than default/absent).
3. **Write the four keys**, using the computed `autoCompactWindow` from
   above.
4. **Validate**: `jq -e '.autoCompactEnabled, .autoCompactWindow, .fileCheckpointingEnabled, .precomputeCompactionEnabled, .terminalProgressBarEnabled' <target-file>` — all five should print without error.
5. **Report back** what was set and, if the context window was assumed
   rather than confirmed, flag that assumption so the user can correct it
   later with `/autocompact <value>` if their actual window differs.

## Idempotency

Safe to re-run. If all four keys are already present with these exact
values, say so and make no changes rather than rewriting the file.