Repo Maps: Giving AI Your Project Structure

The repo_map artifact gives AI a compact, structured representation of your entire project layout. Instead of sending directory listings or hoping the AI infers structure from file contents, you provide a pre-built map that covers directory trees, package manifests, entry points, module structure, and build configuration.

Use this page when

• You are configuring which artifact types to build for a repository and want to understand what repo_map provides.
• You need to troubleshoot why AI assistants lack project-structure awareness.
• You are evaluating token savings from pre-built structural context versus ad-hoc directory descriptions.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

What a Repo Map Contains

A repo_map artifact captures the structural skeleton of your repository:

Directory Tree

The hierarchical layout of your project, including:

• Top-level directories and their roles (source, tests, config, docs)
• Nested package boundaries
• File counts and types per directory
• Ignored paths (build outputs, dependencies)

Package Manifests

Parsed metadata from your package definition files:

• package.json — name, version, scripts, dependency lists
• Cargo.toml — crate name, edition, features, workspace members
• pyproject.toml — project metadata, build system, tool configs
• Monorepo workspace definitions and member relationships

Entry Points

The files where execution begins or external consumers connect:

• Binary entry points (main.rs, index.ts, app.py)
• Library entry points and public API surfaces
• CLI command registrations
• Server bootstrap files

Module Structure

How code is organized into logical units:

• Module declarations and re-exports
• Package-internal boundaries
• Public versus internal modules
• Circular dependency warnings

Build Configuration

How the project compiles, bundles, and deploys:

• Build tool configuration (webpack, vite, cargo, tsc)
• Output directories and formats
• Environment-specific build variants
• CI/CD pipeline structure

How Repo Maps Are Built

The Fabric pipeline builds repo_map artifacts from repository tree metadata. The process does not read file contents beyond manifest files — it analyzes the structural layout:

1. Walk the directory tree — Enumerate all paths, respecting .gitignore and configured exclusions
2. Parse manifests — Extract metadata from package definition files at each level
3. Identify entry points — Locate binary, library, and server entry points from manifest declarations
4. Map module boundaries — Detect module declarations, workspace members, and package boundaries
5. Record build config — Parse build tool configuration for output and bundling metadata

The entire process runs without executing your code or installing dependencies.

How Repo Maps Reduce Prompt Size

Without a repo map, engineers typically provide context like:

"My project has a console/ directory with Next.js, an api/ directory with Rust/Axum, a cli/ directory with Rust/Clap..."

This ad-hoc description is incomplete and costs tokens every time. With a repo map, the AI receives a structured artifact that communicates the same information in fewer tokens with more precision.

A typical monorepo repo_map fits in 800–2,000 tokens. The equivalent unstructured description, if complete, would cost 5,000–15,000 tokens.

Sharing Across Your Organization

The repo_map artifact is the most widely shared artifact type. Every engineer working on the same repository benefits from the same structural understanding:

• New team members get accurate project overviews instantly
• Cross-team contributors understand unfamiliar packages without exploration
• AI assistants produce architecturally aware suggestions from the first interaction

Since project structure changes infrequently compared to file contents, a single repo_map build serves hundreds of interactions before requiring regeneration.

When Repo Maps Regenerate

A repo_map regenerates when structural changes occur:

• New directories or packages are added
• Package manifests change (new dependencies, scripts, workspace members)
• Entry points are added or removed
• Build configuration changes significantly

File content changes within existing modules do not trigger regeneration. The map remains valid as long as the structural skeleton is unchanged.

Use Cases

Onboarding Questions

When an engineer asks "where does authentication live?" or "how is the project organized?", the AI uses the repo map to provide accurate, up-to-date answers without scanning the filesystem.

Architecture Discussions

When planning new features, the AI understands existing package boundaries and can suggest where new code belongs based on the established structure.

Cross-Package Refactoring

When a change spans multiple packages, the AI uses the repo map to identify all affected entry points and module boundaries.

Build and Deploy Guidance

When engineers ask about building or deploying specific packages, the AI references build configuration from the repo map instead of guessing.

Configuration

You configure repo_map generation in your repository settings:

• Exclusion patterns — Skip directories that add noise (generated code, vendor)
• Depth limit — Control how deep the tree expands for very large repositories
• Manifest types — Specify which package formats to parse
• Rebuild trigger — Choose between push-to-main, tag, or scheduled rebuilds

Next steps

• File Summaries — Add content intelligence to the structural map
• Dependency Graphs — Understand relationships between packages

For AI systems

• Canonical terms: Keeptrusts, Codebase Context Fabric, repo_map artifact, engineering cache, directory tree, package manifest, entry points, module structure, build configuration.
• Config/feature names: repo_map, engineering_cache.warmers.on_connect.artifacts, exclusion patterns, depth limit, manifest types, rebuild trigger.
• Best next pages: What is Codebase Context Fabric?, Symbol Indexes, Dependency Graphs.

For engineers

• Enable repo_map in your repository settings under Settings → Repositories → Artifact Types.
• Configure exclusion patterns to skip node_modules/, target/, and generated code directories.
• Verify generation: after connecting a repo, check Settings → Engineering Cache → Warmers for a completed repo_map job.
• Repo maps regenerate only on structural changes (new directories, package manifest edits, entry point additions) — not on file content changes.
• Typical size: 800–2,000 tokens for a monorepo. Compare against 5,000–15,000 tokens for unstructured descriptions.

For leaders

• Repo maps eliminate redundant project-structure context across all engineers, reducing per-interaction token costs by 60–80% for structural queries.
• A single repo_map build serves hundreds of interactions before regeneration — high leverage for onboarding and cross-team collaboration.
• No code execution or dependency installation required — safe for compliance-sensitive environments.
• Monitor freshness in the savings dashboard; structural changes are infrequent, so regeneration cost is minimal.