Ariadne

Semantic code index and gatekeeper for AI coding agents. Builds a compiler-grade symbol graph (defs/refs) via SCIP and a file-level dependency graph via import extraction. Exposes queries via CLI and MCP tools.

No LLMs involved — just static analysis.

What it does

• Indexes your codebase (TypeScript, Python, Go, Rust, Java/Kotlin, Scala, C#, Ruby) into a SQLite graph of symbols, references, imports, and definitions

• Queries let you search symbols, jump to definitions, find all references, trace impact of changes, explore call graphs, and compute structural metrics

• Analyzes transitive impact with risk scoring — BFS across the symbol graph to find all affected files, packages, public API breaks, and relevant tests

• Detects structural drift — dependency cycles (Tarjan's SCC), module coupling (Ca/Ce/instability), and public API surface tracking with snapshot-based diffing

• Enforces architectural policies via ariadne.policies.json — deny new cycles, cap API growth, limit coupling increases

• Verifies repo consistency: stale index detection, empty index detection, missing test runs, type errors, architecture boundary violations, and policy compliance

• Indexes non-code artifacts — .env vars, package.json scripts, SQL migrations, OpenAPI schemas — and links them to source references

• Integrates with Claude Code via hooks (auto-update on edit, gatekeeper on stop) and MCP tools

• Works on any existing project — run setup and it indexes everything from disk

Related MCP server: RepoMap

Install

Standalone binary (recommended)

Download the prebuilt binary for your platform:

curl -fsSL https://raw.githubusercontent.com/simonrueba/ariadne/main/scripts/install.sh | bash

Or specify a version: ARIADNE_VERSION=v0.2.0 curl -fsSL ... | bash

Then set up on your project:

ariadne setup /path/to/your/project

From source

Requires Bun >= 1.0

git clone https://github.com/simonrueba/ariadne.git && cd ariadne && bun install

# Set up on your project
bun run packages/cli/src/index.ts setup /path/to/your/project

SCIP indexers are optional — structural import analysis works without them. Install per language as needed (see Toolchains by language below). Run ariadne doctor to check what's available.

Quick start

Use on any project (recommended)

# Set up on your project — does everything in one step:
# init → index → generate hooks + MCP config
bun run packages/cli/src/index.ts setup /path/to/your/project

This creates:

• .ariadne/ — SQLite database, hook scripts, SCIP cache

• .claude/settings.json — Claude Code hooks (impact context on edit, auto-update, verify gate)

• .mcp.json — MCP server config (14 read-only tools)

• ariadne.boundaries.json — auto-generated architecture boundary config (monorepos)

Then restart Claude Code in your project to pick up the hooks and MCP server.

GitHub Action (CI)

Add structural analysis to your pull requests with a single workflow file:

# .github/workflows/ariadne.yml
name: Ariadne Structural Guard

on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  pull-requests: write

jobs:
  structural-analysis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: simonrueba/ariadne-action@v1
        with:
          comment: 'true'
          fail-on-policy: 'true'

This posts a PR comment with impact radius, risk score, public API breaks, new cycles, test coverage, and policy status. See action/ for full configuration options.

Manual setup (step by step)

# Initialize .ariadne/ directory
bun run packages/cli/src/index.ts init /path/to/your/project

# Build the full index (structural imports + SCIP symbols)
bun run packages/cli/src/index.ts index /path/to/your/project

# Check prerequisites
bun run packages/cli/src/index.ts doctor /path/to/your/project

# Run gatekeeper checks
bun run packages/cli/src/index.ts verify /path/to/your/project

Query examples

# Search for a symbol
bun run packages/cli/src/index.ts query search "MyFunction"

# Find definition
bun run packages/cli/src/index.ts query def "<symbol-id>"

# Find all references
bun run packages/cli/src/index.ts query refs "<symbol-id>"

# Impact analysis — what's affected by changes to a file?
bun run packages/cli/src/index.ts query impact src/foo.ts

# Detailed impact — includes symbol defs, docs, and reference snippets
bun run packages/cli/src/index.ts query impact src/foo.ts --details

# Call graph — who calls a function, and what does it call?
bun run packages/cli/src/index.ts query call-graph "<symbol-id>"
bun run packages/cli/src/index.ts query call-graph "<symbol-id>" --depth 2

# File dependency graph (imports only)
bun run packages/cli/src/index.ts query module-graph

# Hybrid module graph (imports + SCIP semantic edges with weights)
bun run packages/cli/src/index.ts query module-graph --mode hybrid

# Scoped to a directory
bun run packages/cli/src/index.ts query module-graph --path packages/core/

All commands output JSON. Symbol IDs are SCIP symbol strings returned by search.

Transitive impact analysis

# Full transitive impact with risk scoring
bun run packages/cli/src/index.ts impact src/core.ts

# Limit BFS depth
bun run packages/cli/src/index.ts impact src/core.ts --max-depth 2

# Include call graph traversal
bun run packages/cli/src/index.ts impact src/core.ts --call-graph

# Multiple files
bun run packages/cli/src/index.ts impact src/core.ts src/utils.ts

Returns: changed symbols (with public API flag), affected files (with depth and reason), affected packages, public API breaks (with downstream consumers), test files (direct vs transitive), risk score and category (low/medium/high/critical), boundary violation risk.

Structural metrics

# Current metrics (coupling, cycles, API surface)
bun run packages/cli/src/index.ts metrics

# Save baseline snapshot
bun run packages/cli/src/index.ts metrics --snapshot

# Diff current vs baseline
bun run packages/cli/src/index.ts metrics --diff

Policy enforcement

Create ariadne.policies.json in your project root:

{
  "policies": {
    "deny_new_cycles": true,
    "max_public_api_growth": 5,
    "max_coupling_increase": 3
  }
}

Policies are checked automatically by ariadne verify. They compare current metrics against the saved baseline snapshot — run ariadne metrics --snapshot to establish the baseline.

CLI commands

MCP server

The MCP server exposes 14 read-only tools for AI agents:

Configuration

ariadne setup generates this automatically. To configure manually, add .mcp.json to your project root:

{
  "mcpServers": {
    "ariadne": {
      "command": "bun",
      "args": ["run", "/path/to/ariadne/packages/mcp/src/index.ts"],
      "env": { "ARIADNE_ROOT": "." }
    }
  }
}

If you installed via npm (bun add --global ariadne-mcp), use:

{
  "mcpServers": {
    "ariadne": {
      "command": "bunx",
      "args": ["ariadne-mcp"],
      "env": { "ARIADNE_ROOT": "." }
    }
  }
}

The MCP server starts gracefully even if .ariadne/ doesn't exist yet — it creates the directory and logs a helpful message.

Claude Code hooks

ariadne setup generates .claude/settings.json automatically. The hooks reference portable scripts in .ariadne/hooks/ that resolve the ariadne binary dynamically at runtime.

What the hooks do

• Pre-edit impact hook (Edit|Write PreToolUse): runs ariadne impact before every source file edit and injects the blast radius (changed symbols, dependent files, recommended tests) as context so Claude sees what will be affected. Silently skips test files, non-source files, and uninitialized projects. ~240ms latency.

• Post-edit hook (Edit|Write PostToolUse): marks edited source files dirty, runs ariadne update --files <path> for fast single-file updates (no full repo walk), logs the edit to the ledger. Non-source files (README, config, etc.) are skipped to avoid false-positive freshness failures.

• Post-test hook (Bash PostToolUse): detects test runner commands (vitest, jest, pytest, bun test, mocha, ava, cargo test, go test, mvn test, dotnet test, sbt test, bundle exec, playwright), logs test_run to the ledger

• Stop hook: runs ariadne update (auto-triggers SCIP when dirty source files exist), then ariadne verify. On failure, outputs {"decision":"block","reason":"..."} to prevent Claude from stopping until issues are fixed

The stop hook uses atomic mkdir-based locking to prevent concurrent runs, checks stop_hook_active from stdin to prevent infinite loops, and has a 120s stale lock timeout.

All hooks guard against missing .ariadne/ — they silently exit if the project hasn't been initialized.

Gatekeeper checks

ariadne verify runs these checks:

1. Empty index — fails if zero files are indexed (prevents vacuous pass on uninitialized projects)

2. Index freshness — checks the dirty set (files marked changed by hooks or update), filtering to source files only. Fails if any dirty source files exist that haven't been covered by a SCIP index pass. Non-source files are ignored since SCIP can't index them.

3. Missing test runs — checks the ledger for a test_run event after the most recent edit. Fails if no tests were run after editing.

4. Typecheck — runs language-appropriate type checkers (tsc --noEmit, go vet, cargo check, mvn compile, sbt compile, dotnet build) against detected projects. Fails on any type errors. On failure, includes recommendations with ariadne query impact and ariadne query search commands for the affected files and identifiers. Skipped if no supported project is detected.

5. Architecture boundaries — reads ariadne.boundaries.json and checks all imports edges against layer allowlists. Fails if any file imports from a layer not in its canImport list. Skipped if no config file exists.

6. Policy compliance — reads ariadne.policies.json and compares current structural metrics against the saved baseline snapshot. Checks: deny_new_cycles (no new dependency cycles), max_public_api_growth (cap on new exported symbols per package), max_coupling_increase (cap on coupling metric increases per module). Skipped if no config file or no baseline snapshot exists.

Architecture

graph TD
    subgraph Indexing Pipeline
        A[Source Files<br>.ts .tsx .js .jsx .py .go .rs<br>.java .kt .scala .cs .rb] --> B[Structural Pass<br>import/export extraction]
        A --> C[SCIP Pass<br>scip-typescript / scip-python<br>scip-go / rust-analyzer<br>scip-java / scip-dotnet / scip-ruby]
        D[Artifact Files<br>.env package.json *.sql] --> E[Artifact Pass<br>pseudo-symbol extraction]
    end

    subgraph SQLite Store
        B --> F[(index.db<br>WAL mode)]
        C --> F
        E --> F
        F --- G[files · symbols · edges<br>occurrences · dirty · ledger]
    end

    subgraph Consumption
        F --> H[CLI Queries<br>search · refs · impact<br>call-graph · module-graph<br>transitive-impact · metrics<br>context · preflight]
        F --> I[MCP Server<br>14 read-only tools]
        F --> J[Verify Engine<br>freshness · tests · typecheck<br>boundaries · policies]
    end

    subgraph Claude Code Hooks
        K[Pre-edit] -->|impact context| H
        L[Post-edit] -->|dirty mark + update| F
        M[Post-test] -->|ledger log| F
        N[Stop] -->|update + verify| J
    end

How indexing works

Three-pass pipeline:

1. Structural pass (instant, per-file) — regex-based extraction of import/export/from/use/require/using statements across all supported languages. Creates file-level imports edges with resolved file paths (e.g. ./utils → src/utils.ts) so edges point to actual file nodes. Runs on every update.

2. SCIP pass (slower, full project) — runs the appropriate SCIP indexer per detected sub-project, producing a protobuf index. The parser decodes it and extracts symbols, occurrences (with line:col ranges), and definition/reference roles. Creates symbol-level defines, references, and approximate calls edges (via enclosing-definition heuristic). Runs on index, update (when dirty source files exist), and update --full (forced).

3. Artifact pass (instant, per-file) — extracts pseudo-symbols from non-code files: .env vars (env_var), package.json/tsconfig.json keys (config_key), SQL migrations (table, index), and OpenAPI specs (api_endpoint, api_schema). Scans dirty source files for references (process.env.KEY, os.environ, SQL table names) and creates config_ref edges. Runs on every update.

All passes write to the same SQLite database (.ariadne/index.db). The database uses WAL mode, busy_timeout=5000 for concurrent access from hooks, and transactions for atomic SCIP ingestion. Bulk ingestion uses index-drop/recreate and PRAGMA synchronous=OFF for faster writes, and skips unchanged files by content hash comparison.

Multi-project support

Ariadne auto-detects sub-projects in monorepos by scanning for language-specific config files (tsconfig.json, pyproject.toml/setup.py, go.mod, Cargo.toml, pom.xml/build.gradle, build.sbt, .sln/.csproj, Gemfile). Each sub-project is indexed independently with correct path prefixing so that SCIP-relative paths map correctly to repo-root-relative file paths.

Module graph modes

The module-graph query supports three modes:

• imports (default) — structural import edges only

• semantic — SCIP-derived edges with occurrence weights (how many times symbols from file A are referenced in file B)

• hybrid — union of both, with source tagging (import, semantic, or import+semantic)

Output formats: json (default), dot (Graphviz), mermaid.

Project structure

packages/
  core/     ariadne-core library (636 tests)
    src/
      store/       SQLite schema, queries (7 focused query classes + facade), types, transactions
      scip/        protobuf parser + SCIP types + call graph derivation
      indexers/    scip-typescript, scip-python, scip-go, scip-rust, scip-java, scip-csharp, scip-ruby, import extractor, project detector, artifact extractor, config ref scanner
      graph/       refs, impact analysis (basic + transitive with risk scoring), call graph, module graph (import/semantic/hybrid), structural metrics (coupling, cycles, API surface), context compiler, preflight analyzer, shared utils
      verify/      gatekeeper engine + checks (freshness, tests, typecheck, boundaries, policies)
      ledger/      execution event log
  cli/      CLI command router + hooks
    src/
      commands/    init, setup, index, update, query, verify, status, dirty, doctor, ledger, impact, metrics, ci, context, preflight
      hooks/       pre-edit-impact.sh, post-edit.sh, post-test.sh, stop-verify.sh
      lib/         context, output helpers
  mcp/      MCP stdio server (14 read-only tools)

Performance

Benchmarked on Ariadne's own codebase (95 files, 3 sub-projects). Apple M3.

Hook latency stays under 200ms — fast enough to run on every edit without noticeable delay in Claude Code.

Development

bun install
bun test                  # 636 tests across 29 files
bunx tsc --noEmit         # type-check all packages
bun run packages/cli/src/index.ts doctor  # check prerequisites

Toolchains by language

Required: Bun >= 1.0

Optional: SCIP indexers add symbol-level analysis (defs/refs/call graph) on top of structural imports. Without them, you still get file-level dependency graphs, import edges, and artifact indexing.

Language roadmap

SCIP indexers exist for these languages and could be integrated:

Contributions welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE