---
description: Reminder that agents must route exploration through the `ft` binary. Fire when an agent is burning context on raw Read/Grep/rg, hand-prefixing `ft`, or hitting `ft ft`/`ft <unknown>` errors. Triggers on /use-ft, "use ft", "stop grepping", "you forgot ft".
allowed-tools: Bash, Read, Grep
---

# Use ft

Audience: AI coding agents first.

You are burning context on raw exploration. Fix now, this turn.

## Rules

1. **Locating a symbol → `ft sym <Name>`. NEVER Grep-then-Read.** Declaration sites only. Measured 62B vs 1217B for the same `rg`.
2. **One file's shape → `ft outline <file>`.** Declarations, no bodies. NEVER Read a whole file to find where a function lives.
3. **Unfamiliar tree → `ft map [dir]`.** file→declaration map. NEVER Glob-then-Read-many.
4. **NEVER hand-prefix `ft` on a Bash command.** The `bash-gate` PreToolUse hook wraps high-output commands itself. `ft ft <cmd>` is REFUSED, exit 2.
5. **NEVER prefix `ft` on `map`/`sym`/`refs`/`outline`.** Already compact.
6. **Full raw output → `FT_FULL=1 <cmd>`.** Only when the filtered form genuinely lost what you need.

```bash
# DO NOT
Grep(pattern:"function run_sym") ; Read(file) ; rg -n run_sym
ft rg -n run_sym                 # hook already wraps; ft ft = exit 2
# target
ft sym run_sym
ft outline src/repomap.rs
```

## Where ft does NOT apply

- `ft sym`/`map`/`outline` see **source extensions only** (ts tsx js jsx mjs cjs astro vue svelte rs py) and **declarations only**. Config, comments, string literals, `.env`, dotfiles are invisible. A miss is NOT proof of absence → fall back to Grep.
- `ft refs <Name>` = scoped rename survey ONLY. Measured LARGER than `rg` on common identifiers (`useState`: 8752B vs 7592B). NEVER a general-search replacement.
- Regex / substring / non-source files → Grep stays correct.

## Verify the surface

Run `ft --help` — it lists every command with a dedicated filter and the code-nav verbs. That output is authoritative; do not guess what ft wraps.

Canonical doctrine: `~/.claude/CLAUDE.md` § Bash. Do not restate it elsewhere.