drail gives AI agents a small, explicit command set for reading code, finding symbols, searching text, tracing callers, listing files, mapping codebases, and checking file-level dependencies.

One drail call replaces 3-6 Read/Grep/Glob cycles. Agents navigate code faster, use fewer tokens, and recover from bad queries without spiraling into tool thrash.

Why drail

Generic shell tools force agents into multi-step loops: list files, guess which matters, read too much, grep again, re-read a narrower slice. Each step costs tokens and risks context drift.

drail turns those loops into single commands with stable output contracts:

| Without drail | With drail | |---|---| | grep -rn "MyClass" src/ | drail symbol find MyClass --scope src/ | | find . -name "*.py" + cat each | drail files "*.py" --scope src/ | | grep + Read + grep + Read | drail scan --scope src/ --pattern "X" --read-matching | | Manual caller tracing | drail symbol callers fn_name --scope src/ | | Multiple reads for hierarchy | drail symbol find Class --scope src/ --parents |

Benchmarks

We test drail on 6 challenging code navigation tasks against real ML codebases (HuggingFace Transformers, TRL, Unsloth). Each task is scored 0-5 by an automated grader.

| Version | Mode | Hierarchy | Deep Analysis | Multi-hop | Comparison | Cross-repo | Deps | Total | Tokens (in/out) | Time | |---|---|---|---|---|---|---|---|---|---|---| | 0.0.7 | No Skill | 4.4 | 4.3 | 4.0 | 4.2 | 5.0 | 5.0 | 26.9 | 2.5M / 13K | 1m 44s | | | With drail | 5.0 | 5.0 | 5.0 | 4.2 | 5.0 | 4.2 | 28.4 | 3.7M / 17K | 2m 2s |

Run bash skill/benchmark.sh --release --parallel to generate a new release benchmark.

Quick Start

npm install -g drail    # installs binary + Claude Code skill automatically

# Explore a codebase
drail map --scope src/
drail symbol find main --scope src/
drail files "*.rs" --scope src/
drail deps src/main.rs

Commands

| Command | Purpose | Example | |---|---|---| | read <path> | Read files, line ranges, headings, JSON keys | drail read src/main.rs --lines 10:50 | | symbol find <q> | Find definitions + usages with inline bodies | drail symbol find MyClass --scope src/ --parents | | symbol callers <q> | Call sites + 2nd-hop impact analysis | drail symbol callers handler --scope src/ | | search text <q> | Literal text search | drail search text "TODO" --scope src/ | | search regex <p> | Regex pattern search | drail search regex "fn\s+\w+" --scope src/ | | files <glob> | Find files by pattern | drail files "*.py" --scope src/ | | deps <path> | Import/dependent analysis | drail deps src/auth.ts | | map | Structural codebase overview | drail map --scope src/ --depth 3 | | scan | Composite: files + search + outlines | drail scan --scope src/ --pattern "pub fn" --read-matching |

Global flags

All commands support:

• --json — stable machine-readable JSON envelope (schema v2)
• --budget <bytes> — cap response size, trims least-important data first
• --limit <n> — override default result caps
• --scope <dir> — directory to search within

Output structure

Every command returns 4 sections: Meta (query info), Evidence (your answer), Next (recovery suggestions), Diagnostics (warnings/errors). Empty sections render as (none). Errors follow the same structure on stderr.

# symbol.find

## Meta
- definitions: 1
- query: main
- scope: /path/to/src

## Evidence
symbol find "main" in /path/to/src — 2 matches

- main.rs:5-15 [definition]
  fn main() {

## Next
(none)

## Diagnostics
(none)

{
  "command": "symbol.find",
  "schema_version": 2,
  "ok": true,
  "data": {
    "meta": {}
  },
  "next": [],
  "diagnostics": []
}

Read examples

cargo run -- read README.md --lines 45:56         # line range
cargo run -- read README.md --heading "## Commands" # markdown section

JSON navigation — --key and --index are JSON-only selectors:

cargo run -- read tests/fixtures/json/users.json --key users.0.accounts             # nested key
cargo run -- read tests/fixtures/json/root-array.json --index 0:1                   # array slice
cargo run -- read tests/fixtures/json/users.json --key users.0.accounts --index 0:1 # combined

JSON files always render as TOON text (compact, agent-friendly).

Error handling

cargo run -- files "*.definitely-nope" --scope src --json  # no-match → hint + next suggestion
cargo run -- search regex "(" --scope src                  # invalid regex → error diagnostic on stderr

When content is minified, oversized, or parse-unreliable, read returns a bounded preview instead of dumping unreadable raw content. This preview fallback is skipped when you explicitly ask for raw/targeted content via --full or an explicit selector (--lines, --heading, --key, or --index).

When structural parsing is unavailable, symbol find falls back to usage-only matches with snippet text, and symbol callers returns best-effort text fallback rows, uses "<text-fallback>" for caller, leaves impact empty.

Special features

• --parents — trace class/type inheritance hierarchy (shows Parents: and Hierarchy: chains)
• JSON navigation — drail read data.json --key users.0.name for dot-path access, --index 0:3 for array slicing
• Composite scanning — drail scan --scope src --scope tests --files "*.rs" --pattern "TODO" --read-matching replaces chained files + search + read
• .drailignore — scope-root ignore file for traversal filtering at the active scope root. .gitignore is not read. Explicit paths bypass ignore: read still works for ignored paths, and deps accepts an ignored target path but filters traversal-derived results.

cargo run -- files "*.rs" --scope tests/fixtures/drailignore  # demonstrates .drailignore filtering

Installation

npm (recommended)

npm install -g drail

Downloads the prebuilt binary for your platform and auto-installs the Claude Code skill. Supports Linux x64, Linux arm64, and Windows x64.

From source (Cargo)

cargo install --path .
drail install-skill     # install Claude Code skill separately

Local installer

./install.sh          # install to ~/.local/bin
./install.sh --dry-run  # preview only

Claude Code Skill

drail ships with a Claude Code skill that teaches AI agents to use drail for all code navigation tasks. Install it to get AST-aware, token-efficient code exploration out of the box.

Build & Test

cargo build --release
cargo test
cargo clippy -- -D warnings
cargo fmt --check

Pre-commit hook: git config core.hooksPath .githooks

Stability

Stable surfaces: subcommand names, JSON envelope schema, diagnostics schema, text section ordering.

Not supported: legacy query shorthands, editor integrations, undocumented aliases.

License

MIT