Docs / Commands
map, skeleton, query, impact, semantic
Updated
These five commands answer "where is the code I need?" without loading whole files into your agent's context. Use them when you don't yet know where something lives. If you already know the path, open the file directly: that is cheaper than any summary.
All five read a local index of your repository. It is built the first time you need it and refreshed automatically. Nothing leaves your machine.
Pick the right command
| You want to know | Command |
|---|---|
| What is in this repo, and where | tokenade map [<path>] |
| What a file declares, without its bodies | tokenade skeleton <file…> |
| Where a symbol is defined and who calls it | tokenade query <symbol…> |
| What breaks if you change a file | tokenade impact <file…> |
| Where a concept is handled, in plain words | tokenade semantic "<question>" |
Every command accepts several targets in one call (tokenade skeleton a.rs b.rs c.rs). One call with three files costs one round-trip instead of three.
Shared flags
| Flag | Applies to | Effect |
|---|---|---|
-o, --output-mode, --format | all five | full (default), paths, count; query and semantic also accept outline |
--budget N | skeleton, semantic | Cap the answer at N tokens. The footer says how much was withheld, so a trimmed answer never reads as complete |
--json | map, query, impact | Machine-readable output |
paths is the form to feed into a follow-up Read. count answers "is there any?" in one line.
map
Prints directories, what lives in them and how big each part is. <path> narrows the map to one directory or file; the counts and the --json output then cover only that scope.
38 files, 612 symbols indexed under src/billing
by directory:
src/billing/ 21 files, 290 symbols (+188 test)
src/billing/providers/ 9 files, 104 symbols
src/billing/webhooks/ 8 files, 30 symbols (+12 test)
top files (10 of 38, densest first):
src/billing/invoice.ts (44 symbols)
src/billing/providers/stripe.ts (31 symbols +18 test)
…
files: 2247, symbols: 29648
skeleton
Shows signatures only. Each body becomes a // … N lines … marker. --budget defaults to 20k tokens.
import { Money } from "../money";
// … 3 lines …
export interface Invoice {
// … 9 lines …
}
export class InvoiceService {
constructor(private repo: InvoiceRepo) {}
async create(input: NewInvoice): Promise<Invoice> {
// … 22 lines …
async finalize(id: string): Promise<Invoice> {
// … 14 lines …
query
[--context N] [--json]
| Flag | Effect |
|---|---|
--file <path> | Answer about that file only. Repeatable. A path suffix is enough (invoice.ts, billing/invoice.ts), and a directory scopes everything under it |
--context N, -C N | Include N surrounding source lines, so you don't need a follow-up grep |
fn finalizeInvoice — src/billing/invoice.ts:88
called by: handleCheckoutCompleted (src/billing/webhooks/checkout.ts:41), … +3 more
When a name matches many places, the output says so and shows the first 30: [30 of 165 matches shown — narrow the name to see the rest]. Add --file to narrow it.
impact
Lists the files that depend on this one and the symbols they use.
src/billing/invoice.ts declares (17 symbols):
fn (9): create, finalize, voidInvoice, totalFor, …
type (3): Invoice, NewInvoice, InvoiceStatus
dependents (5):
src/billing/webhooks/checkout.ts
src/api/routes/invoices.ts
…
… 12 more file(s) call a name this file declares, but that name has
several declarations, so the call cannot be pinned here.
A file the indexer never parsed says so instead of reporting "no dependents". An empty answer and an unknown file are different facts.
semantic
Aliases: ask, sem. Searches your code by meaning as well as by keyword. It returns the passages that answer, not whole files.
| Flag | Effect |
|---|---|
--limit N, -n N | How many ranked hits to consider (default 10). Raising it looks past the first screen; it does not re-rank |
--budget N | Cap the answer at N tokens |
0.71 src/billing/retry.ts [failed, payment, payments, retry, retried]
0.64 src/billing/webhooks/payment_failed.ts [failed, payment, retry]
0.58 src/jobs/dunning.ts [payment, retried, failed]
[tokenade:depth] 3 shown — the ranking considered 12+. Raise with --limit 6 to look past the first screen.
Several questions in one call share one index build: tokenade semantic "where is auth wired" "how are retries configured". An unquoted sequence of words is read as one question.
The local search model (about 132 MB) is downloaded once, the first time you run semantic.
The index
| Command | Effect |
|---|---|
tokenade index [--force] | Build and cache the symbol index now. --force ignores the cache |
tokenade watch | Reindex incrementally on every save. Ctrl+C to stop |
tokenade semantic-status [--json] | List indexed projects: files, size on disk, last-indexed time. Read-only |
You rarely need index or watch: the commands above build and refresh the index on demand. Indexes live in ~/.tokenade/index.db and ~/.tokenade/semantic.db. Indexes unused for 7 days are dropped by tokenade evict-stale.
Exit codes and gotchas
- Exit
0on success, including "no match". A missing file passed toskeletonorimpactexits1. An unknown flag exits2. - Unknown flags and stray arguments are refused, not folded into the question. A typo fails loudly instead of changing what you asked.
- Quote multi-word questions for
semantic. An unquoted word starting with a dash is read as a flag and refused. no match for '<query>'echoes the question exactly as it was understood, which is the fastest way to see what was searched.- Savings from these commands can't be measured directly (you never read the file you didn't need). They appear as estimates, kept apart from measured savings. See how savings are measured.