{"id":40273383,"url":"https://github.com/butttons/dora","last_synced_at":"2026-02-22T17:25:37.753Z","repository":{"id":333082262,"uuid":"1136143664","full_name":"butttons/dora","owner":"butttons","description":"CLI built for AI agents to help navigate codebases better. An alternative to grep/find/glob","archived":false,"fork":false,"pushed_at":"2026-02-21T11:17:25.000Z","size":5858,"stargazers_count":78,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-21T17:40:50.830Z","etag":null,"topics":["ai-agent","bun","claude-code","cli","code-analysis","code-intelligence","open-code","scip","sourcegraph","sqlite","terminal"],"latest_commit_sha":null,"homepage":"https://dora-cli.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/butttons.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T06:20:46.000Z","updated_at":"2026-02-21T11:17:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/butttons/dora","commit_stats":null,"previous_names":["butttons/dora"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/butttons/dora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butttons%2Fdora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butttons%2Fdora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butttons%2Fdora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butttons%2Fdora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/butttons","download_url":"https://codeload.github.com/butttons/dora/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/butttons%2Fdora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29720562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","bun","claude-code","cli","code-analysis","code-intelligence","open-code","scip","sourcegraph","sqlite","terminal"],"created_at":"2026-01-20T03:02:31.435Z","updated_at":"2026-02-22T17:25:37.737Z","avatar_url":"https://github.com/butttons.png","language":"TypeScript","readme":"# dora - Code Context CLI for AI Agents\n\nStop wasting tokens on grep/find/glob. Give your AI agent fast, structured code intelligence.\n\n## Features\n\n- **Instant answers** - Pre-computed aggregates mean no waiting for grep/find/glob to finish or tokens wasted on file reads\n- **Understand relationships** - See what depends on what without reading import statements or parsing code\n- **Find issues fast** - Detect circular dependencies, coupling, and complexity hotspots with pre-indexed data\n- **Track usage** - Know where every symbol is used across your codebase in milliseconds, not minutes\n- **Language-agnostic** - Works with any SCIP-compatible indexer (TypeScript, Java, Rust, Python, etc.)\n\n## See It In Action\n\n### Typical Workflow Without dora\n\n![Baseline CLI workflow showing grep/find approach](docs/public/baseline-cli.gif)\n\n### With dora CLI\n\n![dora CLI workflow showing fast structured queries](docs/public/dora-cli.gif)\n\n## System Requirements\n\n- **Binary users**: No dependencies - standalone executable\n- **From source**: Bun 1.0+ required\n- **SCIP indexer**: Language-specific (e.g., scip-typescript for TS/JS)\n- **Supported OS**: macOS, Linux, Windows\n- **Disk space**: ~5-50MB for index (varies by codebase size)\n\n## Installation\n\n### Option 1: Download Pre-built Binary (Recommended)\n\nDownload the latest binary for your platform from the [releases page](https://github.com/butttons/dora/releases):\n\n```bash\n# macOS (ARM64)\ncurl -L https://github.com/butttons/dora/releases/latest/download/dora-darwin-arm64 -o dora\nchmod +x dora\nsudo mv dora /usr/local/bin/\n\n# macOS (Intel)\ncurl -L https://github.com/butttons/dora/releases/latest/download/dora-darwin-x64 -o dora\nchmod +x dora\nsudo mv dora /usr/local/bin/\n\n# Linux\ncurl -L https://github.com/butttons/dora/releases/latest/download/dora-linux-x64 -o dora\nchmod +x dora\nsudo mv dora /usr/local/bin/\n\n# Windows\n# Download dora-windows-x64.exe and add to PATH\n```\n\n### Option 2: Install via npm\n\nRequires [Bun](https://bun.sh) runtime installed.\n\n```bash\nbun install -g @butttons/dora\n```\n\nOr run without installing:\n\n```bash\nbunx @butttons/dora\n```\n\n### Option 3: Build from Source\n\n```bash\n# Install Bun (if not already installed)\ncurl -fsSL https://bun.sh/install | bash\n\n# Clone the repository\ngit clone https://github.com/butttons/dora.git\ncd dora\n\n# Install dependencies\nbun install\n\n# Build the binary\nbun run build\n\n# The binary will be at dist/dora\n# Move it to your PATH\nsudo mv dist/dora /usr/local/bin/\n```\n\n### Install SCIP Indexer\n\nYou'll need a SCIP indexer for your language. For TypeScript/JavaScript:\n\n```bash\n# Install scip-typescript globally\nnpm install -g @sourcegraph/scip-typescript\n\n# Verify installation\nscip-typescript --help\n```\n\nFor other languages, see [SCIP Indexers](#scip-indexers).\n\n## AI Agent Integration\n\n**→ See [AGENTS.README.md](AGENTS.README.md) for complete integration guides** for:\n\n- **Claude Code** - Skills, hooks, auto-indexing\n- **OpenCode** - Agent system integration\n- **Cursor** - Custom commands and rules\n- **Windsurf** - Skills, AGENTS.md, and rules\n- **Other AI agents** - Generic integration using SKILL.md and SNIPPET.md\n\nQuick start for any agent:\n\n```bash\ndora init \u0026\u0026 dora index    # Initialize and index your codebase\ndora cookbook show agent-setup --format markdown  # Get setup instructions for your agent\ndora status                # Verify index is ready\n```\n\n## Claude Code Integration\n\ndora integrates with Claude Code via settings and optional skill configuration. Just add these files to your project:\n\n**1. Add to `.claude/settings.json`** (enables auto-indexing and permissions):\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"Bash(dora:*)\", \"Skill(dora)\"]\n  },\n  \"hooks\": {\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"dora status 2\u003e/dev/null \u0026\u0026 (dora index \u003e /tmp/dora-index.log 2\u003e\u00261 \u0026) || echo 'dora not initialized. Run: dora init \u0026\u0026 dora index'\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"(dora index \u003e /tmp/dora-index.log 2\u003e\u00261 \u0026) || true\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n**2. (Optional) Add the dora skill** at `.claude/skills/dora/SKILL.md`:\n\nAfter running `dora init`, create a symlink:\n\n```bash\nmkdir -p .claude/skills/dora\nln -s ../../../.dora/docs/SKILL.md .claude/skills/dora/SKILL.md\n```\n\nThis enables the `/dora` command in Claude Code. [View the skill file](https://github.com/butttons/dora/blob/main/src/templates/docs/SKILL.md).\n\n**3. Add to CLAUDE.md** (after running `dora init`):\n\n```bash\ncat .dora/docs/SNIPPET.md \u003e\u003e CLAUDE.md\n```\n\nThis 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.\n\n**4. Initialize dora:**\n\n```bash\ndora init\ndora index\n```\n\n**What this gives you:**\n\n- Auto-indexing after each Claude turn\n- Pre-approved permissions (no prompts for dora commands)\n- Session startup checks\n- CLAUDE.md context for better code exploration\n\n**Troubleshooting:**\n\n- **Index not updating?** Check `/tmp/dora-index.log` for errors\n- **dora not found?** Ensure dora is in PATH: `which dora`\n\n## MCP Server\n\ndora can run as an MCP (Model Context Protocol) server.\n\n### Quick Start\n\n```bash\n# Start MCP server (runs in foreground)\ndora mcp\n```\n\n### Claude Code\n\nAdd the MCP server with one command:\n\n```bash\nclaude mcp add --transport stdio dora -- dora mcp\n```\n\n### Other MCP Clients\n\nAdd to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"dora\": {\n      \"type\": \"stdio\",\n      \"command\": \"dora\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n### What You Get\n\nAll dora commands are available as MCP tools:\n\n- `dora_status` - Check index health\n- `dora_map` - Get codebase overview\n- `dora_symbol` - Search for symbols\n- `dora_file` - Analyze files with dependencies\n- `dora_deps` / `dora_rdeps` - Explore dependencies\n- And all other dora commands\n\n## Quick Start\n\n### 1. Initialize\n\n```bash\ndora init\n```\n\nThis creates a `.dora/` directory with a default config.\n\n### 2. Configure Commands\n\nEdit `.dora/config.json` to configure your SCIP indexer:\n\n**For TypeScript/JavaScript:**\n\n```json\n{\n  \"commands\": {\n    \"index\": \"scip-typescript index --output .dora/index.scip\"\n  }\n}\n```\n\n**For Rust:**\n\n```json\n{\n  \"commands\": {\n    \"index\": \"rust-analyzer scip . --output .dora/index.scip\"\n  }\n}\n```\n\n### 3. Index Your Codebase\n\n```bash\n# If commands are configured:\ndora index\n\n# Or manually:\nscip-typescript index --output .dora/index.scip\n```\n\n### 4. Try It Out\n\n```bash\n# Check index status\ndora status\n\n# Get codebase overview\ndora map\n\n# Find a symbol\ndora symbol Logger\n```\n\n### 5. Example Workflow\n\n```bash\n# Find a class definition\ndora symbol AuthService\n\n# Explore the file\ndora file src/auth/service.ts\n\n# See what depends on it\ndora rdeps src/auth/service.ts --depth 2\n\n# Check for circular dependencies\ndora cycles\n```\n\n### 6. Learn Custom Queries\n\nNew to dora? The cookbook has recipes with real examples:\n\n```bash\n# Start here - complete walkthrough\ndora cookbook show quickstart\n\n# Find class methods\ndora cookbook show methods\n\n# Track symbol references\ndora cookbook show references\n\n# Find exported APIs\ndora cookbook show exports\n```\n\nAll recipes include tested SQL patterns from real codebases.\n\n## Commands Overview\n\n### Setup \u0026 Status\n\n```bash\ndora init                    # Initialize in repo\ndora index                   # Index codebase\ndora status                  # Show index health\ndora map                     # High-level statistics\n```\n\n### Code Navigation\n\n```bash\ndora ls [directory]          # List files in directory with metadata\ndora symbol \u003cquery\u003e          # Find symbols by name\ndora file \u003cpath\u003e             # File info with dependencies\ndora refs \u003csymbol\u003e           # Find all references\ndora deps \u003cpath\u003e --depth 2   # Show dependencies\ndora rdeps \u003cpath\u003e --depth 2  # Show dependents\ndora adventure \u003cfrom\u003e \u003cto\u003e   # Find shortest path\n```\n\n### Documentation\n\n```bash\ndora docs                    # List all documentation files\ndora docs --type md          # Filter by document type\ndora docs search \u003cquery\u003e     # Search documentation content\ndora docs show \u003cpath\u003e        # Show document details\n```\n\n### Architecture Analysis\n\n```bash\ndora cycles                  # Find bidirectional dependencies\ndora coupling --threshold 5  # Find tightly coupled files\ndora complexity --sort complexity  # High-impact files\ndora treasure --limit 20     # Most referenced files\ndora lost --limit 50       # Potentially dead code\ndora leaves --max-dependents 3  # Leaf nodes\n```\n\n### Advanced Queries\n\n```bash\ndora schema                  # Show database schema\ndora cookbook show [recipe]  # Show query pattern examples\ndora query \"\u003csql\u003e\"           # Execute raw SQL (read-only)\ndora changes \u003cref\u003e           # Changed/impacted files\ndora exports \u003cpath|package\u003e  # List exports\ndora imports \u003cpath\u003e          # Show imports\ndora graph \u003cpath\u003e            # Dependency graph\n```\n\n## Command Reference\n\nQuick reference for all commands with common flags:\n\n### Setup Commands\n\n| Command       | Description                   | Common Flags                                  |\n| ------------- | ----------------------------- | --------------------------------------------- |\n| `dora init`   | Initialize dora in repository | -                                             |\n| `dora index`  | Build/update index            | `--full`, `--skip-scip`, `--ignore \u003cpattern\u003e` |\n| `dora status` | Check index status            | -                                             |\n| `dora map`    | High-level statistics         | -                                             |\n\n### Code Navigation\n\n| Command                      | Description                    | Common Flags                  |\n| ---------------------------- | ------------------------------ | ----------------------------- |\n| `dora ls [directory]`        | List files in directory        | `--limit N`, `--sort \u003cfield\u003e` |\n| `dora file \u003cpath\u003e`           | Analyze file with dependencies | -                             |\n| `dora symbol \u003cquery\u003e`        | Search for symbols             | `--kind \u003ctype\u003e`, `--limit N`  |\n| `dora refs \u003csymbol\u003e`         | Find all references            | -                             |\n| `dora deps \u003cpath\u003e`           | Show dependencies              | `--depth N` (default: 1)      |\n| `dora rdeps \u003cpath\u003e`          | Show reverse dependencies      | `--depth N` (default: 1)      |\n| `dora adventure \u003cfrom\u003e \u003cto\u003e` | Find dependency path           | -                             |\n\n### Documentation\n\n| Command                    | Description                  | Common Flags                       |\n| -------------------------- | ---------------------------- | ---------------------------------- |\n| `dora docs`                | List all documentation files | `--type \u003ctype\u003e` (md, txt)          |\n| `dora docs search \u003cquery\u003e` | Search documentation content | `--limit N` (default: 20)          |\n| `dora docs show \u003cpath\u003e`    | Show document metadata       | `--content` (include full content) |\n\n### Architecture Analysis\n\n| Command           | Description                     | Common Flags                 |\n| ----------------- | ------------------------------- | ---------------------------- |\n| `dora cycles`     | Find bidirectional dependencies | `--limit N` (default: 50)    |\n| `dora coupling`   | Find tightly coupled files      | `--threshold N` (default: 5) |\n| `dora complexity` | Show complexity metrics         | `--sort \u003cmetric\u003e`            |\n| `dora treasure`   | Most referenced files           | `--limit N` (default: 10)    |\n| `dora lost`       | Find unused symbols             | `--limit N` (default: 50)    |\n| `dora leaves`     | Find leaf nodes                 | `--max-dependents N`         |\n\n### Advanced Commands\n\n| Command                       | Description                 | Common Flags                               |\n| ----------------------------- | --------------------------- | ------------------------------------------ |\n| `dora schema`                 | Show database schema        | -                                          |\n| `dora cookbook show [recipe]` | Query pattern cookbook      | `quickstart`, `methods`, `refs`, `exports` |\n| `dora query \"\u003csql\u003e\"`          | Execute raw SQL (read-only) | -                                          |\n| `dora changes \u003cref\u003e`          | Git impact analysis         | -                                          |\n| `dora exports \u003ctarget\u003e`       | List exported symbols       | -                                          |\n| `dora imports \u003cpath\u003e`         | Show file imports           | -                                          |\n| `dora graph \u003cpath\u003e`           | Dependency graph            | `--depth N`, `--direction`                 |\n\n## SCIP Indexers\n\n- [scip-typescript](https://github.com/sourcegraph/scip-typescript): TypeScript, JavaScript\n- [scip-java](https://github.com/sourcegraph/scip-java): Java, Scala, Kotlin\n- [rust-analyzer](https://github.com/rust-lang/rust-analyzer): Rust\n- [scip-clang](https://github.com/sourcegraph/scip-clang): C++, C\n- [scip-ruby](https://github.com/sourcegraph/scip-ruby): Ruby\n- [scip-python](https://github.com/sourcegraph/scip-python): Python\n- [scip-dotnet](https://github.com/sourcegraph/scip-dotnet): C#, Visual Basic\n- [scip-dart](https://github.com/Workiva/scip-dart): Dart\n- [scip-php](https://github.com/davidrjenni/scip-php): PHP\n\n## Output Format\n\nAll commands output [TOON](https://github.com/toon-format/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.\n\n```bash\n# Default: TOON output\ndora status\n\n# JSON output\ndora --json status\ndora status --json\n```\n\nErrors always go to stderr as JSON with exit code 1.\n\n### TOON vs JSON size comparison\n\nMeasured on dora's own codebase (79 files, 3167 symbols):\n\n| Command | JSON | TOON | Savings |\n|---|---|---|---|\n| `status` | 206 B | 176 B | 15% |\n| `map` | 68 B | 62 B | 9% |\n| `ls src/commands` | 2,258 B | 975 B | **57%** |\n| `ls` (all files) | 6,324 B | 2,644 B | **58%** |\n| `file src/index.ts` | 6,486 B | 6,799 B | -5% |\n| `symbol setupCommand` | 130 B | 130 B | 0% |\n| `refs wrapCommand` | 510 B | 549 B | -8% |\n| `deps (depth 2)` | 2,158 B | 1,332 B | **38%** |\n| `rdeps (depth 2)` | 1,254 B | 802 B | **36%** |\n| `adventure` | 110 B | 97 B | 12% |\n| `leaves` | 142 B | 129 B | 9% |\n| `exports` | 488 B | 511 B | -5% |\n| `imports` | 1,978 B | 1,998 B | -1% |\n| `lost` | 1,876 B | 1,987 B | -6% |\n| `treasure` | 893 B | 577 B | **35%** |\n| `cycles` | 14 B | 11 B | 21% |\n| `coupling` | 35 B | 31 B | 11% |\n| `complexity` | 2,716 B | 932 B | **66%** |\n| `schema` | 6,267 B | 4,389 B | **30%** |\n| `query` | 692 B | 464 B | **33%** |\n| `docs` | 1,840 B | 745 B | **60%** |\n| `docs search` | 277 B | 171 B | **38%** |\n| `docs show` | 820 B | 870 B | -6% |\n| `graph` | 2,434 B | 1,894 B | **22%** |\n| `changes` | 1,112 B | 1,026 B | 8% |\n\nCommands 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.\n\n## Debug Logging\n\nFor debug logging, testing, building, and development instructions, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue                      | Solution                                                     |\n| -------------------------- | ------------------------------------------------------------ |\n| **Database not found**     | Run `dora index` to create the database                      |\n| **File not in index**      | Check if file is in .gitignore, run `dora index`             |\n| **Stale results**          | Run `dora index` to rebuild                                  |\n| **Slow queries**           | Use `--depth 1` when possible, reduce `--limit`              |\n| **Symbol not found**       | Ensure index is up to date: `dora status`, then `dora index` |\n| **dora command not found** | Ensure dora is in PATH: `which dora`, reinstall if needed    |\n\n### Integration Issues\n\n**Claude Code index not updating:**\n\n- Check `/tmp/dora-index.log` for errors\n- Verify dora is in PATH: `which dora`\n- Test manually: `dora index`\n- Ensure `dora index` is in the `allow` permissions list in `.claude/settings.json`\n\n**Stop hook not firing:**\n\n- Verify `.claude/settings.json` syntax is correct (valid JSON)\n- Check that the hook runs by viewing verbose logs\n- Try manually running the hook command\n\n**Want to see indexing progress:**\n\n- Edit `.claude/settings.json` Stop hook\n- Change command to: `\"DEBUG=dora:* dora index 2\u003e\u00261 || true\"` (removes background `\u0026`)\n- You'll see progress after each turn, but will wait 15-30s\n\n### Performance Issues\n\n**Index takes too long:**\n\n- Run SCIP indexer separately if it supports caching\n- Use background indexing mode in Claude Code integration\n- Check if your SCIP indexer can be optimized\n\n**Queries are slow:**\n\n- Use `--depth 1` instead of deep traversals\n- Reduce `--limit` for large result sets\n- Ensure database indexes are created (automatic)\n- Run `dora index` if database is corrupted\n\n## Contributing\n\nContributions are welcome! For development setup, testing, building binaries, and code style guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nQuick start:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests (`bun test`)\n4. Submit a pull request\n\nFor detailed architecture and development guidelines, see [CLAUDE.md](./CLAUDE.md).\n\n## License\n\nMIT\n\n## Links\n\n- **AI Agent Integration**: [AGENTS.README.md](./AGENTS.README.md) - Integration guides for Claude Code, OpenCode, Cursor, Windsurf\n- **GitHub**: [https://github.com/butttons/dora](https://github.com/butttons/dora)\n- **SCIP Protocol**: [https://github.com/sourcegraph/scip](https://github.com/sourcegraph/scip)\n- **Claude Code**: [https://claude.ai/code](https://claude.ai/code)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbutttons%2Fdora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbutttons%2Fdora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbutttons%2Fdora/lists"}