by butttons
CLI built for AI agents to help navigate codebases better. An alternative to grep/find/glob
# Add to your Claude Code skills
git clone https://github.com/butttons/doraA 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.
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.
Download the latest binary from the releases page:
# 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):
bun install -g @butttons/dora
dora needs a SCIP index to work. Install one for your language:
# TypeScript / JavaScript
npm install -g @sourcegraph/scip-typescript
Other languages: scip-java, rust-analyzer, scip-python, scip-ruby, scip-clang, scip-dotnet, scip-dart.
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.
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
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
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
These commands parse source directly without needing an index:
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:
bun add -g tree-sitter-typescript
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
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
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"
dora mcp # start MCP server (stdio)
# Claude Code
claude mcp add --transport stdio dora -- dora mcp
All commands output TOON by default — a compact JSON encoding optimized for LLM token usage. Pass --json for standard JSON.
dora status --json
For agent-specific setup (hooks, skills, AGENTS.md snippets) for Claude Code, OpenCode, Cursor, and Windsurf:
dora cookbook show agent-setup
Or see AGENTS.README.md.
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)
See CONTRIBUTING.md.
MIT
No comments yet. Be the first to share your thoughts!