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.

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.

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.

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.

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 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.