pyramid-context

Multi-resolution codebase context for AI coding agents.

Generate a pyramid of context at three zoom levels — a scannable L0 index in your agent config, L1 summaries on disk, and L2 detail files per module — so AI agents can understand your entire codebase without wasting context tokens.

Based on StrongDM's pyramid summaries pattern for AI agent codebase comprehension. See Prior Art for details.

Quick Start

npx pyramid-context

This scans ./src, generates L0/L1/L2 context, and injects the L0 index into AGENTS.md.

How It Works

| Level | Detail | Location | Purpose | |-------|--------|----------|---------| | L0 | 2-3 word tag per file | AGENTS.md / CLAUDE.md | Scan the whole codebase at a glance | | L1 | One sentence per file | .context/L1.md | Decide which files to read deeper | | L2 | Exports, imports, deps | .context/{path}.md | Understand a module without reading source |

L2 files are generated per source file (e.g. .context/analyzers/typescript.ts.md), so agents can pull only the modules they need into context rather than loading the whole codebase.

Commit .context/ to git — the generated context is useful for anyone (human or AI) reading the codebase. Re-run pyramid-context when source changes to keep it fresh.

Install

npm install -g pyramid-context    # global
npm install -D pyramid-context    # devDependency
npx pyramid-context               # one-shot

Usage

# Generate pyramid (default: scans ./src)
pyramid-context

# Custom source directory
pyramid-context --src lib

# Explicit target file
pyramid-context --target AGENTS.md

# Language filter
pyramid-context --lang ts,js

# Use LLM for better descriptions
pyramid-context --llm

# Check if pyramid is stale (for CI / hooks)
pyramid-context --check

# Dry run
pyramid-context --dry-run

# Initialize project
pyramid-context init

Configuration

Optional .pyramidrc.json:

{
  "src": ["src", "lib"],
  "targets": ["AGENTS.md", "CLAUDE.md"],
  "exclude": ["**/*.test.ts", "**/*.spec.ts"],
  "contextDir": ".context",
  "llm": {
    "enabled": true,
    "provider": "anthropic",
    "apiKeyEnv": "ANTHROPIC_API_KEY",
    "model": "claude-haiku-4-5-20251001"
  }
}

LLM Configuration

When --llm is passed (or llm.enabled is set in config), pyramid-context calls an LLM to generate higher-quality L0 tags and L1 summaries. Without an API key it silently falls back to heuristic analysis.

| Field | Default | Description | |-------|---------|-------------| | llm.provider | "anthropic" | "anthropic" or "openai" | | llm.apiKeyEnv | "ANTHROPIC_API_KEY" | Environment variable holding the API key. Restricted to ANTHROPIC_API_KEY, OPENAI_API_KEY, LITELLM_API_KEY. | | llm.model | "claude-haiku-4-5-20251001" | Model ID to use | | llm.baseUrl | (provider default) | Custom API base URL |

LLM results are cached in the manifest — unchanged files won't be re-sent on subsequent runs.

L0 Format

A single pipe-delimited line optimized for minimal tokens:

[Codebase Map]|root:./src|L1:.context/L1.md|L2:.context/{path}.md|agent/{loop.ts:goal poller,runner.ts:LLM tool loop}|tools/{bash.ts:shell exec,wiki.ts:shared wiki}

For a 30-file project, the entire L0 index fits in ~300 tokens.

Language Support

| Language | Extensions | Export Detection | Import Detection | |----------|-----------|-----------------|-----------------| | TypeScript | .ts, .tsx | export function/class/interface/type/const | from '...' | | JavaScript | .js, .jsx, .mjs, .cjs | export, module.exports | from '...', require() | | Python | .py | Top-level def, class, __all__ | import, from ... import | | Go | .go | Capitalized names | import "..." | | Rust | .rs | pub fn/struct/enum/trait | use ... |

Hook Integration

Claude Code

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "npx pyramid-context --check && exit 0 || npx pyramid-context"
      }]
    }]
  }
}

Git Pre-Commit

npx pyramid-context --check 2>/dev/null || npx pyramid-context
git add AGENTS.md CLAUDE.md .context/ 2>/dev/null

Programmatic API

import { generatePyramid, injectIntoFile } from 'pyramid-context'

const pyramid = await generatePyramid({
  src: ['src'],
  languages: ['typescript'],
})

// pyramid.files — array of { path, l0, l1, l2, hash }
// pyramid.l0Index — pipe-delimited string
// pyramid.l1Content — markdown string
// pyramid.staleCount — number of changed files

Porting to Other Languages

The full specification lives in SPEC.md — it describes every output format, algorithm, and edge case in enough detail to reimplement pyramid-context in any language.

The fastest way to port it: give SPEC.md to an AI coding agent and ask it to implement the spec in your language of choice.

Here is a specification for a codebase context generator.
Please implement it in [Python/Go/Rust/etc].

<paste SPEC.md contents>

The spec is self-contained — it covers the output formats (L0/L1/L2), the analyzer regex patterns for each language, the injection algorithm, the manifest format, and the security considerations. No knowledge of this TypeScript implementation is needed.

Prior Art

| Tool | Approach | Limitation | |------|----------|------------| | Vercel @next/codemod agents-md | Pipe-delimited docs index | Next.js-specific | | Aider .aider.repo-map | AST-based repo map | Aider-specific, requires tree-sitter | | StrongDM pyramid summaries | Multi-resolution LLM summaries | Internal technique, not packaged |

pyramid-context combines the best ideas: Vercel's surgical injection + StrongDM's multi-resolution pyramid + universal agent support + automatic code analysis.

License

MIT