@nerviq/cli 0.9.0-beta.1 → 0.9.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +35 -423
- package/package.json +1 -1
- package/src/codex/setup.js +2 -14
- package/src/codex/techniques.js +630 -25
- package/src/techniques.js +127 -35
package/README.md
CHANGED
|
@@ -1,447 +1,59 @@
|
|
|
1
|
-
# claudex-setup
|
|
1
|
+
# claudex-setup → Nerviq
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **This project has been renamed and expanded to [Nerviq](https://github.com/nerviq/nerviq).**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
[](https://www.npmjs.com/package/claudex-setup)
|
|
7
|
-
[](LICENSE)
|
|
5
|
+
## What changed
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
`claudex-setup` started as a Claude Code audit tool (85 checks, single platform).
|
|
10
8
|
|
|
11
|
-
|
|
12
|
-
- A **Claude Code workflow audit and improvement tool** — not an MCP installer, not a code generator
|
|
13
|
-
- Scores your repo 0-100 across CLAUDE.md, hooks, commands, agents, skills, MCP, security, and more
|
|
14
|
-
- Proposes changes as diffs you review — applies only what you approve, with rollback for every change
|
|
15
|
-
- Includes governance (permission profiles, hook registry, policy packs) and benchmark (isolated before/after)
|
|
9
|
+
**Nerviq** is the next generation — the intelligent nervous system for **all** AI coding agents:
|
|
16
10
|
|
|
17
|
-
|
|
11
|
+
- **8 platforms**: Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Aider, OpenCode
|
|
12
|
+
- **639 checks** across all platforms
|
|
13
|
+
- **Harmony**: detect drift between agents on the same project
|
|
14
|
+
- **Synergy**: make agents amplify each other (1+1+1 > 3)
|
|
15
|
+
- **135 modules**, 172 exports
|
|
18
16
|
|
|
19
|
-
|
|
20
|
-
- Not a code generator or refactoring tool — it configures how Claude works with your repo, not the code itself
|
|
21
|
-
- Not a replacement for hand-crafted CLAUDE.md — generated output is a strong starting point, not a final answer
|
|
22
|
-
- Not a score you should chase blindly — 90/100 with bad code is still bad code
|
|
23
|
-
|
|
24
|
-
## Quick Start
|
|
17
|
+
## Install the new version
|
|
25
18
|
|
|
26
19
|
```bash
|
|
27
|
-
|
|
28
|
-
npx claudex-setup # Audit your project (10 seconds)
|
|
29
|
-
npx claudex-setup --snapshot # Save a normalized snapshot under .claude/claudex-setup/
|
|
30
|
-
npx claudex-setup setup # Create a starter-safe baseline
|
|
31
|
-
npx claudex-setup augment # Repo-aware plan, no writes
|
|
32
|
-
npx claudex-setup plan # Export proposal bundles with file previews
|
|
33
|
-
npx claudex-setup governance # See permission profiles, packs, and pilot guidance
|
|
34
|
-
npx claudex-setup governance --out governance.md # Export a shareable governance report
|
|
35
|
-
npx claudex-setup benchmark # Measure before/after in an isolated temp copy
|
|
36
|
-
npx claudex-setup --threshold 60 # Fail CI if score is below 60
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
No install. No config. No dependencies.
|
|
40
|
-
|
|
41
|
-
## Real Results
|
|
42
|
-
|
|
43
|
-
Tested on 4 real projects — not demos:
|
|
44
|
-
|
|
45
|
-
| Project | Type | Before | After | Delta |
|
|
46
|
-
|---------|------|--------|-------|-------|
|
|
47
|
-
| CLAUDEX | Research engine, Python | 62 | 90 | **+28** |
|
|
48
|
-
| VTCLE | Marketing automation, FastAPI | 46 | 64 | **+18** |
|
|
49
|
-
| Social | Mobile app, React Native | 40 | 48 | **+8** |
|
|
50
|
-
| Polymiro | Prediction system, Python/Docker | 35 | 48 | **+13** |
|
|
51
|
-
|
|
52
|
-
Most common gaps found: missing secrets protection, no deny rules, no mermaid diagram, no hooks in settings.
|
|
53
|
-
|
|
54
|
-
> Scores measured with claudex-setup@1.10.3 on 2026-04-03. Current npm latest: 1.16.1, so exact scores may differ slightly on the newer release.
|
|
55
|
-
>
|
|
56
|
-
> Canonical proof artifacts: [Index](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/README.md) | [CLAUDEX trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/claudex-self-dogfood-proof-trace-2026-04-03.md) | [VTCLE trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/vtcle-proof-trace-2026-04-03.md) | [Social trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/social-proof-trace-2026-04-03.md) | [Polymiro trace](https://github.com/DnaFin/claudex/blob/main/research/proof-artifacts/polymiro-proof-trace-2026-04-03.md)
|
|
57
|
-
>
|
|
58
|
-
> Narrative case studies: [VTCLE](https://github.com/DnaFin/claudex/blob/main/research/case-study-vtcle-2026-04-03.md) | [Social](https://github.com/DnaFin/claudex/blob/main/research/case-study-social-2026-04-03.md) | [Polymiro](https://github.com/DnaFin/claudex/blob/main/research/case-study-polymiro-2026-04-03.md)
|
|
59
|
-
|
|
60
|
-
## What You Get
|
|
61
|
-
|
|
62
|
-
```
|
|
63
|
-
claudex-setup audit
|
|
64
|
-
═══════════════════════════════════════
|
|
65
|
-
Detected: React, TypeScript, Docker
|
|
66
|
-
|
|
67
|
-
████████████████░░░░ 78/100
|
|
68
|
-
|
|
69
|
-
✅ Passing
|
|
70
|
-
CLAUDE.md project instructions
|
|
71
|
-
Mermaid architecture diagram
|
|
72
|
-
Hooks (PreToolUse + PostToolUse)
|
|
73
|
-
Custom slash commands (5 commands)
|
|
74
|
-
XML constraint blocks
|
|
75
|
-
Secrets protection configured
|
|
76
|
-
|
|
77
|
-
🟡 High Impact
|
|
78
|
-
CI pipeline configured
|
|
79
|
-
→ Add .github/workflows/ for automated testing
|
|
80
|
-
|
|
81
|
-
⚡ Top 5 Next Actions
|
|
82
|
-
1. Add CLAUDE.md verification criteria
|
|
83
|
-
Why: Claude needs an explicit verification loop before handoff
|
|
84
|
-
Trace: failed-check:verificationLoop | impact:critical | category:quality
|
|
85
|
-
Risk: high | Confidence: high
|
|
86
|
-
Fix: Add test/lint/build commands to CLAUDE.md so Claude can verify its own work
|
|
87
|
-
|
|
88
|
-
2. Configure safe permissions + deny rules
|
|
89
|
-
Why: Explicit permissions are the main safety layer for repo writes
|
|
90
|
-
Trace: failed-check:permissionDeny | impact:high | category:security
|
|
91
|
-
Risk: medium | Confidence: high
|
|
92
|
-
Fix: Add permissions.deny rules to block dangerous operations
|
|
93
|
-
|
|
94
|
-
Weakest areas:
|
|
95
|
-
design: none (0/2)
|
|
96
|
-
devops: none (0/4)
|
|
97
|
-
|
|
98
|
-
29/85 checks passing
|
|
99
|
-
Next command: npx claudex-setup setup
|
|
20
|
+
npm i -g @nerviq/cli
|
|
100
21
|
```
|
|
101
22
|
|
|
102
|
-
|
|
23
|
+
## Usage
|
|
103
24
|
|
|
104
25
|
```bash
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|---------|-------------|
|
|
114
|
-
| `npx claudex-setup` | **Discover** - Score 0-100 against 85 checks |
|
|
115
|
-
| `npx claudex-setup discover` | **Discover** - Alias for audit mode |
|
|
116
|
-
| `npx claudex-setup setup` | **Starter** - Smart CLAUDE.md + hooks + commands + agents |
|
|
117
|
-
| `npx claudex-setup starter` | **Starter** - Alias for setup mode |
|
|
118
|
-
| `npx claudex-setup setup --auto` | **Auto-setup** - No prompts, apply all |
|
|
119
|
-
| `npx claudex-setup augment` | **Augment** - Repo-aware improvement plan, no writes |
|
|
120
|
-
| `npx claudex-setup suggest-only` | **Suggest-Only** - Structured recommendation report, no writes |
|
|
121
|
-
| `npx claudex-setup plan` | **Plan** - Export proposal bundles with previews, rationale, and file-level changes |
|
|
122
|
-
| `npx claudex-setup apply` | **Apply** - Apply ready proposal bundles with rollback + activity artifacts |
|
|
123
|
-
| `npx claudex-setup governance` | **Governance** - Permission profiles, hook registry, policy packs, pilot kit |
|
|
124
|
-
| `npx claudex-setup benchmark` | **Benchmark** - Before/after evidence from an isolated temp copy |
|
|
125
|
-
| `npx claudex-setup interactive` | **Wizard** - Step-by-step guided tour |
|
|
126
|
-
| `npx claudex-setup watch` | **Watch** - Live monitoring with score delta and cross-platform directory fallback |
|
|
127
|
-
| `npx claudex-setup badge` | **Badge** - Generate shields.io badge for README |
|
|
128
|
-
| `npx claudex-setup feedback` | **Feedback** - Record local recommendation outcomes or show outcome summary |
|
|
129
|
-
| `npx claudex-setup deep-review` | **Deep Review** - AI-powered config analysis (Claude Code or API key, selected config only) |
|
|
130
|
-
| `npx claudex-setup insights` | **Insights** - View community aggregate stats |
|
|
131
|
-
|
|
132
|
-
## Codex Preview On Main
|
|
133
|
-
|
|
134
|
-
The current published npm package is still Claude-first.
|
|
135
|
-
|
|
136
|
-
On the current main branch and next release line, `claudex-setup` also includes a Codex vertical through:
|
|
137
|
-
|
|
138
|
-
- `npx claudex-setup --platform codex`
|
|
139
|
-
- `npx claudex-setup --platform codex augment`
|
|
140
|
-
- `npx claudex-setup --platform codex suggest-only`
|
|
141
|
-
- `npx claudex-setup --platform codex setup`
|
|
142
|
-
- `npx claudex-setup --platform codex plan`
|
|
143
|
-
- `npx claudex-setup --platform codex apply`
|
|
144
|
-
- `npx claudex-setup --platform codex governance`
|
|
145
|
-
- `npx claudex-setup --platform codex benchmark`
|
|
146
|
-
|
|
147
|
-
That means the Codex line now has:
|
|
148
|
-
|
|
149
|
-
- audit and `--lite`
|
|
150
|
-
- no-write advisory flows (`augment`, `suggest-only`)
|
|
151
|
-
- setup / plan / apply
|
|
152
|
-
- governance and benchmark
|
|
153
|
-
- initial domain pack recommendations (`baseline-general`, `backend-api`, `frontend-ui`, `enterprise-governed`, `monorepo`, `infra-platform`)
|
|
154
|
-
|
|
155
|
-
Current pre-release validation artifacts:
|
|
156
|
-
|
|
157
|
-
- [Codex v1.0 validation summary](https://github.com/DnaFin/claudex/blob/main/research/codex-v1.0-validation-results-v1-2026-04-03.md)
|
|
158
|
-
- [Codex case study — CLAUDEX](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-claudex-2026-04-03.md)
|
|
159
|
-
- [Codex case study — claudex-setup](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-claudex-setup-2026-04-03.md)
|
|
160
|
-
- [Codex case study — VTCLE](https://github.com/DnaFin/claudex/blob/main/research/case-study-codex-vtcle-2026-04-03.md)
|
|
26
|
+
nerviq audit # Audit Claude Code (default)
|
|
27
|
+
nerviq audit --platform codex # Audit Codex setup
|
|
28
|
+
nerviq audit --platform gemini # Audit Gemini CLI setup
|
|
29
|
+
nerviq audit --platform copilot # Audit GitHub Copilot setup
|
|
30
|
+
nerviq audit --platform cursor # Audit Cursor setup
|
|
31
|
+
nerviq audit --platform windsurf # Audit Windsurf setup
|
|
32
|
+
nerviq audit --platform aider # Audit Aider setup
|
|
33
|
+
nerviq audit --platform opencode # Audit OpenCode setup
|
|
161
34
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
- these Codex artifacts are measured on the local `1.16.2` pre-release line
|
|
165
|
-
- do not present them as npm-latest proof until the Codex-capable package line is published
|
|
166
|
-
|
|
167
|
-
### Options
|
|
168
|
-
|
|
169
|
-
| Flag | Effect |
|
|
170
|
-
|------|--------|
|
|
171
|
-
| `--threshold N` | Exit with code 1 if score is below `N` (great for CI) |
|
|
172
|
-
| `--out FILE` | Write JSON or markdown output to a file |
|
|
173
|
-
| `--plan FILE` | Load a previously exported plan file |
|
|
174
|
-
| `--only A,B` | Limit plan/apply to selected proposal ids |
|
|
175
|
-
| `--profile NAME` | Choose a permission profile for write-capable flows |
|
|
176
|
-
| `--mcp-pack A,B` | Merge named MCP packs into generated or patched settings |
|
|
177
|
-
| `--key NAME` | Recommendation key for `feedback` logging |
|
|
178
|
-
| `--status VALUE` | Outcome status: `accepted`, `rejected`, or `deferred` |
|
|
179
|
-
| `--effect VALUE` | Outcome effect: `positive`, `neutral`, or `negative` |
|
|
180
|
-
| `--score-delta N` | Optional observed score delta tied to the feedback event |
|
|
181
|
-
| `--snapshot` | Save a normalized artifact under `.claude/claudex-setup/snapshots/` |
|
|
182
|
-
| `--lite` | Show a short top-3 quick scan with one clear next command |
|
|
183
|
-
| `--dry-run` | Preview apply without writing files |
|
|
184
|
-
| `--verbose` | Show all recommendations (not just critical/high) |
|
|
185
|
-
| `--json` | Machine-readable JSON output (for CI) |
|
|
186
|
-
| `--auto` | Apply setup files without prompts |
|
|
187
|
-
| `--insights` | Enable anonymous usage insights (off by default) |
|
|
188
|
-
|
|
189
|
-
## Smart CLAUDE.md Generation
|
|
190
|
-
|
|
191
|
-
Not a generic template. The `setup` command actually analyzes your project:
|
|
192
|
-
|
|
193
|
-
- **Reads package.json** - includes your actual test, build, lint, dev commands
|
|
194
|
-
- **Reads pyproject.toml** - uses Python project name/description when package.json does not exist
|
|
195
|
-
- **Detects framework** - Next.js Server Components, Django models, FastAPI Pydantic, React hooks
|
|
196
|
-
- **TypeScript-aware** - detects strict mode, adds TS-specific rules
|
|
197
|
-
- **Auto Mermaid diagram** - scans directories and generates architecture visualization (Mermaid diagrams are more token-efficient than prose descriptions, per Anthropic docs)
|
|
198
|
-
- **XML constraint blocks** - adds `<constraints>` and `<verification>` with context-aware rules
|
|
199
|
-
- **Verification criteria** - auto-generates checklist from your actual commands
|
|
200
|
-
- **Safer settings.json** - generated hooks config now includes `acceptEdits` plus deny rules for dangerous or secret-sensitive operations
|
|
201
|
-
|
|
202
|
-
## Mode Model
|
|
203
|
-
|
|
204
|
-
- **Discover**: score the repo, surface critical issues, and show the best next actions
|
|
205
|
-
- **Starter**: generate a safe baseline when the repo has little or no Claude setup
|
|
206
|
-
- **Augment**: inspect the current repo and build a structured improvement plan without writing files
|
|
207
|
-
- **Suggest-Only**: same no-write analysis, optimized for sharing or manual review
|
|
208
|
-
- **Governance**: surface permission profiles, shipped hooks, policy packs, and pilot guidance
|
|
209
|
-
- **Benchmark**: prove value on an isolated copy before touching the real repo
|
|
210
|
-
|
|
211
|
-
## Proposal + Apply Workflow
|
|
212
|
-
|
|
213
|
-
Use `plan` when you want a file-by-file proposal bundle before any write happens:
|
|
214
|
-
|
|
215
|
-
```bash
|
|
216
|
-
npx claudex-setup plan --out claudex-plan.json
|
|
35
|
+
nerviq harmony-audit # Cross-platform harmony score
|
|
36
|
+
nerviq synergy-report # Synergy amplification report
|
|
217
37
|
```
|
|
218
38
|
|
|
219
|
-
|
|
39
|
+
## Links
|
|
220
40
|
|
|
221
|
-
-
|
|
222
|
-
-
|
|
223
|
-
-
|
|
224
|
-
- risk/confidence labels
|
|
41
|
+
- **npm**: [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli)
|
|
42
|
+
- **GitHub**: [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
|
|
43
|
+
- **Website**: [nerviq.net](https://nerviq.net)
|
|
225
44
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
```bash
|
|
229
|
-
npx claudex-setup apply --plan claudex-plan.json --only claude-md,hooks
|
|
230
|
-
```
|
|
45
|
+
## Legacy
|
|
231
46
|
|
|
232
|
-
|
|
47
|
+
The original `claudex-setup` package on npm is deprecated. All future development happens at [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli).
|
|
233
48
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
Use `governance` when the question is "can we pilot this safely?" instead of "what files can you generate?".
|
|
237
|
-
|
|
238
|
-
```bash
|
|
239
|
-
npx claudex-setup governance
|
|
240
|
-
npx claudex-setup governance --out governance.md
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
It exposes:
|
|
244
|
-
|
|
245
|
-
- permission profiles: `read-only`, `suggest-only`, `safe-write`, `power-user`, `internal-research`
|
|
246
|
-
- hook registry with trigger point, purpose, side effects, risk, and rollback path
|
|
247
|
-
- policy packs for baseline engineering, security-sensitive repos, OSS, and regulated-lite teams
|
|
248
|
-
- 16 domain packs: backend-api, frontend-ui, data-pipeline, infra-platform, oss-library, enterprise-governed, monorepo, mobile, regulated-lite, ecommerce, ai-ml, devops-cicd, design-system, docs-content, security-focused, baseline-general
|
|
249
|
-
- 26 MCP packs: Context7, Next.js devtools, GitHub, PostgreSQL, Playwright, Docker, Notion, Linear, Sentry, Slack, Stripe, Figma, Shopify, Hugging Face, Blender, WordPress, Jira/Confluence, GA4, Search Console, n8n, Zendesk, Infisical, Composio, memory, sequential-thinking, mcp-security
|
|
250
|
-
- a pilot rollout kit with scope, approvals, success metrics, and rollback expectations
|
|
251
|
-
|
|
252
|
-
Use `--out governance.md` if you want a shareable artifact for leads, platform teams, or security review.
|
|
253
|
-
|
|
254
|
-
## Domain Packs And MCP Packs
|
|
255
|
-
|
|
256
|
-
`augment` and `suggest-only` now recommend repo-shaped guidance instead of giving every project the same advice.
|
|
257
|
-
|
|
258
|
-
- 16 domain packs identify repo shape and recommend relevant modules
|
|
259
|
-
- 26 MCP packs recommend tooling companions matched to your detected domain and stack
|
|
260
|
-
- write-capable flows can merge MCP packs directly into `.claude/settings.json`
|
|
49
|
+
If you were using `claudex-setup`, simply switch:
|
|
261
50
|
|
|
262
51
|
```bash
|
|
263
|
-
|
|
264
|
-
npx claudex-setup
|
|
265
|
-
npx claudex-setup apply --plan claudex-plan.json --only hooks --mcp-pack context7-docs,next-devtools
|
|
266
|
-
```
|
|
52
|
+
# Old
|
|
53
|
+
npx claudex-setup
|
|
267
54
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
Use `benchmark` to measure the impact of starter-safe improvements without modifying your working repo:
|
|
271
|
-
|
|
272
|
-
```bash
|
|
273
|
-
npx claudex-setup benchmark --out benchmark.md
|
|
55
|
+
# New
|
|
56
|
+
npx @nerviq/cli audit
|
|
274
57
|
```
|
|
275
58
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
- runs a baseline audit on your repo
|
|
279
|
-
- copies the repo to an isolated temp workspace
|
|
280
|
-
- applies starter-safe artifacts only in the copy
|
|
281
|
-
- reruns the audit and emits before/after deltas, workflow-evidence coverage, a case-study summary, and an executive recommendation
|
|
282
|
-
|
|
283
|
-
If you want repeatable evidence artifacts for before/after work, add `--snapshot` to `audit`, `augment`, `suggest-only`, `benchmark`, or `governance`.
|
|
284
|
-
|
|
285
|
-
```bash
|
|
286
|
-
npx claudex-setup --snapshot
|
|
287
|
-
npx claudex-setup augment --snapshot
|
|
288
|
-
npx claudex-setup benchmark --snapshot
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
Snapshots are written to `.claude/claudex-setup/snapshots/` with a shared envelope and an `index.json` history file.
|
|
292
|
-
|
|
293
|
-
If you want a local-first recommendation loop, record what actually helped:
|
|
294
|
-
|
|
295
|
-
```bash
|
|
296
|
-
npx claudex-setup feedback --key permissionDeny --status accepted --effect positive --score-delta 12
|
|
297
|
-
npx claudex-setup feedback
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
Feedback stays under `.claude/claudex-setup/outcomes/` and is used only as a local ranking signal. Recommendations with repeated positive outcomes get a measured boost; recommendations with repeated negative or rejected outcomes get pushed down.
|
|
301
|
-
|
|
302
|
-
`watch` uses native `fs.watch` with recursive directory watches where the platform supports them, and an expanded directory fallback elsewhere. That keeps nested `.claude/` and `.github/` changes visible on Linux too, while staying zero-dependency. Native filesystem watch semantics can still be noisier on very large repos or network filesystems, so the command is best treated as fast local feedback rather than a CI-grade signal.
|
|
303
|
-
|
|
304
|
-
## Use Inside Claude Code
|
|
305
|
-
|
|
306
|
-
If you want the first Claude-native entry point, copy the shipped skill template into your repo.
|
|
307
|
-
|
|
308
|
-
If `claudex-setup` is installed locally in `node_modules`, use:
|
|
309
|
-
|
|
310
|
-
```bash
|
|
311
|
-
mkdir -p .claude/skills/audit-repo
|
|
312
|
-
cp ./node_modules/claudex-setup/content/claude-code/audit-repo/SKILL.md .claude/skills/audit-repo/SKILL.md
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
If you are using `npx` only, copy the same file from the GitHub repo at `content/claude-code/audit-repo/SKILL.md`.
|
|
316
|
-
|
|
317
|
-
The skill runs `npx claudex-setup --json`, summarizes the score, shows the top next actions, and points to the right next command without applying changes.
|
|
318
|
-
|
|
319
|
-
## 85 Checks Across 14 Categories
|
|
320
|
-
|
|
321
|
-
The exact applicable count can be lower on a given repo because stack-specific checks are skipped when they do not apply.
|
|
322
|
-
|
|
323
|
-
| Category | Checks | Key items |
|
|
324
|
-
|----------|-------:|-----------|
|
|
325
|
-
| Memory | 8 | CLAUDE.md, architecture, conventions, imports |
|
|
326
|
-
| Quality | 6 | verification loops, test/lint/build, testing strategy |
|
|
327
|
-
| Git Safety | 6 | .gitignore, env protection, attribution, secret detection |
|
|
328
|
-
| Workflow | 12 | commands, skills, rules, agents, snapshots |
|
|
329
|
-
| Security | 7 | permissions, secrets, deny rules, sandbox awareness |
|
|
330
|
-
| Automation | 7 | hook coverage, specificity, session and error hooks |
|
|
331
|
-
| Design | 2 | frontend anti-slop guidance, styling signals |
|
|
332
|
-
| DevOps | 5 | Docker, CI, Terraform, infra signals |
|
|
333
|
-
| Hygiene | 8 | README, changelog, license, env example, version pinning |
|
|
334
|
-
| Performance | 3 | context management, compaction, effort level |
|
|
335
|
-
| MCP & Tools | 4 | servers, Context7, tool companions, env config |
|
|
336
|
-
| Prompting | 6 | constraints, examples, negative rules, style guidance |
|
|
337
|
-
| Features | 2 | channels, worktrees |
|
|
338
|
-
| **Quality Deep** | **9** | **freshness, contradictions, deprecated patterns, maxTurns, $ARGUMENTS, hook specificity** |
|
|
339
|
-
|
|
340
|
-
## Stack Detection
|
|
341
|
-
|
|
342
|
-
Auto-detects and tailors output for 30 stacks:
|
|
343
|
-
|
|
344
|
-
| | |
|
|
345
|
-
|--|--|
|
|
346
|
-
| **Frontend** | React, Vue, Angular, Next.js, Svelte, Astro |
|
|
347
|
-
| **Backend** | Node.js, Python, Django, FastAPI, Express, NestJS, Spring Boot |
|
|
348
|
-
| **Mobile** | React Native, Expo, Flutter, Swift, Kotlin |
|
|
349
|
-
| **Systems** | Rust, Go, Java, Ruby, C++, Bazel, Deno, Bun |
|
|
350
|
-
| **Language** | TypeScript |
|
|
351
|
-
| **Infra** | Docker, Terraform, Kubernetes, Wrangler |
|
|
352
|
-
|
|
353
|
-
## GitHub Action
|
|
354
|
-
|
|
355
|
-
Add to `.github/workflows/claudex.yml`:
|
|
356
|
-
|
|
357
|
-
```yaml
|
|
358
|
-
name: CLAUDEX Audit
|
|
359
|
-
on: [pull_request]
|
|
360
|
-
jobs:
|
|
361
|
-
audit:
|
|
362
|
-
runs-on: ubuntu-latest
|
|
363
|
-
steps:
|
|
364
|
-
- uses: actions/checkout@v4
|
|
365
|
-
- uses: DnaFin/claudex-setup@v1.16.1
|
|
366
|
-
with:
|
|
367
|
-
threshold: 50
|
|
368
|
-
```
|
|
369
|
-
|
|
370
|
-
## Badge
|
|
371
|
-
|
|
372
|
-
Add a readiness badge to your README:
|
|
373
|
-
|
|
374
|
-
```bash
|
|
375
|
-
npx claudex-setup badge
|
|
376
|
-
# Output: [](...)
|
|
377
|
-
```
|
|
378
|
-
|
|
379
|
-
## For Veteran Claude Code Users
|
|
380
|
-
|
|
381
|
-
Already have a solid CLAUDE.md and hooks? Two things for you:
|
|
382
|
-
|
|
383
|
-
### Deep Review (AI-powered)
|
|
384
|
-
|
|
385
|
-
```bash
|
|
386
|
-
npx claudex-setup deep-review
|
|
387
|
-
```
|
|
388
|
-
|
|
389
|
-
Claude reads your actual config and gives specific feedback: what's strong, what has issues, what's missing for your stack. This is an AI-assisted review, not a local heuristic audit. Your config goes to the Anthropic API only when you run this command; we do not receive it.
|
|
390
|
-
|
|
391
|
-
Deep-review trust boundary:
|
|
392
|
-
|
|
393
|
-
- sends only selected Claude-facing config surfaces: `CLAUDE.md`, settings, commands, agents, rules, hooks, and package scripts
|
|
394
|
-
- truncates large files before sending
|
|
395
|
-
- redacts embedded secrets before sending
|
|
396
|
-
- treats embedded repo text as untrusted review data, not as instructions to follow
|
|
397
|
-
- keeps all non-`deep-review` flows local
|
|
398
|
-
|
|
399
|
-
### Quality-Deep Checks
|
|
400
|
-
|
|
401
|
-
The v0.4.0 quality-deep checks catch what basic audits miss:
|
|
402
|
-
|
|
403
|
-
| Check | What it catches |
|
|
404
|
-
|-------|----------------|
|
|
405
|
-
| **Freshness** | CLAUDE.md that doesn't mention modern features (hooks, skills, MCP) |
|
|
406
|
-
| **Conciseness** | CLAUDE.md over 200 lines (wastes tokens every session) |
|
|
407
|
-
| **Contradictions** | Conflicting rules ("always X" + "never X") |
|
|
408
|
-
| **Hook specificity** | Hooks without matchers that fire on every tool call |
|
|
409
|
-
| **Permission hygiene** | bypassPermissions still enabled in production |
|
|
410
|
-
| **Command flexibility** | Commands without $ARGUMENTS (static, not reusable) |
|
|
411
|
-
| **Agent limits** | Agents without maxTurns (can run forever) |
|
|
412
|
-
| **Security workflow** | No /security-review in your process |
|
|
413
|
-
| **Deprecated patterns** | Old model names, prefill, deprecated API formats |
|
|
414
|
-
|
|
415
|
-
These checks evaluate **quality**, not just existence. A well-configured project with stale patterns will surface real improvements.
|
|
416
|
-
|
|
417
|
-
## Privacy
|
|
418
|
-
|
|
419
|
-
- **Zero dependencies** - nothing extra to audit
|
|
420
|
-
- **Core flows run locally** - audit, setup, augment, plan, apply, governance, and benchmark run on your machine
|
|
421
|
-
- **Deep review is opt-in** - only `deep-review` sends selected config to Anthropic or your local Claude Code session for analysis
|
|
422
|
-
- **Deep review sanitizes before send** - selected snippets are truncated, secret-redacted, and wrapped as untrusted review data
|
|
423
|
-
- **Benchmark uses an isolated temp copy** - your live repo is not touched
|
|
424
|
-
- **Anonymous insights** - opt-in, no PII, no file contents (enable with `--insights`)
|
|
425
|
-
- **MIT Licensed** - use anywhere
|
|
426
|
-
|
|
427
|
-
## Backed by Research
|
|
428
|
-
|
|
429
|
-
Every check traces to a verified technique from a systematic audit of:
|
|
430
|
-
- All 73 official Claude Code documentation pages
|
|
431
|
-
- 100+ community MCP servers verified via GitHub API
|
|
432
|
-
- Anthropic blog posts and benchmark papers
|
|
433
|
-
- 194 hands-on experiments with real evidence
|
|
434
|
-
|
|
435
|
-
The catalog includes 1,107 entries (features, techniques, patterns, tools, stats, and known limitations) — not all are actionable checks. 948 were verified with real evidence. Continuously updated.
|
|
436
|
-
|
|
437
|
-
**Note:** A hand-crafted CLAUDE.md that reflects your real conventions will always be better than a generated one. This tool is most useful for projects starting from zero, or as a checklist for what you might be missing.
|
|
438
|
-
|
|
439
|
-
## Requirements
|
|
440
|
-
|
|
441
|
-
- Node.js 18+
|
|
442
|
-
- macOS, Linux, Windows
|
|
443
|
-
- No global install (npx handles it)
|
|
444
|
-
|
|
445
|
-
## License
|
|
446
|
-
|
|
447
|
-
MIT
|
|
59
|
+
All features from claudex-setup are preserved and expanded in Nerviq.
|
package/package.json
CHANGED
package/src/codex/setup.js
CHANGED
|
@@ -199,27 +199,15 @@ function buildAgentsMd(ctx, stacks) {
|
|
|
199
199
|
}
|
|
200
200
|
|
|
201
201
|
function buildConfigToml() {
|
|
202
|
+
// Updated 2026-04-05: removed stale keys (model_for_weak_tasks, full_auto_error_mode,
|
|
203
|
+
// history.send_to_server) that no longer exist in official Codex config schema
|
|
202
204
|
return [
|
|
203
|
-
'profile = "safe"',
|
|
204
205
|
'model = "gpt-5.4"',
|
|
205
206
|
'model_reasoning_effort = "medium"',
|
|
206
|
-
'model_for_weak_tasks = "gpt-5.4-mini"',
|
|
207
207
|
'approval_policy = "on-request"',
|
|
208
208
|
'sandbox_mode = "workspace-write"',
|
|
209
|
-
'full_auto_error_mode = "ask-user"',
|
|
210
209
|
'project_doc_fallback_filenames = ["AGENTS.md"]',
|
|
211
210
|
'',
|
|
212
|
-
'[profiles.safe]',
|
|
213
|
-
'approval_policy = "on-request"',
|
|
214
|
-
'sandbox_mode = "workspace-write"',
|
|
215
|
-
'',
|
|
216
|
-
'[features]',
|
|
217
|
-
'codex_hooks = false',
|
|
218
|
-
'undo = false',
|
|
219
|
-
'',
|
|
220
|
-
'[history]',
|
|
221
|
-
'send_to_server = false',
|
|
222
|
-
'',
|
|
223
211
|
'[sandbox_workspace_write]',
|
|
224
212
|
'network_access = false',
|
|
225
213
|
'',
|