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

1. pack_codebase - Package local directory into consolidated file
2. pack_remote_repository - Clone and package GitHub repository
3. attach_packed_output - Load existing packed output for analysis
4. read_repomix_output - Read specific lines from packed output
5. grep_repomix_output - Search patterns in packed output
6. 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

1. Scope appropriately: Pack only relevant directories to reduce tokens
2. Use compression: Enable Tree-sitter compression for large codebases
3. Combine with grep: Use grep_repomix_output for targeted searches
4. Sequential workflow: Pack → Analyze → Plan → Implement
5. 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