git-fork-recon 0.1.4

Analyse the network of forked git repositories

Git fork recon

Analyse the network of forked git repositories, summarise changes and innovations in forked repositories.

Features

• Intelligent analysis of fork networks using LLM-powered summaries
• Filters and prioritizes forks based on number of commits ahead of parent, starts, recent activity, PRs. Ignores forks with no changes.
• Local caching of git repositories and forks as remotes
• Detailed Markdown reports with:
  • Repository overview
  • Analysis of significant forks
  • Commit details and statistics
  • Links to GitHub commits and repositories
  • Overall summary of changes and innovations highlighting the most interesting forks
• REST API server for programmatic access with:
  • Asynchronous analysis with background processing
  • Versioned caching with filesystem storage
  • Authentication support with Bearer tokens
  • Health check endpoints
  • Configurable concurrency and rate limiting

Installation

pip install git-fork-recon

# For server functionality
pip install 'git-fork-recon[server]'

Installation (development)

Using uv (recommended):

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create and activate a new virtual environment (optional but recommended)
uv venv
source .venv/bin/activate

# Install the package in editable mode
uv pip install -e .

# Install server dependencies
uv pip install -e '.[server]'

# Install development dependencies
uv pip install -e '.[dev]'

Alternatively, using uv sync (modern dependency management):

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync with base dependencies
uv sync

# Sync with server dependencies
uv sync --extra server

# Sync with development dependencies
uv sync --extra dev

# Sync with all extras
uv sync --all-extras

Note: The first time you run uv sync, it will create a uv.lock file for reproducible builds. This file should be committed to version control to ensure all developers use the exact same dependency versions.

Configuration

Configuration is stored in a TOML file located in the platform-specific config directory (e.g., ~/.config/git-fork-recon/config.toml on Linux). On first run, an interactive setup wizard will guide you through configuration.

First-Time Setup

When you run git-fork-recon for the first time, you'll be prompted for some configuration values.

You will need:

1. A Github API token to READ repositories and their forks.

• Go to https://github.com/settings/tokens and make an access token with permissions: public_repo, user:email - provide the key when prompted.

2. Access to an OpenAI-compatible endpoint. You can use:

• OpenRouter (paid but cheap, also some free endpoints if you create an API key: https://openrouter.ai/settings/keys),
• Pollinations (a free LLM API - YMMV)
• a local server (Ollama, llama.cpp server, etc.)
• any remote OpenAI-compatible endpoint (e.g. OpenAI, Google, etc.)

First-time configuration wizard options:

• OpenAI-Compatible Endpoint: Choose from:
  • Environment variable (OPENAI_BASE_URL)
  • Local Ollama server (http://localhost:11434)
  • Pollinations (free API)
  • OpenRouter
  • Custom URL
• Endpoint API Key: Enter your API key or choose to always use an environment variable
• Model: Select a model based on your chosen endpoint
• GitHub Token: Enter your GitHub token or choose to always use an environment variable
• Cache Directories: Configure repository and report cache locations (defaults to $HOME/.cache/git-fork-recon/repos and $HOME/.cache/git-fork-recon/reports)

Config File Structure

The config file (config.toml) has the following structure:

# Configure an OpenAI-compatible endpoint
[endpoint]
base_url = "https://openrouter.ai/api/v1"
api_key = "sk-..."
model = "deepseek/deepseek-v3.2"
# context_length = 64000  # Optional: Override default context length

[github]
# Get a token https://github.com/settings/tokens with permissions: public_repo, user:email
token = "ghp_..."

[cache]
repo = "$HOME/.cache/git-fork-recon/repos"
report = "$HOME/.cache/git-fork-recon/reports"

[server]
# Server configuration options (commented out by default)

Environment Variable References

You can use environment variable references in the config file by prefixing with $:

[endpoint]
base_url = "$OPENAI_BASE_URL"  # Reads from OPENAI_BASE_URL env var
api_key = "$OPENAI_API_KEY"    # Reads from OPENAI_API_KEY env var

[github]
token = "$GITHUB_TOKEN"        # Reads from GITHUB_TOKEN env var

Custom Config File

You can specify a custom config file location using the --config option:

git-fork-recon --config /path/to/config.toml https://github.com/user/repo

Server Configuration

For the REST API server, additional environment variables are available:

• ALLOWED_MODELS: Comma-separated list of allowed LLM models (default: unrestricted)
• SERVER_HOST: Host to bind the server to (default: 127.0.0.1)
• SERVER_PORT: Port to bind the server to (default: 8000)
• REPORT_CACHE_DIR: Directory for server report cache (defaults to ~/.cache/git-fork-recon/reports using platformdirs)
• DISABLE_AUTH: Set to 1 to disable authentication (default: enabled)
• AUTH_BEARER_TOKEN: Bearer token for API authentication
• PARALLEL_TASKS: Maximum concurrent analysis tasks (default: 2)
• DISABLE_UI: Set to 1 to disable the web UI at /ui endpoint (default: enabled)

Running

# Using installed package
git-fork-recon https://github.com/martinpacesa/BindCraft

# Using uv run (recommended for development - automatically uses virtual environment)
uv run git-fork-recon https://github.com/martinpacesa/BindCraft

Note: This project requires PyGithub v2.8.1+ for GitHub API rate limit handling. The dependency is automatically managed when using uv sync or pip install.

REST API Server

Start the server:

# Using installed package
git-fork-recon-server --host 127.0.0.1 --port 8000

# Using uv run (recommended for development)
uv run git-fork-recon-server --host 127.0.0.1 --port 8000

Go to http://localhost:8000/ui to see the web UI.

API Endpoints

• POST /analyze - Start repository analysis
• GET /report/{owner}/{repo}/{timestamp}/report.{format} - Get cached report
• GET /report/{owner}/{repo}/latest/report.{format} - Get latest cached report
• GET /report/{owner}/{repo}/{timestamp}/status - Get status for specific report version
• GET /report/{owner}/{repo}/latest/status - Get status for latest report
• GET /metadata/{owner}/{repo}/{timestamp} - Get metadata for specific report version
• GET /metadata/{owner}/{repo}/latest - Get metadata for latest report
• GET /health - Health check endpoint
• GET /health/ready - Readiness check endpoint
• GET /ui - Web UI for repository analysis (unless disabled with DISABLE_UI=1)

Example Request

curl -X POST "http://localhost:8000/analyze" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/martinpacesa/BindCraft",
    "model": "deepseek/deepseek-chat-v3-0324:free",
    "format": "markdown"
  }'

Example Response

{
  "status": "generating",
  "retry-after": "2025-10-04T12:35:00Z"
}

When analysis is complete:

{
  "status": "available",
  "link": "/report/martinpacesa/BindCraft/latest/report.md",
  "last-updated": "2025-10-04T12:34:56Z"
}

Retrieving the Generated Report

Once the analysis is complete, you can retrieve the report using the provided link:

# Get the latest report
curl -X GET "http://localhost:8000/report/martinpacesa/BindCraft/latest/report.md" \
  -H "Authorization: Bearer your-token" \
  -o martinpacesa-BindCraft-forks.md

# Or get a specific version by timestamp
curl -X GET "http://localhost:8000/report/martinpacesa/BindCraft/2025-10-04T12-34-56Z/report.md" \
  -H "Authorization: Bearer your-token" \
  -o martinpacesa-BindCraft-forks-v2025-10-04.md

# Get report in different formats (markdown, json, html, pdf)
curl -X GET "http://localhost:8000/report/martinpacesa/BindCraft/latest/report.json" \
  -H "Authorization: Bearer your-token" \
  -o martinpacesa-BindCraft-forks.json

Checking Analysis Status

If you request a report while it's still being generated, you'll receive a 202 Accepted response with a Retry-After header:

curl -X GET "http://localhost:8000/report/martinpacesa/BindCraft/latest/report.md" \
  -H "Authorization: Bearer your-token"

Response (while generating):

{
  "status": "generating",
  "retry-after": "Wed, 05 Oct 2025 12:35:00 GMT"
}

Output is generated as {username}-{repo}-forks.md by default (use -o to specify a different file name, -o - to print to stdout).

Options

$ git-fork-recon --help

 Usage: git-fork-recon [OPTIONS] [REPO_URL]

 Analyze a GitHub repository's fork network and generate a summary report.


╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│   repo_url      [REPO_URL]  URL of the GitHub repository to analyze          │
│                             [default: None]                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output              -o      PATH     Output file path (defaults to         │
│                                        {repo_name}-forks.md)                 │
│                                        [default: None]                       │
│ --active-within               TEXT     Only consider forks with activity     │
│                                        within this time period (e.g. '1      │
│                                        hour', '2 days', '6 months', '1       │
│                                        year')                                │
│                                        [default: None]                       │
│ --config                      PATH     Path to config.toml file [default:     │
│                                        None]                                  │
│ --model                       TEXT     OpenRouter model to use (overrides    │
│                                        MODEL env var)                        │
│                                        [default: None]                       │
│ --context-length              INTEGER  Override model context length         │
│                                        (overrides CONTEXT_LENGTH env var)    │
│                                        [default: None]                       │
│ --api-base-url                TEXT     OpenAI-compatible API base URL        │
│                                        [default: None]                       │
│ --api-key-env-var             TEXT     Environment variable containing the   │
│                                        API key                               │
│                                        [default: None]                       │
│ --parallel            -p      INTEGER  Number of parallel requests           │
│                                        [default: 5]                          │
│ --verbose             -v               Enable verbose logging                │
│ --clear-cache                          Clear cached repository data before   │
│                                        analysis                              │
│ --force                                Force overwrite existing output file  │
│ --max-forks                   INTEGER  Maximum number of forks to analyze    │
│                                        (default: no limit)                   │
│                                        [default: None]                       │
│ --output-formats              TEXT     Comma-separated list of additional    │
│                                        formats to generate (html,pdf)        │
│                                        [default: None]                       │
│ --install-completion                   Install completion for the current    │
│                                        shell.                                │
│ --show-completion                      Show completion for the current       │
│                                        shell, to copy it or customize the    │
│                                        installation.                         │
│ --help                                 Show this message and exit.           │
╰──────────────────────────────────────────────────────────────────────────────╯

Running with Docker

Build the image:

docker build --build-arg USER_ID=$(id -u) --build-arg GROUP_ID=$(id -g) -t git-fork-recon .

Run the analysis (replace the repository URL with your target):

# Create cache directory with correct permissions
mkdir -p "${HOME}/.cache/git-fork-recon"

docker run --rm \
  -v "$(pwd):/app" \
  -v "${HOME}/.cache/git-fork-recon:/app/.cache" \
  -v "${HOME}/.config/git-fork-recon:/app/.config/git-fork-recon" \
  --user "$(id -u):$(id -g)" \
  git-fork-recon \
  "https://github.com/martinpacesa/BindCraft"

See also

• Useful forks
• frogmouth - a quick viewer for the generated Markdown