Fux

A search index for your written knowledge — decisions, runbooks, specs, wiki pages — committed to git and read by agents.

Fux ranks documents from a small, plain-text index committed to git, then reads the answer back from the source itself. No server, no vector database, no API key, and no model anywhere on the path.

Status: 2.0.0 — released on PyPI and npm. The 2.x CLI and index format are what the next 2.x releases keep; a break waits for the next major. Every change is in CHANGELOG.md.

Why fux

• Clone and ask. The index is committed under .fux/index/, so every clone — yours, a teammate's, CI's, an agent's — searches the same thing. Nothing to host.
• Text you can review. One JSON line per document, sharded and sorted, so it diffs like code. A bundled git merge driver handles index changes from two branches.
• Documents stay where they are. The index holds statistics, not content. answer reads the cited lines from the source and says whether they are still current.
• Deterministic. Ranking is BM25F arithmetic (SR-RANKING). The same sources build the same index.
• Says when it doesn't know. Results carry a confidence band, and an unrelated question gets "No confident matches" rather than the nearest noise (SR-CONFIDENCE).
• It indexes documents, not code. Fux runs no parser over source files — no AST, no symbols, no call graph — and source extensions are not on its default type list. Pair it with a code-graph tool when you want structure.

The whole idea in one picture: work/architecture-high-level.svg. How a verb actually works: ask · answer · decoders. Python versus Node, component for component: two readers.

Install

pip install --pre fux-engine    # Python ≥ 3.11 · Linux, macOS, Windows

--pre is needed while fux is in alpha. The command is fux.

You can also read an index without Python. fux setup vendors a zero-dependency Node reader into .fux/node/ — one generated file, not fux's source tree — so a clone answers with nothing installed at all:

.fux/fux find rollback        # the shim: correct in every shape, so it is the one to use
npx fux-engine find rollback  # from npm, without a repository

It only reads — ingest, build and every other writing verb stay with Python — and it is held byte-equal to Python by a third arm of the differential law. In a monorepo fux setup detects the workspace instead and declares .fux/node as a member, so the reader comes from your lockfile; either way .fux/fux is the command.

And fux is importable, not only spawnable:

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

Quickstart

$ cd your-repo
$ fux setup      # writes .fux/ and agent instructions; only creates missing files
$ fux ingest     # indexes what .fux/sources/dirs lists (setup seeds README.md and docs/)
ingested 2 docs (2 changed, 0 carried forward), 0 not indexed, 0 skipped, 2 shards written
accelerator: 31 terms, 31 blocks, 34 postings (derived, not committed)

$ fux ask "how do I roll back a release"
2.2044  Deploying the payments service  (docs/deploy.md)

$ fux answer "how do I roll back a release"
# Rollback
...
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.

$ git add .fux fux.toml && git commit -m "Add fux index"

.fux/ explains itself: setup writes a .fux/README.md and a .gitignore that keeps the derived and fetched parts out of git (SR-DOTFUX).

Everyday commands

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

With coding agents

Agents are fux's primary reader.

• Instructions out of the box. fux setup adds skills and instructions for Claude Code, Codex, GitHub Copilot and Kiro, plus a root AGENTS.md. They tell the agent to search the index before grepping and how to read a result. Skip with --no-agents (SR-AGENT-POLICY).
• MCP. fux mcp serves the index over stdio as three tools: fux_search, fux_passage and fux_related. There is no answer tool — the agent is the answerer (SR-MCP).
• Read the JSON, not the prose. --json and --band carry the fields an agent should branch on, including whether a result is archived (SR-ARCHIVED-CONTENT).

Beyond Markdown

• File formats. Markdown, reStructuredText, AsciiDoc, Org and plain text, plus decoders for PDF, Word, PowerPoint, Excel, CSV/TSV, HTML, email, draw.io, JSON, YAML, TOML, INI, XML, SVG and images. The decoders are copied into .fux/decoders/ as your code, to edit or replace (SR-DECODE).
• Web pages and wikis. fux add <url> fetches through a fetcher in .fux/fetchers/: http.py for a plain GET, or cdp.py (--cdp) to use the session your signed-in Chrome already holds. Both are yours to edit — and fetch=<name> on a URL line resolves to any .py you put in that directory, the same way .fux/decoders/ already works. A fetcher retrieves bytes and never converts them: the same line says decoder=<name> for the decoder that turns those bytes into Markdown, written once by fux add from the type it observed, so which decoder read a page is a committed line rather than whatever the server said that morning (SR-FETCHER, SR-URL-LIST).
• Offline unless you ask. Only explicit, opt-in commands touch the network, and they say so on stderr (L4).
• Sensitive text. .fux/pii.toml redacts matches from the committed index (SR-PII). fux setup writes it, and fux will not run without it. .fux/refusals.toml stops a sign-in wall being indexed as the page behind it (SR-REFUSAL).
• Images and scans. Fux never calls a model. fux enrich plans the work for your coding agent and validates what it writes (SR-ENRICH).

Measured, not assumed

Claims ship with a pre-registered bar and a published run — including the ones that failed.

• Speed. Warm ask --fast on 8,870 RFCs: worst-case p95 27.2 ms against a 150 ms bar (run, 2026-08-12, pre-2.0). The accelerator must return byte-identical results to the default scan.
• Graph. 24/24 on a graded 66-document corpus; the derived graph hashes identically on x86-64 Linux and arm64 macOS (run).
• Kept the failures. Pruning the index to top terms failed its gate (verdict). A dense embedding lane measured 0 fixed / 2 broken queries and was deleted in alpha.1.

Design rules

Fux is built under eleven laws, each with its own record in the SR register (SR-LAWS): L0 SRs are the source of truth · L1 $0, FOSS-only · L2 content never durable · L3 deterministic · L4 offline by default · L5 hashed meta · L6 say "index" · L7 Python ≥ 3.11 · L8 use record never committed · L10 build output, never source · L11 the sealed answer key is closed to Claude.

Reading order

1. docs/index.md — the map of every doc in the repo
2. The SR register — every decision of record
3. Detailed architecture diagram — every plane, what is committed and what is not, and the two query paths
4. The paper — the architecture of record, v1.0 (2026-09-14): what ships, what was measured, what was designed and not built, and the open work — with twenty diagrams
5. Sibling environments — the sandbox, the measurement lab and the benchmark harness that sit next to this repo
6. CLAUDE.md — how work is done here, for people and agents

Contributing

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

Every change to an SR-owned component updates its owning record in the same commit; CI checks it. Start with CLAUDE.md.

License

MIT