fux

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". It gets back 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"
# Deploying and rolling back

# Deploying and rolling back

To roll back a bad release, run `make rollback` from the release branch.
The previous image tag is kept for 7 days.

Deploys go out from `main` every weekday at 10:00.

  -- docs/deploy.md:L1-L6 (sha 6155f9c4ddf7, current)

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

• The first answer quotes the exact lines it came from, and checks that they still say that today.
• The second one refuses. Your docs don't cover the question, and a confident wrong answer is worse than none.

Edit the source, and the same answer tells you:

$ fux answer "how do I roll back a release"
note: 1 source(s) changed: docs/deploy.md.
…
  -- docs/deploy.md:L1-L7 (sha a76c0744a2dc, stale)

In plain words

• fux is a card catalogue for your team's documents. It doesn't copy the books; it notes which words are on which pages.
• The catalogue lives in your git repo, so everyone who clones it, and every AI assistant they use, searches the same thing.
• Ask a question and fux points to the page, quotes the lines, and tells you whether the page has changed since it was catalogued.
• If nothing in your documents answers it, fux says so instead of guessing.
• No AI runs inside fux, so the same question gets the same answer on every machine.

Why people use fux

• 🗂 Clone and ask. The index lives in .fux/index/. Every clone searches the same thing: yours, a teammate's, CI's and your agent's. Nothing to deploy.
• 🔍 Answers you can audit. answer re-reads the cited lines from the source and says whether they still match. --receipt records the index, settings and source shas an answer came from, and fux verify checks a receipt against the tree.
• 🤖 Built for agents first. fux setup writes ready-made skills and instructions for Claude Code, Codex, GitHub Copilot and Kiro. fux mcp serves the index over MCP, fux lsp serves it to your editor, and fux llms prints it as an llms.txt.
• 🔒 Offline unless you ask. No telemetry and no network on any default path. PII is redacted 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 fux-engine           # Python ≥ 3.12 · Linux, macOS, Windows · zero deps
cd your-repo
fux setup                        # writes .fux/, fux.toml and the agent instructions
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.

• What gets indexed is listed in .fux/sources.yaml (README.md and docs to start). Anything you don't want indexed goes in .fux/.fuxignore.
• fux ingest reports what it did: ingested 3 docs (3 changed, 0 carried forward), 0 not indexed, 0 skipped, 3 shards written.
• fux doctor checks the setup. It's read-only and offline.

No Python on the machine? Install the single-file, zero-dependency Node reader from npm — npm install fux-engine, then npx fux find rollback (Node ≥ 22; the package's bin is fux). That is the only way to get it: fux setup no longer vendors a copy into .fux/node/ or writes a .fux/fux shim, so a clone with nothing installed no longer answers from Node — one package install first. A repository pins it by listing fux-engine in its own package.json.

A machine that only reads, or only writes? Since 4.0.0, fux ships as four packages on one version. fux-engine is all of them. fux-reader ranks and answers, fux-writer ingests and keeps the index current, and fux-core is what both share. A verb from a package you didn't install is refused by name.

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
fux lsp          # LSP over stdio: search, link hovers, backlinks, archived-link warnings
fux llms --full  # an llms-full.txt of the corpus, to stdout

VS Code: install the .vsix from the latest release with code --install-extension fux-<version>.vsix. It registers fux mcp for agent mode automatically and runs fux lsp, so there's no mcp.json to write (vscode/ · SR-VSCODE).

• The instructions teach the agent to search the index before grepping, to read the JSON rather than the prose, and to 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).
• Turn the agent files off with [agents] install = [] in fux.toml, or with fux setup --no-agents.

What it can read

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

In 4.1, every decoder and fetcher is copied into .fux/ as your code, for you to read, edit or replace (SR-DECODE, SR-FETCHER).

Everyday commands

fux ask --why shows its working:

$ fux ask --why "how many times do we retry a card"
[why] reachable 3 -> window 2 -> placed 2 -> answered 1 (cut at 0.4903)
       #1 docs/adr-007-retries.md 2.7167  matched retry,card  absent many,times,do
       #2 README.md 0.4903  matched card  absent many,times,do,retry

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 (verdict).

Is fux for you?

Choose fux when:

• your agents keep answering from stale or invented context, and you want every answer tied to lines you can check;
• your knowledge is spread across formats: Markdown, PDFs, Office files, wiki pages;
• you want search that works on a fresh clone and in CI, with nothing to host and no key to manage;
• you need answers that are reproducible and auditable, such as for regulated or review-heavy work.

Look elsewhere when:

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

Roadmap

From the live queue, work/OPEN-WORK.md:

FAQ

Does fux call an AI model? No. No fux path may call a model, and nothing in the maintenance path uses one. Your agent can generate enrichment through fux enrich, and fux validates it.

Does my content get copied into the repo? No. The committed index holds statistics, not your documents' text. answer fetches the cited lines from the source at answer time.

What stops a secret from reaching git? .fux/config/pii.toml redacts matches before anything reaches the committed index, and fux won't run without it (SR-PII).

Does it need the network? Only for commands you run on purpose, such as fux add <url>, and they say so on stderr (L5).

How do teammates stay in sync? They pull. The index is plain JSONL in git, it merges with fux hooks' merge driver, and a pull request shows exactly what changed.

Status

5.0.0 is the latest release on PyPI (pip install fux-engine) and npm (npx fux-engine). 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 about new versions.

Under the hood

Contributing

Issues and PRs are welcome, and a bug report with a failing query is gold. See CONTRIBUTING.md for the build, the two test suites and what a change owes its record. Please follow the Code of Conduct, and report security issues privately (SECURITY.md).

License

MIT. Free forever, with FOSS-only dependencies forever (L2).