MCP Skill: Repomix

Scope

Use the MCP server configured as repomix in .vscode/mcp.json to:

• Package entire codebase into consolidated files for AI analysis

• Search and grep through packed repository outputs

• Understand project structure and file organization

• Provide comprehensive context for large-scale refactoring

Preconditions

• Ensure .vscode/mcp.json contains a server entry named repomix .

• The Repomix MCP server provides tools for codebase packaging and analysis.

Operating Rules

• Use pack_codebase to create consolidated repository snapshots for analysis

• Use grep_repomix_output to search within packed outputs

• Use attach_packed_output to load existing Repomix output files

• Prefer Repomix for full codebase context gathering before major refactors

• Use XML or Markdown output styles for better LLM comprehension

When To Use

• Before major architectural changes: Get full codebase snapshot

• Cross-cutting refactors: Changes affecting multiple capabilities/layers

• Understanding legacy code: Analyze entire module structure

• Documentation generation: Extract all files for comprehensive docs

• Code review preparation: Package changes with full context

• Migration planning: Understand all dependencies before migration

• Pattern analysis: Search for specific patterns across entire codebase

Key Tools Available

• pack_codebase - Package local directory into consolidated file

• pack_remote_repository - Clone and package GitHub repository

• attach_packed_output - Load existing packed output for analysis

• read_repomix_output - Read specific lines from packed output

• grep_repomix_output - Search patterns in packed output

• generate_skill - Create Claude Agent Skill from codebase

Output Formats

• XML: Structured with <file> tags (best for precise parsing)

• Markdown: Human-readable with code blocks (best for review)

• JSON: Machine-readable key-value pairs

• Plain: Simple text with separators

Integration with Black-Tortoise Workflow

• Combine with mcp-sequential-thinking for complex refactoring plans

• Use before running architecture:gate for comprehensive boundary analysis

• Essential for understanding DDD layer dependencies

• Helps validate "no deep imports" rule across entire codebase

Prompt Templates

• "Pack the codebase and analyze all DDD boundary violations"

• "Use Repomix to find all usages of [pattern] across the entire repository"

• "Package src/app/capabilities and identify cross-capability dependencies"

• "Create a full codebase snapshot before starting [major refactor]"

• "Search the packed repository for all event emission points"

Best Practices

• Scope appropriately: Pack only relevant directories to reduce tokens

• Use compression: Enable Tree-sitter compression for large codebases

• Combine with grep: Use grep_repomix_output for targeted searches

• Sequential workflow: Pack → Analyze → Plan → Implement

• Version control: Save packed outputs for before/after comparison

Example Workflows

Workflow 1: Cross-Capability Analysis

1. pack_codebase(directory: "src/app/capabilities", compress: true)
2. grep_repomix_output(pattern: "import.from.@app/", contextLines: 3)
3. Identify violations of "no deep imports" rule
4. Use sequential-thinking to plan refactoring

Workflow 2: Event Flow Analysis

1. pack_codebase(directory: "src/app", includePatterns: "**/*.ts")
2. grep_repomix_output(pattern: "publishEvent|EventBus", contextLines: 5)
3. Map all event producers and consumers
4. Validate append-before-publish contract

Workflow 3: Dependency Analysis

1. pack_codebase(directory: "src/app", style: "json")
2. grep_repomix_output(pattern: "from ['"]@angular/fire", contextLines: 2)
3. Ensure all Firebase imports are in integration layer only
4. Document violations for remediation

Safety & Performance

• Large repositories: Use compress: true to reduce token usage by ~70%

• Incremental analysis: Use grep_repomix_output instead of re-packing

• File limits: Use includePatterns and ignorePatterns to scope packing

• Context management: Attach packed outputs once, reuse for multiple queries

Compliance with Black-Tortoise Rules

• Occam's Razor: Use Repomix only when full context is genuinely needed

• Minimal changes: Helps identify smallest change radius for refactors

• DDD boundaries: Essential for validating layer dependencies

• Documentation: Can generate comprehensive project structure docs