GitHub Repository Analysis Tool

This tool uses Claude Code's MCP capabilities to automatically analyze GitHub repositories, generate documentation, and create visual diagrams of code architecture.

Quick Start with AI Assistant

The fastest way to get started: Have your AI coding assistant help you set up this tool!

Simply tell your AI assistant: "Please read and execute the setup instructions in SETUP_ASSISTANT_PROMPT.md"

The AI assistant will guide you through the entire setup process in about 5-10 minutes.

After setup, use USAGE_ASSISTANT_PROMPT.md to have your AI assistant help you configure and use the tool effectively.

Features

• Repository Analysis: Clone and analyze GitHub repositories
• Code Structure Mapping: Generate maps of code organization and relationships
• Critical File Identification: Highlight the most important files in the repository
• Diagram Generation: Create component, sequence, and class diagrams
• Documentation Creation: Generate comprehensive markdown documentation
• Multiple Analysis Profiles: Create targeted documentation for different audiences

Output Examples

You can find sample outputs generated by this tool in the examples/ directory of this repository. These examples include generated documentation and diagrams to help you understand what to expect from running the tool.

Recent Updates

• Analysis Profiles: Generate different documentation for different audiences (developers, architects, operations, etc.) from the same repository
• Confluence Integration: Now supports automatic upload of documentation and diagrams to Atlassian Confluence spaces using the Conduit MCP server

Setup

Option 1: AI-Assisted Setup (Recommended)

Your AI coding assistant can set this up for you in minutes! Just tell it:

"Please read and execute the setup instructions in SETUP_ASSISTANT_PROMPT.md"

The assistant will handle most of the setup automatically.

Option 2: Manual Setup

1. Clone this repository:

   git clone https://github.com/your-username/gh-repo-code-intelligence.git
   cd gh-repo-code-intelligence

2. Configure Claude permissions by copying the settings template:

   cp .claude/settings.local.json.template .claude/settings.local.json

   This file contains the necessary permissions for Claude to use all required tools.

3. Configure MCP tools using the commands provided in the MCP Tool Setup section below.

4. Create a config.json file based on the template:

   cp config.json.template config.json

5. Edit config.json to include the repositories you want to analyze:

   {
     "repos": [
       {
         "name": "organization/repository-name",
         "github_url": "https://github.com/organization/repository-name"
       }
     ],
     "preferred_diagrams": ["component", "sequence", "class"],
     "doc_format": "markdown",
     "analysis_options": {
       "critical_files_limit": 50,
       "include_metrics": true,
       "max_tokens": 5000,
       "analysis_profile": "standard"
     },
     "confluence": {
       "enabled": false,
       "site_alias": "your-site-alias",  // Must match a site in Conduit's config.yaml
       "space_key": "YOUR_SPACE",
       "parent_page_title": "Parent Page Title",
       "page_suffix": ""
     }
   }

   Confluence Integration (Optional)

   To enable automatic upload of documentation to Confluence:

   1. Set confluence.enabled to true
   2. Configure your Atlassian site alias, space key, and parent page
   3. Ensure the Conduit MCP server is configured in .mcp.json with proper authentication

   When enabled, the tool will upload generated documentation and diagrams as Confluence pages.

   IMPORTANT: Always use HTTPS URLs (https://github.com/...) for repositories, not SSH URLs ([email protected]:...). SSH URLs will prompt for SSH key passphrase, which breaks automation. However, if you do provide a URL that starts with [email protected]:..., Claude Code will attempt to convert that to https://github.com/... and use that for clone operations.

Analysis Profiles

The tool supports different analysis profiles to create targeted documentation for specific audiences. You can run the tool multiple times on the same repository with different profiles to generate documentation tailored to different needs.

Available Profiles

1. standard (default)

   • General-purpose technical documentation
   • Balanced coverage of architecture, code, and functionality
   • Output: ~15-20 pages

2. developer_onboarding

   • For new developers joining the project
   • Focuses on: technology stack, development setup, code organization, design patterns
   • Output: ~25-30 pages

3. architecture_review

   • For architects and technical leads
   • Emphasizes: system design, architectural decisions, patterns, scalability
   • Output: ~25-30 pages

4. business_understanding

   • For product managers and business stakeholders
   • Highlights: business capabilities, domain concepts, workflows
   • Output: ~20-25 pages

5. operations_handover

   • For DevOps and operations teams
   • Covers: deployment, configuration, monitoring, dependencies
   • Output: ~20-25 pages

Configuring Analysis Profiles

To use a specific analysis profile, update your config.json:

{
  "analysis_options": {
    "analysis_profile": "developer_onboarding"
  },
  "confluence": {
    "page_suffix": " - Developer Guide"
  }
}

The page_suffix is optional but recommended when using multiple profiles to distinguish between different versions of documentation for the same repository.

Example: Creating Multiple Documentation Types

To create both developer and architecture documentation for the same repository:

1. First run with developer profile:

   {
     "analysis_options": {
       "analysis_profile": "developer_onboarding"
     },
     "confluence": {
       "page_suffix": " - Developer Guide"
     }
   }

2. Then run with architecture profile:

   {
     "analysis_options": {
       "analysis_profile": "architecture_review"
     },
     "confluence": {
       "page_suffix": " - Architecture Review"
     }
   }

This will create two separate Confluence pages (if enabled) with different documentation perspectives for the same repository.

Usage

AI-Assisted Usage (Recommended)

For help with configuration, running analyses, choosing profiles, and troubleshooting:

Tell your AI assistant: "Please read USAGE_ASSISTANT_PROMPT.md and help me use this tool"

Your AI assistant can help you:

• Configure repositories and analysis options
• Choose the right analysis profile for your needs
• Run the tool with appropriate output options
• Troubleshoot any issues
• Understand the generated documentation

Manual Usage

Run the tool using Claude Code:

cd /path/to/gh-repo-code-intelligence
claude -p "Analyze repositories according to CLAUDE.md" --dangerously-skip-permissions

The tool will follow the instructions in CLAUDE.md to analyze your configured repositories.

Recommended Execution Methods

For automated or scheduled runs, use one of these approaches to avoid terminal hanging issues:

1. Simple output redirection (recommended for automation):

   claude -p "Analyze repositories according to CLAUDE.md" --dangerously-skip-permissions --verbose --output-format stream-json > output.json

2. Unbuffered output with real-time viewing:

   claude -p "Analyze repositories according to CLAUDE.md" --dangerously-skip-permissions --verbose --output-format stream-json | stdbuf -o0 tee output.json

3. Non-interactive mode for scripts:

   claude -p "Analyze repositories according to CLAUDE.md" --dangerously-skip-permissions --verbose --output-format stream-json --no-interactive > output.json 2>&1

Note: The --dangerously-skip-permissions flag is required for this tool to function properly, as it needs to spawn sub-agents that process repositories in parallel.

Note: When using tee without unbuffering, the terminal may appear to hang even after completion. This is just buffering behavior - the analysis is complete. Press Ctrl+C to exit.

What the Tool Does

1. Read repositories from your config.json
2. Create or update state.json to track progress
3. Clone or refresh each repository
4. Analyze the repository structure
5. Generate diagrams based on the code analysis
6. Create comprehensive documentation with embedded diagrams
7. Store all outputs in the output/ directory with timestamped folders
8. (Optional) Upload documentation and diagrams to Confluence if enabled

Output Structure

output/
└── {repo_name}/
    └── {timestamp}/
        ├── docs.md        <- Generated documentation
        └── diagrams/      <- Generated diagrams
            ├── component_diagram.png
            ├── sequence_diagram.png
            └── class_diagram.png

Debugging

For troubleshooting or detailed analysis of the tool's operation, use verbose mode with JSON output:

claude -p "Analyze repositories according to CLAUDE.md" --dangerously-skip-permissions --verbose --output-format stream-json | tee output.json

This will:

• Show detailed progress and debugging information
• Output structured JSON data for each step
• Save all output to output.json for later analysis
• Allow real-time monitoring of the analysis process

Requirements

• Claude Code CLI
• MCP tools access:
  • code-understanding (required)
  • mermaid_image_generator (required)
  • Conduit (required for Confluence integration)

MCP Tool Setup

This project depends on three MCP tools. There are two ways to add them to Claude Code:

Method 1: Using claude mcp add-json commands (Recommended)

# Add Mermaid Image Generator
claude mcp add-json -s user mermaid_image_generator '{"type":"stdio","command":"uvx","args":["mcp_mermaid_image_gen"]}'

# Add Code Understanding (replace YOUR_GITHUB_TOKEN with your personal access token if analyzing private repos)
claude mcp add-json -s user code-understanding '{"type":"stdio","command":"uvx","args":["code-understanding-mcp-server","--max-cached-repos","20"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"YOUR_GITHUB_TOKEN"}}'

# Add Conduit (requires prior installation - see special note below)
claude mcp add-json -s user Conduit '{"type":"stdio","command":"mcp-server-conduit","args":[]}'

Method 2: Using .mcp.json.template

Alternatively, you can copy and modify the provided template:

cp .mcp.json.template ~/.claude/.mcp.json

Then edit the file to add your GitHub token and adjust paths as needed. See .mcp.json.template for the structure.

IMPORTANT - Conduit Setup: The Conduit MCP server requires manual initialization regardless of installation method:

1. Install: pipx install conduit-connect
2. Initialize: conduit --init
3. Configure: Edit ~/.config/conduit/config.yaml (or %APPDATA%\conduit\config.yaml on Windows)
4. Add your Atlassian credentials to the config.yaml file

Note: You'll need a GitHub Personal Access Token if analyzing private repositories. Create one at https://github.com/settings/tokens

Required MCP Tools

1. Code Understanding MCP Tool (Required for repository analysis)

   • GitHub Repository
   • Provides repository cloning, analysis, and code structure mapping

2. Mermaid Image Generator MCP Tool (Required for diagram generation)

   • GitHub Repository
   • Creates visual diagrams from code analysis

3. Conduit MCP Tool (Required for Confluence integration)

   • GitHub Repository
   • Provides Confluence and Jira integration
   • Developed by CodingTheFutureWithAI
   • See the repository for installation instructions

Confluence Integration Setup

If you want to enable automatic upload to Confluence:

1. Install and configure the Conduit MCP server - see Conduit repository for installation instructions
2. Configure your Atlassian credentials in Conduit's config file
3. Set confluence.enabled: true in your config.json
4. Provide the site_alias, space_key, and parent_page_title in config.json

The site_alias in your config.json must match a site configured in Conduit.

GitHub Authentication

For the code-understanding MCP tool to clone repositories:

1. Public repositories: No authentication required, but rate limits apply

2. Private repositories: Requires a GitHub Personal Access Token:

   "code-understanding": {
     "command": "code-understanding-mcp-server",
     "args": [
       "--cache-dir", "/path/to/cache-dir",
       "--max-cached-repos", "20"
     ],
     "env": {
       "GITHUB_TOKEN": "your-personal-access-token"
     }
   }

3. URL format: Regardless of repository visibility:

   • Always use HTTPS URLs in your config.json, not SSH URLs
   • SSH URLs will prompt for SSH key passphrase, breaking automation
   • Example: use https://github.com/organization/repo-name.git instead of [email protected]:organization/repo-name.git

Configuration Options

See config.json.template for the full configuration options. Key settings include:

• repos: List of repositories to analyze
• preferred_diagrams: Types of diagrams to generate
• analysis_options: Settings for code analysis depth and detail
  • analysis_profile: Choose from standard, developer_onboarding, architecture_review, business_understanding, or operations_handover
• confluence.page_suffix: Optional suffix to distinguish between different profile outputs for the same repository

Future Enhancements

We're actively working on enhancing this tool with more features:

• Confluence Integration: Automatically publish documentation to Atlassian Confluence spaces
• Documentation Templates: Customizable templates for different types of documentation
• Enhanced Diagram Types: Additional diagram formats for more comprehensive visualization
• Automated Scheduling: Integrated scheduling for regular repository analysis updates

License

This project is licensed under the MIT License - see the LICENSE file for details.