Skip to main content

Quickstart

This walk-through uses a small TypeScript/Express storefront called acme-shop. Every output below is real ovecc output. Substitute your own repository — any supported language works.

0. Get ovecc​

If you have not installed it, npm is the shortest path — it pulls only the binary for your platform:

npm i -g ovecc

Every ovecc below also works as npx ovecc with nothing installed at all.

1. Initialize​

From the repository root (or pass --repo <path> from anywhere):

$ ovecc init
Wrote ~/projects/acme-shop/.ovecc/config.toml
Added .ovecc/ to .gitignore

Next steps:
  ovecc index .        build the architecture model (fully local)
  ovecc summary        one-screen health
  ovecc diagnose       named architecture smells, each with a fix
  ovecc mcp            expose every command to your coding agent

init is idempotent and optional — index works without it — but it writes a fully commented config.toml (every value shown is the default) and git-ignores ovecc's local state for you.

2. Index​

$ ovecc index .
Indexed repository: ~/projects/acme-shop
Database: ~/projects/acme-shop/.ovecc/graph.db
Snapshot: snapshot:8230ae07ba488166774d0865
Files scanned: 9
Files indexed: 9
Files parsed: 9
Files from cache: 0
Modules: 6
Dependencies: 17
External dependencies: 5
Symbols: 27
Calls: 51
APIs: 4
Tables: 3
Commits ingested: 1

One pass parsed the sources, resolved every import, extracted symbols, call edges, HTTP routes (APIs: 4) and SQL table accesses (Tables: 3), ingested Git history, and persisted a snapshot of it all. Re-runs are incremental: unchanged files come from a content-addressed parse cache (Files from cache).

3. Get the one-screen picture​

$ ovecc summary
Repository: ~/projects/acme-shop
Snapshot: snapshot:8230ae07ba488166774d0865
Files: 9
Modules: 6
Dependencies: 17
External dependencies: 5
Circular deps: 0
Boundary violations: 1
Coupling density: 23.33%
Risk score: Medium

Hotspots:
  routes (score 8, fan-in 1, fan-out 2, instability 0.67)
  services (score 8, fan-in 1, fan-out 2, instability 0.67)
  core (score 6, fan-in 3, fan-out 0, instability 0.00)
  ...

4. See what's wrong — with file:line evidence​

$ ovecc violations
Violations: 14

[Medium] Banned import: lodash*
  Rule: banned-import/no-lodash
  Type: ForbiddenImport
  Evidence: src/utils/helpers.ts:1 (lodash/groupBy)

[Medium] Weak hash algorithm: MD5
  Rule: security/weak-hash
  Type: WeakCrypto
  Evidence: src/utils/auth.ts:4 (MD5)

[Low] Unused export: formatEuros in src/utils/helpers.ts
  Rule: unused-export
  Type: UnusedExport
  Evidence: src/utils/helpers.ts:10

[Low] Unused file: src/legacy/old-report.ts
  Rule: unused-file
  Type: UnusedFile
  Evidence: src/legacy/old-report.ts:1
...

Every finding names its rule, carries a severity, and points at exact evidence. Security findings get their own focused view with ovecc security, dead code with ovecc deadcode, complexity with ovecc health.

5. Ask an architectural question​

$ ovecc query "rdeps core"
Dependents: 3
  routes
  services
  src

$ ovecc explain core
# core

`core` is foundational: 3 component(s) depend on it and it has no dependencies of
its own, so changes here ripple outward. It lies on 3 traced call path(s).
...

query, impact, and explain all answer from the persisted graph — deterministically, offline, in well under a second.

6. Let ovecc clean up after itself​

$ ovecc fix
Fix plan: 10 change(s), 1 skipped — dry-run (pass --apply to write)

[planned] remove_unused_dependency — package.json:1 (unused-dependency)
    remove "left-pad" from dependencies

[planned] remove_unused_file — src/legacy/old-report.ts:1 (unused-file)
    delete file (no entry point reaches it)

[planned] remove_unused_export — src/utils/helpers.ts:10 (unused-export)
    - export function formatEuros(cents: number): string {
    + function formatEuros(cents: number): string {
...

fix is dry-run by default and only ever performs mechanical, verifiable edits. Pass --apply when the plan looks right.

7. Catch regressions on every change​

Index again after a change and ask what the change introduced:

$ ovecc index . && ovecc review
Review: fail (risk Critical) snapshot:85ee2372… -> snapshot:5ab78093…
  - 1 new dependency cycle(s): core ↔ services
  - 6 new security finding(s)
  ...
New cycles:
  core <-> services
    src/core/db.ts:2 imports ../services/billing -> src/services/billing.ts
    src/services/billing.ts:1 imports ../core/db -> src/core/db.ts

This is the heart of the PR review loop: review names the new defects, gate turns them into a pass/fail CI verdict.

8. Write the architecture down​

Everything so far read the code as it is. The contract states how it is supposed to be, and holds the code to it:

$ ovecc architecture init
Wrote .ovecc/architecture.toml (6 components, 9 declared dependencies).

Every depends_on entry mirrors an import that exists today, so the contract starts with zero violations. Delete the entries you regret, and each deletion becomes a divergence the build reports:

$ ovecc architecture check --fail-on high
Divergences (1):
  [High] core -> services is not in the contract
    src/core/db.ts:2 (../services/billing)

The full story is in the architecture contract.

Where to go next​

  • Core concepts — snapshots, modules, findings, and why everything is deterministic.
  • The architecture contract — write your architecture down and gate CI on it.
  • Guides — task-oriented workflows: auditing, PR reviews, security, dead code, drift.
  • Command reference — every command, flag by flag.
  • MCP server — hand all of this to your coding agent.