README.md

Source outlines #

The outline tool provides a source outline. It keeps declarations, comments, and original line ranges. It hides function bodies, including declarations inside them.

Language File extensions
TypeScript .ts, .mts, .cts
TSX .tsx
Go .go
Rust .rs
Python .py, .pyi
C .c, .h
Lua .lua
Bash .sh, .bash

Prefer it for navigation in unfamiliar supported files. Use read directly for known ranges, implementation details, or exact edits. Read the original ranges before edits or behavior claims. Normal read stays unchanged.

Reload Pi with /reload to load the tool. It is available as a direct tool and through codemode:

Codemode receives structured data. Outline results contain mode, path, language, and declarations. Each entry has kind, startLine, endLine, and text. Entries describe top-level source nodes, including comments and attributes. kind uses tree-sitter names. Enclosing declarations contain method outlines.

Select the entries you need instead of printing all data:

const result = await tools.outline({ path: "src/example.ts" });
if (result.mode === "outline") {
    text(result.declarations.filter((entry) => entry.startLine <= 80));
} else {
    for (const part of result.content) {
        if (part.type === "image") {
            image(part);
        } else {
            text(part.text);
        }
    }
}

Raw and error results contain the original text/image blocks in content and a reason. A failed read has mode: "error" and remains a failed tool call. Codemode receives this error data so scripts can handle it. Direct calls keep readable text, with results hidden until expanded.

Rust outlines keep attributes, qualifiers, type members, trait and impl structure, modules, and macro text. They omit function and closure bodies. They do not expand macros or evaluate conditional compilation.

Python outlines keep decorators, class structure, and function signatures. Lua outlines keep function headers and end markers. C outlines keep type declarations, macros, and preprocessor branches. C headers use the C grammar. Bash outlines keep commands outside functions and redirects attached to function declarations. Conditional compilation and shell commands are not evaluated.

The tool reads through Pi's current read pipeline. Existing path checks and read limits apply. Unsupported, truncated, invalid, or unreduced input stays raw. Read failures and cancellation remain failures.

Run checks from the repository root:

pnpm --filter pi-extension-outline test