ForkFind

Discover hidden value in GitHub fork ecosystems with LLM-backed analysis.

English | 中文

Table of Contents

• Quick Start
• Why ForkFind
• Features
• How It Works
• Installation
• Configuration
• API Reference
• Development
• Contributing
• License

Quick Start

docker run -d -p 8787:8787 -v $(pwd)/data:/app/data ghcr.io/zmide/forkfind:latest

Open http://localhost:8787 in your browser.

Requires a GitHub personal access token and an OpenAI-compatible API endpoint (see Configuration).

Why ForkFind

Open source projects accumulate valuable changes across their fork networks — bug fixes, feature additions, Docker support, platform ports — that often go unnoticed when not submitted as pull requests.

ForkFind scans forks, compares diffs, reads commit history and branch names, then uses LLMs to match findings against your question. It surfaces evidence-backed candidates so you can discover, cherry-pick, or merge work that already exists.

Ask questions like:

"Did any fork fix issue #4714?"
"Which fork added Docker Compose support?"
"Has anyone ported this to Windows?"

Features

• Smart Scanning Compare diffs, read commits, and discover branches across the fork network. Branch-name discovery matches issue numbers like #4714 even in unmerged branches.

• LLM-Powered Analysis Uses OpenAI-compatible APIs (OpenAI, DeepSeek, MiMo, Claude-compatible gateways) with per-stage model routing. Each fork gets its own LLM summary based on commit and diff evidence.

• Evidence-Backed Reports Match scores are rule-based first, then refined by LLM judgment. Low-confidence matches are downgraded — no misleading 98% scores when the evidence is weak.

• Background Jobs Analysis runs server-side. Close your browser and come back later. Jobs survive restarts, and you can retry failed fork analysis stages individually.

• Webhook Notifications Post job completion to Slack, DingTalk, WeChat Work, or any custom webhook. Supports variable substitution for report summaries and links.

• Follow-Up Questions Ask the LLM additional questions against the generated report without re-running the full analysis.

• Usage Tracking Monitor GitHub API request counts and LLM token consumption per job. Real-time rate-limit display for core, search, graphql, and code_search quotas.

How It Works

1. Configure — Add your GitHub token and LLM API credentials in the Settings page.
2. Submit a job — Provide a GitHub repo and a question (e.g., "Did any fork add Docker support?").
3. Background analysis — ForkFind scans forks, reads commits, runs compare diffs, and calls LLMs for per-fork summaries.
4. View results — Open the report to see ranked candidates with match scores, evidence, and fork ecosystem insights.
5. Follow up — Ask follow-up questions about the report.

Installation

Docker (recommended)

docker run -d -p 8787:8787 -v $(pwd)/data:/app/data ghcr.io/zmide/forkfind:latest

The data volume stores your configuration and job history in SQLite. Access the app at http://localhost:8787.

Build from source

Prerequisites: Node.js 22+, Deno 2.x

npm install

# Start frontend (http://127.0.0.1:5173)
npm run dev

# Start backend (http://127.0.0.1:8787)
npm run server

For production, build the frontend and serve via the backend:

npm run build
VITE_API_BASE_URL="" npm run server

Environment Variables

Variable	Default	Description
PORT	8787	Server port
FORKFIND_HOSTNAME	127.0.0.1	Server bind address (set to 0.0.0.0 in Docker)
FORKFIND_DB_PATH	data/forkfind.sqlite	SQLite database location
GITHUB_TOKEN	—	GitHub personal access token (can also be set in-app)
VITE_API_BASE_URL	http://127.0.0.1:8787	Frontend API base URL (set empty for Docker same-origin)

Configuration

All settings are available in the web UI under the Settings page.

GitHub Token

Create a personal access token with public_repo scope. ForkFind can work without a token, but you'll hit rate limits quickly.

LLM Setup

ForkFind uses OpenAI-compatible chat completions and embeddings APIs. Typical examples:

Provider	Base URL	Auth Header
OpenAI	https://api.openai.com/v1	Bearer
DeepSeek	https://api.deepseek.com/v1	Bearer
MiMo (Xiaomi)	https://api.xiaomi.com/v1	Bearer
Custom Gateway	https://your-gateway/v1	Bearer or api-key

Model Routing

Different analysis stages can use different models:

Stage	Purpose
Default Chat	General-purpose fallback
Query Decomposition	Break down user questions into search signals
Fork Summary	Summarize per-fork commits and diffs
Candidate Ranking	Rank and score fork candidates
Final Assessment	Generate the final report
Embedding	Semantic vector search (optional)

Webhook Variables

Configure webhook notifications in Settings. Supported variables:

Variable	Description
{{repo}}	Repository full name
{{question}}	User question
{{summary}}	Report summary
{{candidates}}	Candidate count
{{scannedForks}}	Number of forks scanned
{{branchMatches}}	Number of branch-name matches
{{llmUsage}}	LLM stages used
{{jobId}}	Background job ID
{{completedAt}}	Completion timestamp
{{reportUrl}}	Local report URL

API Reference

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/config	Read configuration
PUT	/api/config	Save configuration
POST	/api/jobs	Create analysis job
GET	/api/jobs	List jobs
GET	/api/jobs/:id	Job detail
GET	/api/jobs/:id/result	Job report
GET	/api/jobs/:id/events	Job event log
POST	/api/test/github	Test GitHub token
GET	/api/github/rate-limit	View rate limits
POST	/api/test/llm	Test LLM connection
POST	/api/models/list	Fetch model list
POST	/api/test/webhook	Test webhook
POST	/api/follow-up	Follow-up question

See docs/api.md for request/response examples.

Development

npm install        # Install dependencies
npm run dev        # Frontend dev server (:5173)
npm run server     # Backend server (:8787)
npm test           # Run tests
npm run test:watch # Tests in watch mode
npm run lint       # Lint (oxlint)
npm run format     # Format (oxfmt)

Project Structure

src/              Frontend (React + Vite + TypeScript)
packages/
  shared/         Shared TypeScript types
  server/         Backend (Deno + Hono)
    lib/          Core modules (analyzer, github, llm, job-worker, etc.)
docs/             Documentation and screenshots
data/             SQLite database (gitignored)

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT

---