fux

Google does not store the web. It builds an index of the web, and the index is what you search.

fux does the same for the documents your team writes: ADRs, runbooks, specs, wiki pages, the PDF someone attached to a ticket in 2023. It builds a small index, commits it to your repository, and from then on anyone who clones the repo searches the same thing and gets the same answer. The primary searcher is your AI coding agent, which gets evidence it must cite and a refusal when the docs are silent. Because nothing inside fux is AI, the same index also serves a person at a terminal, an editor, and a script in CI, for free.

$ fux answer "how do I roll back a release"
# 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 tool 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.
• Your coding agent is the first customer. fux hands it ranked evidence with line numbers, and a refusal when there is none, so it stops inventing.
• No AI runs inside fux. It is arithmetic over words, so the same question gets the same answer on every machine. That is also why it works with no AI at all: the same index is a search engine for people and scripts.

Who searches it

The same index, five ways in. The coding agent is the primary one; the other four come free, because an index that is only arithmetic can be read by anything. None of them needs a server.

The longer version, as five short stories, is How fux is used.

Why not just grep?

grep and rg are the right tool when you know the string. fux is for when you know the question.

• 🗂 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.
• 🔒 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.
• 🤖 Agents first, everyone else free. fux setup writes ready-made skills for Claude Code, Codex, GitHub Copilot and Kiro; that is the primary path. Turn them off with --no-agents and the same index is still a search engine for people and scripts.

60-second quickstart

pip install fux-engine           # Python ≥ 3.12 · Linux, macOS, Windows · zero deps
cd your-repo
fux setup                        # writes .fux/, fux.toml, the agent files; prints one pip install line if your docs need decoders
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, their editors, your CI 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). The Node reader ranks and answers; ingest is Python. A repository pins it by listing fux-engine in its own package.json.

A machine that only reads, or only writes? 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.

Packages that ship their own index

Released in 5.1.0 (SR-PKG-INDEX).

A library's documentation is a corpus too, and today every consumer who wants to search it has to index it themselves. Since 5.1.0, the package author does it once:

1. The author runs fux ingest over the package's docs and fux pack to produce a small index segment, and ships it inside the npm tarball or the wheel (the recipe).
2. The consumer pins it with one row in .fux/config/plugins.toml, by name, version and digest.
3. One query searches the repo's own index and every pinned package's, ranked once on word statistics summed across all of them; fux ask --scope repo|packages|all (and scope on fux_search) narrows it when a large package crowds the top of the list. A hit names its package, and the passage is read in place inside the installed package. Nothing is copied; nothing is re-ingested.

Take sheetpane, two web components that view, edit and review .xlsx and .csv files inside any web page. Once its CI packs an index (it does not yet), an app that depends on it can ask "does sheetpane support formulas" and get the line from sheetpane's own docs that says it doesn't, next to the hit from the app's own ADR that says why it was chosen anyway. The first consumer is codelaw's rule packs: the spike that gated the design put the right rule in the top five for 19 of 20 plain-words questions, against a bar of 16 (run).

The 10 000-document design point counts the merged corpus, repo plus every pinned segment, and fux doctor reports the sum.

What it can read

• Built in: Markdown and plain text.
• Through declared decoder packages: reStructuredText, AsciiDoc, Org · PDF, Word, PowerPoint, Excel, CSV/TSV · JSON, JSONL, YAML, TOML, INI, XML, RTF · 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.

Since 5.0, only the engine is mandatory. Every other format is read by a fux-decoder-* or fux-fetcher-* package that your repository declares in the committed .fux/config/plugins.toml, pinned to one version and digest; fux setup scans your sources, writes the declaration and prints the one pip install line. A package nobody declared never runs (SR-PLUGINS, 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).
• 📦 19/20 plain-words questions found the right rule in the top five of a published rule pack, the spike that gated package indexes (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 coding agents keep answering from stale or invented context, and you want every answer tied to lines you can check (the primary case);
• you want search over what your team wrote down, from a fresh clone and in CI, with nothing to host and no key to manage;
• your knowledge is spread across formats: Markdown, PDFs, Office files, wiki pages;
• you need answers that are reproducible and auditable, such as for regulated or review-heavy work;
• you maintain a library and want its users, and their agents, to search your docs without copying them (5.1.0, above).

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 are building a chat feature into a product. That is a vector store, an embedding model and a server, run for your end users at runtime. fux is the developer-side index of a team's own documents, committed next to them. Different job; see the FAQ.

Roadmap

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

FAQ

Do I need an AI to use fux? No. fux is built for AI coding agents first, and that is where most teams start. But no AI runs inside it, so the same index is a plain search engine with a terminal, a browser page, an editor plug-in and a library interface. Scripts and people are the second audience, and they need nothing extra.

Is fux a vector database, or a RAG stack? No, and it isn't trying to be. A vector store plus an embedding model is what you run behind a chat feature inside a product, serving end users at runtime. fux is the index of the documents a team writes, committed with them and searched by the people and tools working on that repo. If you build a product chatbot later, fux can be the thing that hands it cited, verified passages; it does not replace the chatbot's own stack.

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.

How big can it go? The design point is 10 000 documents, and that is a ceiling on what fux measures and promises, not a target it merely reaches. Every published number was taken at or below it.

Status

5.1.0 is the latest release on PyPI (pip install fux-engine) and npm (npm install 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 you, or 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).