AI agents & the JSON contract

ovecc is built to be consumed by AI systems first. The design inverts the usual relationship: instead of an LLM guessing at architecture from file contents, the agent queries a deterministic model and reasons over facts. An LLM may consume ovecc's output; it is never the source of truth.

Start with the contract

ovecc capabilities --format json

One call returns every command (with key parameters and a read_only flag), every metric and rule with a definition, the severity vocabulary, the exit-code contract, and the output formats — enough to drive an end-to-end audit without reading these docs. Details: capabilities.

The JSON envelope

Every command's JSON is wrapped in a stable, self-describing envelope:

{
  "schema_version": 1,
  "tool": { "name": "ovecc", "version": "0.1.0" },
  "command": "summary",
  "meta": { "metrics": { "...": {} }, "rules": { "...": {} } },
  "data": { "...": {} }
}

Contract rules an agent can rely on:

• schema_version is an integer; additive changes never bump it. Detect new fields by key presence, not by gating on the number.
• meta carries metric/rule definitions so values are interpretable without a docs site. Pass --no-meta once you've read them (the MCP server does this automatically).
• Paths are repo-relative and POSIX-normalized in every format.
• Output is byte-identical across runs for an unchanged database — cache aggressively.
• Exit codes are stable (see the table); exit 1 is "threshold crossed", not "crash", and the full payload is still emitted.

Consumption patterns

Over MCP (recommended)

Register ovecc mcp with the client and let the agent call tools live — see the MCP server guide.

Direct CLI invocation

Anything that can run a subprocess can consume ovecc:

ovecc --repo /path/to/repo --format json --no-meta violations --severity high

ndjson streams one finding per line (after a leading meta record) for pipelines that process findings incrementally.

Context slices for prompts

To give an external LLM the facts about one element without handing it the whole repository:

ovecc export context src/core/db.ts --format json

The slice contains dependencies, dependents, call paths, related APIs/schemas, and findings — deterministic, compact, and safe (nothing is transmitted; it prints).

A "before editing" ritual for agents

The highest-leverage pattern, in three calls:

1. ovecc_advise <file> — what's already wrong here and what the established fixes are.
2. ovecc_impact <file> — the blast radius: who is affected if this edit changes behavior.
3. After editing and re-indexing: ovecc_review — did the change introduce new cycles, findings, or duplication? A pass verdict is a deterministic, evidence-backed claim the agent can report verbatim.

Severity → action mapping

Findings carry machine-readable remediation actions (e.g. rotate_and_externalize_secret, sanitize_tainted_flow, break_cycle, remove_unused_export), and each is flagged auto-fixable or not. A safe policy:

Finding property	Agent behavior
auto-fixable: yes	Delegate to ovecc_fix (dry-run, inspect, then apply: true)
critical / high, not auto-fixable	Surface to the human with the evidence and suggested action
Taint findings	Treat as review items — they are explicit reachability over-approximations