claudex-setup 1.10.3 → 1.11.0

package/CHANGELOG.md

@@ -15,6 +15,21 @@
 - README and docs now reflect snapshot artifacts, governance export, and the Claude-native skill path
 - packaged content and public-facing counts are now aligned with the current CLAUDEX state
 
+## [1.11.0] - 2026-04-03
+
+### Added
+- `history` command — show score timeline from saved snapshots
+- `compare` command — diff latest vs previous snapshot with delta, regressions, improvements
+- `trend --out report.md` — export trend report as shareable markdown
+- `--require A,B` CI flag — exit code 1 if named checks fail (policy guardrails)
+- Agentic DX positioning in README
+- Real results table (4 case studies) in README
+- Claude-native integration guide (skill, hook, agent examples)
+- Trust-first help text reordering
+
+### Fixed
+- Hook checks (hooksInSettings, preToolUse, postToolUse, sessionStart) now OR across settings.json and settings.local.json
+
 ## [1.10.2] - 2026-04-02
 
 ### Fixed

package/README.md

@@ -8,6 +8,7 @@
 
 ### What this is
 
+- The **Agentic DX layer for Claude Code** — audit, improve, govern, and benchmark how Claude works with your repo
 - A **Claude Code workflow audit and improvement tool** — not an MCP installer, not a code generator
 - Scores your repo 0-100 across CLAUDE.md, hooks, commands, agents, skills, MCP, security, and more
 - Proposes changes as diffs you review — applies only what you approve, with rollback for every change
@@ -37,6 +38,19 @@ npx claudex-setup --threshold 60   # Fail CI if score is below 60
 
 No install. No config. No dependencies.
 
+## Real Results
+
+Tested on 4 real projects — not demos:
+
+| Project | Type | Before | After | Delta |
+|---------|------|--------|-------|-------|
+| CLAUDEX | Research engine, Python | 62 | 90 | **+28** |
+| VTCLE | Marketing automation, FastAPI | 46 | 64 | **+18** |
+| Social | Mobile app, React Native | 40 | 48 | **+8** |
+| Polymiro | Prediction system, Python/Docker | 35 | 48 | **+13** |
+
+Most common gaps found: missing secrets protection, no deny rules, no mermaid diagram, no hooks in settings.
+
 ## What You Get
 
 ```
@@ -291,7 +305,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: DnaFin/claudex-setup@v1.10.3
+      - uses: DnaFin/claudex-setup@v1.11.0
         with:
           threshold: 50
 ```

package/bin/cli.js

@@ -19,7 +19,7 @@ const COMMAND_ALIASES = {
   suggest: 'suggest-only',
   gov: 'governance',
 };
-const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'help', 'version'];
+const KNOWN_COMMANDS = ['audit', 'setup', 'augment', 'suggest-only', 'plan', 'apply', 'governance', 'benchmark', 'deep-review', 'interactive', 'watch', 'badge', 'insights', 'history', 'compare', 'trend', 'help', 'version'];
 
 function levenshtein(a, b) {
   const matrix = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
@@ -61,12 +61,13 @@ function parseArgs(rawArgs) {
   let only = [];
   let profile = 'safe-write';
   let mcpPacks = [];
+  let requireChecks = [];
   let commandSet = false;
 
   for (let i = 0; i < rawArgs.length; i++) {
     const arg = rawArgs[i];
 
-    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack') {
+    if (arg === '--threshold' || arg === '--out' || arg === '--plan' || arg === '--only' || arg === '--profile' || arg === '--mcp-pack' || arg === '--require') {
       const value = rawArgs[i + 1];
       if (!value || value.startsWith('--')) {
         throw new Error(`${arg} requires a value`);
@@ -77,10 +78,16 @@ function parseArgs(rawArgs) {
       if (arg === '--only') only = value.split(',').map(item => item.trim()).filter(Boolean);
       if (arg === '--profile') profile = value.trim();
       if (arg === '--mcp-pack') mcpPacks = value.split(',').map(item => item.trim()).filter(Boolean);
+      if (arg === '--require') requireChecks = value.split(',').map(item => item.trim()).filter(Boolean);
       i++;
       continue;
     }
 
+    if (arg.startsWith('--require=')) {
+      requireChecks = arg.split('=').slice(1).join('=').split(',').map(item => item.trim()).filter(Boolean);
+      continue;
+    }
+
     if (arg.startsWith('--threshold=')) {
       threshold = arg.split('=')[1];
       continue;
@@ -124,35 +131,41 @@ function parseArgs(rawArgs) {
 
   const normalizedCommand = COMMAND_ALIASES[command] || command;
 
-  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks };
+  return { flags, command, normalizedCommand, threshold, out, planFile, only, profile, mcpPacks, requireChecks };
 }
 
 const HELP = `
   claudex-setup v${version}
-  Audit and optimize any project for Claude Code.
-  Backed by CLAUDEX research and evidence.
-
-  Usage:
-    npx claudex-setup                  Run audit on current directory
-    npx claudex-setup --lite           Run the quick-scan beginner view
-    npx claudex-setup discover         Discover the highest-value improvements
-    npx claudex-setup audit            Same as above
-    npx claudex-setup starter          Alias for setup
-    npx claudex-setup setup            Apply recommended configuration
-    npx claudex-setup setup --auto     Apply all without prompts
-    npx claudex-setup augment          Repo-aware augment plan (no writes)
-    npx claudex-setup suggest-only     Structured suggestion report (no writes)
-    npx claudex-setup plan             Exportable proposal bundles with file previews
-    npx claudex-setup apply            Apply ready proposal bundles with rollback manifest
-    npx claudex-setup governance       Profiles, hooks, and pilot rollout guidance
-    npx claudex-setup benchmark        Measure before/after impact in an isolated temp copy
-    npx claudex-setup deep-review      AI-powered config review (uses Claude Code or API key)
+  Score your repo's Claude Code setup. Fix gaps safely. Benchmark the impact.
+
+  Start here (read-only, nothing changes):
+    npx claudex-setup                  Audit your project (10 seconds)
+    npx claudex-setup --lite           Quick scan: top 3 gaps + next command
+    npx claudex-setup augment          Repo-aware analysis, no writes
+    npx claudex-setup suggest-only     Structured report, no writes
+
+  Plan and apply (when you're ready to change things):
+    npx claudex-setup plan             Export proposal bundles with previews
+    npx claudex-setup apply            Apply proposals selectively with rollback
+    npx claudex-setup setup            Generate starter-safe baseline
+    npx claudex-setup setup --auto     Apply all generated files without prompts
+
+  Track progress over time:
+    npx claudex-setup history          Show score history from saved snapshots
+    npx claudex-setup compare          Compare latest vs previous snapshot
+    npx claudex-setup trend --out r.md Export trend report as markdown
+
+  Advanced:
+    npx claudex-setup governance       Permission profiles, hooks, policy packs
+    npx claudex-setup benchmark        Before/after in isolated temp copy
+    npx claudex-setup deep-review      AI-powered config review (opt-in, uses API)
     npx claudex-setup interactive      Step-by-step guided wizard
-    npx claudex-setup watch            Monitor changes and re-audit live
+    npx claudex-setup watch            Live monitoring on config changes
     npx claudex-setup badge            Generate shields.io badge markdown
 
   Options:
     --threshold N   Exit with code 1 if score is below N (useful for CI)
+    --require A,B   Exit with code 1 if named checks fail (e.g. --require secretsProtection,permissionDeny)
     --out FILE      Write JSON or markdown output to a file
     --plan FILE     Load a previously exported plan file
     --only A,B      Limit plan/apply to selected proposal ids or technique keys
@@ -227,6 +240,7 @@ async function main() {
     only: parsed.only,
     profile: parsed.profile,
     mcpPacks: parsed.mcpPacks,
+    require: parsed.requireChecks,
     dir: process.cwd()
   };
 
@@ -261,7 +275,48 @@ async function main() {
   }
 
   try {
-    if (normalizedCommand === 'badge') {
+    if (normalizedCommand === 'history') {
+      const { formatHistory } = require('../src/activity');
+      console.log('');
+      console.log(formatHistory(options.dir));
+      console.log('');
+      process.exit(0);
+    } else if (normalizedCommand === 'compare') {
+      const { compareLatest } = require('../src/activity');
+      const result = compareLatest(options.dir);
+      if (!result) {
+        console.log('\n  Need at least 2 snapshots to compare. Run `npx claudex-setup --snapshot` twice.\n');
+        process.exit(0);
+      }
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const sign = result.delta.score >= 0 ? '+' : '';
+        console.log('');
+        console.log(`  Previous: ${result.previous.score}/100 (${result.previous.date?.split('T')[0]})`);
+        console.log(`  Current:  ${result.current.score}/100 (${result.current.date?.split('T')[0]})`);
+        console.log(`  Delta:    ${sign}${result.delta.score} points`);
+        console.log(`  Trend:    ${result.trend}`);
+        if (result.improvements.length > 0) console.log(`  Fixed:    ${result.improvements.join(', ')}`);
+        if (result.regressions.length > 0) console.log(`  New gaps: ${result.regressions.join(', ')}`);
+        console.log('');
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'trend') {
+      const { exportTrendReport } = require('../src/activity');
+      const report = exportTrendReport(options.dir);
+      if (!report) {
+        console.log('\n  No snapshots found. Run `npx claudex-setup --snapshot` to start tracking.\n');
+        process.exit(0);
+      }
+      if (options.out) {
+        require('fs').writeFileSync(options.out, report, 'utf8');
+        console.log(`\n  Trend report exported to ${options.out}\n`);
+      } else {
+        console.log(report);
+      }
+      process.exit(0);
+    } else if (normalizedCommand === 'badge') {
       const { getBadgeMarkdown } = require('../src/badge');
       const result = await audit({ ...options, silent: true });
       console.log(getBadgeMarkdown(result.score));
@@ -406,6 +461,19 @@ async function main() {
         }
         process.exit(1);
       }
+      if (options.require && options.require.length > 0) {
+        const failedRequired = options.require.filter(key => {
+          const check = result.results.find(r => r.key === key);
+          return !check || check.passed !== true;
+        });
+        if (failedRequired.length > 0) {
+          if (!options.json) {
+            console.error(`\n  Required checks failed: ${failedRequired.join(', ')}`);
+            console.error('  These must pass for CI to succeed.\n');
+          }
+          process.exit(1);
+        }
+      }
     }
   } catch (err) {
     console.error(`\n  Error: ${err.message}`);

package/content/claude-native-integration.md

@@ -0,0 +1,64 @@
+# Using claudex-setup from inside Claude Code
+
+## Skill: Audit Repo
+
+Add this to `.claude/skills/audit-repo.md` in any project:
+
+```markdown
+---
+name: audit-repo
+description: Run claudex-setup audit on the current project and show score + top gaps
+---
+
+Run `npx claudex-setup --json` on the current project directory.
+Parse the JSON output and present:
+1. Score X/100
+2. Top 3 critical/high gaps with fix descriptions
+3. Suggest next command based on score
+
+$ARGUMENTS — optional: --lite for quick scan
+```
+
+## Hook: Auto-audit on SessionStart
+
+Add to `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"try{const r=require('child_process').execSync('npx claudex-setup --json 2>/dev/null',{timeout:15000}).toString();const d=JSON.parse(r);if(d.score<50)console.log(JSON.stringify({systemMessage:'⚠️ Claude Code setup score: '+d.score+'/100. Consider running: npx claudex-setup --lite'}))}catch(e){console.log('{}')}\"",
+            "timeout": 20,
+            "statusMessage": "Checking Claude Code setup..."
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Agent: Setup Advisor
+
+Add to `.claude/agents/setup-advisor.md`:
+
+```markdown
+---
+name: setup-advisor
+description: Analyzes Claude Code setup and recommends improvements
+tools: [Bash, Read, Glob, Grep]
+model: haiku
+maxTurns: 10
+---
+
+You are a Claude Code setup advisor.
+
+1. Run `npx claudex-setup augment --json` on the current project
+2. Analyze gaps and strengths
+3. Recommend top 5 improvements with rationale
+4. If user approves, guide them through applying changes
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudex-setup",
-  "version": "1.10.3",
+  "version": "1.11.0",
   "description": "Score your repo's Claude Code setup against 62 checks. See gaps, apply fixes selectively with rollback, govern hooks and permissions, and benchmark impact — without breaking existing config.",
   "main": "src/index.js",
   "bin": {

package/src/activity.js

@@ -163,9 +163,139 @@ function writeSnapshotArtifact(dir, snapshotKind, payload, meta = {}) {
   };
 }
 
+function readSnapshotIndex(dir) {
+  const indexPath = path.join(dir, '.claude', 'claudex-setup', 'snapshots', 'index.json');
+  if (!fs.existsSync(indexPath)) return [];
+  try {
+    const entries = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+function getHistory(dir, limit = 20) {
+  const entries = readSnapshotIndex(dir);
+  return entries
+    .filter(e => e.snapshotKind === 'audit')
+    .sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt))
+    .slice(0, limit);
+}
+
+function compareLatest(dir) {
+  const audits = getHistory(dir, 2);
+  if (audits.length < 2) return null;
+
+  const current = audits[0];
+  const previous = audits[1];
+
+  const delta = {
+    score: (current.summary?.score || 0) - (previous.summary?.score || 0),
+    organic: (current.summary?.organicScore || 0) - (previous.summary?.organicScore || 0),
+    passed: (current.summary?.passed || 0) - (previous.summary?.passed || 0),
+  };
+
+  const regressions = [];
+  const improvements = [];
+
+  const prevKeys = new Set(previous.summary?.topActionKeys || []);
+  const currKeys = new Set(current.summary?.topActionKeys || []);
+
+  for (const key of currKeys) {
+    if (!prevKeys.has(key)) regressions.push(key);
+  }
+  for (const key of prevKeys) {
+    if (!currKeys.has(key)) improvements.push(key);
+  }
+
+  return {
+    current: { date: current.createdAt, score: current.summary?.score, passed: current.summary?.passed },
+    previous: { date: previous.createdAt, score: previous.summary?.score, passed: previous.summary?.passed },
+    delta,
+    regressions,
+    improvements,
+    trend: delta.score > 0 ? 'improving' : delta.score < 0 ? 'regressing' : 'stable',
+  };
+}
+
+function formatHistory(dir) {
+  const history = getHistory(dir, 10);
+  if (history.length === 0) return 'No snapshots found. Run `npx claudex-setup --snapshot` to save one.';
+
+  const lines = ['Score history (most recent first):', ''];
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || 'unknown';
+    const score = entry.summary?.score ?? '?';
+    const passed = entry.summary?.passed ?? '?';
+    const total = entry.summary?.checkCount ?? '?';
+    lines.push(`  ${date}  ${score}/100  (${passed}/${total} passing)`);
+  }
+
+  const comparison = compareLatest(dir);
+  if (comparison) {
+    lines.push('');
+    const sign = comparison.delta.score >= 0 ? '+' : '';
+    lines.push(`  Trend: ${comparison.trend} (${sign}${comparison.delta.score} since previous)`);
+    if (comparison.improvements.length > 0) {
+      lines.push(`  Fixed: ${comparison.improvements.join(', ')}`);
+    }
+    if (comparison.regressions.length > 0) {
+      lines.push(`  New gaps: ${comparison.regressions.join(', ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+function exportTrendReport(dir) {
+  const history = getHistory(dir, 50);
+  if (history.length === 0) return null;
+
+  const comparison = compareLatest(dir);
+  const lines = [
+    '# Claude Code Setup Trend Report',
+    '',
+    `**Project:** ${path.basename(dir)}`,
+    `**Generated:** ${new Date().toISOString().split('T')[0]}`,
+    `**Snapshots:** ${history.length}`,
+    '',
+    '## Score History',
+    '',
+    '| Date | Score | Passed | Checks |',
+    '|------|-------|--------|--------|',
+  ];
+
+  for (const entry of history) {
+    const date = entry.createdAt?.split('T')[0] || '?';
+    lines.push(`| ${date} | ${entry.summary?.score ?? '?'}/100 | ${entry.summary?.passed ?? '?'} | ${entry.summary?.checkCount ?? '?'} |`);
+  }
+
+  if (comparison) {
+    lines.push('');
+    lines.push('## Latest Comparison');
+    lines.push('');
+    lines.push(`- **Previous:** ${comparison.previous.score}/100 (${comparison.previous.date?.split('T')[0]})`);
+    lines.push(`- **Current:** ${comparison.current.score}/100 (${comparison.current.date?.split('T')[0]})`);
+    lines.push(`- **Delta:** ${comparison.delta.score >= 0 ? '+' : ''}${comparison.delta.score} points`);
+    lines.push(`- **Trend:** ${comparison.trend}`);
+    if (comparison.improvements.length > 0) lines.push(`- **Fixed:** ${comparison.improvements.join(', ')}`);
+    if (comparison.regressions.length > 0) lines.push(`- **New gaps:** ${comparison.regressions.join(', ')}`);
+  }
+
+  lines.push('');
+  lines.push(`---`);
+  lines.push(`*Generated by claudex-setup v${version}*`);
+  return lines.join('\n');
+}
+
 module.exports = {
   ensureArtifactDirs,
   writeActivityArtifact,
   writeRollbackArtifact,
   writeSnapshotArtifact,
+  readSnapshotIndex,
+  getHistory,
+  compareLatest,
+  formatHistory,
+  exportTrendReport,
 };

package/src/techniques.js

@@ -425,9 +425,11 @@ const TECHNIQUES = {
     id: 8801,
     name: 'Hooks configured in settings',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.hooks) return false;
-      return Object.keys(settings.hooks).length > 0;
+      const shared = ctx.jsonFile('.claude/settings.json');
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      const hasSharedHooks = shared && shared.hooks && Object.keys(shared.hooks).length > 0;
+      const hasLocalHooks = local && local.hooks && Object.keys(local.hooks).length > 0;
+      return hasSharedHooks || hasLocalHooks;
     },
     impact: 'high',
     rating: 4,
@@ -440,9 +442,9 @@ const TECHNIQUES = {
     id: 8802,
     name: 'PreToolUse hook configured',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.hooks) return false;
-      return !!settings.hooks.PreToolUse;
+      const shared = ctx.jsonFile('.claude/settings.json');
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      return !!(shared?.hooks?.PreToolUse || local?.hooks?.PreToolUse);
     },
     impact: 'high',
     rating: 4,
@@ -455,9 +457,9 @@ const TECHNIQUES = {
     id: 8803,
     name: 'PostToolUse hook configured',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.hooks) return false;
-      return !!settings.hooks.PostToolUse;
+      const shared = ctx.jsonFile('.claude/settings.json');
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      return !!(shared?.hooks?.PostToolUse || local?.hooks?.PostToolUse);
     },
     impact: 'high',
     rating: 4,
@@ -470,9 +472,10 @@ const TECHNIQUES = {
     id: 8804,
     name: 'SessionStart hook configured',
     check: (ctx) => {
-      const settings = ctx.jsonFile('.claude/settings.local.json') || ctx.jsonFile('.claude/settings.json');
-      if (!settings || !settings.hooks) return false;
-      return !!settings.hooks.SessionStart;
+      const shared = ctx.jsonFile('.claude/settings.json');
+      const local = ctx.jsonFile('.claude/settings.local.json');
+      if (!(shared?.hooks || local?.hooks)) return false;
+      return !!(shared?.hooks?.SessionStart || local?.hooks?.SessionStart);
     },
     impact: 'medium',
     rating: 4,