# map, skeleton, query, impact, semantic

> Find where code lives, see a file's shape, locate symbols, measure a change's blast radius and search by meaning, without reading whole files.

Source: https://tokenade.net/en/docs/code-intelligence · Updated: 2026-10-07

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

```text
tokenade map [<path>] [-o full|paths|count] [--json]
```

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.

```text
$ tokenade map src/billing
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)
  …
```

```text
$ tokenade map -o count
files: 2247, symbols: 29648
```

## skeleton

```text
tokenade skeleton <file…> [-o full|paths|count] [--budget N]
```

Shows signatures only. Each body becomes a `// … N lines …` marker. `--budget` defaults to 20k tokens.

```text
$ tokenade skeleton src/billing/invoice.ts
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

```text
tokenade query <symbol…> [--file <path>…] [-o full|paths|count|outline]
                         [--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 |

```text
$ tokenade query finalizeInvoice
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

```text
tokenade impact <file…> [-o full|paths|count] [--json]
```

Lists the files that depend on this one and the symbols they use.

```text
$ tokenade impact src/billing/invoice.ts
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

```text
tokenade semantic "<query>"…  [-o <mode>] [--budget N] [--limit N]
```

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 |

```text
$ tokenade semantic "where are failed payments retried" --limit 3
 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`](https://tokenade.net/en/docs/maintenance).

## Exit codes and gotchas

- Exit `0` on success, including "no match". A missing file passed to `skeleton` or `impact` exits `1`. An unknown flag exits `2`.
- 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](https://tokenade.net/en/docs/savings-measurement).

## Related

- [Read documents and media](https://tokenade.net/en/docs/read-documents-media)
- [How savings are measured](https://tokenade.net/en/docs/savings-measurement)
- [How hooks intercept tool calls](https://tokenade.net/en/docs/hooks)
- [Maintenance commands](https://tokenade.net/en/docs/maintenance)
