dl4rce/flaiwheel

What's New in v3.0.0

Flaiwheel graduates from a developer search tool to a fully ambient engineering knowledge platform. Three major additions make Flaiwheel work automatically — without being explicitly invoked.

1. Behavioral Directives — AI Agents Work Silently

Four new machine-level directives in AGENTS.md and .cursor/rules/flaiwheel.mdc force AI agents (Cursor, Claude Code, VS Code Copilot) to use Flaiwheel in the background without asking:

| Directive | Effect |
|---|---|
| SILENT_BACKGROUND_SEARCH | Agent searches Flaiwheel before every response, automatically |
| AUTO_CLOSE_THE_LOOP | Agent documents after every completed task (bugfix → write_bugfix_summary, feat → write_changelog_entry, etc.) |
| REUSE_BEFORE_RECREATE | Agent checks for existing knowledge before writing anything new |
| FILE_CONTEXT_PRELOAD | Agent calls get_file_context() before touching any source file |

No prompt engineering needed. The agent just knows.

2. post-commit Git Hook — IDE-Agnostic Knowledge Capture

Every fix:, feat:, refactor:, perf:, docs: commit is automatically captured as a structured knowledge doc — no agent, no IDE, no manual action required.

• Works from any editor — IntelliJ, Neovim, terminal, CI/CD
• Zero credentials — Flaiwheel trusts 127.0.0.1 (localhost) implicitly, no password stored
• Installed automatically by install.sh (new Phase 10)
• New REST endpoint: POST /api/capture-commit

git commit -m "fix: race condition in payment webhook"
# → [flaiwheel] ✓ Knowledge captured → bugfix-log/2026-03-01-race-condition-in-payment-webhook.md

3. get_file_context(filename) — Spatial Knowledge Pre-Loading

New MCP tool (tool #27) that pre-loads relevant knowledge for any source file the agent is about to edit.

get_recent_sessions()        → What did we do last time? (temporal)
get_file_context("payment.ts") → What do we know about this file? (spatial)

Derives the search query from the filename automatically — no manual query needed. Works across all MCP clients.

Also added: GET /api/search/by-file?filename=... REST endpoint for IDE extensions and Claude Code hooks.

Breaking Changes

None. Fully backward-compatible with all 2.x setups.

Stats

• 230 tests — all passing (4 new tests for get_file_context)
• 27 MCP tools (was 26)
• +2 REST endpoints (/api/capture-commit, /api/search/by-file)
• +1 script (scripts/flaiwheel-hook.sh)

Upgrade

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

The installer detects your existing container, updates it, and installs the new git hook automatically.