Skip to main content

What is ovecc

ovecc is a CLI-first architecture intelligence engine. It builds a deterministic, persistent model of a repository and answers architectural questions about structure, change impact, coupling, drift, ownership, security, and long-term maintainability — directly from your terminal, your CI, or your coding agent.

Repository → deterministic analysis → architecture database → insights → optional AI consumption

ovecc is not a code generator, a chat tool, or a dashboard. It is an architecture database plus deterministic analysis commands that make architecture queryable and enforceable. AI-assisted coding raises both code output and the risk of architectural erosion; ovecc exists for that problem. An LLM may consume ovecc's output (see the MCP server), but it is never the source of truth.

Sixty seconds of ovecc​

ovecc index .                 # parse, resolve, and persist the model into .ovecc/
ovecc summary                 # coupling, density, cycles, risk score
ovecc violations              # architecture + security findings, with file:line
ovecc review                  # the NAMED new defects a change introduced
ovecc impact billing          # blast radius of a change
ovecc fix                     # apply mechanical fixes (dry-run by default)
ovecc export graph --html     # interactive dependency-graph viewer, one offline file
ovecc mcp                     # expose every command to your coding agent

Every command renders as text, json, ndjson, or markdown (plus sarif for GitHub code scanning and codeclimate for GitLab), and returns stable exit codes for CI.

What ovecc can tell you​

QuestionCommand
How healthy is this codebase right now?summary, report
What breaks if I touch this module / API / table?impact, query
What is wrong, exactly, and where?violations, security, health
What did this change introduce?review, gate, diff
Which architectural smells exist, and how do I fix them?diagnose, advise
Which dependencies are vulnerable?audit
What code is dead, duplicated, or too complex?deadcode, dupes, health
Can any of that be fixed mechanically?fix
Is the codebase getting better or worse over time?drift, history
Where does refactoring pay off first?hotspots

Design guarantees​

  • Deterministic before generative. Every finding is traceable to explicit facts; the same input produces the same output. An unchanged database renders byte-identical output across runs.
  • Local and private. Indexing, analysis, and explanation run entirely on your machine. Nothing is ever sent anywhere. The single opt-in exception is audit --fetch, which downloads public vulnerability advisories — and only when you pass the flag.
  • Incremental. Re-indexing an unchanged repository re-parses nothing (a content-addressed parse cache and differential sync make re-runs fast) and writes only a new snapshot.
  • Machine-consumable by design. Every command is exposed 1:1 as an MCP tool, every JSON payload ships in a stable, self-describing envelope, and capabilities publishes the full contract so an agent can drive ovecc without reading these docs.

How it works​

  1. ovecc index walks the repository, parses source files, resolves imports (including real tsconfig paths and package exports), extracts symbols, call edges, HTTP APIs, and database table accesses, ingests Git history (churn and ownership), evaluates governance rules and security detectors, and persists everything into a local database under .ovecc/.
  2. Every other command reads that model — no re-parsing, no network. Queries over the graph are sub-second even on very large repositories.
  3. Each index run stores a snapshot, so change-scoped commands (review, gate, diff, drift, history) can compare any two points in time.

Language support​

The JavaScript/TypeScript family has the deepest support (module resolution, per-function complexity, exports and dead-code analysis, taint tracking). Python, Go, Rust, and C++ are covered by a specification-driven adapter feeding the same language-agnostic model, so dependency resolution, the call graph, and the rules work across every supported language. See the language matrix.

Where to go next​

:::info Early stage ovecc is currently version 0.1.0 and under active development. The command surface documented here is generated against the real binary, but details may evolve between releases. schema_version in JSON output only changes on breaking changes — additive fields never bump it. :::