name: context-builder description: > Package codebases into LLM-optimized markdown, and run the Deep Think Authority pipeline (context-builder → Deep Think review → structured AUTHORITY → Flash/Antigravity implementation agent). Use when generating project context, preparing Deep Think reviews, or binding a weaker coding agent to a senior reasoning pass. homepage: https://github.com/igorls/context-builder version: 0.10.0 requires:

context-builder

Context Builder — Agentic Skill

Generate a single, structured markdown file from any codebase directory. The output is optimized for LLM consumption with relevance-based file ordering, AST-aware code signatures, automatic token budgeting, and smart defaults.

Also: orchestrate the Deep Think Authority handoff so tool-using agents (Antigravity, Gemini Flash, etc.) implement senior one-shot reviews instead of freelancing. Full harness: docs/agent-harness/.

Installation

# Requires Rust toolchain. Builds from source with cryptographic verification via crates.io.
cargo install context-builder --features tree-sitter-all

Pre-built binaries with SHA256 checksums are also available for manual download from GitHub Releases.

Verify: context-builder --version (expected: 0.10.0)

Security & Path Scoping

IMPORTANT: This tool reads file contents from the specified directory. Agents MUST follow these rules:

Only target explicit project directories — always pass the exact project root (e.g., /home/user/projects/myapp). Never point at home directories, system paths, or credential stores (~/.ssh, ~/.aws, /etc, ~, /)
Use scoped filters — use -f to limit to known source extensions (e.g., -f rs,toml,md), reducing exposure surface
Output to project-local paths — write output to the project's docs/ folder or /tmp/, never to shared or public locations
Review before sharing — the output may contain API keys, secrets, or credentials embedded in source files; always review or use .gitignore patterns to exclude sensitive files

Built-in protections (always active, no configuration needed):

Excludes .git/, node_modules/, and 19 other heavy/sensitive directories at any depth
Respects .gitignore rules when a .git directory is present
Binary files are auto-detected and skipped via UTF-8 sniffing
Output file and cache directory are auto-excluded to prevent self-ingestion

When to Use

Deep code review — Feed an entire codebase to an LLM for architecture analysis or bug hunting
Deep Think → agent pipeline — Package context for Ultra Deep Think, then bind Antigravity/Flash to the resulting AUTHORITY document
Onboarding — Generate a project snapshot for understanding unfamiliar codebases
Diff-based updates — After code changes, generate only the diffs to update an LLM's understanding
AST signatures — Extract function/class signatures for token-efficient structural understanding
Cross-project research — Quickly package a dependency's source for analysis

Deep Think Authority Pipeline (primary multi-model workflow)

Weak agent harnesses (e.g. Gemini Flash in Antigravity) are strong at tools and weak at novel reasoning. Deep Think (Ultra web) is the inverse. Do not try to make Flash invent architecture. Inject Deep Think as law, then let Flash execute.

context-builder  →  Deep Think (AUTHORITY)  →  Agent BUILD  →  RESULT
                         ↑                         │
                         └──── CONFLICT / DEBUG ────┘

Agent rules (always)

AUTHORITY is law — do not redesign, re-prioritize, or “improve” beyond the packet
Stop on conflict — if the live repo contradicts AUTHORITY, emit CONFLICT; do not freestyle
Do not re-inject the full context dump into the agent — Deep Think already distilled it; the agent should use tools on the real tree
Prefer a tight AUTHORITY (≈2–4k tokens): verdict, ordered file-level steps, verification commands
Verification is mandatory before DONE

Step-by-step

# 0) Size check
context-builder -d /abs/path/to/project --token-count

# 1) Package for Deep Think (adjust -f to the language)
mkdir -p docs/handoffs/$(date +%Y-%m-%d)-topic
context-builder -d /abs/path/to/project \
  -f rs,toml,md \
  --max-tokens 120000 \
  -y -o docs/handoffs/$(date +%Y-%m-%d)-topic/00-context.md

Deep Think (Ultra web): attach 00-context.md, paste docs/agent-harness/templates/01-problem.md, require AUTHORITY shape from 02-authority.md.
Human: trim fluff → save 02-authority.md (budget beats volume for Flash).
Agent: load system prompt from docs/agent-harness/antigravity-system-prompt.md; paste 03-build.md with AUTHORITY inlined or path-referenced.
Agent returns RESULT (04-result.md) or CONFLICT (05-conflict.md).
Optional second Deep Think pass: context-builder -d ... -y --diff-only after implementation.

Harness overview, attention budget, and re-escalation table: docs/agent-harness/README.md.

What this changes about Flash’s behavior

| Without AUTHORITY | With engineered AUTHORITY | | --- | --- | | Invents architecture mid-task | Executes ordered steps | | Thrash-refactors “while here” | Surgical diffs only | | Vague “done” | Verification commands required | | Silent plan failure | CONFLICT stop → re-escalate |

It does not give Flash Deep Think’s raw intelligence. It meaningfully raises implementation fidelity when AUTHORITY is high quality.

Core Workflow

1. Quick Context (whole project)

context-builder -d /path/to/project -y -o context.md

-y skips confirmation prompts (recommended for agent workflows when path is explicitly scoped)
Output includes: header → file tree → files sorted by relevance (config → source → tests → docs)

2. Scoped Context (specific file types)

context-builder -d /path/to/project -f rs,toml -i docs,assets -y -o context.md

-f rs,toml includes only Rust and TOML files
-i docs,assets excludes directories by name

3. AST Signatures Mode (minimal tokens)

context-builder -d /path/to/project --signatures -f rs,ts,py -y -o signatures.md

Replaces full file content with extracted function/class signatures (~4K vs ~15K tokens per file)
Supports 8 languages: Rust, JavaScript (.js/.jsx), TypeScript (.ts/.tsx), Python, Go, Java, C, C++
Requires --features tree-sitter-all at install time

4. Signatures with Structural Summary

context-builder -d /path/to/project --signatures --structure -y -o context.md

--structure appends a count summary (e.g., "6 functions, 2 structs, 1 impl block")
Combine with --visibility public to show only public API surface

5. Budget-Constrained Context

context-builder -d /path/to/project --max-tokens 100000 -y -o context.md

Caps output to ~100K tokens (estimated)
Files are included in relevance order until budget is exhausted
Automatically warns if output exceeds 128K tokens

6. Token Count Preview

context-builder -d /path/to/project --token-count

Prints estimated token count without generating output
Use this first to decide if filtering or --signatures is needed

7. Incremental Diffs

First, ensure context-builder.toml exists with:

timestamped_output = true
auto_diff = true

Then run twice:

# First run: baseline snapshot
context-builder -d /path/to/project -y

# After code changes: generates diff annotations
context-builder -d /path/to/project -y

For minimal output (diffs only, no full file bodies):

context-builder -d /path/to/project -y --diff-only

Smart Defaults

These behaviors require no configuration:

| Feature | Behavior | |---------|----------| | Auto-ignore | node_modules, dist, build, __pycache__, .venv, vendor, and 12 more heavy dirs are excluded at any depth | | Self-exclusion | Output file, cache dir, and context-builder.toml are auto-excluded | | .gitignore | Respected automatically when .git directory exists | | Binary detection | Binary files are skipped via UTF-8 sniffing | | File ordering | Config/docs first → source (entry points before helpers) → tests → build/CI → lockfiles |

CLI Reference (Agent-Relevant Flags)

| Flag | Purpose | Agent Guidance | |------|---------|----------------| | -d <PATH> | Input directory | Always use absolute paths for reliability | | -o <FILE> | Output path | Write to project docs/ or /tmp/ | | -f <EXT> | Filter by extension | Comma-separated: -f rs,toml,md | | -i <NAME> | Ignore dirs/files | Comma-separated: -i tests,docs,assets | | --max-tokens <N> | Token budget cap | Use 100000 for most models, 200000 for Gemini | | --token-count | Dry-run token estimate | Run first to check if filtering is needed | | -y | Skip all prompts | Use only with explicit, scoped project paths | | --preview | Show file tree only | Quick exploration without generating output | | --diff-only | Output only diffs | Minimizes tokens for incremental updates | | --signatures | AST signature extraction | Requires tree-sitter-all feature at install | | --structure | Structural summary | Pair with --signatures for compact output | | --visibility <V> | Filter by visibility | all (default), public (public API only) | | --truncate <MODE> | Truncation strategy for --max-tokens | smart (AST-aware) or byte | | --init | Create config file | Auto-detects project file types | | --clear-cache | Reset diff cache | Use if diff output seems stale |

Recipes

Recipe: Deep Think Code Review (one-shot only)

context-builder -d /path/to/project -f rs,toml --max-tokens 120000 -y -o docs/deep_think_context.md
# Attach to Deep Think + a structured review prompt (see docs/research/prompts/)

For review → implement (Deep Think then Antigravity), use the Deep Think Authority Pipeline above, not a freeform paste.

Recipe: API Surface Review (signatures only)

# Extract only public signatures — typically 80-90% fewer tokens than full source
context-builder -d /path/to/project --signatures --visibility public -f rs -y -o docs/api_surface.md

Recipe: Compare Two Versions

# Generate context for both versions
context-builder -d ./v1 -f py -y -o /tmp/v1_context.md
context-builder -d ./v2 -f py -y -o /tmp/v2_context.md

# Feed both to an LLM for comparative analysis

Recipe: Monorepo Slice

# Focus on a specific package within a monorepo
context-builder -d /path/to/monorepo/packages/core -f ts,tsx -i __tests__,__mocks__ -y -o core_context.md

Recipe: Quick Size Check Before Deciding Strategy

# Check if the project fits in context
context-builder -d /path/to/project --token-count

# If > 128K tokens, try signatures mode first:
context-builder -d /path/to/project --signatures --token-count

# Or scope it down:
context-builder -d /path/to/project -f rs,toml --max-tokens 100000 --token-count

Configuration File (Optional)

Create context-builder.toml in the project root for persistent settings:

output = "docs/context.md"
output_folder = "docs"
filter = ["rs", "toml"]
ignore = ["target", "benches"]
timestamped_output = true
auto_diff = true
max_tokens = 120000
signatures = true
structure = true
visibility = "public"

Initialize one automatically with context-builder --init.

Output Format

The generated markdown follows this structure:

# Directory Structure Report
[metadata: project name, filters, content hash]

## File Tree
[visual tree of included files]

## Files
### File: src/main.rs
[code block with file contents, syntax-highlighted by extension]

### File: src/lib.rs
...

Files appear in relevance order (not alphabetical), prioritizing config and entry points so LLMs build understanding faster.

When --signatures is active, file contents are replaced with extracted signatures:

### File: src/lib.rs
```rust
pub fn run_with_args(args: Args, config: Config, prompter: &dyn Prompter) -> Result<()>
pub fn generate_markdown_with_diff(...) -> Result<String>
```

Error Handling

If context-builder is not installed, install with cargo install context-builder --features tree-sitter-all
If --signatures shows no output for a file, the language may not be supported or the feature was not enabled at install
If output exceeds token limits, add --max-tokens or narrow with -f / -i, or use --signatures
If the project has no .git directory, auto-ignores still protect against dependency flooding
Use --clear-cache if diff output seems stale or incorrect

Context Builder: Codebase-to-LLM Context Generator

Recommended for