Nerviq

Your agent docs lie. Nerviq finds the lies in 30 seconds.

CLAUDE.md says npm test — but the script doesn't exist. AGENTS.md says Next 15 — package.json says 16. Your Cursor rules and your Copilot instructions give the agent contradictory orders. Nerviq is a zero-dependency CLI that catches stale references and cross-platform drift in AI-agent configs — deterministically, with findings you can verify by hand.

npx @nerviq/cli drift    # 30 seconds. Finds the lies. Exit 1 if your docs lie.

The two things it does best

1. Stale-reference detection (the lies)

nerviq drift (and every nerviq audit) runs a deterministic scan:

• Scripts that don't exist. Your AGENTS.md says "run npm test" but scripts.test isn't defined in package.json. Flagged.
• Framework versions that drifted. Your CLAUDE.md says "Next.js 15 app" but package.json declares next@^16.x. Flagged.
• Near-zero false positives. Every finding verifiable in 30 seconds: cat package.json against the agent doc.

It found a real one in this very repo's AGENTS.md. It will probably find one in yours.

2. Cross-platform drift (Harmony)

Most teams run 2+ agents — Claude Code and Cursor, Copilot and Codex. Their config files drift silently until the agents behave differently on the same repo. When 2+ platforms are configured, nerviq audit leads with the Harmony report: what contradicts what, where, and the one-line fix.

$ nerviq audit
Harmony: 3 drift issues across Claude Code + Cursor
  ✗ test command: CLAUDE.md says `npm test` · .cursor/rules says `pnpm vitest`
  ✗ framework: AGENTS.md says Next 15 · package.json says next@16.1.2
  ...

Single-platform repos still get a normal per-platform audit — the Harmony report only appears when 2+ platforms are detected. Use --no-harmony-first to suppress it even on multi-platform repos.

And when you want the big picture

Nerviq also ships a full config-governance layer: a 0–100 score across 8 platforms (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Windsurf, Aider, OpenCode — 2,441 checks), safe autofix with dry-run patches, snapshots/trend, CI gate (GitHub Action), SDK, and an MCP server. Every check carries a source URL and a freshness date. The per-platform breakdown and the full command surface are below the fold — start with drift, grow into the rest when you need it.

Scope — the 4 layers

Every Nerviq check is tagged with one of four explicit layers so you know exactly what the tool claims (and does not claim) to cover:

• governance — agent configuration posture: presence, content, and quality of agent-instruction files and platform settings.
• drift — cross-platform consistency: do your configured platforms agree, and does declared state match repo reality?
• hygiene — repo-level cleanliness adjacent to agents (gitignore, CHANGELOG, SECURITY.md, LICENSE, Node version pinning, etc.).
• shallow-risk — obvious agent-config ↔ codebase boundary issues emitted through the experimental --shallow-risk lane.

There is deliberately no "deep-review" or general-security-scanning layer — Nerviq is an agent-configuration audit tool, not a code-review tool. The experimental nerviq audit --shallow-risk pass now adds an opt-in, non-scoring boundary scan on top of the four-layer model. The full taxonomy and disambiguation rules live in docs/integration-contracts.md §8, and the layer field is surfaced in every output format (JSON, CSV, JUnit, Markdown, text).

Quick Start

npx @nerviq/cli drift              # Do your agent docs lie? Stale refs + cross-platform drift (exit 1 on findings)
npx @nerviq/cli --beginner         # Show only the 5 starter commands
npx @nerviq/cli audit              # Quick scan: score + top 3 actions
npx @nerviq/cli audit --fix        # Dry-run deterministic autofix plan + audit-fix.patch
npx @nerviq/cli audit --full       # Full audit with all checks + badge
npx @nerviq/cli audit --snapshot --tag "pre-refactor"  # Save a named snapshot for history/compare/trend
npx @nerviq/cli audit --diff-only  # PR/working-tree audit: changed files + linked governance/config surfaces only
npx @nerviq/cli compare            # Detailed per-check diff between latest 2 audit snapshots
npx @nerviq/cli audit --webhook https://hooks.slack.com/services/...  # Push audit results to Slack/Discord/generic HTTP
npx @nerviq/cli audit --workspace packages/*  # Monorepo: root governance + stack-specific workspace profiles
npx @nerviq/cli setup              # Generate starter-safe baseline
npx @nerviq/cli augment            # Improvement plan, no writes
npx @nerviq/cli governance         # Permission profiles + policy packs
npx @nerviq/cli benchmark          # Baseline vs projected score in isolated copy

No install required. Zero dependencies.

Text-mode CLI output explains terms like MCP, hooks, deny rules, and governance inline when they appear, so a first audit is easier to read.

If you want the shortest possible command list inside the terminal, start with:

npx @nerviq/cli --beginner

Safe Autofix with --fix

nerviq audit --fix now defaults to a safe dry-run. Nerviq only plans deterministic file-level fixes on an allowlist of governance and hygiene files such as CLAUDE.md, AGENTS.md, .claude/settings.json, .gitignore, .editorconfig, CHANGELOG.md, CONTRIBUTING.md, and LICENSE.

npx @nerviq/cli audit --fix                # Preview changes and write audit-fix.patch
npx @nerviq/cli audit --fix --apply --auto # Apply deterministic fixes
npx @nerviq/cli audit --fix --pr           # Create a local branch and stage the autofix files

Checks that need judgment stay advisory-only and are listed as manual follow-ups. See docs/audit-fix.md for the full contract.

Get Started by Role

2,441 Checks Across 96 Categories (8 Platforms × ~300 Governance Rules)

8 Platforms Supported

Nerviq audits, sets up, and governs AI coding agent configurations for 8 platforms, in two support tiers:

Verified tier — primary documentation sources are actively re-verified on the freshness cycle (last full pass: 2026-07-06).

Community tier — all checks still ship and run exactly as before (nothing was deleted or disabled), but we are honest about maintenance: check freshness for these platforms is not guaranteed current. Sources are re-verified opportunistically or via community contribution — PRs updating them are very welcome. The tier split is reversible per platform (src/platform-tiers.js).

10 Stack-Specific Languages

Category Groups

Harmony — Cross-Platform Alignment GA

Harmony detects drift between your AI coding platforms and keeps them in sync.

npx @nerviq/cli harmony-audit      # Cross-platform DX audit (0-100 harmony score)
npx @nerviq/cli harmony-sync       # Sync shared config across platforms
npx @nerviq/cli harmony-drift      # Detect drift between platform configs
npx @nerviq/cli harmony-advise     # Cross-platform improvement advice
npx @nerviq/cli harmony-watch      # Live monitoring for config drift
npx @nerviq/cli harmony-governance # Unified governance across platforms
npx @nerviq/cli harmony-add <platform>  # Add a new platform to your project

Synergy — Multi-Agent Amplification EXPERIMENTAL

Synergy analyzes how your platforms work together and finds amplification opportunities. Currently uses static routing rules — learned routing is planned for v2.0.

npx @nerviq/cli synergy-report     # Multi-agent synergy analysis

Synergy evaluates compound audit results, discovers compensation patterns (where one platform covers another's gaps), and ranks recommendations by cross-platform impact.

SDK — @nerviq/cli/sdk BETA

Programmatic access to all Nerviq capabilities. The SDK ships inside the @nerviq/cli package (no separate install) per MEMO-03 (B = BUNDLE, signed 2026-04-28).

Recommended (single install):

// Both forms work — same code path, both exported from @nerviq/cli.
const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/cli');
// OR for explicit SDK-shape (input validation, typed):
const sdk = require('@nerviq/cli/sdk');

async function main() {
  try {
    const result = await audit('.', 'claude');
    console.log(`Score: ${result.score}/100`);

    const platforms = detectPlatforms('.');
    console.log(`Active platforms: ${platforms.join(', ') || 'none detected'}`);

    const harmony = await harmonyAudit('.');
    console.log(`Harmony score: ${harmony.harmonyScore}/100`);
  } catch (error) {
    console.error(error instanceof Error ? error.message : 'Unknown SDK error');
    process.exitCode = 1;
  }
}

main();

Migration note (2026-04-29): Earlier docs referenced require('@nerviq/sdk') as a separate npm package. That package was never published. The SDK now ships bundled inside @nerviq/cli (zero additional install). Existing require('@nerviq/sdk') calls will fail with module-not-found; switch to require('@nerviq/cli') or require('@nerviq/cli/sdk'). See research/memo-03-sdk-decision-2026-04-28.md for the rationale.

Stable SDK surfaces: audit, harmonyAudit, detectPlatforms, getCatalog
Experimental SDK surfaces: synergyReport, routeTask

See sdk/README.md for full JavaScript examples, error handling guidance, and TypeScript usage.

Integration Contract Pack

Nerviq publishes a compact integration pack so external systems do not need to scrape CLI text:

• OpenAPI 3.1 contract from nerviq serve via GET /api/openapi.json
• Separate nerviq-mcp stdio JSON-RPC 2.0 transport for MCP hosts
• Generic audit webhook schema at contracts/audit-webhook-event.schema.json
• CI reference patterns in docs/ci-integration.md
• SDK usage guide in sdk/README.md
• First-tier release gate in docs/first-tier-integration-gate.md

See docs/integration-contracts.md for the full pack.

Category Definition Kit

Nerviq is positioned as the control plane for AI-enabled development:

• a repo-native governance layer for AI coding agents
• a cross-platform drift detector and operating model
• not a full SAST scanner, prompt library, or single-vendor IDE plugin

See docs/category-definition-kit.md for the category language, comparison matrix, operating model, and adoption playbook.

HTTP API — nerviq serve

Nerviq ships with a built-in local HTTP API for dashboards, wrappers, scripts, and language-neutral integrations:

npx @nerviq/cli serve --port 3000

Endpoints:

• GET /api/openapi.json — Live OpenAPI 3.1 contract for this serve instance
• GET /api/health — Server health check
• GET /api/catalog — Full check catalog
• GET /api/audit — Run audit on a directory and platform via query params
• GET /api/harmony — Cross-platform harmony data

All successful operational responses are wrapped in a JSON envelope:

{
  "data": {},
  "meta": {
    "version": "1.31.0",
    "timestamp": "2026-04-29T12:00:00.000Z"
  }
}

Pull the contract directly into Swagger UI, Postman, or internal tooling:

curl http://127.0.0.1:3000/api/openapi.json > nerviq-openapi.json

This HTTP surface is separate from the MCP transport. If your host expects Model Context Protocol over stdio, register the nerviq-mcp binary instead of pointing it at nerviq serve:

{
  "mcpServers": {
    "nerviq": {
      "command": "npx",
      "args": ["-y", "-p", "@nerviq/cli", "nerviq-mcp"]
    }
  }
}

Plugin System — nerviq.config.js

Extend Nerviq with custom checks via a config file in your project root:

// nerviq.config.js
module.exports = {
  plugins: [
    {
      name: 'my-company-checks',
      checks: {
        internalDocs: {
          id: 'internalDocs',
          name: 'Internal docs present',
          check: (dir) => require('fs').existsSync(`${dir}/docs/internal.md`),
          impact: 'medium',
          category: 'Quality',
          fix: 'Add docs/internal.md with team-specific guidelines',
        },
      },
    },
  ],
};

See docs/plugins.md for full plugin API reference.

GitHub Action

Add Nerviq to your CI pipeline:

# .github/workflows/nerviq.yml
name: Nerviq Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nerviq/nerviq@v1
        with:
          threshold: 60

The action outputs score, passed, and total for use in downstream steps. Fails the workflow if the score is below the configured threshold.

Certification

Earn a Nerviq certification badge for your project:

npx @nerviq/cli certify            # Run certification and display badge

Levels:

• Gold — Harmony score >= 80, all platforms >= 70
• Silver — Harmony score >= 60, all platforms >= 50
• Bronze — Any platform >= 40

All Commands

Options

CI output formats

Pipe audit output straight into the standard CI surfaces:

# PR comment (GitHub-flavoured markdown)
npx @nerviq/cli audit --format=markdown --out audit.md

# CI test report (JUnit XML — Jenkins, GitLab, GitHub Actions reporter)
npx @nerviq/cli audit --format=junit --out junit.xml

# Spreadsheet / dashboard ingestion (RFC 4180 CSV)
npx @nerviq/cli audit --format=csv --out audit.csv

Webhook delivery automatically retries transient failures twice by default. For authenticated internal endpoints, you can add custom headers such as:

npx @nerviq/cli audit \
  --webhook https://ops.example.com/nerviq/audit \
  --webhook-header "Authorization: Bearer $NERVIQ_WEBHOOK_TOKEN" \
  --webhook-header "X-Nerviq-Environment: production" \
  --webhook-retries 4

Generic webhook endpoints now receive a stable nerviq.audit.completed event envelope with:

• backward-compatible top-level platform, score, passed, failed, and results
• nested data and meta blocks for new consumers
• schema versioning through schemaVersion

For PR-focused audits, you can scope Nerviq to the working tree or an explicit base/head range:

npx @nerviq/cli audit --diff-only
npx @nerviq/cli audit --diff-only --diff-base origin/main --diff-head HEAD

--diff-only is intentionally a scoped review surface. It reports a diff-only changed-file audit score, lists the changed files it considered, and reminds you to run a full nerviq audit for the complete repo posture. Because diff-only scores are not directly comparable to full audit history, Nerviq blocks --diff-only --snapshot.

For multi-repo governance, Nerviq also supports inherited policy layers:

• .nerviq/org-policy.json in an ancestor directory for org defaults
• .nerviq/team-policy.json in the repo for team overrides
• .nerviq/repo-policy.json in the repo for repo-specific overrides

Inspect the resolved contract with:

npx @nerviq/cli org policy
npx @nerviq/cli org scan ./app ./api ./infra --json

For opt-in outcome-layer inspection, Nerviq can also run a local behavioral drift review:

npx @nerviq/cli deep-review --behavioral
npx @nerviq/cli deep-review --behavioral --snapshot --milestone baseline --tag "behavioral-baseline"
npx @nerviq/cli deep-review --behavioral --history
npx @nerviq/cli deep-review --behavioral --compare

Behavioral drift mode is intentionally guarded:

• It analyzes repository structure and instruction-vs-outcome mismatch heuristics
• It does not claim agent attribution without explicit evidence
• It is not marketed as SAST, semantic code review, or runtime analysis

nerviq setup now seeds a trust-boundary section in CLAUDE.md and an injection-defense starter hook for WebFetch, WebSearch, Read, Grep, Glob, and MCP-backed external-content flows. nerviq doctor validates that the declared starter hook still runs and logs suspicious prompt-injection patterns correctly.

Backed by Research

Nerviq is built on the NERVIQ knowledge engine — the largest verified catalog of AI coding agent techniques:

• 540+ research documents covering all 8 platforms
• 400+ experiments with tested, rated results
• 2,441 checks across 8 platforms (~300 unique governance rules × 8 platform adaptations), each with sourceUrl and confidence level (0.0-1.0)
• Every check is traceable to primary documentation or verified experiment
• Freshness: actively maintained on the verified tier (Claude Code, Codex, Copilot, Cursor — last full P0 source pass 2026-07-06); community-tier platforms (Gemini CLI, Windsurf, Aider, OpenCode) are re-verified opportunistically and their freshness is not guaranteed current. Items older than 90 days are confidence-weighted

Safety Modes

Nerviq provides explicit safety controls so you decide what it can touch:

Every write command supports --snapshot for automatic backup before changes.

Privacy

• Zero dependencies — nothing to audit
• Runs locally — audit, setup, plan, apply, governance, benchmark all run on your machine
• Deep review is opt-in — deep-review sends selected config for AI analysis, while deep-review --behavioral stays local and uses heuristic outcome-layer analysis only
• MIT Licensed — open source, no strings attached

Links

• npm: @nerviq/cli
• GitHub: github.com/nerviq/nerviq
• Website: nerviq.net

If Nerviq helped you, consider giving it a ⭐ on GitHub — it helps others discover the project.

What Nerviq Is — and Isn't

Best for: Teams going from zero governance to a strong baseline — fast. If you're starting with AI coding agents or have a few platforms running without consistent configuration, Nerviq gets you to a governed setup quickly.

Not designed for: Deeply customized setups with 20+ skills, agent teams, and bespoke MCP integrations. If you've already built advanced agent workflows, you may not need this.

Strongest at: AI agent governance, configuration intelligence, workflow policy hygiene, cross-platform alignment, and setup standardization.

Not a replacement for: Deep architectural review of business logic, runtime performance profiling, full SAST coverage, secret scanning, or security penetration testing. Nerviq focuses on how your AI coding agents are configured and governed — not on what your application code does.

Confidence levels: Every check includes a confidence score (0.0–1.0) and a sourceUrl linking to primary documentation. Checks marked heuristic are pattern-based and may produce false positives on non-standard project structures.

Feature maturity: