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