build_project_context
Scans a repository and builds a token-optimized, multi-tier AST context for LLM prompts, enabling architecture-aware coding sessions and refactors within a set token budget.
Instructions
Scans the target repository file system and constructs a token-optimized AST context payload for LLM prompts across multiple hierarchy tiers (T-1 to T-4), distinguishing from 'prune_code_snippet' and 'search_codebase' by constructing multi-tier repository architecture trees rather than pruning individual in-memory snippets or executing keyword searches.
Parameters:
project_root(str, optional, default='.'): Target repository root path to scan.context_type(str, optional, default='tree'): Context generation mode: 'tree' for hierarchical multi-tier AST tree, 'repo_map' for compact symbol index, 'skeleton' for focus-file implementation with 1st-degree caller/callee skeletons, 'zero_waste_prompt' for agent prompt prefix with pruned AST, 'incremental_diff' for git diff context.focus_file(str, optional, default=''): Optional path to a focus file when context_type is 'skeleton' or 'incremental_diff'.reduction_mode(str, optional, default='ultra'): AST reduction depth level ('ultra' for 80-95% compression with signatures and docstrings, 'balanced' for signatures + control structures, 'none' for verbatim source code).max_tokens(int, optional, default=64000): Upper token budget threshold for returned context.include_file_contents(bool, optional, default=True): If True, includes AST-reduced file bodies; if False, emits directory hierarchy only.
Behavior:
Read-only: Scans workspace files and parses AST signatures without modifying disk state.
Idempotent: Generates deterministic context representations for identical workspace revisions.
100% Offline: Operates entirely locally with zero telemetry, remote embedding APIs, or cloud billing.
Auth & Rate Limits: Zero authentication or cloud credentials required; completes in <2s for 1,000 files.
Error Handling: Returns clean Markdown warning notices if no analyzable files exist in the specified path.
Usage Guidelines:
When to use: Ingest repository architecture, module indexes, focus file skeletons, or zero-waste prompts at the beginning of an agent coding session or major refactor (80-95% token savings).
When NOT to use: Do not use for stripping implementation bodies from a single in-memory code string or diff patch (use 'prune_code_snippet' instead); do not use for querying specific code symbols or text without building a full context tree (use 'search_codebase' instead).
Returns: Structured Markdown document featuring '# Repository Architecture (T-1)', '# Module Dependencies (T-2)', '# AST Signatures (T-3)', '# Architectural Rules (T-4)', and token compression metrics.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| focus_file | No | Optional path to a focus file when context_type is 'skeleton' or 'incremental_diff'. | |
| max_tokens | No | Upper token budget threshold for returned context. | |
| context_type | No | Context generation mode: 'tree' for hierarchical multi-tier AST tree, 'repo_map' for compact symbol index, 'skeleton' for focus-file implementation with 1st-degree caller/callee skeletons, 'zero_waste_prompt' for agent prompt prefix with pruned AST, 'incremental_diff' for git diff context. | tree |
| project_root | No | Target repository root path to scan (default: current working directory). | . |
| reduction_mode | No | AST reduction level: 'ultra' for signatures & docstrings (80-95% reduction), 'balanced' for signatures + control headers, 'none' for verbatim source. | ultra |
| include_file_contents | No | When True, includes AST-reduced file bodies; when False, emits directory hierarchy only. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |