dora - Code Context CLI for AI Agents

Stop wasting tokens on grep/find/glob. Give your AI agent fast, structured code intelligence.

Features

• Instant answers - Pre-computed aggregates mean no waiting for grep/find/glob to finish or tokens wasted on file reads
• Understand relationships - See what depends on what without reading import statements or parsing code
• Find issues fast - Detect circular dependencies, coupling, and complexity hotspots with pre-indexed data
• Track usage - Know where every symbol is used across your codebase in milliseconds, not minutes
• Language-agnostic - Works with any SCIP-compatible indexer (TypeScript, Java, Rust, Python, etc.)

See It In Action

Typical Workflow Without dora

With dora CLI

System Requirements

• Binary users: No dependencies - standalone executable
• From source: Bun 1.0+ required
• SCIP indexer: Language-specific (e.g., scip-typescript for TS/JS)
• Supported OS: macOS, Linux, Windows
• Disk space: ~5-50MB for index (varies by codebase size)

Installation

Option 1: Download Pre-built Binary (Recommended)

Download the latest binary for your platform from the releases page:

# macOS (ARM64)
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/
Windows
Download dora-windows-x64.exe and add to PATH

Option 2: Install via npm

Requires Bun runtime installed.

bun install -g @butttons/dora

Or run without installing:

bunx @butttons/dora

Option 3: Build from Source

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash
Clone the repository
git clone https://github.com/butttons/dora.git
cd dora
Install dependencies
bun install
Build the binary
bun run build
The binary will be at dist/dora
Move it to your PATH
sudo mv dist/dora /usr/local/bin/

Install SCIP Indexer

You'll need a SCIP indexer for your language. For TypeScript/JavaScript:

# Install scip-typescript globally
npm install -g @sourcegraph/scip-typescript
Verify installation
scip-typescript --help

For other languages, see SCIP Indexers.

AI Agent Integration

→ See AGENTS.README.md for complete integration guides for:

• Claude Code - Skills, hooks, auto-indexing
• OpenCode - Agent system integration
• Cursor - Custom commands and rules
• Windsurf - Skills, AGENTS.md, and rules
• Other AI agents - Generic integration using SKILL.md and SNIPPET.md

Quick start for any agent:

dora init && dora index    # Initialize and index your codebase
dora cookbook show agent-setup --format markdown  # Get setup instructions for your agent
dora status                # Verify index is ready

Claude Code Integration

dora integrates with Claude Code via settings and optional skill configuration. Just add these files to your project:

1. Add to .claude/settings.json (enables auto-indexing and permissions):

{
  "permissions": {
    "allow": ["Bash(dora:*)", "Skill(dora)"]
  },
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "dora status 2>/dev/null && (dora index > /tmp/dora-index.log 2>&1 &) || echo 'dora not initialized. Run: dora init && dora index'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "(dora index > /tmp/dora-index.log 2>&1 &) || true"
          }
        ]
      }
    ]
  }
}

2. (Optional) Add the dora skill at .claude/skills/dora/SKILL.md:

After running dora init, create a symlink:

mkdir -p .claude/skills/dora
ln -s ../../../.dora/docs/SKILL.md .claude/skills/dora/SKILL.md

This enables the /dora command in Claude Code. View the skill file.

3. Add to CLAUDE.md (after running dora init):

cat .dora/docs/SNIPPET.md >> CLAUDE.md

This gives Claude quick access to dora commands and guidance on when to use dora for code exploration. The snippet includes command reference and best practices.

4. Initialize dora:

dora init
dora index

What this gives you:

• Auto-indexing after each Claude turn
• Pre-approved permissions (no prompts for dora commands)
• Session startup checks
• CLAUDE.md context for better code exploration

Troubleshooting:

• Index not updating? Check /tmp/dora-index.log for errors
• dora not found? Ensure dora is in PATH: which dora

MCP Server

dora can run as an MCP (Model Context Protocol) server.

Quick Start

# Start MCP server (runs in foreground)
dora mcp

Claude Code

Add the MCP server with one command:

claude mcp add --transport stdio dora -- dora mcp

Other MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "dora": {
      "type": "stdio",
      "command": "dora",
      "args": ["mcp"]
    }
  }
}

What You Get

All dora commands are available as MCP tools:

• dora_status - Check index health
• dora_map - Get codebase overview
• dora_symbol - Search for symbols
• dora_file - Analyze files with dependencies
• dora_deps / dora_rdeps - Explore dependencies
• And all other dora commands

Quick Start

1. Initialize

dora init

This creates a .dora/ directory with a default config.

2. Configure Commands

Edit .dora/config.json to configure your SCIP indexer:

For TypeScript/JavaScript:

{
  "commands": {
    "index": "scip-typescript index --output .dora/index.scip"
  }
}

For Rust:

{
  "commands": {
    "index": "rust-analyzer scip . --output .dora/index.scip"
  }
}

3. Index Your Codebase

# If commands are configured:
dora index
Or manually:
scip-typescript index --output .dora/index.scip

4. Try It Out

# Check index status
dora status
Get codebase overview
dora map
Find a symbol
dora symbol Logger

5. Example Workflow

# Find a class definition
dora symbol AuthService
Explore the file
dora file src/auth/service.ts
See what depends on it
dora rdeps src/auth/service.ts --depth 2
Check for circular dependencies
dora cycles

6. Learn Custom Queries

New to dora? The cookbook has recipes with real examples:

# Start here - complete walkthrough
dora cookbook show quickstart
Find class methods
dora cookbook show methods
Track symbol references
dora cookbook show references
Find exported APIs
dora cookbook show exports

All recipes include tested SQL patterns from real codebases.

Commands Overview

Setup & Status

dora init                    # Initialize in repo
dora index                   # Index codebase
dora status                  # Show index health
dora map                     # High-level statistics

Code Navigation

dora ls [directory]          # List files in directory with metadata
dora symbol <query>          # Find symbols by name
dora file <path>             # File info with dependencies
dora refs <symbol>           # Find all references
dora deps <path> --depth 2   # Show dependencies
dora rdeps <path> --depth 2  # Show dependents
dora adventure <from> <to>   # Find shortest path

Documentation

dora docs                    # List all documentation files
dora docs --type md          # Filter by document type
dora docs search <query>     # Search documentation content
dora docs show <path>        # Show document details

Architecture Analysis

dora cycles                  # Find bidirectional dependencies
dora coupling --threshold 5  # Find tightly coupled files
dora complexity --sort complexity  # High-impact files
dora treasure --limit 20     # Most referenced files
dora lost --limit 50       # Potentially dead code
dora leaves --max-dependents 3  # Leaf nodes

Advanced Queries

dora schema                  # Show database schema
dora cookbook show [recipe]  # Show query pattern examples
dora query "<sql>"           # Execute raw SQL (read-only)
dora changes <ref>           # Changed/impacted files
dora exports <path|package>  # List exports
dora imports <path>          # Show imports
dora graph <path>            # Dependency graph

Command Reference

Quick reference for all commands with common flags:

Setup Commands

Command	Description	Common Flags
dora init	Initialize dora in repository	-
dora index	Build/update index	--full, --skip-scip, --ignore <pattern>
dora status	Check index status	-
dora map	High-level statistics	-

Code Navigation

Command	Description	Common Flags
dora ls [directory]	List files in directory	--limit N, --sort <field>
dora file <path>	Analyze file with dependencies	-
dora symbol <query>	Search for symbols	--kind <type>, --limit N
dora refs <symbol>	Find all references	-
dora deps <path>	Show dependencies	--depth N (default: 1)
dora rdeps <path>	Show reverse dependencies	--depth N (default: 1)
dora adventure <from> <to>	Find dependency path	-

Documentation

Command	Description	Common Flags
dora docs	List all documentation files	--type <type> (md, txt)
dora docs search <query>	Search documentation content	--limit N (default: 20)
dora docs show <path>	Show document metadata	--content (include full content)

Architecture Analysis

Command	Description	Common Flags
dora cycles	Find bidirectional dependencies	--limit N (default: 50)
dora coupling	Find tightly coupled files	--threshold N (default: 5)
dora complexity	Show complexity metrics	--sort <metric>
dora treasure	Most referenced files	--limit N (default: 10)
dora lost	Find unused symbols	--limit N (default: 50)
dora leaves	Find leaf nodes	--max-dependents N

Advanced Commands

Command	Description	Common Flags
dora schema	Show database schema	-
dora cookbook show [recipe]	Query pattern cookbook	quickstart, methods, refs, exports
dora query "<sql>"	Execute raw SQL (read-only)	-
dora changes <ref>	Git impact analysis	-
dora exports <target>	List exported symbols	-
dora imports <path>	Show file imports	-
dora graph <path>	Dependency graph	--depth N, --direction

SCIP Indexers

• scip-typescript: TypeScript, JavaScript
• scip-java: Java, Scala, Kotlin
• rust-analyzer: Rust
• scip-clang: C++, C
• scip-ruby: Ruby
• scip-python: Python
• scip-dotnet: C#, Visual Basic
• scip-dart: Dart
• scip-php: PHP

Output Format

All commands output TOON (Token-Oriented Object Notation) by default. TOON is a compact, human-readable encoding of JSON that minimizes tokens for LLM consumption. Pass --json to any command for JSON output.

# Default: TOON output
dora status
JSON output
dora --json status
dora status --json

Errors always go to stderr as JSON with exit code 1.

TOON vs JSON size comparison

Measured on dora's own codebase (79 files, 3167 symbols):

Command	JSON	TOON	Savings
status	206 B	176 B	15%
map	68 B	62 B	9%
ls src/commands	2,258 B	975 B	57%
ls (all files)	6,324 B	2,644 B	58%
file src/index.ts	6,486 B	6,799 B	-5%
symbol setupCommand	130 B	130 B	0%
refs wrapCommand	510 B	549 B	-8%
deps (depth 2)	2,158 B	1,332 B	38%
rdeps (depth 2)	1,254 B	802 B	36%
adventure	110 B	97 B	12%
leaves	142 B	129 B	9%
exports	488 B	511 B	-5%
imports	1,978 B	1,998 B	-1%
lost	1,876 B	1,987 B	-6%
treasure	893 B	577 B	35%
cycles	14 B	11 B	21%
coupling	35 B	31 B	11%
complexity	2,716 B	932 B	66%
schema	6,267 B	4,389 B	30%
query	692 B	464 B	33%
docs	1,840 B	745 B	60%
docs search	277 B	171 B	38%
docs show	820 B	870 B	-6%
graph	2,434 B	1,894 B	22%
changes	1,112 B	1,026 B	8%

Commands with uniform arrays of objects (ls, complexity, docs, treasure) see 35-66% reduction. Nested or non-uniform outputs (file, refs, exports) are roughly equal or slightly larger.

Debug Logging

For debug logging, testing, building, and development instructions, see CONTRIBUTING.md.

Troubleshooting

Common Issues

Issue	Solution
Database not found	Run dora index to create the database
File not in index	Check if file is in .gitignore, run dora index
Stale results	Run dora index to rebuild
Slow queries	Use --depth 1 when possible, reduce --limit
Symbol not found	Ensure index is up to date: dora status, then dora index
dora command not found	Ensure dora is in PATH: which dora, reinstall if needed

Integration Issues

Claude Code index not updating:

• Check /tmp/dora-index.log for errors
• Verify dora is in PATH: which dora
• Test manually: dora index
• Ensure dora index is in the allow permissions list in .claude/settings.json

Stop hook not firing:

• Verify .claude/settings.json syntax is correct (valid JSON)
• Check that the hook runs by viewing verbose logs
• Try manually running the hook command

Want to see indexing progress:

• Edit .claude/settings.json Stop hook
• Change command to: "DEBUG=dora:* dora index 2>&1 || true" (removes background &)
• You'll see progress after each turn, but will wait 15-30s

Performance Issues

Index takes too long:

• Run SCIP indexer separately if it supports caching
• Use background indexing mode in Claude Code integration
• Check if your SCIP indexer can be optimized

Queries are slow:

• Use --depth 1 instead of deep traversals
• Reduce --limit for large result sets
• Ensure database indexes are created (automatic)
• Run dora index if database is corrupted

Contributing

Contributions are welcome! For development setup, testing, building binaries, and code style guidelines, see CONTRIBUTING.md.

Quick start:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests (bun test)
4. Submit a pull request

For detailed architecture and development guidelines, see CLAUDE.md.

License

MIT

Links

• AI Agent Integration: AGENTS.README.md - Integration guides for Claude Code, OpenCode, Cursor, Windsurf
• GitHub: https://github.com/butttons/dora
• SCIP Protocol: https://github.com/sourcegraph/scip
• Claude Code: https://claude.ai/code