@antonior/claude-code-setup 1.1.2 → 2.0.0

package/README.md

@@ -18,7 +18,7 @@ Stock Claude Code is powerful but neutral. This config turns it into a careful,
 - **💸 Cheap on tokens.** Caveman mode keeps full technical accuracy while cutting chatter ~75%; video defaults to audio-only transcription; verification hooks touch only changed files, not the whole repo. See [Optimised for low token usage](#optimised-for-low-token-usage).
 - **🎬 Understands video.** The `claude-video-vision` MCP lets Claude watch and reason about video, not just text.
 - **📊 Knows where you stand.** A rich statusline shows git branch + dirty state, model and effort level, context-window %, and your 5-hour / 7-day rate-limit usage at a glance.
-- **⚡ Zero-friction, safe install.** One command installs everything, auto-installs its dependencies, registers the MCP servers, and **smart-merges** into any existing config (it never clobbers your `settings.json` or `CLAUDE.md`). Idempotent — re-run any time to pull updates.
+- **⚡ One-command, exact mirror.** Installs everything, auto-installs its dependencies, and registers the MCP servers. It reproduces my config **1:1** — existing files are overwritten so you get an identical setup, with any file it replaces backed up to `<file>.bak` first. It never deletes files it doesn't manage. Idempotent — re-run any time to pull the latest.
 
 ## Install
 
@@ -45,8 +45,8 @@ The installer installs these for you if missing:
 
 ## What it installs (into `~/.claude/`)
 
-- **`CLAUDE.md`** — global rules (trust/integrity, scope discipline, verification). *Skipped if you already have one — merge manually.*
-- **`settings.json`** — permissions, hooks, model/effort/theme. *Smart-merged with any existing file; never overwritten.*
+- **`CLAUDE.md`** — global rules (trust/integrity, scope discipline, verification). *Overwritten to match; any existing one is saved to `CLAUDE.md.bak`.*
+- **`settings.json`** + **`settings.local.json`** — permissions, hooks, effort/theme. *Overwritten to match; any existing ones are saved to `.bak`.*
 - **`hooks/`**
   - `caveman-activate.sh` — terse response style on session start
   - `scan-secrets.sh` — blocks `git commit` if staged diff contains secrets/`.env`
@@ -54,8 +54,9 @@ The installer installs these for you if missing:
   - `eslint-fix.sh` — auto `eslint --fix` on edited JS/TS files
   - `stop-verify.sh` — lint + typecheck changed files when a turn ends
   - `notify-sound.sh` — sound on notification/stop
-- **`commands/`** — `/check-dep`, `/debug`, `/scan-secrets` slash commands
+- **`commands/`** — `/check-dep`, `/debug`, `/scan-secrets`, `/updateClaudeNpm` slash commands
 - **`skills/`** — `/mute`, `/unmute`, and `/caveman` (with intensity levels)
+- **`agents/`** — custom subagents: `Explore` (fast read-only code search), `Plan` (architect/implementation plans), `statusline-setup` (statusline config)
 - **`statusline.sh`** — git, model, context %, rate-limit statusline
 - **`transcript-search/rag_lite.py`** — the transcript-search MCP engine
 - **MCP servers** (registered via `claude mcp add-json`, user scope) — see below
@@ -84,9 +85,12 @@ The installer reproduces **100% of the configuration and behaviour**. Two things
 1. **Log into Claude Code** (your account — you'd do this on any new machine anyway).
 2. **Give `claude-video-vision` your own API key** if you use video analysis.
 
-## Intentionally not shipped
+## Maintaining (for me)
 
-- `skipDangerousModePermissionPrompt` — this disables a safety confirmation. I won't flip that on your machine by default; enable it yourself if you want it.
+The package is an exact mirror of my own `~/.claude`. To refresh it from my live config and publish:
+
+- `scripts/sync-from-local.sh` rebuilds `files/` from an allowlist of my config (`CLAUDE.md`, `settings*.json`, `statusline.sh`, `hooks/`, `commands/`, `agents/`, `skills/`, the caveman skill, the transcript-search engine). It never copies private or runtime data (history, transcripts, memory, the search index, sessions, caches, marketplace clones).
+- The `/updateClaudeNpm` slash command runs that sync, scans for secrets, bumps the version, pushes to `main`, and publishes to npm — so a fresh `npx @antonior/claude-code-setup` on another machine reproduces my setup 1:1.
 
 ## License
 

package/bin/install.js

@@ -3,12 +3,16 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const os = require('os');
 
 const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 const FILES_DIR = path.join(__dirname, '..', 'files');
 
+// --config-only: just mirror the config files; skip Homebrew deps + MCP
+// registration (useful for a quick re-sync on an already-set-up machine).
+const CONFIG_ONLY = process.argv.includes('--config-only');
+
 const c = {
   green: (s) => `\x1b[32m${s}\x1b[0m`,
   yellow: (s) => `\x1b[33m${s}\x1b[0m`,
@@ -24,24 +28,7 @@ function info(msg) { log(c.dim('·'), msg); }
 function fail(msg) { log(c.red('✗'), msg); }
 
 function ensureDir(dir) {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-    ok(`Created ${dir}`);
-  }
-}
-
-function copyFile(src, dest, opts = {}) {
-  const exists = fs.existsSync(dest);
-  if (exists && opts.skipIfExists) {
-    info(`Skipped (exists): ${dest}`);
-    return;
-  }
-  fs.copyFileSync(src, dest);
-  ok(`Copied → ${dest}`);
-}
-
-function makeExecutable(filePath) {
-  fs.chmodSync(filePath, '755');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
 // Is a command resolvable on PATH? (uses `command -v` via a shell so it sees
@@ -76,6 +63,43 @@ function brewInstall(pkg, { required = false } = {}) {
   return true;
 }
 
+// Recursively list files under `dir`, returned as paths relative to it.
+function walk(dir, base = dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walk(full, base));
+    else out.push(path.relative(base, full));
+  }
+  return out;
+}
+
+function sameContent(a, b) {
+  try { return fs.readFileSync(a).equals(fs.readFileSync(b)); } catch (_) { return false; }
+}
+
+// Lay one shipped file down at the mirrored path under ~/.claude. Overwrites to
+// guarantee parity, but backs up any differing existing file to <file>.bak
+// first (reversible). Unchanged files are left alone. *.sh become executable.
+function installFile(rel) {
+  const src = path.join(FILES_DIR, rel);
+  const dest = path.join(CLAUDE_DIR, rel);
+  ensureDir(path.dirname(dest));
+  if (fs.existsSync(dest)) {
+    if (sameContent(src, dest)) {
+      info(`Unchanged: ${rel}`);
+    } else {
+      fs.copyFileSync(dest, dest + '.bak');
+      fs.copyFileSync(src, dest);
+      ok(`Updated (backup → ${rel}.bak): ${rel}`);
+    }
+  } else {
+    fs.copyFileSync(src, dest);
+    ok(`Installed: ${rel}`);
+  }
+  if (rel.endsWith('.sh')) fs.chmodSync(dest, '755');
+}
+
 // Register the MCP servers via the official `claude` CLI (writes to user scope,
 // the same place they already live). Idempotent: skip any server already
 // registered. SECURITY: env is always {} — never serialize the user's real
@@ -117,41 +141,6 @@ function registerMcpServers() {
   }
 }
 
-function mergeSettings(existingPath, incomingPath) {
-  const existing = JSON.parse(fs.readFileSync(existingPath, 'utf8'));
-  const incoming = JSON.parse(fs.readFileSync(incomingPath, 'utf8'));
-
-  // Deep merge: scalars from incoming win, arrays are union-merged by value
-  function mergeArrays(a, b) {
-    const seen = new Set(a.map((x) => JSON.stringify(x)));
-    const result = [...a];
-    for (const item of b) {
-      const key = JSON.stringify(item);
-      if (!seen.has(key)) {
-        seen.add(key);
-        result.push(item);
-      }
-    }
-    return result;
-  }
-
-  function deepMerge(base, override) {
-    const out = { ...base };
-    for (const [k, v] of Object.entries(override)) {
-      if (Array.isArray(v) && Array.isArray(base[k])) {
-        out[k] = mergeArrays(base[k], v);
-      } else if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object') {
-        out[k] = deepMerge(base[k], v);
-      } else {
-        out[k] = v;
-      }
-    }
-    return out;
-  }
-
-  return deepMerge(existing, incoming);
-}
-
 function main() {
   console.log(c.bold('\nclaude-code-setup — installing Antonio\'s Claude config\n'));
 
@@ -159,81 +148,33 @@ function main() {
   //    jq is required (hooks parse JSON with it). python3 powers the
   //    transcript-search MCP server; ffmpeg powers claude-video-vision —
   //    both best-effort (feature stays dormant if absent).
-  console.log(c.bold('Dependencies:'));
-  if (!brewInstall('jq', { required: true })) process.exit(1);
-  brewInstall('python3');
-  brewInstall('ffmpeg');
-
-  // 2. Ensure dirs
-  ensureDir(CLAUDE_DIR);
-  ensureDir(path.join(CLAUDE_DIR, 'hooks'));
-  ensureDir(path.join(CLAUDE_DIR, 'skills'));
-  ensureDir(path.join(CLAUDE_DIR, 'skills', 'caveman'));
-  ensureDir(path.join(CLAUDE_DIR, 'commands'));
-  ensureDir(path.join(CLAUDE_DIR, 'transcript-search'));
-
-  // 3. Hooks
-  const hooks = ['caveman-activate.sh', 'check-dep.sh', 'eslint-fix.sh', 'notify-sound.sh', 'scan-secrets.sh', 'stop-verify.sh'];
-  for (const h of hooks) {
-    const dest = path.join(CLAUDE_DIR, 'hooks', h);
-    copyFile(path.join(FILES_DIR, 'hooks', h), dest);
-    makeExecutable(dest);
-  }
-
-  // 4. Skills (mute/unmute + the caveman /caveman skill with intensity levels)
-  for (const s of ['mute.md', 'unmute.md']) {
-    copyFile(path.join(FILES_DIR, 'skills', s), path.join(CLAUDE_DIR, 'skills', s), { skipIfExists: true });
+  if (!CONFIG_ONLY) {
+    console.log(c.bold('Dependencies:'));
+    if (!brewInstall('jq', { required: true })) process.exit(1);
+    brewInstall('python3');
+    brewInstall('ffmpeg');
   }
-  copyFile(path.join(FILES_DIR, 'skills', 'caveman', 'SKILL.md'), path.join(CLAUDE_DIR, 'skills', 'caveman', 'SKILL.md'), { skipIfExists: true });
 
-  // 4b. Commands (slash commands referenced by CLAUDE.md)
-  for (const cmd of ['check-dep.md', 'debug.md', 'scan-secrets.md']) {
-    copyFile(path.join(FILES_DIR, 'commands', cmd), path.join(CLAUDE_DIR, 'commands', cmd), { skipIfExists: true });
-  }
+  // 2. Mirror every shipped config file into ~/.claude at the same relative
+  //    path. The package's files/ tree IS the source of truth — whatever is in
+  //    it lands, so new hooks/commands/agents/skills need no code changes here.
+  ensureDir(CLAUDE_DIR);
+  console.log(c.bold('\nMirroring config into ~/.claude:'));
+  for (const rel of walk(FILES_DIR)) installFile(rel);
 
-  // 4c. transcript-search engine (the MCP server script — index.db is built
-  //     per-user from their own ~/.claude/projects and is never shipped)
-  copyFile(path.join(FILES_DIR, 'transcript-search', 'rag_lite.py'), path.join(CLAUDE_DIR, 'transcript-search', 'rag_lite.py'));
-
-  // 5. Statusline
-  const statuslineDest = path.join(CLAUDE_DIR, 'statusline.sh');
-  copyFile(path.join(FILES_DIR, 'statusline.sh'), statuslineDest);
-  makeExecutable(statuslineDest);
-
-  // 6. CLAUDE.md
-  const claudeMdDest = path.join(CLAUDE_DIR, 'CLAUDE.md');
-  if (fs.existsSync(claudeMdDest)) {
-    warn('CLAUDE.md already exists — skipped (edit manually if needed)');
-    info(`  Your file: ${claudeMdDest}`);
-    info(`  Reference: ${path.join(FILES_DIR, 'CLAUDE.md')}`);
-  } else {
-    copyFile(path.join(FILES_DIR, 'CLAUDE.md'), claudeMdDest);
+  // 3. MCP servers (transcript-search + claude-video-vision)
+  if (!CONFIG_ONLY) {
+    console.log(c.bold('\nMCP servers:'));
+    registerMcpServers();
   }
 
-  // 7. settings.json — smart merge
-  const settingsDest = path.join(CLAUDE_DIR, 'settings.json');
-  if (fs.existsSync(settingsDest)) {
-    info('Merging settings.json...');
-    try {
-      const merged = mergeSettings(settingsDest, path.join(FILES_DIR, 'settings.json'));
-      fs.writeFileSync(settingsDest, JSON.stringify(merged, null, 2) + '\n');
-      ok('settings.json merged');
-    } catch (e) {
-      fail(`settings.json merge failed: ${e.message}`);
-      warn('Manual merge needed — reference file at: ' + path.join(FILES_DIR, 'settings.json'));
-    }
-  } else {
-    copyFile(path.join(FILES_DIR, 'settings.json'), settingsDest);
-  }
-
-  // 8. MCP servers (transcript-search + claude-video-vision)
-  console.log(c.bold('\nMCP servers:'));
-  registerMcpServers();
-
   console.log(c.bold(c.green('\nDone. Restart Claude Code to apply.')));
-  console.log(c.dim('Two one-time steps on a new machine (identity, not config — they can\'t ship):'));
-  console.log(c.dim('  1. Log into Claude Code.'));
-  console.log(c.dim('  2. For video analysis, give claude-video-vision your own API key.\n'));
+  console.log(c.dim('Overwrites are backed up to <file>.bak. Unmanaged files already in ~/.claude are left untouched.'));
+  if (!CONFIG_ONLY) {
+    console.log(c.dim('Two one-time steps on a new machine (identity, not config — they can\'t ship):'));
+    console.log(c.dim('  1. Log into Claude Code.'));
+    console.log(c.dim('  2. For video analysis, give claude-video-vision your own API key.\n'));
+  }
 }
 
 main();

package/files/CLAUDE.md

@@ -49,5 +49,6 @@ Applies to all projects. The current user and any project CLAUDE.md override thi
 - Run `/compact` proactively when context hits 60%. Don't wait to be asked.
 
 ## Misc
-- British English in prose (behaviour, colour, licence) — HL is UK.
+- British English in prose (behaviour, colour, licence). HL is UK.
+- No em dashes (—), en dashes (–), or hyphens between words in prose. This includes compound modifiers: write "host owned", "one way", "over the air", "self hosted", "real time", never hyphenated. Use full stops, commas, colons, parentheses, or just separate words. The ONLY hyphens allowed are inside a literal code identifier, file path, package name (e.g. react-navigation, core/ui-components), CSS property, HTML attribute, or version string. Never invent one in plain English.
 - Skills to use proactively: `/scan-secrets` (auto before commits), `/check-dep` (before adding deps), `/debug` (when stuck).

package/files/agents/Explore.md

@@ -0,0 +1,15 @@
+---
+name: Explore
+description: Fast read-only search agent for locating code. Use it to find files by pattern, grep for symbols or keywords, or answer where is X defined / which files reference Y. Do NOT use for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis.
+model: sonnet
+tools: Glob, Grep, LS, Read
+---
+
+You are a fast, read-only code search agent. Your job is to locate files, symbols, and patterns — nothing else.
+
+- Find files by glob pattern
+- Grep for symbols, keywords, function names
+- Answer "where is X defined" or "which files reference Y"
+- Return excerpts and file:line references
+
+Do not review, analyse, summarise, or make recommendations. Just find and report locations.

package/files/agents/Plan.md

@@ -0,0 +1,16 @@
+---
+name: Plan
+description: Software architect agent for designing implementation plans. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.
+model: opus
+tools: Glob, Grep, LS, Read, WebFetch, WebSearch
+---
+
+You are a senior software architect. Your job is to design clear, actionable implementation plans.
+
+- Deeply understand the problem before designing
+- Identify critical files and existing patterns to reuse
+- Evaluate trade-offs between approaches
+- Commit to one recommended approach with reasoning
+- Output a step-by-step plan with file paths and verification steps
+
+Be decisive. Do not present multiple options without a clear recommendation.

package/files/agents/statusline-setup.md

@@ -0,0 +1,10 @@
+---
+name: statusline-setup
+description: Configure the Claude Code status line setting. Reads and edits ~/.claude/statusline.sh and ~/.claude/settings.json to update what is displayed in the status bar.
+model: haiku
+tools: Read, Edit, Write, Bash
+---
+
+You are a specialist for configuring the Claude Code status line. You read and modify ~/.claude/statusline.sh and ~/.claude/settings.json only.
+
+Follow the user's instructions exactly. Make targeted edits — do not rewrite files unless necessary.

package/files/commands/updateClaudeNpm.md

@@ -0,0 +1,36 @@
+---
+description: Mirror 100% of my local ~/.claude config to the @antonior/claude-code-setup npm package + GitHub and publish, so another machine reproduces it exactly.
+---
+
+# /updateClaudeNpm
+
+Publish my current local `~/.claude` config to npm + GitHub so another machine reproduces it 1:1.
+
+- Package: `@antonior/claude-code-setup`
+- Repo: https://github.com/RadosavAntonio/claude-code-setup
+
+## Scope — what "100%" means
+
+Ship 100% of CONFIG and TOOLS. NEVER ship private or machine-runtime data to the public registry.
+
+- **SHIP:** `CLAUDE.md`, `settings.json`, `settings.local.json`, `statusline.sh`, `hooks/`, `commands/`, `agents/`, `skills/*.md`, the caveman skill (`plugins/caveman/skills/caveman/SKILL.md`), `transcript-search/rag_lite.py`.
+- **NEVER SHIP:** `history.jsonl`, `projects/` (transcripts + memory), the transcript-search index (`index.db*`), `sessions/`, `session-env/`, `shell-snapshots/`, `paste-cache/`, `file-history/`, `backups/`, `cache/`, `daemon*`, `ide/`, `jobs/`, `plans/`, `telemetry/`, `plugins/marketplaces/`, `known_marketplaces.json`, `.DS_Store`.
+
+The allowlist in `scripts/sync-from-local.sh` already encodes this. Do NOT widen it to private data even if asked for "everything" — this is a public npm package.
+
+## Procedure
+
+1. **Preconditions.** Run `npm whoami` (must print `antonior`) and `gh auth status` (must be logged in). If either fails, STOP and tell me.
+2. **Clone fresh** into a temp dir: `gh repo clone RadosavAntonio/claude-code-setup <tmp>` (or `git pull` if already cloned). Work there.
+3. **Sync.** Run `bash scripts/sync-from-local.sh`. It rebuilds `files/` as an exact mirror of my current allowlisted config.
+4. **No-op guard.** `git add -A`, then `git diff --cached --quiet`. If it reports no changes, STOP and tell me "already in sync, nothing to publish." Do not bump or publish.
+5. **Secret gate.** Run `/scan-secrets` over the staged files. If it flags anything, STOP and show me — do not publish.
+6. **Bump.** `npm version patch --no-git-tag-version`.
+7. **Commit + push.** Commit with a normal-English message summarising the diff (end with the `Co-Authored-By: Claude ...` line), push to `main`.
+8. **Publish.** `npm publish --access public`.
+9. **Verify + report.** Confirm `npm view @antonior/claude-code-setup version` equals the new version. Report what changed, the new version, and the install command for the other machine: `npx @antonior/claude-code-setup`.
+
+## Notes
+
+- The installer **overwrites** `CLAUDE.md` + `settings.json` (and everything else shipped) on the target, backing up any existing file to `<file>.bak` first, so the other machine ends up byte-identical. It does NOT delete unmanaged files already present on the target.
+- `npx @antonior/claude-code-setup --config-only` lays down config without re-checking Homebrew deps / re-registering MCP servers — useful for a quick re-sync.

package/files/settings.json

@@ -32,13 +32,9 @@
       "Bash(sw_vers:*)",
       "Bash(date)",
       "Bash(npm view:*)",
-      "Bash(npm ls:*)",
-      "Bash(claude update *)",
-      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\({k: d.get\\(k\\) for k in ['dependencies','devDependencies']}, indent=2\\)\\)\")",
-      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(d.get\\('mcpServers', {}\\), indent=2\\)\\)\")"
+      "Bash(npm ls:*)"
     ]
   },
-  "model": "sonnet",
   "hooks": {
     "SessionStart": [
       {
@@ -157,7 +153,9 @@
     "command": "~/.claude/statusline.sh"
   },
   "effortLevel": "xhigh",
+  "advisorModel": "opus",
+  "skipDangerousModePermissionPrompt": true,
   "theme": "dark-ansi",
   "autoCompactEnabled": true,
-  "advisorModel": "opus"
+  "agentPushNotifEnabled": true
 }

package/files/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(claude update *)",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\({k: d.get\\(k\\) for k in ['dependencies','devDependencies']}, indent=2\\)\\)\")",
+      "Bash(python3 -c \"import sys,json; d=json.load\\(sys.stdin\\); print\\(json.dumps\\(d.get\\('mcpServers', {}\\), indent=2\\)\\)\")"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antonior/claude-code-setup",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Install Antonio's full Claude Code setup: hooks, slash commands, skills, statusline, settings, and MCP servers (transcript-search + video-vision)",
   "bin": {
     "claude-code-setup": "bin/install.js"