Codebase Packager

TLDR Expert

Overview

Achieves high-fidelity codebase comprehension at a fraction of the token cost through semantic layers, structured digests, and advanced context packaging. Combines Repomix for context packing, Gitingest for repository digests, and llm-tldr for graph-based code analysis.

When to use: Reducing prompt overhead for large codebases, onboarding to unfamiliar repositories, mapping cross-file dependencies, creating AI-optimized context bundles.

When NOT to use: Small single-file tasks, final implementation debugging (read the full file), real-time code editing.

Quick Reference

Common Mistakes

Delegation

• Repository structure discovery: Use Explore agent to map directory layout and identify key modules before building context bundles
• Multi-step context packing workflow: Use Task agent to run Gitingest digest, Repomix compression, and llm-tldr indexing in sequence
• Architecture analysis and planning: Use Plan agent to design context engineering strategy for large monorepos

References

• Context Engineering Patterns -- packing strategies, XML tagging, signal-to-noise optimization, warm-up prompts
• Repomix and Gitingest Mastery -- configuration, compression mode, digest generation, Tree-sitter extraction
• Semantic Graph Analysis -- llm-tldr CLI tools, impact analysis, semantic search, architectural audits

Context Engineering Patterns

Context engineering is the practice of selecting, ordering, and formatting information to maximize an LLM's reasoning capability within its context window.

Top-Down Priority Hierarchy

When packing context for an LLM, follow this priority order. Higher-priority items go first in the context window.

Key principle: More data is not always better. Irrelevant context leads to "lost in the middle" errors where models fail to attend to important information buried between noise.

XML Tagging Pattern

Use distinct XML tags to help the model distinguish between different parts of the context. This is the default format used by Repomix.

<file path="src/auth.ts">
export async function authenticate(token: string): Promise<User> {
  const decoded = verifyJWT(token);
  return findUser(decoded.sub);
}
</file>

<file path="src/types.ts">
export interface User {
  id: string;
  email: string;
  role: 'admin' | 'user';
}
</file>

<instruction_context>
The authentication module uses JWT tokens with RS256 signing.
User roles determine access to admin endpoints.
</instruction_context>

Signal-to-Noise Ratio Optimization

The goal is to increase signal (knowledge) and decrease noise (boilerplate).

Pruning Imports

Most imports are boilerplate. Remove them from context bundles unless the import source is non-obvious.

// REMOVE from context (obvious)
import { useState, useEffect } from 'react';
import { z } from 'zod';

// KEEP in context (non-obvious, project-specific)
import { useAuthGuard } from '@/hooks/use-auth-guard';
import { type PaymentIntent } from '@/lib/stripe-types';

Stubbing Constants

If a file has a large constants object, replace it with a stub unless the constants are directly relevant.

// Original: 500 lines of country codes
export const COUNTRY_CODES = {
  US: 'United States',
  // ... 200+ entries
};

// Stubbed for context: 1 line
export const COUNTRY_CODES: Record<string, string>; // 200+ country code mappings

Type Aggregation

Move all relevant TypeScript interfaces into a single block at the top of the context bundle for quick reference.

Warm-Up Prompt Pattern

Before asking for a complex change, warm up the model's context by asking it to summarize the provided bundle. This ensures the model has attended to the key parts.

Step 1: Provide Repomix bundle

Step 2: "Read this bundle and list the 3 most critical modules
         for implementing feature X. Explain their roles."

Step 3: "Now, based on that analysis, implement feature X
         following the existing patterns you identified."

This two-step approach produces higher-quality output than a single prompt because the model has explicitly processed the relevant modules before generating code.

Automated Context Packing Protocol

Before tackling a complex feature, prepare a context bundle:

# Package the relevant subdirectory with compression
repomix --include "src/features/auth/**" --output auth-context.md --compress

# Add the dependency graph from llm-tldr
tldr context login --project src/features/auth >> auth-context.md

Troubleshooting

Repomix and Gitingest Mastery

Repomix: Context Snapshot Tool

Repomix packages codebases into single, AI-optimized XML or Markdown files. It is the primary tool for creating context bundles.

Recommended Configuration

{
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml",
    "removeComments": true,
    "removeEmptyLines": true,
    "showLineNumbers": true
  },
  "include": ["src/**/*"],
  "ignore": {
    "customPatterns": ["**/*.test.ts", "**/dist/**", "**/docs/**"]
  }
}

Save as repomix.config.json in the project root.

Common Commands

# Full project pack (respects config)
repomix

# Pack specific subdirectory with compression
repomix --include "src/features/auth/**" --output auth-context.md --compress

# Compressed mode (extracts signatures via Tree-sitter, removes function bodies)
repomix --include "src/huge-module/**" --compress

# Pack with Markdown output instead of XML
repomix --style markdown --output context.md

# Metadata only without file contents
repomix --no-files

# Pack a remote GitHub repository (clones to temp, packs, cleans up)
repomix --remote yamadashy/repomix
repomix --remote https://github.com/org/repo --remote-branch main

# Combine remote with compression and filtering
repomix --remote user/repo --compress --include "src/**/*.ts"

Output Modes

Security: Secretlint Integration

Repomix includes built-in secretlint scanning to ensure context bundles never contain:

• API keys or secrets
• PII (personally identifiable information)
• Internal IP addresses or sensitive metadata

This runs automatically on every pack operation. Disable with --no-security-check if needed.

MCP Server Mode

Repomix can run as an MCP server for Claude Code, enabling AI agents to pack repositories on demand:

# Add Repomix as an MCP server in Claude Code
claude mcp add repomix -- npx -y repomix --mcp

This exposes Repomix's packing capabilities as tools that Claude Code can invoke directly during a session, eliminating the need to pre-generate context bundles.

Gitingest: Repository Digest Tool

Gitingest (Python: pip install gitingest) transforms entire Git repositories into structured text digests optimized for LLM consumption.

Key Use Cases

Dependency discovery: Point Gitingest at a library's GitHub URL to understand its API surface.

gitingest https://github.com/org/library -o library-digest.txt

Architecture review: Get a tree view and file-size breakdown for quick orientation.

gitingest . -o project-digest.txt

Onboarding digest: Create a prompt-friendly summary for new contributors or sub-agents.

gitingest . -o digest.txt

Configuration Tips

• Ensure a valid .gitignore exists at the project root for clean output (files in .gitignore are skipped by default)
• Use --include-gitignored if you need ignored files in the digest
• Use -o - to pipe output to STDOUT instead of a file
• Use --token or GITHUB_TOKEN env var for private repository access
• Use remote GitHub URLs for third-party library analysis

Tree-sitter Signature Extraction

Tree-sitter (used internally by Repomix --compress and llm-tldr) extracts the "shape" of code without implementation details.

// Tree-sitter extraction produces signatures like:
export function calculateTax(amount: number): number;
export class TaxEngine {
  constructor(config: Config);
  process(item: Item): Result;
}

This gives the AI the "what" without the "how," saving thousands of tokens while preserving structural understanding.

Troubleshooting

Semantic Graph Analysis

llm-tldr provides a graph-based view of a project. Instead of seeing files as flat text, it maps relationships between functions, classes, and modules through AST analysis, call graphs, control flow, data flow, and program dependence layers.

Installation and Setup

llm-tldr is a Python package. Install and initialize:

pip install llm-tldr
tldr warm .

The warm command builds all indexes including semantic embeddings. The embedding model (bge-large-en-v1.5, 1.3GB) downloads on first run.

CLI Command Reference

tldr impact <function_name> <project_path>

Purpose: Reverse call graph analysis. Identify the blast radius of a change by finding every call site that would be affected by modifying a function.

# Find all callers of the authenticate function
tldr impact authenticate .

# Output shows reverse call graph:
# src/middleware/auth.ts:15 - verifyRequest()
# src/api/users.ts:32 - getUserProfile()
# src/api/admin.ts:8 - adminGuard()

Use this before any refactoring to understand downstream impact.

tldr calls <project_path>

Purpose: Build the forward call graph across the project. Understand what functions call what other functions.

# Build forward call graph
tldr calls .

tldr context <function_name> --project <path>

Purpose: Generate an LLM-ready context summary for a function. Extracts the function along with its dependencies, achieving approximately 95% token savings compared to reading entire files.

# Get LLM-ready context for the login handler
tldr context login --project src/features/auth

# Output includes:
# - Function signatures
# - Type definitions
# - Constants used
# - Utility functions called

tldr arch <project_path>

Purpose: Detect architectural issues across the codebase.

Detects:

• Circular dependencies -- File A imports File B, which imports File A (high technical debt)
• Layer violations -- UI layer directly imports DB layer, bypassing the API
• Dead code -- Functions or classes with zero callers

tldr arch .

# Output:
# CIRCULAR: src/auth.ts <-> src/session.ts
# VIOLATION: src/components/Dashboard.tsx -> src/db/queries.ts (UI -> DB)

tldr dead <project_path>

Purpose: Find unreachable code -- functions with zero callers and zero importers.

tldr dead .

# Output:
# src/utils/legacy-format.ts:formatV1() - 0 callers

tldr extract <file_path>

Purpose: Extract the full AST from a file -- functions, classes, and imports -- without reading the full implementation. Use this before reading any file over 500 lines.

tldr extract src/lib/payment-engine.ts

# Output: exported function and type signatures

tldr daemon status

Purpose: Check whether the llm-tldr daemon is running. The daemon auto-starts on first query and auto-stops after 5 minutes of inactivity.

tldr daemon status

# Output:
# Daemon running on port 9119
# Files indexed: 342

If the index is stale after a significant refactor, run tldr warm . to rebuild it.

Additional Commands

Semantic Search Strategy

When text-based search (rg, grep) fails because naming is inconsistent, use semantic search to find logic by meaning.

# Effective semantic queries:
tldr semantic "session expiration and cookie cleanup logic" .
tldr semantic "main entry point for the payment gateway" .
tldr semantic "JWT token rotation handling" .
tldr semantic "components using the bento grid layout" .

Tips for effective semantic queries:

• Describe the behavior, not the function name
• Include domain-specific terms (e.g., "JWT," "bento grid")
• If results are empty, fall back to rg for keywords, then use tldr context on the results
• The semantic index is cached in .tldr/cache/semantic.faiss

MCP Server Integration

llm-tldr can operate as an MCP server for Claude Code and Claude Desktop:

{
  "mcpServers": {
    "tldr": {
      "command": "tldr-mcp",
      "args": ["--project", "/path/to/project"]
    }
  }
}

Standard Operating Procedure

1. Build indexes: Run tldr warm . to build all indexes including embeddings 2. Map architecture: Run tldr arch . to understand layers and detect issues 3. Discover: Use semantic search and impact analysis to isolate feature logic 4. Pack context: Create a Repomix bundle for the specific sub-module 5. Execute: Pass the optimized context to the reasoning model

Troubleshooting