Build & Integrate / For Agents

Nerviq for AI coding agents

If you are an autonomous AI coding agent — or building one — this page is the contract. It tells you how to call Nerviq, what it returns, what each value means, and where the boundaries are.

Agent-callableMCP / SDK / JSONContinuous governance

Why agents should call Nerviq

Cross-platform configuration governance is itself an agent-relevant concern.

An autonomous coding agent operating in a repo needs to know whether the configuration it is reading is current, consistent, and aligned with the other agents that work on the same repo. That is exactly what Nerviq surfaces. An agent that calls nerviq audit --json at the start of a task gets a machine-readable picture of:

  • What other agents are configured (detectedConfigFiles)
  • Whether their instructions agree (harmonyScore)
  • What is stale or contradictory (staleReferences)
  • What the highest-leverage improvements are (topNextActions)
  • What OWASP categories are involved (shallowRiskHints[].owaspTags)

The agent can then make informed decisions about whether to follow ambient instructions, flag contradictions to the user, or invoke a fix.

Three call surfaces

Pick the one that fits the agent's runtime.

JSON-RPC 2.0 stdio

MCP

Run nerviq-mcp as an MCP server and register it in the host's MCP config (Claude Code, Codex CLI, Cursor, etc.). The agent gets check_score, get_config, apply_fix tools.

Best when the agent already speaks MCP.

Node typed API

SDK

const { audit, harmonyAudit } = require('@nerviq/cli') — typed entry points for Node-based agent loops. Same shape as --json; lower latency than spawning a subprocess.

Best for agents written in Node.

--agent-mode --json

CLI subprocess

nerviq audit --agent-mode --json emits a stable JSON envelope with recommendation, remediation_command, and machine-friendly exit codes (0 / 1 / 2). Works from any language.

Best for cross-language agents.

The four governance loops

Where the agent fits in Nerviq's continuous-governance model (POS-05).

  1. Local Dev loop. When the agent edits CLAUDE.md, AGENTS.md, .cursor/rules/*, or .mcp.json, it should re-run audit afterward. nerviq watch --alerts automates this for human-in-the-loop sessions.
  2. PR / CI loop. When the agent opens a PR, run nerviq pr-check --threshold 70 --json. Exit 1 means the gate failed; the JSON envelope includes the markdown body suitable for posting as a PR comment.
  3. Org loop. For agents operating across multiple repos in an org, nerviq org scan repo1 repo2 ... --json returns a fleet rollup. The agent can use score bands to decide where to spend attention.
  4. AI behavior loop. When the agent finishes a task, it can record outcome via nerviq feedback --key <K> --status accepted|rejected|deferred --effect positive|neutral|negative. This feeds the local suggest-rules learning loop. (Future: rule-adherence measurement per PROD-02 / ZORO.)

JSON contract — what to expect

The fields agents most often consume.

{
  "score": 73,
  "organicScore": 54,
  "platform": "claude",
  "passed": 52,
  "failed": 37,
  "harmonyScore": 78,
  "detectedConfigFiles": ["CLAUDE.md", ".claude/settings.json", "AGENTS.md"],
  "staleReferences": {
    "count": 4,
    "byKey": {
      "agent-config-script-not-in-package-json": 3,
      "agent-config-framework-version-mismatch": 1
    },
    "topSample": [
      { "key": "agent-config-script-not-in-package-json",
        "file": "AGENTS.md", "line": 3,
        "fix": "AGENTS.md tells the agent to run \`npm test\`, but \`scripts.test\` is not defined in package.json..." }
    ],
    "headline": "4 stale references found in agent docs."
  },
  "shallowRiskHints": [
    { "key": "...", "severity": "...", "file": "...", "line": 0,
      "fix": "...", "owaspTags": ["agentic-top-10:tool-instruction-integrity"] }
  ],
  "liteSummary": {
    "topNextActions": [
      { "key": "claudeMd", "name": "...", "impact": "critical",
        "fix": "...", "remediation_command": "nerviq fix claudeMd",
        "projectedScoreDelta": 12, "projectedScoreAfter": 85 }
    ]
  },
  "suggestedNextCommand": "nerviq audit --diff-only"
}

Self-governing agent pattern

A reference loop the agent can run autonomously.

  1. At task start: nerviq audit --agent-mode --json. Read staleReferencesfirst; if count > 0, surface to the user before acting.
  2. If harmonyScore < 60 AND the task touches multi-platform configuration, run nerviq harmony-sync --fix --json as a separate decision (not silently).
  3. Make the actual code change.
  4. Re-audit: nerviq audit --diff-only --drift-mode ci --json. Exit 1 means the change introduced regression; surface this and offer rollback.
  5. Record the outcome: nerviq feedback --key <the rule that drove the change> --status accepted|rejected|deferred --score-delta <observed>. The learning loop benefits.
Don't bypass user consent

An autonomous agent should NOT silently apply --apply --auto on critical fixes that materially modify governance posture (deny rules, MCP permissions, hooks). Surface the plan, let the user approve, then apply. The CLI's --apply is gated on --autofor exactly this reason — so the agent can't bypass user consent through a single flag.

What Nerviq does NOT cover (for agents)

Agents shouldn't escalate Nerviq beyond its scope.

  • Runtime governance. Nerviq audits config-time. For runtime policy enforcement, identity, sandboxing, and SRE telemetry, see Microsoft Agent Governance Toolkit.
  • Code quality / SAST. Nerviq does not analyze the code an agent produces. Pair with SonarQube, Semgrep, or similar.
  • Prompt evaluation. Nerviq doesn't test prompts. Pair with promptfoo for adversarial / red-team testing.
  • Single-platform deep linting. If the agent only touches one platform's config (e.g., Cursor only), cursor-doctor goes deeper there. Nerviq is the breadth layer.

Governance overhead

What it costs the agent to call Nerviq, in wall-clock terms. Honest measurements, not aspirational targets.

Every call adds a small amount of wall-clock overhead. We measure this honestly because the agent budget directly translates to user-perceived task latency.

FixtureFilesFirst-run audit% of 60s reference task
Synthetic small repo3~250 ms0.42%
Site repo (Next.js)~120~494 ms (post-AI-12a, ~600 ms pre)0.82%
Research repo~600~700 ms1.17%

Working budget: <2% wall-clock cumulative under continuous use, <1% per-call on repos under 200 files. This is a revision (downward in honesty) from the original "<1% overhead" aspiration once real measurements landed. See AI-12 memo for methodology + the AI-12a CLI optimization that produced the post-Round-11 numbers above.

Reference links

When in doubt, read the source.