Flaiwheel

Self-hosted memory & governance layer for AI coding agents. Turn every bug fix into permanent knowledge. Zero cloud. Zero lock-in.

🚀 Why Flaiwheel Exists

AI coding agents forget everything between sessions. That leads to repeated bugs, lost architectural decisions, and knowledge decay.

Flaiwheel ensures:

• Agents search before coding
• Agents document after fixing
• Commits automatically capture knowledge
• Memory compounds over time

Every bug fixed makes the next bug cheaper.

🧠 How Flaiwheel Is Different

• Persistent AI Memory That Compounds — knowledge doesn't reset between sessions.
• Git-Native Automation — commits automatically become structured knowledge.
• Governance, Not Just Storage — quality gates + enforced documentation.
• Hybrid Search + Reranking — high-precision context for real codebases.
• Fully Self-Hosted — single Docker container, no external infrastructure.
• Zero Lock-In — all knowledge stored as structured flat files in Git.

✅ Who Flaiwheel Is For

• Engineering teams using AI coding assistants in real projects
• Codebases where repeated bugs are expensive
• Teams requiring full data control
• AI-native development environments

❌ Not For

• Small hobby projects under a few thousand lines
• Developers who just want better autocomplete
• Pure SaaS workflows with no interest in self-hosting

🆚 Where Flaiwheel Fits

• AI coding tools generate code.
• RAG tools retrieve documents.
• Flaiwheel governs and compounds structured engineering knowledge inside your own infrastructure.

It does not replace your AI assistant. It makes it reliable at scale.

📄 Whitepaper (PDF) — Vision, architecture, and design in depth.

⚙️ Key Technical Features

Flaiwheel is a self-contained Docker service that operates on three levels: Pull — agents search before they code (search_docs, get_file_context)
Push — agents document as they work (write_bugfix_summary, write_architecture_doc, …)
Capture — git commits auto-capture knowledge via a post-commit hook, even without an AI agent

• Indexes your project documentation (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) into a vector database
• Provides an MCP server that AI agents (Cursor, Claude Code, VS Code Copilot) connect to
• Hybrid search — combines semantic vector search with BM25 keyword search via Reciprocal Rank Fusion (RRF) for best-of-both-worlds retrieval
• Cross-encoder reranker — optional reranking step that rescores candidates with a cross-encoder model for significantly higher precision on vocabulary-mismatch queries
• Behavioral Directives — AI agents silently search Flaiwheel before every response, auto-document after every task, and reuse before recreating — all without being asked
• get_file_context(filename) — pre-loads spatial knowledge for any file the agent is about to edit (complements get_recent_sessions for full temporal + spatial context)
• post-commit git hook — captures every fix:, feat:, refactor:, perf:, docs: commit as a structured knowledge doc automatically
• Living Architecture — AI agents are instructed to maintain self-updating Mermaid.js diagrams for system components and flows
• Executable Test Flows — test scenarios are documented in machine-readable BDD/Gherkin format (Given, When, Then) for QA automation
• Learns from bugfixes — agents write bugfix summaries that are instantly indexed
• Structured write tools — 7 category-specific tools (bugfix, architecture, API, best-practice, setup, changelog, test case) that enforce quality at the source
• Pre-commit validation — validate_doc() checks freeform markdown before it enters the knowledge base
• Ingest quality gate — files with critical issues are automatically skipped during indexing (never deleted — you own your files)
• Auto-syncs via Git — pulls AND pushes to a dedicated knowledge repo
• Tool telemetry (persistent) — tracks every MCP call per project (searches, writes, misses, patterns), detects knowledge gaps, and nudges agents to document — persisted across restarts and visible in the Web UI
• Impact metrics API — /api/impact-metrics computes estimated time saved + regressions avoided; CI pipelines can post guardrail outcomes to /api/telemetry/ci-guardrail-report
• Proactive quality checks — automatically validates knowledge base after every reindex
• Knowledge Bootstrap — "This is the Way": analyse messy repos, classify files, detect duplicates, propose a cleanup plan, execute with user approval (never deletes files)
• Cold-Start Codebase Analyzer — analyze_codebase(path) scans a source code directory entirely server-side (zero tokens, zero cloud). Uses Python's built-in ast module for Python, regex for TypeScript/JavaScript, the existing MiniLM embedding model for classification and duplicate detection. Returns a single bootstrap_report.md with language distribution, category map, top 20 files to document first ranked by documentability score, duplicate pairs, and coverage gaps. Reduces cold-start token cost by ~90% on legacy codebases.
• Multi-project support — one container manages multiple knowledge repos with per-project isolation
• Includes a Web UI for configuration, monitoring, and testing

What’s New in v3.9.29

• Glama tool detection fix — AuthManager crashed on read-only /data before the MCP server could start (the real reason Glama saw 0 tools). Skipped in stdio cold-start mode.
• Zero print() on stdout — 36 remaining print() in watcher, indexer, readers, bootstrap replaced with diag() (stderr). Verified: full MCP handshake returns all 28 tools over stdio.
• config.save() resilient — read-only filesystem logs warning instead of crashing.

Previous: v3.9.28

• Glama / MCP stdio fix — all diagnostic output moved to stderr; stdout is now JSON-RPC only. Glama Inspector now detects all 28 tools correctly.
• Improved cold-start detection — stdio cold-start logic handles empty Docker volumes correctly (no bootstrap / model download during Glama inspection).

Previous: v3.9.27

• License cleanup — one LICENSE file (BSL 1.1) for correct GitHub/Glama detection; all docs and headers point to LICENSE (not LICENSE.md).
• Glama / stdio inspection — optional [inspect] deps and cold-start stdio path for lightweight MCP directory builds.

Previous: v3.9.26

• Claude Cowork skill — the Flaiwheel workflow is now distributed as a native Claude skill. The installer writes .skills/skills/flaiwheel/SKILL.md to your project. When you open the project in Claude (Cowork), the skill is auto-available — no extra setup needed. The skill drives session-start context restore, pre-coding knowledge search, mandatory post-bugfix documentation, and session-end summarisation.
• Skill source also committed to skills/flaiwheel/SKILL.md in this repo for reference and manual install.

Previous: v3.9.25

• WSL2 automatic pre-flight setup — WSL2 is now detected automatically and a dedicated pre-flight block runs before the main installer flow. No manual steps required:
  1. Switches iptables to legacy backend (fixes Docker networking / DNAT errors)
  2. Adds the current user to the docker group (no more permission denied)
  3. Starts the Docker daemon via service (no systemd on WSL2)
  4. Adds a Docker auto-start snippet to ~/.bashrc (idempotent, runs on every WSL2 login)
• Scattered WSL2 checks throughout the script consolidated into the single pre-flight block.

Previous: v3.9.24

• Fix: auto-install python3 if missing — the installer uses python3 extensively for JSON manipulation. On minimal Linux/WSL2 systems without python3, config file writes silently failed (/dev/fd/63: line N: python3: command not found). python3 is now checked as prerequisite #0 and auto-installed via apt/dnf/yum/pacman/brew if missing.

Previous: v3.9.23

• Fix: Docker daemon start on WSL2 with iptables-legacy — Docker on WSL2 often fails to start silently because the default iptables-nft backend is not supported. The installer now switches to iptables-legacy via update-alternatives before starting Docker. Also adds the current user to the docker group automatically.
• All install commands updated to bash <(curl ...) — every displayed install/re-run command throughout the script (error messages, AGENTS.md, Cursor rules, etc.) now uses process substitution to avoid WSL2 pipe issues.

Previous: v3.9.22

• Fix: curl | bash pipe write failures on WSL2 — curl | bash can fail with curl: (23) Failure writing output on WSL2 due to pipe/tmp permission issues. The primary install command in README is now bash <(curl ...) (process substitution), which avoids the pipe entirely. The re-exec block also tries $HOME as a fallback temp dir when /tmp writes fail. Error message explicitly recommends the bash <(curl ...) form.

Previous: v3.9.21

• Fix: sudo guard moved before re-exec block — when sudo curl | bash was used, the curl: (23) pipe error truncated the script before the previous sudo guard (which was after colors/functions) was ever reached. The guard is now the very first executable line (set -euo pipefail aside), so it fires even on a truncated download. Duplicate guard after colors removed.

Previous: v3.9.20

• Fix: Docker daemon startup poll on WSL2 — instead of a fixed 5-second sleep, the installer now polls docker info every 2 seconds for up to 30 seconds after service docker start. Also shows the actual output of service docker start so startup errors are visible instead of silently swallowed.

Previous: v3.9.19

• Fix: Docker daemon start on WSL2 — WSL2 typically has no systemd, so systemctl start docker silently failed. The installer now detects WSL2 via /proc/version and uses sudo service docker start instead. If Docker still isn't running after install, a clear WSL2-specific error is shown with the exact fix command and a tip to add it to ~/.bashrc for auto-start on login.

Previous: v3.9.18

• Fix: block sudo curl | bash and sudo bash install.sh — running the installer as root via sudo breaks GitHub CLI authentication: gh auth stores credentials in /root/.config/gh/ instead of the real user's home, making every subsequent gh call fail. Also caused curl: (23) Failure writing output pipe errors on WSL. The installer now detects SUDO_USER at startup and exits immediately with a clear message telling the user to re-run without sudo. Privilege escalation for package installs is handled internally.

Previous: v3.9.17

• Fix: gh auth login must not be run with sudo — after auto-installing gh on Linux/WSL, the installer now explicitly tells the user to run gh auth login without sudo. If auth was previously done with sudo, credentials ended up in /root/.config/gh/ and were invisible to the current user, causing the auth check to fail. The error messages at both the post-install and the auth-check step now clearly warn: do not use sudo for gh auth.

Previous: v3.9.16

• Fix: installer works on WSL and non-root Linux — all Linux package manager commands (apt-get, dnf, yum, zypper, pacman), Docker convenience script, and systemctl calls now automatically use sudo when the installer is not running as root. Root installs are unaffected. Fixes Permission denied / lock file errors on WSL and standard Linux desktop users.

Previous: v3.9.15

• Cold-start report cached in /data/ — analyze_codebase() saves the report to /data/coldstart-<project>.md after the first run. Subsequent calls return the cached report instantly (<1s). The installer also writes the cache during install so the very first MCP call by any agent is instant. Call with force=True to regenerate after major codebase changes.
• analyze_codebase() in all agent Session Setup templates — AGENTS.md, .cursor/rules/flaiwheel.mdc, CLAUDE.md, and .github/copilot-instructions.md all now include it as step 3 of Session Setup. Agents automatically get the codebase overview before starting work.
• Cold-start prompt asked before Docker rebuild — all interactive questions (embedding model + cold-start) are now batched upfront, then the rebuild runs unattended.
• Fix: used docker exec for cold-start — replaced broken HTTP calls to the MCP SSE endpoint with direct docker exec python3. Analysis now works reliably in ~20s.

Previous: v3.9.14

• Fix: fast-path always prompts for cold-start — no more silent skip when cached report exists.

Previous: v3.9.13

• Improved cold-start classification — two-pass classifier: path heuristics first, code-specific embedding templates as fallback.

Previous: v3.9.12

• Fix: y/n answer respected before cache check — explicit y now always re-runs analysis even when cached report exists.

Previous: v3.9.11

• Fix: coldstart functions in global scope — moved _run_coldstart/_do_coldstart_analysis to top of script so fast-path can call them.

Previous: v3.9.10

• Fix: version check — LATEST_VERSION now uses _FW_VERSION directly, no CDN fetch.

Previous: v3.9.9

• Fix: cold-start on all paths — _run_coldstart() called from fast-path, update, and fresh install. Smart cache detection.

Previous: v3.9.8

• Cold-start report caching — analyze_codebase() cached to /data/coldstart-<project>.md for instant reads. New force=True param.

Previous: v3.9.7

• Agent Session Setup — all instruction templates now include analyze_codebase() as a first-session step.

Previous: v3.9.6

• Fix: use docker exec — replaced broken HTTP calls to MCP SSE endpoint with direct docker exec python3 invocation. Cold-start report now actually works (~20s).

Previous: v3.9.5

• Fix: warm up embedding model — added model warm-up before cold-start analysis (superseded by v3.9.6).

Previous: v3.9.4

• Fix: cold-start retries while model loads — installer now retries analyze_codebase() for up to 90s after container starts.

Previous: v3.9.3

• Fix: update detection always checks main — LATEST_VERSION now fetched from main branch so stale cached installers no longer silently skip updates.

Previous: v3.9.2

• Cold-start prompt moved before Docker rebuild — all interactive questions now batched upfront.

Previous: v3.9.1

• Cold-start prompt moved upfront — the install.sh cold-start question is now asked right after the embedding model selection (before the Docker rebuild), so all interactive questions are gathered first and the user never misses the prompt after a long rebuild.

Previous: v3.9.0

• analyze_codebase(path) — new 28th MCP tool for zero-token cold-start analysis of legacy codebases. Runs entirely server-side in Docker. Uses Python ast, regex, MiniLM embeddings, and nearest-centroid classification. Returns a ranked bootstrap_report.md with language distribution, category map, top 20 files by documentability score, near-duplicate pairs, and recommended next steps. Reduces cold-start token cost by ∼90%.

Previous: v3.8.3

• No auto-index on project add — adding a project via the web UI no longer immediately pulls and embeds the knowledge repo. Indexing is now deferred until explicitly triggered (“Git Pull + Reindex” or reindex() MCP tool), keeping the vector DB clean until the repo has been reviewed.

Previous: v3.6.x

• VS Code / GitHub Copilot support — installer writes .vscode/mcp.json and .github/copilot-instructions.md.
• Claude Desktop support — installer auto-configures Claude Desktop via mcp-remote.
• Web UI Client Configuration panel — VS Code and Claude Code CLI tabs added.

Previous: v3.5.x

• Claude Desktop + Claude Code CLI support added.
• README strategically rewritten with positioning, target audience, and competitive framing.

Previous: v3.4.x

• Search miss rate fix — search_bugfixes calls no longer inflate miss rate above 100%.
• Classification consistency — _path_category_hint unified token-based approach across all categories.
• CHANGELOG.md added to repo root.

Quick Start — One Command (recommended)

Prerequisites: GitHub CLI authenticated (gh auth login), Docker running.

Platform support: macOS and Linux work out of the box. On Windows, run the installer from WSL or Git Bash (Docker Desktop must be running with WSL 2 backend enabled).

Run this from inside your project directory:

bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)

WSL2 / Linux note: Use the bash <(curl ...) form above — it avoids curl: (23) pipe write errors that occur with curl | bash on some WSL2 setups. Never prefix with sudo.

That's it. The installer automatically:

1. Detects your project name and GitHub org from the git remote
2. Creates a private <project>-knowledge repo with the standard folder structure
3. Starts the Flaiwheel Docker container pointed at that repo
4. Configures Cursor — writes .cursor/mcp.json and .cursor/rules/flaiwheel.mdc
5. Configures VS Code / GitHub Copilot — writes .vscode/mcp.json (native SSE, VS Code 1.99+) and .github/copilot-instructions.md
6. Configures Claude Desktop (macOS app) — writes claude_desktop_config.json via mcp-remote bridge (requires Node.js)
7. Configures Claude Code CLI — writes .mcp.json + CLAUDE.md and runs claude mcp add automatically if the CLI is on PATH
8. Installs Claude Cowork skill — writes .skills/skills/flaiwheel/SKILL.md so the full Flaiwheel workflow is available as a native Claude skill
9. Writes AGENTS.md for all other agents
10. If existing .md docs are found, creates a migration guide — the AI will offer to organize them into the knowledge repo

After install:

The installer also sets up a post-commit git hook that automatically captures every fix:, feat:, refactor:, perf:, and docs: commit as a structured knowledge doc — no agent or manual action required.

Once connected, the AI has access to all Flaiwheel tools. If you have existing docs, tell the AI: "migrate docs".

Optional: Open Terminal Local Daemon (Open WebUI)

If you also use Open WebUI's Open Terminal integration, this repo includes helper installers for a local open-terminal daemon.

Third-party write-ups (for example AI·Collab — Open Terminal) may mirror only the Linux script; macOS uses scripts/macos/install-open-terminal-launchagent.sh below. After any mirror update, re-check the file with shasum -a 256 against the same revision on GitHub.

One-liner install via curl (no git clone)

Use main or pin a commit SHA / tag in the URL for reproducible bytes.

Linux / WSL2 (systemd --user):

curl -fsSL -o install-open-terminal-systemd-user.sh \
  https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install-open-terminal-systemd-user.sh
/bin/chmod +x install-open-terminal-systemd-user.sh
/bin/bash ./install-open-terminal-systemd-user.sh

macOS (LaunchAgent; do not use sudo):

curl -fsSL -o install-open-terminal-launchagent.sh \
  https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/macos/install-open-terminal-launchagent.sh
/bin/chmod +x install-open-terminal-launchagent.sh
/bin/bash ./install-open-terminal-launchagent.sh

If chmod or bash are “not found”, your PATH is broken (often Conda base); the /bin/… paths above still work.

Linux / WSL2 (systemd --user)

./scripts/install-open-terminal-systemd-user.sh

• Service name: com.flaiwheel.open-terminal-local.service
• Default endpoint: http://localhost:8000
• The script auto-generates an API key and prints it after install/reset.
• On WSL2, make sure systemd=true is enabled in /etc/wsl.conf.

Useful commands:

systemctl --user status com.flaiwheel.open-terminal-local.service
journalctl --user -u com.flaiwheel.open-terminal-local.service -f

macOS (launchctl LaunchAgent)

./scripts/macos/install-open-terminal-launchagent.sh

• LaunchAgent label: com.flaiwheel.open-terminal-local
• Default endpoint: http://localhost:8000
• The script auto-generates an API key and prints it after install/reset.
• The LaunchAgent sets WorkingDirectory to $HOME by default so Open Terminal does not start in /private/tmp.
• PATH: launchd does not load ~/.zshrc, so the daemon used to see only /usr/bin:/bin:… and miss Homebrew / Supabase CLI. The generated wrapper prepends /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, and ~/.npm-global/bin. Re-run the installer (menu →1 Update) after pulling this change so the wrapper is regenerated.
• Persisted custom folder: the installer can save a path in ~/.config/flaiwheel/open-terminal-working-directory (fresh-install prompt, or menu →5 when re-running the script). Update (menu →1) keeps using that saved path. One-off override: set OPEN_TERMINAL_WORKING_DIRECTORY for that run only.

Environment overrides (both scripts):

HOST=127.0.0.1 PORT=8000 OPEN_TERMINAL_CORS_ALLOWED_ORIGINS='https://your-openwebui.example' ./scripts/install-open-terminal-systemd-user.sh

HOST=127.0.0.1 PORT=8000 OPEN_TERMINAL_CORS_ALLOWED_ORIGINS='https://your-openwebui.example' ./scripts/macos/install-open-terminal-launchagent.sh

macOS only — custom initial folder for Open Terminal (must exist before you save it):

OPEN_TERMINAL_WORKING_DIRECTORY="$HOME/projects/my-repo" ./scripts/macos/install-open-terminal-launchagent.sh

Re-run the same script and choose 5 to change or clear the saved folder (or edit ~/.config/flaiwheel/open-terminal-working-directory). Non-interactive install: set the env var above or create that file with a single line (path); use AUTO_INSTALL_DEPS=1 to skip the first-run path prompt.

Updating

Run the same install command again from your project directory:

bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)

The installer detects the existing container, asks for confirmation, then:

• Rebuilds the Docker image with the latest code
• Recreates the container (preserves your data volume + config)
• Refreshes all agent configs and guides

Your knowledge base, index, and credentials are preserved — only the code is updated.

Manual Setup

# On GitHub, create: <your-project>-knowledge (private repo)
mkdir -p architecture api bugfix-log best-practices setup changelog
echo "# Project Knowledge Base" > README.md
git add -A && git commit -m "init" && git push

git clone https://github.com/dl4rce/flaiwheel.git /tmp/flaiwheel-build
docker build -t flaiwheel:latest /tmp/flaiwheel-build
docker run -d \
  --name flaiwheel \
  -p 8080:8080 \
  -p 8081:8081 \
  -e MCP_GIT_REPO_URL=https://github.com/you/yourproject-knowledge.git \
  -e MCP_GIT_TOKEN=ghp_your_token \
  -v flaiwheel-data:/data \
  flaiwheel:latest

{
  "mcpServers": {
    "flaiwheel": {
      "type": "sse",
      "url": "http://localhost:8081/sse"
    }
  }
}

{
  "servers": {
    "flaiwheel": {
      "type": "sse",
      "url": "http://localhost:8081/sse"
    }
  }
}

{
  "mcpServers": {
    "flaiwheel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8081/sse"]
    }
  }
}

claude mcp add --transport sse --scope project flaiwheel http://localhost:8081/sse

Knowledge Repo Structure

yourproject-knowledge/
├── README.md              ← overview / index
├── architecture/          ← system design, decisions, diagrams
├── api/                   ← endpoint docs, contracts, schemas
├── bugfix-log/            ← auto-generated bugfix summaries
│   └── 2026-02-25-fix-payment-retry.md
├── best-practices/        ← coding standards, patterns
├── setup/                 ← deployment, environment setup
├── changelog/             ← release notes
└── tests/                 ← test cases, scenarios, regression patterns

Supported Input Formats

Flaiwheel indexes 9 file formats. All non-markdown files are converted to markdown-like text in memory at index time — no generated files on disk, no repo clutter.

Quality checks (structure, completeness, bugfix format) apply only to .md files. Other formats are indexed as-is.

Configuration

All config via environment variables (MCP_ prefix), Web UI (http://localhost:8080), or .env file.

Multi-Repo Support

A single Flaiwheel container can manage multiple knowledge repositories — one per project. Each project gets its own ChromaDB collection, git watcher, index lock, health tracker, and quality checker, while sharing one embedding model in RAM and one MCP/Web endpoint.

How it works:

• The first install.sh run creates the Flaiwheel container with project A
• Subsequent install.sh runs from other project directories detect the running container and register the new project via the API — no additional containers
• All MCP tools accept an optional project parameter (e.g., search_docs("query", project="my-app"))
• Call set_project("my-app") at the start of every conversation to bind all subsequent calls to that project (sticky session)
• Without an explicit project parameter, the active project (set via set_project) is used; if none is set, the first project is used
• The Web UI has a project selector dropdown to switch between projects
• Use list_projects() via MCP to see all registered projects (shows active marker)

Adding/removing projects:

• Via AI agent: call setup_project(name="my-app", git_repo_url="...") — registers, clones, indexes, and auto-binds
• Via install script: run install.sh from a new project directory (auto-registers)
• Via Web UI: click "Add Project" in the project selector bar
• Via API: POST /api/projects with {name, git_repo_url, git_branch, git_token}
• Remove: DELETE /api/projects/{name} or the "Remove" button in the Web UI

Backward compatibility: existing single-project setups continue to work without changes. If no projects.json exists but MCP_GIT_REPO_URL is set, Flaiwheel auto-creates a single project from the env vars.

Embedding Model Hot-Swap

When you change the embedding model via the Web UI, Flaiwheel re-embeds all documents in the background using a shadow collection. Search remains fully available on the old model while the migration runs. Once complete, the new index atomically replaces the old one — zero downtime.

The Web UI shows a live progress bar with file count and percentage. You can cancel at any time.

Embedding Models (local, free)

Select via Web UI or MCP_EMBEDDING_MODEL env var. Full list in the Web UI.

Cross-Encoder Reranker (optional)

The reranker is a second-stage model that rescores the top candidates from hybrid search. It reads the full (query, document) pair together, which produces much more accurate relevance scores than independent embeddings — especially for vocabulary-mismatch queries where the user and the document use different words for the same concept.

How it works:

1. Hybrid search (vector + BM25) retrieves a wider candidate pool (top_k × 5)
2. RRF merges and ranks the candidates
3. The cross-encoder rescores the top candidates and returns only the best top_k

Enable via Web UI (Search & Retrieval card) or environment variable:

docker run -d \
  -e MCP_RERANKER_ENABLED=true \
  -e MCP_RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2 \
  ...

The reranker is off by default (zero overhead). When enabled, it adds ~50ms latency per search but typically improves precision by 10-25% on vocabulary-mismatch queries.

GitHub Webhook (instant reindex)

Instead of waiting for the 300s polling interval, configure a GitHub webhook for instant reindex on push:

1. In your knowledge repo on GitHub: Settings → Webhooks → Add webhook
2. Payload URL: http://your-server:8080/webhook/github
3. Content type: application/json
4. Secret: set the same value as MCP_WEBHOOK_SECRET
5. Events: select "Just the push event"

The webhook endpoint verifies the HMAC signature if MCP_WEBHOOK_SECRET is set. Without a secret, any POST triggers a pull + reindex.

CI Guardrail Telemetry (ROI tracking)

Track non-vanity engineering impact directly in Flaiwheel:

• POST /api/telemetry/ci-guardrail-report — CI reports guardrail findings/fixes per PR
• GET /api/impact-metrics?project=<name>&days=30 — returns estimated time saved + regressions avoided

Example payload:

{
  "project": "my-app",
  "violations_found": 4,
  "violations_blocking": 1,
  "violations_fixed_before_merge": 2,
  "cycle_time_baseline_minutes": 58,
  "cycle_time_actual_minutes": 43,
  "pr_number": 127,
  "branch": "feature/payment-fix",
  "commit_sha": "abc1234",
  "source": "github-actions"
}

Flaiwheel persists telemetry on disk (<vectorstore>/telemetry) so metrics survive container restarts and updates.

Diff-aware Reindexing

Reindexing is incremental by default — only files whose content changed since the last run are re-embedded. On a 500-file repo, this means a typical reindex after a single-file push takes <1s instead of re-embedding everything.

Use reindex(force=True) via MCP or the Web UI "Reindex" button to force a full rebuild (e.g. after changing the embedding model).

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Docker Container (single process, N projects)               │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Web-UI (FastAPI)                        Port 8080    │  │
│  │  Project CRUD, config, monitoring, search, health     │  │
│  └─────────────────────┬─────────────────────────────────┘  │
│                         │ shared state (ProjectRegistry)     │
│  ┌─────────────────────┴─────────────────────────────────┐  │
│  │  MCP Server (FastMCP)                    Port 8081    │  │
│  │  28 tools (search, write, classify, manage, projects) │  │
│  └─────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌─────────────────────┴─────────────────────────────────┐  │
│  │  Shared Embedding Model (1× in RAM)                   │  │
│  └─────────────────────┬─────────────────────────────────┘  │
│                         │                                    │
│  ┌──────────────────────┴────────────────────────────────┐  │
│  │  Per-Project Contexts (isolated)                      │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │  │
│  │  │  Project A  │  │  Project B  │  │  Project C  │   │  │
│  │  │  collection │  │  collection │  │  collection │   │  │
│  │  │  watcher    │  │  watcher    │  │  watcher    │   │  │
│  │  │  lock       │  │  lock       │  │  lock       │   │  │
│  │  │  health     │  │  health     │  │  health     │   │  │
│  │  │  quality    │  │  quality    │  │  quality    │   │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘   │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                              │
│  /docs/{project}/  ← per-project knowledge repos             │
│  /data/            ← shared vectorstore + config + projects  │
└─────────────────────────────────────────────────────────────┘

Search Pipeline

query
  │
  ├──► Vector Search (ChromaDB/HNSW, cosine similarity)
  │         fetch top_k (or top_k×5 if reranker enabled)
  │
  ├──► BM25 Keyword Search (bm25s, English stopwords)
  │         fetch top_k (or top_k×5 if reranker enabled)
  │
  ├──► RRF Fusion (configurable k, vector/BM25 weights)
  │         merge + rank candidates
  │
  ├──► [optional] Cross-Encoder Reranker
  │         rescore (query, doc) pairs for higher precision
  │
  ├──► Min Relevance Filter (configurable threshold)
  │
  └──► Return top_k results with relevance scores

Web UI

Access at http://localhost:8080 (HTTP Basic Auth — credentials shown on first start).

Features:

• System health panel: last index, last git pull, git commit, version, search metrics, quality score, skipped files count
• Index status and statistics (including reranker status)
• Embedding model selection (visual picker)
• Search & Retrieval tuning: cross-encoder reranker toggle + model picker, RRF weights, minimum relevance threshold
• Chunking strategy configuration
• Git sync settings (URL, branch, auto-push toggle)
• Test search interface
• Knowledge quality checker (also runs automatically after every reindex)
• Search metrics (hits/total, miss rate, per-tool breakdown)
• Skipped files indicator (files excluded from indexing due to critical quality issues)
• "This is the Way" — Knowledge Bootstrap: agent-driven project classification + in-repo cleanup (Web UI shows guidance + advanced scan)
• Multi-project switcher (manage multiple repos from one instance)
• Client configuration snippets (Cursor, Claude Desktop, Docker)
• Password management

Development

# Clone
git clone https://github.com/dl4rce/flaiwheel.git
cd flaiwheel

# Install
pip install -e ".[dev]"

# Run tests (259 tests covering readers, quality checker, indexer, reranker, health tracker, MCP tools, model migration, multi-project, bootstrap, classification, file-context, cold-start analyzer)
pytest

# Run locally (needs /docs and /data directories)
mkdir -p /tmp/flaiwheel-docs /tmp/flaiwheel-data
MCP_DOCS_PATH=/tmp/flaiwheel-docs MCP_VECTORSTORE_PATH=/tmp/flaiwheel-data python -m flaiwheel

License

Business Source License 1.1 (BSL 1.1)

Flaiwheel is source-available under the Business Source License 1.1.

You may use Flaiwheel for free if:

• Your use is non-commercial (personal, educational, no revenue), or
• Your organization has no more than 10 individuals using it

Commercial use beyond these limits (e.g., teams of 11+ or commercial deployment) requires a paid license.

• Effective 2030-02-25, this version converts to Apache License 2.0 (fully open source)
• Commercial licenses: info@4rce.com | https://4rce.com

See LICENSE for full terms.