Know your codebase. Enforce your intent.

See It on a Real Codebase

No sales deck. This is IntentWeave analyzing its own repository, live — click around.

Context Package (RAG)

Same query returns better neighbors as your repo evolves, zero extra LLM calls.

Explore the context package →

Doc ↔ Code Map

Every doc, grounded to real code. 1,054 annotations, zero LLM calls, computed in under a second.

Explore the map →

Rules Catalog

Structural and behavioral rules, checked against your real call graph — not just your imports.

See the rules run →

---

Quick Start

npm install -g @intentweave/cli
cd your-project
iw init

Step 1 — Observe (CARI Evidence Engine):

iw index build                         # < 3 seconds, zero API calls

Step 2 — Enforce (Intent Engine):

iw intent check                        # check rules.yaml against the index

Step 3 — Deliver (Insights Book):

iw index export --book                 # open insights-book.html

The Insights Book shows your architecture, violations grouped by domain (structural / behavioral / documentary), per-ADR flow diagrams, call graph, and a living documentation score — all from a single local SQLite file. No LLM, no servers, no API keys required for steps 1–3.

More CARI Evidence Engine commands

iw index retrieve "authentication"     # ranked file retrieval
iw index connections "AuthService"     # cross-layer connections + gaps
iw index layers-infer                  # auto-infer architectural layers
iw index clones                        # exact duplicate detection
iw index circular-imports            # import cycle detection
iw index hotspot-priority            # high-churn, low-doc files

More Intent Engine commands

# Extract rules from an ADR once (requires LLM)
iw intent extract docs/ADR-001.md --provider openai --output .iw/rules.yaml

# Enforce all three domains: structural + behavioral + documentary
iw intent check
iw intent check --domain behavioral    # Mermaid sequence/flow rules
iw intent check --domain documentary   # coverage + stale docs + terminology

# PR mode: only changed files, only high severity
iw intent check --changed src/auth.ts --severity high --format json

# Regression gating: fail only if violations increased
iw intent check --baseline .iw/baseline.json

# Living Documentation
iw intent living                       # coverage, stale docs, terminology
iw intent score                        # composite A–F score (4 dimensions)

---

How It Works, In Practice: Two Products, One Platform

CARI Evidence Engine — always $0

A zero-cost SQLite index built from your code’s AST, document keywords, and git history. No LLM. No servers. No API keys. 60+ query modes, architecture visualization, community detection, clone detection, call graph, and more — in under 3 seconds. The foundation. Always free. Always local.

Intent Engine

Three enforcement domains in one pass: structural (import graphs), behavioral (Mermaid sequence/flow rules), and documentary (coverage, staleness, terminology). All at $0 after a one-time LLM extraction step.

Semantic Enrichment (optional)

Selectively apply LLM extraction to the files CARI flags as highest-value. Budget-controlled, stored in the same SQLite index. Unlocks decision tracking, diagram validation, and cross-doc contradiction detection.

Knowledge Graph (optional)

Persist to Neo4j for full-scale semantic queries and impact analysis. CypherLite lets the same queries run against both SQLite and Neo4j — swap backends without changing code.

---

What You Get

Architecture Visualization

Auto-infer architectural layers from your import graph. Generate an interactive HTML report with layered views, community clusters, dependency trees, vertical slice detection, and optional LLM-generated names — all in a single shareable file. No similar tool exists for this.

Ranked Retrieval

Find the right files for any topic. CARI combines code structure, document semantics, and git history into a single ranked score with explanations.

Connections & Gaps

See which entities co-occur in docs, co-change in git, or share code imports — and where these signals disagree. Disagreement reveals hidden couplings.

CI Drift Checks

Catch stale documentation before it ships. iw index check detects docs that reference changed code and reports them as CI warnings.

Diagram Validation

LLM reads ASCII art and Mermaid diagrams in your docs, extracts component flows, and CARI validates them against the actual import graph. The diagram in your docs is the architecture spec — no YAML config needed. Run iw index arch-check --from-scan docs/*.md --provider openai.

Decision Tracking

Selective LLM extraction finds decisions in your ADRs and docs. CARI checks which decisions have code grounding and which are unimplemented or stale. Available via the cari_enrich MCP tool, which scores files by impact (hotspots, orphans, hubs, coverage gaps) for LLM enrichment candidacy.

Dead Feature Detection

Combine unused exports, undocumented symbols, and stale files to surface likely dead features. Three independent signals means fewer false positives.

Plugin Architecture

Install only what you need. Core ships zero-cost. Add LLM capability, Neo4j persistence, or language support (Swift, Python) as plugins. iw plugin add llm — done.

---

Benchmarks

Measured on the IntentWeave monorepo (264 code files, 7 docs, 5316 symbols):

| Metric | Structured | Full-Depth | | ------------------------- | ----------: | ----------: | | Build time | 1.1 s | 2.8 s | | Annotations | 6,721 | 11,533 | | Grounded (linked to code) | 2,548 (38%) | 7,360 (64%) | | Co-occurrence edges | 1,099 | 2,631 | | LLM calls | 0 | 0 | | Index file size | ~2 MB | ~4 MB |

Full-depth mode adds +72% more annotations and +189% more grounded links by scanning document body text with dictionary matching and IDF-based noise filtering.

---

How It Works

Source Code ──► AST Extraction ──► Symbol Registry
              (TS/JS/Swift/Python)        │
Markdown Docs ──► Keyword Extraction ──►│──► Annotation Engine ──► SQLite Index
                                        │         │                    │
Git History ──► Co-change Analysis ─────┘    IDF Filtering        .iw/index.db
                                                                       │
                                                    ┌──────────────────┤
                                                    │                  │
                                              CLI Queries        MCP Tools
                                          (retrieve, check,   (cari_retrieve,
                                           connections,         cari_connections,
                                           report)              cari_check)

No servers to run. The index is a single SQLite file. Queries are predefined SQL — sub-100ms latency. The entire pipeline is local and deterministic.

---

Ensure the Intent in the Code (Semantic Rule Checking 0.11.0)

Vibe-coding AI agents and busy developers can easily implement against architectural decisions. IntentWeave turns your Architectural Decision Records (ADRs) and conventions into enforceable code constraints—without requiring Neo4j or LLMs in your CI.

1. Extract and Enforce ADRs

Translate intent from plain-text markdown and check it in CI milliseconds later.

# LLM-assisted: Extract architectural constraints from an ADR into .iw/rules.yaml
iw intent extract docs/ADR-003.md --provider openai --output .iw/rules.yaml

# CI Validation: Check if the codebase violates any architectural rules
iw intent check --changed src/auth.ts --severity high --format text

• iw intent extract options: --provider (e.g. openai), --output (specify rules file path).
• iw intent check options: --changed <files> (comma-separated, incremental CI mode), --severity <level> (filter by high/medium/low), --rule-id <id> (check specific rule), --format <format> (json/text). Runs as iw index rules-check under the hood — see the CLI Reference for every option.

2. Architecture Diagram Validation

Let the diagram be the specification. Extract component flows directly from Mermaid or ASCII diagrams in your markdown files and validate them against actual code imports.

# Validate AST imports against flows found in diagrams
iw index arch-check --from-scan docs/ARCHITECTURE.md --provider openai --strict

• arch-check options: --from-scan <paths> (extract on-the-fly), --from-diagrams (use previously enriched .db diagrams), --strict (fail on undocumented flows), --refresh (ignore cache).

3. Built-in Intent Enforcements (Zero Config)

No LLM or config file required. These built-in rules run via fast AST analysis:

• Deprecated active callers: Find active components ignoring @deprecated signals.

  iw index deprecated-callers --limit 50

• Internal boundary violations: Enforce @internal and _ prefix visibility across package boundaries.

  iw index internal-violations --changed src/ --no-underscore

• Type safety bypassed: Track down as any casts in high-fan-in (highly depended upon) files.

  iw index type-assertions --kind as_any --risk-sort

• Test-intent drift: Detect tests whose descriptions refer to code symbols that no longer exist.

  iw index test-intent --format json

These rules run offline in milliseconds and plug straight into CI. Let standard tools review formatting, and let IntentWeave guard the architectural intent.

---

Architecture Analysis & Visualization

CARI automatically infers your project’s architectural layers from the import graph and generates an interactive HTML report — zero cost, zero configuration:

iw index layers-infer                  # infer layers from import topology
iw index layers-check                  # validate imports against layer boundaries
iw index export --html                 # generate standalone architecture.html

The HTML report includes three interactive views:

• Layers view — files positioned in their inferred tier (foundation → entry points), with import edges and layer violations highlighted in red
• Communities view — force-directed layout with three switchable modes (structural, semantic, temporal), vertical slice highlighting, and documentation nodes as linked purple circles
• Dependencies view — root-focused dependency tree for any selected file

Features: directory aggregation, zoom/pan, edge filtering, node search, community mode switching, slice highlighting, and hover tooltips with per-file metrics (depth, dependents, risk, hub degree).

Optional: LLM-Generated Names

iw index export --html --provider openai --model gpt-4o-mini

An optional LLM pass names layers (“HTTP Layer”, “Core Types”) and directories (“CLI Subcommands”, “Pipeline Stages”) with one-sentence architectural descriptions. The report remains fully functional without this — heuristic labels are used by default.

---

The Upgrade Path

IntentWeave grows with your needs. Start free, add capabilities when you need them:

$0, zero config                    + LLM (budget-controlled)             + Neo4j (full scale)
─────────────────                  ──────────────────────                 ────────────────────
iw index build                     iw plugin add llm                     iw plugin add kg
  → 30+ code intelligence queries    → decision tracking                   → full KG queries
  → architecture visualization       → diagram validation                  → impact analysis
  → CI drift detection                → contradiction detection             → semantic search
  → clone detection                   → config-to-docs sync                → cross-doc reasoning
  → community detection               → same SQLite index                  → Neo4j persistence

No lock-in — each layer is independently useful and stores results in formats you own (SQLite files, Neo4j database).

Contributing

See the contribution guide for how to get involved.

Roadmap

Check the roadmap for what’s next — 80+ features specced, 40+ already shipped.