LLMText Format

Overview

LLMText is the code-outline output format built for Large Language Model input. It prints one line per symbol — class, function, method, type, import, Markdown heading, JSON or YAML key — with the line range where it lives, under the file's real path. Those are the coordinates rg -n prints and an editor or agent opens, so an outline line leads straight to the code.

Key features

• One line per symbol — grammar plumbing (statement blocks, class bodies, object literals) and function locals are folded away.
• Line ranges — every symbol carries its first and last line, 1-based and inclusive.
• Shared kinds — fn, method, class, interface, type, const, and more, the same across TypeScript, JavaScript, Python, Java, C#, Rust, and TypedMind.
• Imports keep their module — imports and re-exports print their source text on one line.

Format structure

After the file header (path (NL)), each line is one symbol. Indentation, one space per level, encodes nesting.

<line>[-<endLine>] [export] <kind> <name>

Usage

# Outline a directory
code-outline "src/**/*.ts" --format llmtext

# Top-level symbols only; --depth counts symbol levels in llmtext
code-outline "src/**/*.ts" --format llmtext --depth 1

# Where is it defined? Matching symbols with their enclosing symbols
code-outline "src/**/*.ts" --match getUser

# Which function is each rg hit inside?
rg -n "findById" src | code-outline --at -

Example output

Given this TypeScript file:

// example.ts
import { Database } from './db';

export class UserService {
  constructor(private db: Database) {}

  async getUser(id: string): Promise<User> {
    return this.db.users.findById(id);
  }

  async createUser(data: UserData): Promise<User> {
    return this.db.users.create(data);
  }
}

export function validateEmail(email: string): boolean {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

Running code-outline example.ts --format llmtext against it:

<Outline format="llmtext-v2">
# <line>[-<endLine>] [export] <kind> <name>; imports/re-exports, headings, and data keys print their text after the range; "! N syntax errors" follows a file header; one space of indent per nesting level; lines 1-based, inclusive
example.ts (18L)
2 import { Database } from './db'
4-14 export class UserService
 5 method constructor
 7-9 method getUser
 11-13 method createUser
16-18 export fn validateEmail
</Outline>

code-outline example.ts --match user keeps the matching symbols and the class around them:

<Outline format="llmtext-v2">
# <line>[-<endLine>] [export] <kind> <name>; imports/re-exports, headings, and data keys print their text after the range; "! N syntax errors" follows a file header; one space of indent per nesting level; lines 1-based, inclusive
example.ts (18L)
4-14 export class UserService
 7-9 method getUser
 11-13 method createUser
</Outline>

rg -Hn "findById" example.ts | code-outline --at - places each hit inside its symbols (-H keeps the file name, which rg omits when searching one file):

example.ts:8  class UserService (4-14) > method getUser (7-9)

The previous format (type_name line:col per syntax node) remains available as --format llmtext-v1.

Comparison with other formats

Use cases

• AI code analysis — give an LLM codebase context without spending its context window on JSON punctuation.
• Code documentation — generate a compact structure summary.
• Automated reviews — feed structure data to an AI review pipeline.
• Code understanding — help an agent orient in a large codebase quickly.

Integration examples

# Pipe to an LLM CLI
code-outline "src/**/*.ts" --format llmtext | your-llm-cli "Analyze this codebase structure"

# Save for later AI processing
code-outline "src/**/*.ts" --format llmtext > codebase-context.txt

# Register the MCP server instead of shelling out
claude mcp add code-outline -- code-outline-mcp