Documentation

Complete guide to using dora - Code Context CLI for AI Agents

Features

  • • Language-Agnostic SCIP Support - Works with any SCIP-compatible indexer (TypeScript, Java, Rust, Python, etc.)
  • • Fast Queries - Uses denormalized database with pre-computed aggregates for common operations
  • • Architecture Analysis - Detect circular dependencies, coupling, and complexity hotspots
  • • Dependency Tracking - Track dependencies at any depth with symbol-level granularity
  • • JSON Output - Structured data for AI agent consumption

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.

# Install globally
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 section below.

AI Agent Integration

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

  • • Claude Code - Skills, hooks, auto-indexing
  • • pi - Project-local extensions, plan mode
  • • 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
$ dora map# See codebase overview

Tip: After dora init, run dora cookbook show agent-setup --format markdown and feed it to your AI agent — it contains ready-to-use setup instructions for Claude Code, pi, OpenCode, Cursor, Windsurf, and more.

Claude Code Integration

Add these files to your project to enable auto-indexing and pre-approved permissions:

1. Create .claude/settings.json 

{
  "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 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, add the command reference to your CLAUDE.md: 

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.

4. Initialize dora 

dora init
dora index

What you get: Auto-indexing after each turn, pre-approved permissions, session startup checks, and CLAUDE.md context

MCP Server

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

Quick Start

$ dora mcp# Start MCP server (runs in foreground)

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 become 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

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

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

Documentation

dora docs# List all documentation files
dora docs search <query># Search documentation content
dora docs show <path># Show document metadata

Advanced Queries

dora schema# Show database schema
dora cookbook show [recipe]# Query patterns (quickstart, methods, refs, exports)
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

For detailed command reference with flags and options, see the Commands page.

Tree-sitter Analysis

dora fn, dora class, and dora smells parse source files directly using WebAssembly grammars. They work without a SCIP index and run on-demand per file.

Install a grammar for your language. For TypeScript and TSX:

$ bun add -g tree-sitter-typescript

For JavaScript and JSX:

$ bun add -g tree-sitter-javascript

dora discovers grammars automatically from local node_modules, global bun packages, or an explicit path in .dora/config.json: 

{
  "treeSitter": {
    "grammars": {
      "typescript": "/path/to/tree-sitter-typescript.wasm"
    }
  }
}

Run dora status to see which grammars are available.

Output Format

All commands output TOON (Token-Oriented Object Notation) by default — a compact JSON encoding optimized for LLM token usage. Pass --json for standard JSON output.

$ dora status# TOON output
$ dora status --json# JSON output

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

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

Issue Solution
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. 1. Fork the repository
  2. 2. Create a feature branch
  3. 3. Make your changes with tests (bun test)
  4. 4. Submit a pull request

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

Links