@nerviq/cli 0.9.0-beta.2 → 0.9.2
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 +103 -406
- 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,144 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Nerviq
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> The intelligent nervous system for AI coding agents — audit, align, and amplify every platform on every project.
|
|
4
4
|
|
|
5
|
-
[](LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@nerviq/cli)
|
|
6
|
+
[](LICENSE)
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
---
|
|
10
9
|
|
|
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)
|
|
10
|
+
### ⚠️ Beta — Currently Claude Code only
|
|
16
11
|
|
|
17
|
-
|
|
12
|
+
Nerviq is in **beta**. The current release fully supports **Claude Code** (90 checks, audit, setup, governance, benchmark).
|
|
18
13
|
|
|
19
|
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
14
|
+
**Coming soon:**
|
|
15
|
+
- Codex (OpenAI)
|
|
16
|
+
- Gemini CLI (Google)
|
|
17
|
+
- GitHub Copilot
|
|
18
|
+
- Cursor
|
|
19
|
+
- Windsurf
|
|
20
|
+
- Aider
|
|
21
|
+
- OpenCode
|
|
22
|
+
- **Harmony** — cross-platform drift detection
|
|
23
|
+
- **Synergy** — multi-agent amplification
|
|
23
24
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
npx claudex-setup --lite # Quick beginner scan: top 3 fixes + next command
|
|
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
|
|
25
|
+
---
|
|
42
26
|
|
|
43
|
-
|
|
27
|
+
## What Nerviq Does
|
|
44
28
|
|
|
45
|
-
|
|
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
|
|
29
|
+
Nerviq scores your AI coding agent setup from 0 to 100, finds what's missing, and fixes it — with rollback for every change.
|
|
61
30
|
|
|
62
31
|
```
|
|
63
|
-
|
|
32
|
+
nerviq audit
|
|
64
33
|
═══════════════════════════════════════
|
|
65
34
|
Detected: React, TypeScript, Docker
|
|
66
35
|
|
|
67
36
|
████████████████░░░░ 78/100
|
|
68
37
|
|
|
69
|
-
✅
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
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
|
|
38
|
+
✅ CLAUDE.md with architecture diagram
|
|
39
|
+
✅ Hooks (PreToolUse + PostToolUse)
|
|
40
|
+
✅ Custom skills (3 skills)
|
|
41
|
+
✅ MCP servers configured
|
|
42
|
+
|
|
43
|
+
⚡ Top 3 Next Actions
|
|
44
|
+
1. Add verification commands to CLAUDE.md
|
|
45
|
+
2. Configure deny rules for dangerous operations
|
|
46
|
+
3. Add path-specific rules in .claude/rules/
|
|
47
|
+
|
|
48
|
+
Next: nerviq setup
|
|
100
49
|
```
|
|
101
50
|
|
|
102
|
-
|
|
51
|
+
## Quick Start
|
|
103
52
|
|
|
104
53
|
```bash
|
|
105
|
-
npx
|
|
54
|
+
npx @nerviq/cli audit # Score your project (10 seconds)
|
|
55
|
+
npx @nerviq/cli audit --lite # Quick top-3 scan
|
|
56
|
+
npx @nerviq/cli setup # Generate starter-safe baseline
|
|
57
|
+
npx @nerviq/cli augment # Improvement plan, no writes
|
|
58
|
+
npx @nerviq/cli governance # Permission profiles + policy packs
|
|
59
|
+
npx @nerviq/cli benchmark # Before/after in isolated copy
|
|
106
60
|
```
|
|
107
61
|
|
|
108
|
-
|
|
62
|
+
No install required. Zero dependencies.
|
|
63
|
+
|
|
64
|
+
## 90 Checks Across 14 Categories
|
|
65
|
+
|
|
66
|
+
| Category | Checks | Examples |
|
|
67
|
+
|----------|--------|---------|
|
|
68
|
+
| Memory & Context | 9 | CLAUDE.md, architecture, @path imports, CLAUDE.local.md |
|
|
69
|
+
| Quality | 8 | verification loops, test/lint/build commands |
|
|
70
|
+
| Security | 7 | permissions, deny rules, secrets detection |
|
|
71
|
+
| Automation | 8 | hooks (30+ event types), notification, subagent tracking |
|
|
72
|
+
| Workflow | 9 | skills, subagents, rules, commands, snapshots |
|
|
73
|
+
| Git & Hygiene | 14 | .gitignore, env protection, README, changelog |
|
|
74
|
+
| Tools & MCP | 4 | .mcp.json, Context7, multi-server |
|
|
75
|
+
| Prompting | 6 | XML tags, constraints, examples, role definition |
|
|
76
|
+
| DevOps | 5 | Docker, CI, Terraform |
|
|
77
|
+
| Design | 2 | frontend anti-slop, Tailwind |
|
|
78
|
+
| Performance | 3 | compaction, context management, effort level |
|
|
79
|
+
| Features | 2 | channels, worktrees |
|
|
80
|
+
| Quality Deep | 9 | freshness, contradictions, deprecated patterns |
|
|
109
81
|
|
|
110
82
|
## All Commands
|
|
111
83
|
|
|
112
84
|
| Command | What it does |
|
|
113
85
|
|---------|-------------|
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
|
|
132
|
-
|
|
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)
|
|
161
|
-
|
|
162
|
-
Boundary note:
|
|
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
|
|
86
|
+
| `nerviq audit` | Score 0-100 against 90 checks |
|
|
87
|
+
| `nerviq audit --lite` | Quick top-3 scan |
|
|
88
|
+
| `nerviq setup` | Generate starter-safe CLAUDE.md + hooks + commands |
|
|
89
|
+
| `nerviq augment` | Repo-aware improvement plan (no writes) |
|
|
90
|
+
| `nerviq suggest-only` | Structured report for sharing |
|
|
91
|
+
| `nerviq plan` | Export proposal bundles with previews |
|
|
92
|
+
| `nerviq apply` | Apply proposals with rollback |
|
|
93
|
+
| `nerviq governance` | Permission profiles, hooks, policy packs |
|
|
94
|
+
| `nerviq benchmark` | Before/after in isolated temp copy |
|
|
95
|
+
| `nerviq deep-review` | AI-powered config review (opt-in) |
|
|
96
|
+
| `nerviq interactive` | Step-by-step guided wizard |
|
|
97
|
+
| `nerviq watch` | Live monitoring with score delta |
|
|
98
|
+
| `nerviq history` | Score history from snapshots |
|
|
99
|
+
| `nerviq compare` | Compare latest vs previous |
|
|
100
|
+
| `nerviq trend` | Export trend report |
|
|
101
|
+
| `nerviq feedback` | Record recommendation outcomes |
|
|
102
|
+
| `nerviq badge` | shields.io badge for README |
|
|
103
|
+
| `nerviq scan dir1 dir2` | Compare multiple repos |
|
|
104
|
+
|
|
105
|
+
## Options
|
|
168
106
|
|
|
169
107
|
| Flag | Effect |
|
|
170
108
|
|------|--------|
|
|
171
|
-
| `--threshold N` | Exit
|
|
172
|
-
| `--
|
|
173
|
-
| `--
|
|
174
|
-
| `--
|
|
175
|
-
| `--
|
|
176
|
-
| `--
|
|
177
|
-
| `--
|
|
178
|
-
| `--
|
|
179
|
-
| `--
|
|
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
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
Each proposal bundle includes:
|
|
220
|
-
|
|
221
|
-
- trigger reasons tied to failed checks
|
|
222
|
-
- file previews and diff-style output
|
|
223
|
-
- `create`, `patch`, or `manual-review` classification
|
|
224
|
-
- risk/confidence labels
|
|
225
|
-
|
|
226
|
-
Apply only the bundles you want:
|
|
227
|
-
|
|
228
|
-
```bash
|
|
229
|
-
npx claudex-setup apply --plan claudex-plan.json --only claude-md,hooks
|
|
230
|
-
```
|
|
231
|
-
|
|
232
|
-
`apply` creates rollback manifests and activity artifacts under `.claude/claudex-setup/`, so every applied batch has a paper trail and a create-or-patch rollback path.
|
|
233
|
-
|
|
234
|
-
## Governance And Pilot Readiness
|
|
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`
|
|
261
|
-
|
|
262
|
-
```bash
|
|
263
|
-
npx claudex-setup suggest-only --json
|
|
264
|
-
npx claudex-setup setup --mcp-pack context7-docs
|
|
265
|
-
npx claudex-setup apply --plan claudex-plan.json --only hooks --mcp-pack context7-docs,next-devtools
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
## Benchmark And Evidence
|
|
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
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
Benchmark mode:
|
|
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
|
|
109
|
+
| `--threshold N` | Exit 1 if score < N (for CI) |
|
|
110
|
+
| `--json` | Machine-readable JSON output |
|
|
111
|
+
| `--out FILE` | Write output to file |
|
|
112
|
+
| `--snapshot` | Save audit snapshot for trending |
|
|
113
|
+
| `--lite` | Compact top-3 quick scan |
|
|
114
|
+
| `--dry-run` | Preview apply without writing |
|
|
115
|
+
| `--auto` | Apply without prompts |
|
|
116
|
+
| `--verbose` | Show all recommendations |
|
|
117
|
+
| `--format sarif` | SARIF output for code scanning |
|
|
282
118
|
|
|
283
|
-
|
|
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
|
-
```
|
|
119
|
+
## Privacy
|
|
299
120
|
|
|
300
|
-
|
|
121
|
+
- **Zero dependencies** — nothing to audit
|
|
122
|
+
- **Runs locally** — audit, setup, plan, apply, governance, benchmark all run on your machine
|
|
123
|
+
- **Deep review is opt-in** — only `deep-review` sends selected config for AI analysis
|
|
124
|
+
- **AGPL-3.0 Licensed** — open source
|
|
301
125
|
|
|
302
|
-
|
|
126
|
+
## Links
|
|
303
127
|
|
|
304
|
-
|
|
128
|
+
- **npm**: [@nerviq/cli](https://www.npmjs.com/package/@nerviq/cli)
|
|
129
|
+
- **GitHub**: [github.com/nerviq/nerviq](https://github.com/nerviq/nerviq)
|
|
130
|
+
- **Website**: [nerviq.net](https://nerviq.net)
|
|
305
131
|
|
|
306
|
-
|
|
132
|
+
## Previously claudex-setup
|
|
307
133
|
|
|
308
|
-
|
|
134
|
+
Nerviq was previously published as `claudex-setup`. If you were using it:
|
|
309
135
|
|
|
310
136
|
```bash
|
|
311
|
-
|
|
312
|
-
|
|
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`.
|
|
137
|
+
# Old
|
|
138
|
+
npx claudex-setup
|
|
316
139
|
|
|
317
|
-
|
|
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
|
|
140
|
+
# New
|
|
141
|
+
npx @nerviq/cli audit
|
|
368
142
|
```
|
|
369
143
|
|
|
370
|
-
|
|
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
|
|
144
|
+
All features are preserved and expanded.
|
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
|
'',
|