claude-code-autoconfig

CLI tool that auto-configures Claude Code for any project. One command analyzes your project, configures Claude, and shows you what it did.

Tech Stack

• Runtime: Node.js (>=18.0.0)
• Type: npm CLI package
• Entry: bin/cli.js

Commands

npm test          # Run ALL tests (full suite — see Testing Requirements below)
npm run test:box  # Run box alignment tests only
npm run test:install # Run CLI install tests only

Project Structure

• bin/cli.js — Main CLI entry point, handles bootstrap and /autoconfig launch
• .claude/commands/ — Slash command definitions (/autoconfig, /autoconfig-update, etc.)
• .claude/hooks/ — Hook scripts (format.js for JS/TS projects)
• .claude/feedback/ — Team feedback and corrections
• test/ — Test files

Publishing

npm version patch && npm publish

After publish, push the branch AND the release tag explicitly (the postversion changelog hook re-tags lightweight): git push origin main && git push origin v<x.y.z>.

Changelog is user-facing — write commits accordingly

CHANGELOG.md regenerates from commit subjects on every npm version, and the installer shows those bullets verbatim to users on upgrade (bin/update-summary.js). So:

• Subjects may stay technical, but then the commit body MUST carry a plain-language trailer the changelog uses instead: Changelog: More reliable 'awaiting your reply' tab indicator. Write it for a CCA user, not a maintainer — name the visible outcome, never internals (no hook/regex/TDZ/function names).
• Changelog: none (or skip) hides an internal-only commit from the changelog.
• Keep the feat:/fix: conventional prefix on the subject — it drives the summary's "New features" vs "Fixes & improvements" grouping.
• Already-pushed commits can't be reworded in git; add a row to OVERRIDES in scripts/generate-changelog.js instead (value null drops the bullet). New work never uses OVERRIDES — author the trailer.

Team Feedback

@.claude/feedback/FEEDBACK.md

Discoveries

Publishing to npm — bypass-2FA token flow (web-auth publish is a DEAD END)

(Supersedes the auto-generated "## Publishing" one-liner above.)

• Primary flow (agent can do it end-to-end): npm test + npm version patch (commit + tag) → npm whoami to verify the Bypass-2FA granular token in ~/.npmrc still authenticates → plain npm publish (works headless, no OTP) → after the + claude-code-autoconfig@<version> line, git push origin main --follow-tags. Never double-bump if the version is already bumped.
• If npm whoami returns E401, the token is dead/expired (90-day cap). The human rotates it (npmjs.com → Access Tokens → Granular → "Bypass 2FA", read-write, scoped to this package only) and pastes it into ~/.npmrc in an editor — never via a command. Stopgap without a token: npm publish --otp=<recovery-code> in the human's own terminal.
• Do NOT use npm login --auth-type=web && npm publish: login succeeds but publish still dies EOTP — the npm CLI can't route publish-time 2FA to the browser on this webauthn-only account (confirmed 2026-07-03, npm 10.9.2). Don't retry it in-agent, and don't ask for a typed TOTP (none exists). Full procedure: .claude/commands/deploy-to-npmjs.md (/deploy-to-npmjs).

Debugging Methodology — Evidence Before Solutions

NEVER jump to a fix based on assumptions. When investigating a bug:

1. Gather evidence first — add logging, check server logs, inspect actual data
2. Confirm the root cause — present findings to the user with evidence
3. Only then propose a fix — based on what you observed, not what you guessed

If you can't determine the root cause from code reading alone, add diagnostic logging and ask the user to reproduce. Do NOT:

• Guess the root cause and immediately start coding a fix
• Assume data mismatches without checking the actual data
• Rewrite logic because you think values "might" differ

The cost of a wrong fix is high: wasted time, unnecessary code complexity, and potentially masking the real issue.

Update System Guidelines

The .claude/updates/ directory is for updates that require Claude to execute instructions — writing to MEMORY.md, modifying user config, running migrations, etc.

Do NOT create update files for simple command file drops. Command files in .claude/commands/ are automatically installed/updated by copyTree in the CLI. The CLI detects new and modified commands and reports them in the console output. Creating an update file for a command that's already shipped via copyTree is redundant.

Rule: If the update is just a file → put it in the right directory and let the CLI copy it. If the update needs instructions → create a NNN-*.md update file.

Command versioning: Every command file must have a <!-- @version N --> comment (typically line 2, after @description). Bump the version number whenever you modify a command. The CLI parses this to show version transitions on upgrade (e.g., ↑ /recover-context (v1 → v2)).

Design Principles

• Each file should have a single responsibility (one reason to change)
• If a file exceeds 500 LOC, it likely lacks separation of concerns — look for decomposition opportunities
• Keep cyclomatic complexity under 10 per function — extract helper functions or simplify branching if higher

Development Rules

Parallel sessions — work in a git worktree

Several Claude sessions run against this repo at once. If another may be open, call EnterWorktree before your first write to a repo file, then node scripts/bootstrap-worktree.js — a fresh worktree has every tracked file and no gitignored one, so without bootstrap there is no node_modules (the full suite fails in complexity-ratchet.test.js, which loads eslint), no .claude/settings.local.json (re-prompts on every Bash call), and no scripts/hook-fleet.local.json for the fleet check. Read-only sessions never enter one; it is one worktree per session, not per task. Skip it entirely when the work touches no repo files, or when it builds on uncommitted changes already in this checkout — those do not come along.

Full loop, the worktree.baseRef: head gotcha, and the list of things worktrees do NOT isolate (~/.claude and the hook fleet, the live twin, .claude/updates/ numbers, publishing): .claude/rules/parallel-session-worktrees.md.

That rule is dev-only — gated out of user installs by DEV_ONLY_FILES in bin/cli.js and the package.json files negation. scripts/ is not in files at all, so the bootstrap script never ships.

Testing Requirements

CRITICAL: Before committing any change to bin/, scripts/, or .claude/hooks/*.js, you MUST run tests and verify they pass:

npm test

This runs the FULL suite: box alignment, CLI install, update system, plugin system, terminal-title behavior, golden endings, live-twin parity, update summary, changelog generation, and the hook suites (npm run test:hooks fans out to .claude/hooks/tests/*.test.cjs — token-saver lives there, and those tests do NOT run any other way).

DO NOT commit or present code changes if tests fail. Fix the issues first.

Dev-box pre-push guard (per-machine setup, not tracked)

.git/hooks/ is untracked, so this hook lives only on the dev box — it is not shipped and not committed. It is the one mechanical guard for the fleet-parity class that CI structurally cannot see: live-twin-parity.test.js skips on CI, so CI green never proves the hook fleet is in sync (see trap 5 / T8 below). The hook blocks a push unless npm test passes AND node scripts/sync-hook-fleet.js (check mode) reports zero drift.

Since 2026-07-25 it checks the whole manifest (terminal-title + token-saver), not just terminal-title — token-saver is the file that actually drifted 231 lines, precisely because nothing checked it. A blocked push means an adopting repo is stale: run node scripts/sync-hook-fleet.js --write, commit the target repo, push again.

Check mode compares against HEAD, not the working tree (2026-08-07). Several sessions edit fleet-synced files here at once, and reading canonical from the working tree meant any one of them holding a file open made every downstream copy read as drifted — blocking every other session's push over a change nobody had committed. A target matching HEAD is therefore let through, narrated as in sync with HEAD (canonical has uncommitted edits). --write deliberately keeps using the working tree, since edit → --write → commit is the normal authoring loop.

test/hook-fleet-sync.test.js runs everywhere (it drives the actuator against throwaway dirs) and pins its semantics — adopt-only, the ~/.claude token-saver carve-out, check-vs-write, the exit codes this hook depends on. It does not replace the guard: it proves the actuator is correct, never that this machine's fleet is actually in sync. Only the check-mode run does that.

A third check warns, never blocks (2026-08-19): after both blocking checks, the hook prints unlandedBranches from .claude/scripts/sync-worktrees.js --json — branches merged nowhere that have no worktree left. A push is the wrong moment to refuse over a branch that isn't the one you're pushing, and a guard that blocks on advisory information is a guard somebody deletes; but nothing else surfaces this without a human remembering to run /sync-worktrees, which is the same passivity that let a branch sit a day behind. Its || true is load-bearing — set -e is on, so a non-zero exit there would abort the push.

On a fresh checkout, recreate .git/hooks/pre-push (then chmod +x it):

#!/bin/sh
# CCA dev-box pre-push guard (see CLAUDE.md). Not tracked; recreate on a fresh checkout.
# Blocks a push unless the full suite passes AND the canonical hook fleet is in sync
# (the parity class CI cannot see — live-twin-parity.test.js skips on CI).
set -e
echo "[pre-push] running full test suite (npm test)..."
npm test
echo "[pre-push] checking hook fleet sync..."
node scripts/sync-hook-fleet.js

# Unlanded-branch notice — WARN ONLY, last on screen, and `|| true` because `set -e` is on.
echo "[pre-push] unlanded branches (warn only)..."
node .claude/scripts/sync-worktrees.js --json 2>/dev/null | node -e '
  let s = "";
  process.stdin.on("data", (d) => (s += d)).on("end", () => {
    let u = [];
    try { u = JSON.parse(s).unlandedBranches || []; } catch { return; }
    if (!u.length) { console.log("[pre-push]   none."); return; }
    console.log("[pre-push]   WARNING: " + u.length + " unlanded branch(es) with no worktree:");
    for (const b of u) {
      console.log("[pre-push]     " + b.branch + " - " + b.ahead + " unlanded, " + b.behind + " behind");
    }
    console.log("[pre-push]   Not blocking. Land them, or reverse-merge before they drift further.");
  });
' || true

echo "[pre-push] OK - tests green, fleet in sync."

Invariants & Landmines — read before editing

Cross-file contracts that don't look like contracts. Each of these survives a naive read and a green feeling, then breaks something real:

• Generated files — never hand-edit. CHANGELOG.md is rebuilt from git history by scripts/generate-changelog.js on every npm version (reword bullets via Changelog: trailers or its OVERRIDES map). .claude/docs/autoconfig.docs.html is rebuilt by node .claude/scripts/sync-docs.js, which locates exact string markers inside that HTML — reformatting the file breaks the next sync.
• The .claude/hooks copies here are the canonical ones — terminal-title.js, terminal-title.directive.md, and token-saver.js (the manifest in scripts/sync-hook-fleet.js). Edit only these, then run node scripts/sync-hook-fleet.js --write to push them to ~/.claude and the fleet. Never edit a copy — the next sync clobbers it; drift fails live-twin-parity.test.js on this machine (the test skips on CI, so CI green ≠ parity ok). Syncing is adopt-only: a target that doesn't already have the file is skipped, never created, so a repo never acquires a hook by sync (that's the installer's job, and an unwired hook reads as adoption while doing nothing). scripts/sync-terminal-title.js still works — it is now a thin front-end over the same code, kept because plan and audit docs name it.
• Dev-only gating lives in DEV_ONLY_FILES (bin/cli.js), NOT package.json files. The npm files negations only shape the tarball; anything absent from DEV_ONLY_FILES is installed into every user project. token-saver + its commands are deliberately gated — do not "fix" that by shipping them. The installer also RETRACTS the 1.0.224 leak (deletes token-saver.js and the pre-rename token-guard.js, plus their commands, and strips both hook entries) unless cca.config.json carries tokenSaver.verdictServiceKey (paid) or tokenSaver.devFleet: true (one of our own repos, where the file arrives via scripts/sync-hook-fleet.js; a legacy tokenGuard block is migrated to tokenSaver on install). Every fleet repo that holds token-saver.js needs the devFleet flag, or its next @latest upgrade deletes the file.
• Commits about dev-gated work need a Changelog: none trailer. feat/fix/perf/refactor bullets surface verbatim on users' upgrade screens (bin/update-summary.js) — announcing a feature users can't receive is a bug. Already-pushed leaks: add an OVERRIDES null. scripts/generate-changelog.js also cross-checks each commit's touched paths against DEV_ONLY_FILES: a commit whose only shipped-area files are gated is dropped whatever its trailer says (stderr names it), a mixed commit keeps its bullet with a verify note, and an explicit OVERRIDES row wins. The trailer still governs mixed and maintainer-only commits.
• token-saver's --analyze digest wording is a machine interface. /analyze-session keys on the literal "live context at end" and the RENT/BOMBS/FLEETS/TTL headers. R6 scope data comes from terminal-title's per-title ledger (.titles/{sid}.history.jsonl: ts, title, optional tokens), parsed by ledgerScopes() and read by /migrate-new-session too. Renaming those ledger fields (they're written by terminal-title.js) silently breaks token-saver drift + that command.
• .claude/updates/ numbers are append-only — next is 005; 002 is a retired tombstone (see .claude/updates/README.md). A reused number is silently skipped by installs that applied the original.
• .claude/settings.json details are load-bearing: CLAUDE_CODE_DISABLE_TERMINAL_TITLE stays "1" (else Claude Code's own title writer races the hook), the --idle-rescue arg on the idle_prompt Notification entry selects a distinct code path (don't "dedupe" the two Notification entries), and hook commands stay ${CLAUDE_PROJECT_DIR:-.}-anchored.
• Hooks fail silent by design (token-saver, terminal-title swallow errors and exit 0). A regression won't crash anything — it quietly stops warning/painting. Run the hook suites; "it didn't error" proves nothing.
• test/golden-endings.json is append-only — never relabel or delete an entry without explicit sign-off; each records a real incident.

Box Drawing Guidelines

When modifying the "READY ..." boxes in bin/cli.js:

1. All lines must be exactly 46 visible characters wide (including the ║ borders)
2. ANSI escape codes (\x1b[...m) don't count toward visible width
3. The boxes are rendered by boxLine(text) / printReadyBox(title, command) inside main() — boxLine pads the visible text (ANSI stripped) to 44 chars between the borders, so never hand-count spaces; wrap colored spans with paint(color, text)
4. Always run npm test after any box modifications — test/box-alignment.test.js runs the real CLI (fresh + upgrade) and asserts the rendered width/structure of both boxes