dora

A CLI that turns a SCIP index into a queryable SQLite database. Gives AI agents structured answers about your codebase instead of making them grep files and read imports.

Why

When an AI agent needs to understand code, it typically reads files, searches for patterns, and traces imports manually. This is slow, burns tokens, and doesn't scale past a few hundred files.

dora pre-indexes your codebase into SQLite. Questions like "what depends on this file?", "where is this symbol used?", and "which files are most coupled?" become millisecond queries instead of multi-step explorations.

Setup

Install

Download the latest binary from the releases page:

bash
# macOS (ARM)
curl -L https://github.com/butttons/dora/releases/latest/download/dora-darwin-arm64 -o dora
chmod +x dora && sudo mv dora /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/butttons/dora/releases/latest/download/dora-darwin-x64 -o dora
chmod +x dora && sudo mv dora /usr/local/bin/

# Linux
curl -L https://github.com/butttons/dora/releases/latest/download/dora-linux-x64 -o dora
chmod +x dora && sudo mv dora /usr/local/bin/

Or via npm (requires Bun):

bash
bun install -g @butttons/dora

Install a SCIP indexer

dora needs a SCIP index to work. Install one for your language:

bash
# TypeScript / JavaScript
npm install -g @sourcegraph/scip-typescript

Other languages: scip-java, rust-analyzer, scip-python, scip-ruby, scip-clang, scip-dotnet, scip-dart.

Initialize

bash
cd your-project
dora init
dora index

dora init creates .dora/config.json. dora index runs the SCIP indexer and converts the output to SQLite.

Usage

Exploring a codebase

bash
dora map                          # file count, symbol count, packages
dora ls src/                      # files in a directory with symbol/dep counts
dora status                       # index health and grammar availability

Finding code

bash
dora symbol AuthService           # find symbols by name
dora file src/auth/service.ts     # symbols, dependencies, dependents for a file
dora refs validateToken           # all references to a symbol across the codebase

Understanding dependencies

bash
dora deps src/auth/service.ts --depth 2    # what this file imports
dora rdeps src/auth/service.ts --depth 2   # what imports this file
dora adventure src/a.ts src/b.ts           # shortest path between two files

Tree-sitter analysis (TypeScript / JavaScript)

These commands parse source directly without needing an index:

bash
dora fn src/auth/service.ts       # functions with complexity, params, return type, LOC
dora class src/auth/service.ts    # classes with methods, implements, decorators
dora smells src/auth/service.ts   # high complexity, long functions, too many params, TODOs

Install a grammar to enable these:

bash
bun add -g tree-sitter-typescript

Architecture

bash
dora cycles                        # bidirectional dependencies (A imports B, B imports A)
dora coupling --threshold 5        # file pairs with high symbol sharing
dora complexity --sort complexity  # files ranked by change risk
dora treasure                      # most imported files
dora lost                          # symbols with zero references

Documentation

bash
dora docs                          # list indexed markdown/text files
dora docs search "authentication"  # full-text search across docs
dora docs show docs/api.md         # which symbols and files a doc references

Custom queries

bash
dora schema                        # database schema
dora cookbook show quickstart      # walkthrough with real SQL examples
dora cookbook show methods         # query patterns for finding methods
dora query "SELECT path, symbol_count FROM files ORDER BY symbol_count DESC LIMIT 10"

MCP server

bash
dora mcp                           # start MCP server (stdio)

# Claude Code
claude mcp add --transport stdio dora -- dora mcp

Output format

All commands output TOON by default — a compact JSON encoding optimized for LLM token usage. Pass --json for standard JSON.

bash
dora status --json

AI agent integration

For agent-specific setup (hooks, skills, AGENTS.md snippets) for Claude Code, OpenCode, Cursor, and Windsurf:

bash
dora cookbook show agent-setup

Or see AGENTS.README.md.

How it works

dora has two layers:

SCIP layer — runs your configured indexer (e.g. scip-typescript) to produce a .scip protobuf file, then parses it and loads it into SQLite. This gives you symbol definitions, references, and file-to-file dependencies derived from actual import resolution.

Tree-sitter layer — parses source files directly using WebAssembly grammars. This runs on-demand per file and extracts things SCIP doesn't cover: function signatures, cyclomatic complexity, class hierarchy details, and code smells.

The SQLite schema uses denormalized counts (symbol_count, dependency_count, dependent_count, reference_count) so most queries are index lookups rather than aggregations.

.dora/
├── config.json      # indexer command, ignore patterns, grammar paths
├── index.scip       # raw SCIP protobuf output
└── dora.db          # SQLite database (the thing dora actually queries)