Nerviq

Continuous cross-platform configuration governance for AI coding agents. Audit, score, and align agent config across 8 platforms — at config-time, before runtime, as a recurring layer (not a one-shot audit). Four lifecycle loops: local dev watch → PR/CI gate → org fleet posture → AI behavior compliance. (Pre-runtime config layer; complements runtime governance like Microsoft AGT and code-quality tools like SonarQube.)

8 Platforms Supported

Nerviq audits, sets up, and governs AI coding agent configurations for 8 platforms:

10 Stack-Specific Languages

What Nerviq Does

Most repos use more than one AI coding agent — Claude and Cursor, Copilot and Codex, Gemini and Windsurf. Their configs drift silently. Nerviq is the neutral control plane that detects that drift, scores it, and helps align it.

Headline value: stale-reference detection

nerviq audit runs a deterministic mini-scan on every invocation that catches the most common form of agent-config rot:

• 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 "this is a Next.js 15 app" but package.json declares next@^16.x. Flagged.

These checks run without a flag, with near-zero false positives, and are surfaced as a top-line section in audit output. Buyers and reviewers can verify each finding in 30 seconds — cat package.json against the agent doc. This is what cross-platform configuration governance looks like at the file boundary.

Cross-platform Harmony

When your repo has 2+ platforms configured, nerviq audit leads with the Harmony Score — cross-platform alignment — before any single-platform results. Single-platform repos still get a normal per-platform audit.

  $ nerviq audit
  Detected: Next.js + TypeScript + Claude + Cursor

  Harmony Score: 78/100 — 3 drift issues across 2 platforms (Claude Code + Cursor)
  Run `nerviq harmony-audit` for the full cross-platform report.

  Platform: Claude Code
    CLAUDE.md .............. 23/25 checks passed
    .claude/settings.json .. 6/9 checks passed

  Platform: Cursor
    .cursor/rules/ ......... 14/16 checks passed
    .cursorrules ........... 4/7 checks passed

  Drift: trust-mode mismatch (Claude relaxed / Cursor strict)
         MCP coverage gap — 3 servers in Claude, 1 in Cursor
         format-on-save hook missing from Cursor

  3 suggestions → `nerviq harmony-sync` to align.

Single-platform repos still work the same way — the Harmony Score only appears when 2+ platforms are detected. Use --no-harmony-first to suppress it even on multi-platform repos.

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 --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)

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.30.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: daily changelog scanning across all 8 platforms, weekly liveness sweep (6 automated checks), monthly quality review, quarterly cross-validation — 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
• AGPL-3.0 Licensed — open source

Links

• npm: @nerviq/cli
• GitHub: github.com/nerviq/nerviq
• Website: nerviq.net
• Discord: Join the community

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: