Your agent can read every line of your code. It still doesn't know why the code is the way it is — that lives in ADRs, runbooks, specs, wiki pages and the PDF someone attached to a ticket in 2023.

So it greps, guesses, or asks a vector database for "the nearest chunk" — and gets an answer that sounds right, from a doc that went stale six months ago.

fux fixes that with boring, auditable arithmetic:

$ fux answer "how do I roll back a release"
To roll back a bad release, run `make rollback` from the release branch.
The previous image tag is kept for 7 days.

  -- docs/deploy.md:L1-L6 (sha 18ac8c4e4d33, current)

$ fux ask --band "kubernetes autoscaling limits"
No confident matches.
confidence: none - nothing in the index scored for this query.

The first answer quotes exact lines and proves they still say that today. The second one refuses — because your docs don't cover it, and a confident wrong answer is worse than none.

Why people use fux

• 🗂 Clone and ask. The index lives in .fux/index/. Every clone — yours, a teammate's, CI's, your agent's — searches the same thing. Nothing to deploy.
• 🔍 Answers you can audit. answer re-reads the cited lines from the source and tells you whether they still match. --receipt + fux verify lets anyone reproduce it later.
• 🤖 Built for agents first. fux setup drops ready-made skills and instructions for Claude Code, Codex, GitHub Copilot and Kiro, and fux mcp serves the index over MCP.
• 🔒 Offline unless you ask. No telemetry, no network on any default path, PII redaction before anything is committed.
• 🧾 Your docs never move. fux stores statistics, not content. Sources stay in the repo or in the system that owns them.

60-second quickstart

pip install --pre fux-engine     # Python ≥ 3.12 · Linux, macOS, Windows · zero deps
cd your-repo
fux setup                        # writes .fux/ and agent instructions (only missing files)
fux ingest                       # indexes README.md and docs/ by default
fux ask "how do we roll back a release"
git add .fux fux.toml && git commit -m "Add fux index"

That's it. Your teammates — and their agents — now get the same answers from a plain git clone.

No Python on the machine? fux setup vendors a single-file, zero-dependency Node reader into .fux/node/, so .fux/fux find rollback works with nothing installed. Or: npx fux-engine find rollback.

Prefer a library?

from fux import open as fux_open
fux_open(".").ask("how do we roll back a release")

Plug it into your coding agent

fux setup        # skills + instructions for Claude Code, Codex, Copilot, Kiro, plus AGENTS.md
fux mcp          # MCP over stdio: fux_search, fux_passage, fux_related

The instructions teach the agent to search the index before grepping, read the JSON (not the prose), and treat an archived document as history rather than as the current design. There's deliberately no answer tool over MCP — the agent is the answerer; fux is the evidence. (SR-AGENT-POLICY · SR-MCP)

What it can read

• Text: Markdown, reStructuredText, AsciiDoc, Org, plain text
• Office & data: PDF, Word, PowerPoint, Excel, CSV/TSV, JSON, YAML, TOML, INI, XML
• Everything else: HTML, email, draw.io, SVG, images (via your agent, fux enrich)
• Web pages and wikis: fux add <url> — plain HTTP, or through the session your signed-in Chrome already holds, so internal wikis work too

Every decoder and fetcher is copied into .fux/ as your code — read it, edit it, replace it (SR-DECODE, SR-FETCHER).

Everyday commands

Full surface: fux --help and SR-CLI.

Measured, not assumed

Every claim ships with a pre-registered bar and a published run — including the ones that failed.

• ⚡ 27.2 ms worst-case p95 for warm ask --fast over 8,870 RFCs, against a 150 ms bar (run). The fast path must return byte-identical results to the full scan.
• 🕸 24/24 on a graded 66-document graph corpus, with the derived graph hashing identically on x86-64 Linux and arm64 macOS (run).
• 🪦 Failures kept on file. Index pruning failed its gate (verdict). A dense embedding lane fixed 0 queries and broke 2 — so it was deleted.

What fux is not

Honesty up front, so you don't find out the hard way:

• Not code search. No AST, no symbols, no call graph. Pair it with a code-graph tool; fux covers what you wrote down.
• Not semantic magic. Ranking is lexical. If your docs say "revert" and you ask "undo", use --expand, or teach it once with fux correct.
• Not a chatbot. fux finds and verifies evidence. Your agent (or you) writes the answer.

Status

3.0.0 is in alpha (pip install --pre fux-engine); 2.0.x is the latest stable line. The index format is versioned and fux tells you when to run fux ingest --full. Every change is in CHANGELOG.md.

⭐ Star the repo if fux saved your agent from one confident wrong answer — it's how other people find it. 👀 Watch → Custom → Releases to hear when 3.0 goes stable.

Under the hood

Contributing

pip install -e ".[dev]" && pytest

Issues and PRs welcome — bug reports with a failing query are gold. Every change to an SR-owned component updates its owning record in the same commit; CI checks it. Start with CLAUDE.md.

License

MIT — free forever, FOSS-only dependencies forever (L2).