@tduyng/pi-outline

A map of a source file instead of the file. One call lists every declaration with its line span, so the read that follows fetches one body.

A 1,213-line TypeScript file puts 51 KB into the transcript, and every later turn of the session re-reads it. The depth-1 outline of that file is 47 rows, about 3 KB, and it names the lines worth reading.

How it works

outline(path: "src/goal.ts", depth: 1)

Depth runs from 0 to 5 and defaults to 1. Depth 0 lists top-level declarations, each extra level adds members, and a row with children past the depth ends in [N nested].

| Language | Declarations | | --- | --- | | TypeScript, JavaScript | functions, classes, interfaces, type aliases, enums, class methods | | Python | def, class | | Go | func, type | | Rust | fn, struct, enum, trait, impl, mod | | Markdown | headings |

Headings inside code fences are ignored.

There is no parser. A parser means a dependency, a language server, and a version of both that disagrees with the repository. The outline is built from single-line rules over the text, and spans come from indentation: a declaration runs until the next line at the same or a lower indent, and includes the closing brace that follows its body.

That covers the languages people actually outline, and a miss is visible. A file the rules do not cover gets a line saying so, with grep and a ranged read as the fallback.

With the read guard

pi-subagent's bulk-read guard blocks a read of a file over 350 lines, and its block message names outline first. outline is deferred, and the guard's message carries the codemode call that reaches it (await tools.outline({path})), so nothing is declared on a request that will not need it. The attempt to read a whole file over 350 lines also arms the tool, which puts it in the list for the turn that acts on the message. A live session read a 400-line file in one call: the first call was refused, the retry went through as the guard intends, and the model's next turn named outline among its tools.

Without the guard the tool still works, it just stops being the thing that catches an oversized read.

Install

pi install npm:@tduyng/pi-outline

Local checkout: pi install /path/to/dotfiles/pi/agent/extensions/pi-outline

Limits

• Files over 2 MB are refused, since the map would be bigger than the useful part.
• At most 200 rows, and a row is cut at 120 characters.
• Spans come from indentation, so unusual formatting can miss a declaration, and an object-literal method can show up as a member.
• No types, no imports, no call graph.