What is ubCode?

ubCode is a Rust-powered engine that deeply understands your Sphinx-Needs project. It parses your reStructuredText files, indexes every need object and its relationships, and gives you real-time feedback — all without running a full Sphinx build.

Note

ubCode also has initial support for parsing MyST Markdown (.md) files, enabled per project via the [parse.parsers] configuration.

What problem does it solve?

Sphinx-Needs turns a Docs-as-Code approach into a full Engineering-as-Code solution: requirements, specifications, test cases, and other traceable items live right alongside your documentation source files. That is powerful, but Sphinx builds can take minutes on large projects. You write a new requirement, fix a link, or rename an ID — then wait for the build to tell you whether anything broke.

ubCode removes that wait. Its Rust core indexes thousands of files and needs in milliseconds, so diagnostics, link resolution, and traceability data update as you type. You get the full analytical power of Sphinx-Needs with the responsiveness of a modern language server.

Three ways to use it

ubCode is not just a VS Code extension. The same engine is available through three interfaces, so you can pick what fits your workflow:

🧩 VS Code extension

Install the ubCode extension for live diagnostics, previews, navigation, auto-completion, and graph views — right in your editor. See Installation for details.

🖥️ ubc CLI

A standalone binary that exposes the same engine on the command line. Run linting, build the needs index, diff two project revisions, or integrate checks into CI/CD pipelines — for example as part of a pre-commit hook or a pull-request gate. AI assistants can also drive the CLI to answer analysis questions about your requirements. See ubc CLI for download links and Using ubc in CI/CD for the full command reference.

🤖 MCP server

A Model Context Protocol server that gives AI assistants deep, structured access to your project’s requirements graph. See Model Context Protocol (MCP) server for details.

All three share a single Rust core and the same ubproject.toml configuration, so results are consistent regardless of how you interact with the engine.

How it relates to Sphinx and Sphinx-Needs

ubCode is a complement to Sphinx and Sphinx-Needs, not a replacement.

• Sphinx remains your documentation build system — it turns RST into HTML, PDF, and other formats.

• Sphinx-Needs remains your requirements-management extension — it defines need types, links, filters, and visualizations.

• ubCode re-implements the analysis side of that pipeline in Rust for speed. It reads the same RST source files and the same need definitions, but it does so in milliseconds instead of minutes.

Because ubCode does not execute Python, it relies on a declarative ubproject.toml configuration file rather than the Python-based conf.py. Starting from Sphinx-Needs 4.1, you can share configuration between both via the needs_from_toml option — see Coming from Sphinx-Needs for migration guidance.

Note

ubCode does not run Sphinx or any user Python code. It only reads RST files and known directives/roles. Custom Sphinx extensions that do not modify primary Sphinx-Needs data can still be used alongside ubCode.

Source code tracing with Codelinks

Beyond RST documentation, ubCode can trace into your source code. Codelinks lets you embed traceability markers directly in code comments — one-line need definitions, need-ID references, or full RST blocks — and ubCode’s Rust engine picks them up in real time.

This means requirements can live where the code is, and the .. src-trace:: directive brings them back into your documentation automatically. Configure it through the [codelinks] section of your ubproject.toml.

Architecture at a glance

        flowchart TD
    core["<b>Rust core engine</b><br/>parsing · indexing · diagnostics · query"]
    core --> ubc["single native <b>ubc</b> binary"]

    ubc -->|ubc serve lsp| lsp["language server"]
    ubc -->|ubc serve mcp| mcp["MCP server"]
    ubc -->|ubc lint · diff · …| commands["direct CLI commands"]

    lsp --> vscode["VS Code extension"]
    mcp --> ai["AI assistants<br/>(Copilot, etc.)"]
    commands --> ci["terminal · CI/CD · pre-commit"]
    

The Rust engine handles all the heavy lifting: parsing RST, resolving need links, running lint checks, evaluating queries, and scanning source code for traceability markers. It is compiled into a single native ubc binary with no Python runtime: the VS Code extension bundles that binary and launches it as a language server (ubc serve lsp) and an MCP server (ubc serve mcp), while running ubc directly on the command line drives the very same engine.

Design trade-offs

To achieve real-time performance, ubCode makes deliberate trade-offs:

• No Python execution — ubCode cannot run conf.py or custom Sphinx extensions. All configuration must be expressed declaratively in ubproject.toml.

• Known directive/role set — ubCode understands a large set of Sphinx and Sphinx-Needs directives and roles, but directives added by third-party extensions need to be declared in the configuration.

• Focus on primary data — ubCode indexes the primary traceability data (need objects, links, statuses, tags, and fields). Rendering-side features such as complex Sphinx-Needs visualizations are gradually being added.

These trade-offs are intentional and continuously minimized. See the Roadmap for upcoming improvements and Supported toolchain for the current feature coverage.