rq finds the code you're looking for. Name a class, method, function, struct or constant, and rq shows where it's defined.
In a Rails checkout:
rq HashWithIndifferentAccess # → activesupport/lib/active_support/hash_with_indifferent_access.rb:55
rq hwia # → the same class: fuzzy and abbreviation-aware
rq 'Hash*Access' # → wildcards: `*` any run, `?` one char (quote them)
rq ActiveRecord::Base # → the Base defined inside ActiveRecord
rq Persistence#save # → the save defined inside Persistence
rq Migration.new # → Migration's constructor (initialize, __init__, constructor)
rq class Base # → a leading kind keyword is shorthand for -k class
rq perform activejob # → the perform under activejob/, rankedrq finds names, not behaviour. If you know what the code does but not what
it's called, reach for text search (rg) instead.
- grep / rg give every textual mention; rq gives the one place a symbol is defined, ranked.
- ctags is static and relevance-blind; rq ranks by match quality, your current repo, recency, and the branch you're on.
- an LSP is heavy — per-language, per-project, slow to warm. rq is one binary across all your repos: sub-millisecond search, warms itself on first use, and self-heals on edits.
Definitions come from Tree-sitter for Ruby, Rust, Go, Python, TypeScript, and JavaScript.
brew install dpep/tools/rq # builds from source; no runtime depsOr build it yourself — rq needs Rust only at build time:
cargo install --path . # or: make installrq <query> # search definitions; ranked
rq <query> -e/--explain # show the score behind each result
rq <query> -j/--json # JSON array (-J/--ndjson for one object per line)
rq <query> [DIR...] # restrict to directories (rg-style; or -p/--path)
rq <query> -k/--kind KIND # restrict to kind: class|module|method|function|struct|enum|trait|constant|type|macro|variant|field
rq KIND <query> # a leading kind keyword is shorthand for -k (rq class Widget)
rq Scope::name # scope-aware: only the name defined inside Scope (or Scope#method)
rq <query> -x/--lang LANG # restrict to language: ruby|rust|go|python|typescript|javascript
# (prefix-matched; r=ruby+rust; aliases rb/rs/ts/js)
rq <query> -l/--limit N # cap the number of results (default 10; 0 = every match)
rq <query> -a/--all-repos # search every indexed checkout (default: just the one you're in)
rq <query> --anchor F:LINE # rank as if asked from that line (F:LINE[:COL])
rq <query> --show # print the definition's source (confident match only)
rq <query> -o/--open # open the best match in your editor
rq <query> -w/--web # open the best match on GitHub, pinned to a pushed sha
rq --symbols FILE # outline a file's definitions, in line order
rq --index [PATH] # index a repository (incremental; safe to re-run)
rq --index --path DIR # seed the index with a subtree first (big monorepos)
rq --drop [PATH|IDENTITY] # remove a checkout's index, or a repo's (opposite of --index)
rq --status # indexing coverage per indexed checkout
rq --storage # the index file's size, and its background cleanup
rq --usage # searches per day, by caller and flagsrq -o <query> jumps to the best match in your editor. On a terminal with
several matches it asks you to choose; otherwise it takes the top hit. The
launcher is, in order:
RQ_OPEN, a command template:{file}is the absolute path,{line}the line,{}both aspath:line. A template with none of them getspath:lineappended as its last argument.- VS Code (
code). $VISUAL, then$EDITOR.- Nothing found: rq prints
path:line.
rq -o Widget # open the top match
RQ_OPEN='vim +{line} {file}' rq -o Widget # runs `vim +12 /abs/path/widget.rb`
RQ_OPEN=subl rq -o Widget # runs `subl /abs/path/widget.rb:12`rq -w <query> does the same in the browser. It opens the match on the repo's
git host (https://<remote>/blob/<sha>/<file>#L<line>), pinned to a commit so
the link survives the branch moving: HEAD, or if HEAD isn't pushed yet, the
newest pushed commit in its history. A result from another repo (-a) links to
that host's default branch, since rq doesn't know what's checked out there. The
launcher is $BROWSER, then open/xdg-open, else rq prints the URL.
For an interactive fzf picker, script/rq-open is a small wrapper around rq.
docs/EDITORS.md covers it, the VS Code extension
(Cmd-click Go to Definition) and Neovim.
--anchor FILE:LINE[:COL] tells rq where the question comes from — an editor's
cursor, or the file an agent is reading. Definitions in the classes and modules
enclosing that line rank first, then the same file and nearby directories. In a
mixed-language repo, definitions the file's language can refer to (TS and JS
reach each other) rank above the rest. When the file imports the name
(import { Widget } from './widget', or from one of the checkout's own
workspace packages), the definition that import resolves to ranks first,
through re-exports and barrels; TypeScript and JavaScript only for now. Asked from inside a test or example
app (examples/blog/), that app's own definitions aren't held back as test or
example code, though a private one only where its language lets the anchor call
it (its own file in TS/JS, its directory elsewhere).
$ rq 'valid?' -l 2
activemodel/lib/active_model/validations.rb:342 method valid? · ActiveModel::Validations
activerecord/lib/active_record/validations.rb:69 method valid? · ActiveRecord::Validations
$ rq 'valid?' --anchor activerecord/lib/active_record/validations.rb:48 -l 1
activerecord/lib/active_record/validations.rb:69 method valid? · ActiveRecord::ValidationsIt reorders and never filters, so it's safe whenever you know the file. FILE
is relative to the current directory; COL is accepted and ignored. rq records
no inheritance, so an inherited method gets no credit from the enclosing class.
The VS Code extension passes --anchor on every click.
-j/--json (array) and -J/--ndjson (one object per line) are the structured
surface for editors, scripts, and AI agents. Every command honors them, not just
search.
A search result, a --show result and a --symbols row share one shape. A field
that doesn't apply is omitted, never null.
| Field | Present | Meaning |
|---|---|---|
name |
always | The symbol's name. |
kind |
always | class, module, method, function, struct, enum, trait, constant, type, macro, variant or field. |
language |
always | ruby, rust, go, python, typescript or javascript. |
file |
always | Path relative to root. |
root |
when rq knows a checkout for the repo (always for --symbols) |
Absolute checkout root. Per result, because -a spans repos: join root and file to read it. |
line |
always | 1-based first line of the definition. |
end_line |
when known | Last line: line..=end_line is the whole definition. |
parent |
when nested | The enclosing scope, e.g. ActiveRecord::Migration. |
visibility |
when the language expresses one | public, crate, private, protected or local (a function nested in another). |
singleton |
when true | true: the definition belongs to the type itself, not its instances — a Ruby class method (def self.x, anything in class << self, a module_function), a Python @classmethod/@staticmethod, a TypeScript/JavaScript static member, a Rust associated fn without self. Constants never carry it, and Go has no such member. Text output says singleton method. |
repo |
always | Repo identity: github.com/org/repo, or local:/abs/path. |
source |
search | index, or live when the result came from a live scan of files on disk because no index pass has finished for this directory yet: one rq doesn't track, or a repo asked with --no-wait before its first index (or after --drop). The hit is real; only its ranking is provisional. In a repo it carries warming, and its confidence is scaled as an index hit's is. See Staying current. |
confidence |
search | 0–1: match quality × how far it leads the runner-up. Near 1 means take it; about 0.5 means it's level with the next result, a coin flip. |
features |
search | The scoring signals that fired, strongest first. |
signature |
when the line is non-empty | The definition's first source line, trimmed. |
body |
--show, confident match |
The full line..=end_line source. |
declarations |
when more than one | How many places declare this name (a reopened module, impl blocks across files), folded into one result. |
also_in |
with declarations |
file:line of the other declarations. |
total |
search | Matches the window was drawn from, before --limit. |
explain |
--explain |
Feature name → score contribution, in whole points. |
query |
batch mode | The stdin line this row answers; on a line that isn't UTF-8, its text with each invalid byte as \u{FFFD}. |
warming |
search, while the checkout's index is still being built | {read, of, interrupted, phase, phase_secs, hint}: files the index holds, files the tree spans (what git tracks, less a sparse checkout's files outside its cone, plus anything else the index holds; omitted outside git, where nothing counts the tree, and then confidence is 0), whether nothing is indexing it any more, what a live pass over it is doing — reading, or finishing (rebuilding the name index and reading commit times, when read stands still for a while) — and for how many whole seconds (both omitted when no pass reports one, such as an older rq's), and what to run. A better match may be in a file not read yet, so confidence is scaled by read / of — on every result from that checkout, live ones too, so they compare. |
A miss is one {"status": …, "query": …} object instead of results:
status |
Exit | Meaning |
|---|---|---|
no_match |
1 | Definitive: nothing by that name. Under -a, incomplete lists the roots of checkouts that aren't fully indexed, which the miss can't speak for; a search in one indexes it. |
scope_not_found |
1 | Nothing in the scope you named; found_in says where the name does live. |
warming |
2 | The index is incomplete; retry. Mostly with --no-wait or a short --wait, since otherwise a cold repo blocks until it can answer. It carries warming (as on a result) for how far the checkout holding the answer back got (under -a, possibly another one being indexed, which its hint names), and when something matched but a file not read yet could hold a better match, the matches so far as provisional. |
interrupted |
2 | Indexing was stopped (Ctrl-C) before it could answer; run again. |
A match exits 0. Every miss is non-zero, so rq … && … reads as "found
something". While an index is being built, a match answers only when no file
left to read could beat it on its name: an exact match in the capitals you
typed, or any exact or prefix match once every file containing the name has
been read. It still carries warming, since another definition of the name may
not be indexed yet. Under -a, "left to read" means by a retry: another
checkout that nothing is indexing answers from what it holds, with
warming.interrupted and the rq --index <root> that would finish it, while
one another process is indexing holds back any match but an exact one in your
capitals — even one from a complete checkout — and the search waits on it,
until that process has written nothing for 5 seconds.
When a run fails under --json/--ndjson — a bad flag or value, an empty
query, an index that can't be opened, a --symbols file that doesn't exist —
stdout carries one object instead of results:
{ "error": "rq: unknown --kind \"widget\" (class, module, method, function, struct, enum, trait, constant, type, macro, variant, field)", "kind": "usage", "code": 64 }kind is stable, and code is the exit code. The message also goes to stderr.
Errors take codes from sysexits(3), so none is ever mistaken for a miss or a
retry:
kind |
Exit | Meaning |
|---|---|---|
usage |
64 | The command line is wrong: an unknown or conflicting flag, a bad value, an empty query — including flags before --json. Fix the command; it won't succeed on retry. |
not_found |
66 | A file the command names doesn't exist (--symbols). |
no_remote, launch |
69 | Nothing to hand off to: -w on a repo with no git host, or an editor or browser that won't start. |
internal |
70 | rq couldn't render its own output — a bug. |
database, index |
74 | The index can't be opened, read or written. |
busy |
75 | Another rq is at work on what this one would change: --drop of a checkout a live --index or background warm is filling (the message names its pid; retry once it finishes), or an --index whose checkout a drop removed part-way (run it again). |
Every code means one thing, so a script can branch on the number: 1 is
absent, 2 is ask again, and anything else is an error, which kind names.
rq --help lists the same table.
An index that's damaged, or whose upgrade fails, is not an error: rq moves it
aside, says where on stderr, and rebuilds it. An older rq that finds a newer
rq's index keeps a separate one beside it. rq --status lists both kinds of
file; either is safe to delete.
Pipe queries on stdin, one per line, with -J. rq resolves the repo and opens
the index once instead of per query, which on a large repo is most of what a
lookup costs:
printf 'HashWithIndifferentAccess\nNoSuchThing\n' | rq -J -l 1{"query":"HashWithIndifferentAccess","name":"HashWithIndifferentAccess","kind":"class",…}
{"query":"NoSuchThing","status":"no_match"}Each row carries its query; a miss row carries its own status. Each line
is answered as it arrives, so a caller can hold the pipe open and ask one name
at a time. A line that isn't UTF-8 gets a usage error row carrying its
query, stderr names its line number, and the batch goes on. The run exits 0 if any query matched,
non-zero only if none did. --json can't frame
several result sets, so batch needs -J, and --show/--open/--web don't
apply. A cold repo is indexed up front, within the --wait budget, before the
first answer. A line that arrives after the pipe sat idle (an edit made between
questions) first takes in what changed in the worktree; lines piped together
are answered against one look.
--show locates and reads in one call. When the top match's confidence is at
least 0.85 it prints the full line..=end_line span (body in JSON); otherwise
it prints the ranked list, so it never dumps a definition it isn't sure about.
rq ActiveSupport::HashWithIndifferentAccess --show # confident: prints the class
rq perform --show # 122 candidates: prints the listrq --status --json emits a coverage row per checkout (repo, root,
status, files, symbols): worktrees and clones of one remote share a
repo and each has its own root. status is complete; warming while
the index is partial — a first index still running (even before it has
written a file), or a pass cut short that the next query continues; or
unindexed for a checkout rq knows but holds nothing for, such as a repo's
other worktrees after an upgrade, until a search there indexes it. A checkout
deleted from disk is forgotten, and doesn't appear. files and symbols count
what the checkout holds so far, and a partial checkout's of the files its tree
spans, as a result's warming counts them, with its phase and phase_secs. A dropped checkout is gone from --status until a query or --index
starts rebuilding it, and then reads warming. rq --index --json emits what
this run parsed (files_added, symbols_added — a file whose content a
sibling checkout already stored is parsed by neither, so a new worktree often
adds nothing) plus the checkout's totals and root. rq --drop inside a
checkout drops that checkout; rq --drop IDENTITY drops the repo with every
checkout of it. --json reports what it removed (repo, root for a
checkout, and files and symbols as --status counted them, summed over
the checkouts for a repo) and dropped; repo is always an identity, even
when there was nothing to drop. rq --storage --json describes the index
file: file (the one in use — beside a newer rq's, this rq's own), bytes
(its pages, as SQLite counts them) and free_bytes (those free inside it),
read in one snapshot with cleanup, what the background cleanup last did:
checked_at (when it last measured; a new index is stamped at creation),
ran_at and reclaimed_bytes (its last pass that gave space back),
skipped (no_room, busy or failed, why its last pass left the free
pages), retry_at (after busy, when it looks again) and error (after
failed, what went wrong) — each absent until it applies. You never need to run anything: after indexing, rq
hands free pages back on its own once they're worth it.
Single-result commands emit one object.
These commands exit 0 whenever they ran, including when there's nothing to
report: an empty --status or --storage, an --index that found nothing new, or a --drop
of a repo that isn't indexed ("dropped": false tells you). They exit non-zero
only with an error code from the table above — for --drop, busy (75) while
another rq is indexing that checkout, which it leaves untouched. --usage is the exception: with
nothing recorded yet it exits 1.
--no-wait answers from whatever's already indexed instead of waiting on a
warming repo — say, right after a branch switch on a huge repo. A miss reports
warming (exit 2) so you can retry, and so does a match the rest of the index
could still beat, with what it found as provisional; warming continues in a
detached background process. On a repo with no index yet it answers from a quick live scan
("source": "live"), and misses only what that scan can't reach. On a small or
fully indexed repo it answers the same as without the flag: the difference
shows only while a large index is being built.
--wait <dur> caps how long a query may wait: 50ms, 2s, 1m, or bare
seconds (--wait 0 is --no-wait). It overrides RQ_WAIT_BUDGET_MS (default 1
minute) for that call, and bounds a search at a terminal too, which otherwise
waits until answered (Ctrl-C stops it).
rq --symbols <file> lists every definition in a file, in line order — a
structural outline, not a ranked search. Honors -k/--kind and -x/--lang, and
emits the same fields as a search result, minus the scoring ones.
A file with no definitions — none at all, none of the kinds asked for, or in a
language rq doesn't parse — is a miss like a search's: {"status": "no_match"},
exit 1, so rq --symbols f && … reads as "it defines something". A file that
doesn't exist is an error (not_found, 66).
rq --symbols src/search/score.rs
rq --symbols src/store/mod.rs -k struct,enum --jsonA query is matched and scored by an additive sum of named signals, and
--explain shows the sum for each result:
$ rq Store --explain -l 2
src/store/mod.rs:84 struct Store
pub(crate) struct Store {
confidence 0.90 · score 1296 = exact 1000 + case 150 + extent 11 + kind 15 + recency 120
src/cli/mod.rs:1873 method store · BranchRefresh
fn store(self, store: &Store) {
confidence 0.04 · score 1123 = exact 1000 + private -15 + extent 18 + recency 120- match quality — exact > prefix > camel/underscore abbreviation > subsequence
- visibility — public API edges out private/protected helpers (Rust
pub, Rubyprivatesections, Python_underscore, Go capitalization, TypeScript member modifiers and ESMexport), and a function nested in another ranks below every same-named definition that isn't (local) - qualifier — a scoped query (
Foo::Bar,Foo#bar,Foo.bar) keeps only the definitions inside that scope;Foo.newfinds the constructor, or the class itself when it inherits one. A package or module scope is read off the file's path, sohugolib.HugoSites,models.QuerySetandmpsc::Senderwork too - path — the query also matches the file's name
- current repo — results are scoped to the checkout you're in by default,
so each worktree answers from its own branch (
-a/--all-reposto search every indexed checkout) - recency — symbols in recently edited or committed files
- branch — on a feature branch, files you're changing vs the trunk (and their directory neighbors) — where you're most likely working
- anchor — with
--anchor, definitions enclosing that line (enclosing), then those in the same file and nearby directories (proximity), and those in a language that file can refer to (reachable: TS and JS reach each other), and the one that file's import of the name resolves to (imported: TS/JS)
Fewer, better, ranked results are the goal — not completeness.
You rarely run rq --index by hand. The first query in a git repo warms the
index, files you're changing on this branch first, and once your answer prints
a detached, low-priority process finishes the sweep in the background. A
cold repo is the exception: the first query indexes until it can answer
rather than report a false miss. On a terminal, a progress line appears if that
takes longer than half a second, and Ctrl-C stops it. It's a one-time cost — the
index persists and self-heals as you search, re-reading edited files and
reconciling added and removed ones.
A non-git directory isn't warmed on a stray query, but rq --index <dir> tracks
it like any repo under a local:<path> identity; otherwise rq live-scans it, so
it still answers at zero coverage. A --no-wait query live-scans a git repo
whose first index hasn't finished the same way. A live answer is marked
"source": "live" in JSON (text output doesn't mark it), -v notes the files it scanned and how long it took against its budget
(RQ_FALLBACK_BUDGET_MS, default 250 ms), and --usage counts these answers
apart. The index is a SQLite file at $RQ_DB
(default ~/.local/share/rq/rq.db; an empty RQ_DB means the default).
RQ_DB must be an absolute path to a file: a relative one would resolve
against each command's working directory and split the index, so rq refuses it
with a usage error (exit 64), as it does a directory, or a default path under an
unset or relative HOME.
rq --completions <shell> # bash, zsh, fish, elvish, powershellHomebrew installs bash/zsh completions automatically.
rq ships with a Claude Code skill (claude/rq-skill.md) so Claude reaches for it when locating a definition instead of grepping the tree. Install the marketplace plugin, which updates itself and brings the sibling skills:
/plugin marketplace add dpep/claude
/plugin install code@dpep
Or copy the one file:
mkdir -p ~/.claude/skills/rq
cp claude/rq-skill.md ~/.claude/skills/rq/SKILL.mdThe plugin is the better default; claude/INSTALL.md covers when it isn't.
The in-process search pipeline measures p50 ~160 µs, max < 0.25 ms on a mid-size
library (a few hundred symbols) — microseconds against a 50 ms first-answer
budget. Benchmark your own tree: make bench REPO=/path/to/repo.
rq indexes definitions — classes, modules, methods, functions. It does
not do call graphs, type inference, reference tracking, inheritance, or LSP
features. It's built for many repositories and millions of symbols, and never
assumes everything belongs to one project. Repository identity is normalized
from the git remote (github.com/org/repo), falling back to
local:/absolute/path. Worktrees and clones of one remote share that identity
and store each file's content once, but each answers from its own files.
See docs/ARCHITECTURE.md for the full design.
MIT © Daniel Pepper.