ForkFind is a repository-analysis platform for exploring useful work across a GitHub fork ecosystem. It prepares immutable repository assets, runs versioned analysis plugins, publishes document-oriented results, and supports durable, evidence-backed conversations.
- Create or reopen a project from
owner/repositoryor a credential-free Git URL. - Prepare repository metadata, refs, immutable commits, files, changed-fork corpora, and a SQLite FTS5 search index through one durable workflow worker.
- Automatically run the compiled-in
fork-analysis@1.0.0plugin after project preparation and synchronization, with deterministic rule scoring and optional OpenAI-compatible summary/reranking. - Read current and immutable run documents at recoverable browser URLs.
- Resume fixed-analysis-run conversations and inspect accepted citation evidence.
- Inspect repositories, snapshots, and unified workflow activity.
- Use English or Chinese layouts on desktop and mobile.
ForkFind automatically installs or rebinds the built-in Fork Analysis plugin and queues analysis after project preparation or synchronization. The project page shows analysis status and provides a retry action after failure. Generic plugin installation remains an internal orchestration API.
ForkFind is a single-node modular monolith:
apps/web React, React Router, TanStack Query
apps/server Deno, Hono, SQLite, Git, one workflow worker
packages/contracts Runtime-validated public/API contracts
packages/plugin-sdk Internal versioned plugin boundary
packages/plugins/fork-analysis Compiled-in Fork Analysis plugin
Analyses and conversations bind to immutable asset snapshots and commits. SQLite is the durable store; retrieval is lexical-only in the first release. There is no legacy job queue, hash router, sample result fallback, or compatibility API.
See the architecture guide, API reference, and operations guide.
Prerequisites: Node.js 22, npm, and Git. npm install provides the pinned
repository-local Deno toolchain used by all Server scripts.
npm install
npm run dev # Web: http://127.0.0.1:5173
npm run server # API: http://127.0.0.1:8787Run the Web and Server commands in separate terminals. The default CORS origin allows the local Web address above.
The default database is data/forkfind-v2.sqlite. Fresh databases use the
journaled Drizzle schema version 3 baseline. Existing refactored schema versions
1 and 2 upgrade additively to version 3; pre-refactor MVP databases are not
imported.
Configuration is read from the process environment at startup. The Settings page is read-only and never returns secrets. Restart the Server after changing runtime variables.
| Variable | Default | Purpose |
|---|---|---|
PORT |
8787 |
Server port |
HOST |
127.0.0.1 |
Bind address |
FORKFIND_V2_DB_PATH |
data/forkfind-v2.sqlite |
SQLite path |
FORKFIND_WEB_ORIGIN |
http://127.0.0.1:5173 |
Allowed CORS origin |
GITHUB_TOKEN |
unset | Optional GitHub API token |
FORKFIND_REPOSITORY_PROXY |
unset | Optional HTTP(S) proxy for GitHub API and Git requests |
FORKFIND_SYNC_DEFAULT_INTERVAL |
disabled |
Default project sync interval (disabled, hourly, daily, or weekly) |
FORKFIND_LLM_BASE_URL |
unset | OpenAI-compatible endpoint |
FORKFIND_LLM_API_KEY |
unset | Model API secret |
FORKFIND_LLM_MODEL |
unset | Model name |
FORKFIND_LLM_PROXY |
unset | Optional HTTP proxy for model requests |
FORKFIND_INTERNAL_TOKEN |
unset | Secret for internal mutation APIs |
FORKFIND_WORKER_CONCURRENCY |
2 |
Concurrent workflow tasks (1-16) |
VITE_API_BASE_URL |
empty | Optional Web build-time API origin; empty uses same-origin requests |
Fork Analysis remains deterministic without model configuration. Conversations
require all three model variables. Web requests are same-origin by default;
Vite proxies local /api requests to http://127.0.0.1:8787. Set
VITE_API_BASE_URL only when the API intentionally uses a separate origin, and
configure FORKFIND_WEB_ORIGIN on that Server to match the Web origin.
Copy .env.example to .env for local development. npm run server and
npm run server:dev load that repository-root file without overriding values
already exported by the process. Docker and deployed environments should inject
variables instead of copying a secret file into the image.
Build the current source tree:
docker build -t forkfind:local .
docker run --rm \
-p 8787:8787 \
-v "$PWD/data:/app/data" \
--env-file .env \
-e HOST=0.0.0.0 \
forkfind:localOpen http://localhost:8787. Keep secrets out of the Docker build context and
provide them only at runtime. ForkFind has no application authentication; place
it behind an authenticated reverse proxy before exposing it to an untrusted
network.
The current local validation environment could not run a Docker build because its daemon was unavailable. See the operations guide for persistence, backup, restore, and recovery details.
/: projects and project creation/projects/:projectId: preparation and overview/projects/:projectId/assets: repositories and immutable snapshots/projects/:projectId/forks: fork availability and sync status/projects/:projectId/activity: unified workflow activity/projects/:projectId/activity/:workflowId: workflow detail and events/projects/:projectId/plugins/fork-analysis: current plugin document/projects/:projectId/plugins/fork-analysis/runs/:runId: immutable run document/projects/:projectId/plugins/fork-analysis/conversations/:conversationId: durable conversation and evidence drawer/settings: read-only runtime capability status
npm run check:boundaries
npm run build
npm test
npm run test:server
npm run test:e2e
npm run verifynpm test covers contracts, plugin SDK, Fork Analysis, and Web tests. Server and
E2E tests are separate. npm run verify runs governance, build, boundaries, all
active tests, and E2E, but not lint, npm audit, or Docker validation.
The production dependency audit reports GHSA-qwww-vcr4-c8h2 through both
react-router-dom and its react-router dependency. ForkFind does not execute
the affected React Router RSC mode, Server Actions, SSR, or framework request
handlers, so the finding is not applicable to this browser-only router. Revisit
the disposition before adding any React Router server/RSC execution.
See CONTRIBUTING.md. Large refactor work follows the active
ExecPlan under docs/refactor/.