---
slug: "dora"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/butttons/dora@main/README.md"
repo: "https://github.com/butttons/dora"
source_file: "README.md"
branch: "main"
---
# 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](https://github.com/butttons/dora/releases):

```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](https://bun.sh)):

```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](https://github.com/sourcegraph/scip-java), [rust-analyzer](https://github.com/rust-lang/rust-analyzer), [scip-python](https://github.com/sourcegraph/scip-python), [scip-ruby](https://github.com/sourcegraph/scip-ruby), [scip-clang](https://github.com/sourcegraph/scip-clang), [scip-dotnet](https://github.com/sourcegraph/scip-dotnet), [scip-dart](https://github.com/Workiva/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](https://github.com/toon-format/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](https://github.com/butttons/dora/blob/HEAD/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)
```

## Contributing

See [CONTRIBUTING.md](https://github.com/butttons/dora/blob/HEAD/CONTRIBUTING.md).

## License

MIT