context-builder

---
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/`](docs/agent-harness/README.md).

## Installation

```bash
# 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](https://github.com/igorls/context-builder/releases/latest).

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)

1. **AUTHORITY is law** — do not redesign, re-prioritize, or “improve” beyond the packet
2. **Stop on conflict** — if the live repo contradicts AUTHORITY, emit CONFLICT; do not freestyle
3. **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
4. **Prefer a tight AUTHORITY** (≈2–4k tokens): verdict, ordered file-level steps, verification commands
5. **Verification is mandatory** before DONE

### Step-by-step

```bash
# 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
```

2. **Deep Think (Ultra web):** attach `00-context.md`, paste [`docs/agent-harness/templates/01-problem.md`](docs/agent-harness/templates/01-problem.md), require AUTHORITY shape from [`02-authority.md`](docs/agent-harness/templates/02-authority.md).
3. **Human:** trim fluff → save `02-authority.md` (budget beats volume for Flash).
4. **Agent:** load system prompt from [`docs/agent-harness/antigravity-system-prompt.md`](docs/agent-harness/antigravity-system-prompt.md); paste [`03-build.md`](docs/agent-harness/templates/03-build.md) with AUTHORITY inlined or path-referenced.
5. **Agent returns** RESULT ([`04-result.md`](docs/agent-harness/templates/04-result.md)) or CONFLICT ([`05-conflict.md`](docs/agent-harness/templates/05-conflict.md)).
6. **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`](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)

```bash
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)

```bash
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)

```bash
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

```bash
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

```bash
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

```bash
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:

```toml
timestamped_output = true
auto_diff = true
```

Then run twice:

```bash
# 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):

```bash
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)

```bash
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](#deep-think-authority-pipeline-primary-multi-model-workflow) above, not a freeform paste.

### Recipe: API Surface Review (signatures only)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```toml
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