sift

Read a file and return a distilled view of what is in it instead of its text. This is for anything already written down that would flood the conversation if opened whole: a log, a saved build or CI transcript, a test report, a crash dump, a long JSON export. The server opens the file, so its contents never enter the conversation -- a 40,000-line log costs a screenful -- and every line shown is the file's own, byte for byte, with `peek` on the same path returning any range in full. Use `outline` instead when the file is source code and the question is what it declares.

Digest several files in one call, asked at the same time. Use it whenever there is more than one file to read: four logs cost four waits asked one by one and roughly one wait asked together, and come back as one tool result instead of four. Each file keeps its own last line saying which it is, and a file that cannot be read says so in its place rather than taking the others down with it.

Return what a background command has printed since the last time you asked, and nothing you have already been shown. Use it with the handle from a `run` call made with `background`. The lines keep the numbers they have in the whole run, so `peek` on any of them returns that same line; a stretch that was only progress comes back as a gap saying how many lines it stands for, and a quiet minute comes back as nothing at all rather than as filler. Set `stop` when you are done with the command: it ends it, and everything it started, and returns the last of the output. Always stop a command you are finished with -- a background command left alone keeps running. With `everything` it answers about every run still going in one call, which is what to use when you started three things and want to know where they are. With `wait` it holds until something is actually said rather than coming back empty: an empty answer is a tool result that stays in the conversation for the rest of it, so waiting once costs less than asking five times.

Return what a file declares -- its types, functions, exports, targets and settings -- without their bodies, so that reading a 2,000-line source file costs a page. This is the machine behind `run` asked a different question: it holds no table of languages and never reads the suffix, so it answers about Rust, Haskell, a Makefile, a config file with no extension, or a language that did not exist last year. Lines come from the file byte for byte, and `peek` on the same path returns any range of it in full.

Return the exact original lines of a capture or a file, byte for byte, with the line numbers they had there. Use it with the handle at the end of a `run` result, or with any path, to open up a gap that a view left behind. A range reaching past the end is clamped rather than refused, and with no range at all it returns the whole thing. With `grep` it searches instead: every line matching your pattern comes back with a few lines of context around it, which is the way into a gap when you know the word you want but not the line number.

Run a shell command and return only the lines that mattered instead of all of its output. Every byte is kept on disk and never enters the conversation, so a 5,000-line test run costs a few dozen lines of context -- and goes on costing nothing on every later turn, because tool results are re-sent with the rest of the transcript. The lines shown are the command's own, byte for byte; each gap states how many lines it stands for, and `peek` with the returned handle brings any range back in full. Prefer this over a plain shell tool whenever the output may be long or noisy. When you already know what you are looking for -- a symbol, a test name, an error code -- pass it as `keep` and every line containing it comes back whatever else was chosen.

Run one of three dense tools and return a distilled view of what it printed: `sg` (ast-grep) for structural search, `diff` (difftastic) for a diff that can tell a reindent from a change, `loc` (scc) for the size of a tree. Each of them answers a question *without opening the file* -- reach for `sg` instead of reading candidates to find where a shape occurs, and `loc` instead of listing a directory to size it. Their output is large by nature and is distilled like anything else, so a 4,000-line structural search costs a screenful with every byte still reachable through `peek`. A tool this machine does not have says so and says what it is called; nothing is installed for you.