ovecc

CLI-first architecture intelligence: understand your codebase, then hold it to the rules you set.

Rust, one binary, no runtime. Runs offline, with no LLM in the loop.

---

What is Ovecc

Ovecc reads your repository once and builds a persistent model of it: every file, import, symbol, and call. From that single index it answers the questions you ask about a codebase:

• What breaks if I change this? (impact)
• Where are the dependency cycles and the tight coupling? (query, summary)
• What is duplicated, dead, or over-complex? (dupes, deadcode, health)
• What is insecure, and which dependencies have known CVEs? (security, audit)
• Where is the churn, and who owns this code? (hotspots)

It is an architecture database with deterministic commands, driven from the CLI, from CI, or by a coding agent over MCP.

React's dependency graph, rendered by ovecc export graph --html into a single file you can open directly, no server or CDN needed.

What it costs an agent

Asking whether a new import closes a dependency cycle, on zod, with Claude Sonnet 4.6:

One run, one model, one question, and agent runs are not deterministic. Method and the cases where ovecc loses are in docs/benchmark/BENCHMARKS.md.

Write your architecture down, and hold the code to it

Most tools stop at reading the code. Ovecc goes one step further: you write down which parts of your codebase are allowed to depend on which, in one small file, and every build checks the real code against it.

Here's one for a small app:

# .ovecc/architecture.toml

[[component]] name = "api" paths = ["src/api/**"] depends_on = ["core"] # the api may use core, nothing else

[[component]] name = "features" paths = ["src/features/**"] depends_on = ["core"] slices = true # and features may not import each other

[[component]] name = "core" paths = ["src/core/**"] deny_capabilities = ["network"] # pure domain: no fetch, no I/O max_cyclomatic = 8 # keep core functions simple

Run the check and every breach comes back with a file and a line:

$ ovecc architecture check

Divergences (1): [High] api -> features is not in the contract src/api/routes.ts:2 (../features/billing/service)

Slice isolation breaches (1): [High] features/billing -> features/users breaks slice isolation src/features/billing/service.ts:1 (../users/repo)

Denied capabilities used (1): [Medium] core uses denied capability 'network' src/core/pricing.ts:3 (fetch)

Complexity budgets exceeded (1): [Medium] core: 1 function over the cyclomatic budget src/core/pricing.ts:8 (cyclomatic 11 > 8)

Four kinds of decay caught in one run: a layer reaching where it shouldn't, a feature tangling into its neighbor, a network call inside code you promised was pure, and a function creeping past the budget you set. Put ovecc architecture check in CI and the pull request fails on the drift, instead of a reviewer noticing three months later, or nobody noticing at all.

Don't have one yet? ovecc architecture suggest recognizes the architecture you already follow (Feature-Sliced, bulletproof-react, Clean/Hexagonal, an Nx workspace) and writes the file bound to your real folders. Or ovecc architecture init drafts it from your actual import graph, so day one starts green and you tighten from there. The details are in the contract reference below.

Install

npx ovecc index .

npm pulls only the binary for your platform. npm i -g ovecc keeps it on your PATH.

Prebuilt binaries are also on the latest release: Linux x86_64 and aarch64, Windows x86_64, macOS arm64. There is nothing else to install: DuckDB is bundled, there is no runtime, and it works fully offline. A rolling dev build ships on every push to main.

The macOS binary is unsigned, so Gatekeeper quarantines it when a browser downloads it. Clear the flag once and it runs:

xattr -d com.apple.quarantine ./ovecc-macos-aarch64

curl and npm don't set that flag, so npx ovecc never runs into it.

Build from source

Builds with stable Rust (on Windows use the windows-gnu toolchain; DuckDB is compiled from source on the first build). The step-by-step Windows setup is in docs/dev/SETUP.md.

cargo build --release

cargo test --workspace

The binary is ovecc (crates/ovecc-cli).

Quick start

ovecc index .                 # parse, resolve, and persist the model into .ovecc/

ovecc summary # coupling, density, cycles, risk score ovecc advise src/server.ts # the agent-facing surface: findings for one file, each with a fix ovecc diagnose # named architectural smells, evidence + curated remediation ovecc history max_cyclomatic # trend one metric across every index run — is it getting better? ovecc violations # architecture + security findings, with file:line ovecc violations --write-baseline # accept today's backlog; later runs surface only what is new ovecc metrics # per-component fan-in/out, instability, abstractness, distance ovecc components # the components the graph recovers, and what they hold ovecc coupling # files that change together but do not import each other ovecc security # secrets, insecure patterns, weak crypto, tainted flows ovecc audit # offline OSV dependency vulnerabilities ovecc impact Billing # blast radius of a change ovecc hotspots # churn x coupling x ownership debt ranking ovecc dupes # duplicated code (clone families), with file:line ovecc health # functions over the complexity thresholds (oxc) ovecc deadcode # unused exports + unreachable files (oxc + reachability) ovecc fix # apply the mechanical fixes for those findings (dry-run by default) ovecc query "cycles" # real elementary dependency cycles (A -> B -> A) ovecc report # one-shot architecture report (markdown or json) ovecc gate # CI gate: fail a PR on new cycles / violations ovecc review # the named new defects a change introduced (file:line + cycle witnesses) ovecc architecture init # draft .ovecc/architecture.toml from the graph, or a --template ovecc architecture check # gate the code against the contract, with file:line ovecc architecture suggest # recognize which architecture the repo already follows ovecc export graph --html # interactive dependency-graph viewer, one self-contained offline file ovecc capabilities # machine-readable contract: commands, metrics, rules, exit codes ovecc mcp # MCP server over stdio: expose every command as an agent tool

If you only ever run three of these, run advise before editing a file, diagnose instead of violations (same findings, plus the fix and when *not* to act), and history to see whether the codebase is improving. summary prints these as a footer, because a list read once loses to output read every run.

Every command renders as text, json, ndjson, or markdown via --format (plus sarif for GitHub code scanning and codeclimate for GitLab Code Quality) and returns stable exit codes for CI. The full per-command reference, with real output, is in docs/COMMANDS.md. For pull requests, the repo ships a drop-in GitHub Action that indexes base and head, comments the review findings on the PR, and gates on severity.

The architecture contract in depth

.ovecc/architecture.toml is your intended architecture as code. Each component claims files by path glob; depends_on is the allow-list of what it may import. ovecc architecture init writes the first draft from the graph you already have, so every entry mirrors a real import and day one has zero violations. Prefer a known shape? init --template fsd (or bulletproof-react, nx-workspace, clean-architecture) drops in a reference architecture, and the diff against your code becomes your migration plan.

From then on, each run compares code to contract and names what it finds:

• a divergence is an import the contract does not allow,
• a bypass is an import that skips a component's declared public interface,
• an absence is a dependency you declared but never actually use.

Three more checks read past the import graph (JS/TS):

• slices = true isolates a component's sub-folders from each other, the rule behind Feature-Sliced Design and bulletproof-react, with FSD's @x public-API escape hatch honored.
• deny_capabilities forbids a component the ambient powers that break purity: network, filesystem, storage, dom, process, time, random. A Date.now() in a pure domain comes back with its file and line.
• max_cyclomatic / max_cognitive put a per-function complexity budget in the contract, so "keep the core simple" becomes a rule the build can check.

Interfaces are virtual: you list a component's public entry files and ovecc enforces them on the real imports, so you get encapsulation without barrel files or an extra re-export layer.

Adoption is meant to be gradual. check --freeze records today's violations in a per-component baseline (one line each, so branches merge cleanly), gates only new ones from then on, and drops entries as you fix them so the count never climbs. Agents can read the contract before editing, through ovecc architecture show or the ovecc_architecture MCP tool.

Rules

Simpler, language-neutral policy lives in .ovecc/config.toml, is enforced at index time, and shows up in violations (and the gate CI check):

# Forbid a module-to-module dependency.

[[rules.boundaries]] name = "billing must not depend on user" source = "billing" target = "user" allowed = false severity = "high"

Ban imports by specifier pattern (exact, prefix*, *suffix, or *infix*).

[[rules.banned_imports]] name = "no-deprecated-lodash" pattern = "lodash" message = "use es-toolkit instead" severity = "medium"

Silence a single finding inline with // ovecc-ignore (or // ovecc-ignore-next-line, and # ovecc-ignore in Python) on the offending line; it is dropped at index time.

For CI and coding agents

Every command is built to run in a pipeline: pick a format with --format, rely on stable exit codes (0 clean, 1 a --fail-on threshold crossed, 2 and up a real error), and emit sarif or codeclimate for GitHub and GitLab. The drop-in GitHub Action wires review into pull requests.

The same analysis is available to coding agents over the Model Context Protocol. ovecc mcp runs an MCP server over stdio that exposes each command as a tool (ovecc_summary, ovecc_impact, `ovecc_archit