X-as-Code engineering in your editor

ubCode lets you write and publish requirements, tests and documentation, with traceability checked in your editor and in CI, for people and AI agents. It reads reStructuredText and, once a project enables it, MyST Markdown, and is compatible with Sphinx and Sphinx-Needs.

Documentation · Install · Quickstart · Feature matrix · What's new

Why ubCode?

• Instant feedback – each file is checked as you type, in VS Code or any editor with a Language Server Protocol client, and in VS Code the whole project each time you save, or as you type with auto-save after a delay.
• Traceability you can gate on – typed, linked needs, validated against your schema and traced into code and test results; ubc check fails a pull request on the findings you choose.
• One binary, batteries included – the ubc CLI checks, queries and reports on your project, and builds its HTML site and PDF, on its own: no Python, LaTeX or conf.py to install.
• AI agents, checked by the engine (Experimental) – AI authors, the graph judges: the engine decides what is done, and holds a stage you mark for review until it passes one.
• Compatible by design – works on existing Sphinx and Sphinx-Needs projects, so you can adopt it step by step and keep your Sphinx build.
• Private by default – no telemetry, every network request listed, and an offline license file for machines without Internet access.

Pick the route that fits: manage requirements and traceability, publish documentation, supercharge your Sphinx project, or engineer with AI agents.

Get started

1. Open a folder with a ubproject.toml, or run ubCode: Create quickstart project from the command palette to scaffold one (quickstart).
2. Coming from Sphinx-Needs? Move your configuration to ubproject.toml and keep your Sphinx build working.

In the sections below, a feature is Stable unless marked Beta, Alpha or Experimental (what the levels mean).

Diagnostics as you type

A native engine parses and checks your files while you edit: markup and directive errors, need fields and link values, and the marker warnings of source files that codelinks traces, in the editor and the Problems panel. The findings that need the whole project (references and need links across files, and the rules of your schema) are listed in the Diagnostics view, refreshed when you open a file and each time you save. Rules can be switched off per project in ubproject.toml (linting).

Live preview

The preview shows how your reStructuredText or MyST will render, synchronized with the editor. Need cards show each need as it will build, with its needextend changes and the needs that link back to it; need views such as tables, flows and charts are drawn from the project index; and sphinx-design layouts and KaTeX math render too. A Structural mode shows how each directive and role was parsed instead. Writing content lists what renders, and the differences say where it departs from a Sphinx build.

Navigation, hover and completion

Go to definition, find all references, peek, document symbols and links, completion, quick-fixes and semantic highlighting, across documents and needs. Hovering a need shows its card (navigation).

Needs Index, filtering and graph

The Needs Index view lists every need of the project, from your documents and from imported and external needs.json files, with its fields and its outgoing and incoming links, which you can group by type, source or status (realtime index).

Beta: filter it with a free-text search, a Python-like expression, or a read-only openCypher query that selects needs by how they link to one another.

The needs graph view draws the links around a need: zoom, pan, and click a node for its details. Open it with ubCode: Open needs graph view from the command palette, the eye icon in the Needs Index, or a right-click on a need's id.

The Site Map view shows the project's toctree structure from its root document.

The index and its caches are built for size: here the indexer runs, before any cache exists, on projects of 14,000 and 84,000 needs.

Formatting

A reStructuredText formatter keeps indentation, line lengths and list styles consistent, and can wrap paragraphs to a line length or at semantic boundaries (configure it). Use Format Document, or format on save with these lines in your settings.json:

"[restructuredtext]": {
  "editor.defaultFormatter": "useblocks.ubcode",
  "editor.formatOnSave": true
}

Traceability beyond the documents

• Variants: one set of needs for several product variants.
• Intersphinx: references into other projects' documentation resolve.
• Beta: Codelinks turns traceability markers in source-code comments into needs in the same graph.
• Beta: Test reports turn JUnit-style XML results into needs, with the sphinx-test-reports directives.

Reports

Beta: the Reports view renders your own Jinja (.html.j2) report templates against the needs index into self-contained HTML documents, to attach to a release or archive for an audit. Preview one in a panel beside the editor, open it in the browser, or scaffold a starter template; render failures appear in the Problems panel. Alpha: insights run Cypher queries before their template, and can be rendered for a need from its CodeLens.

AI agents

The AI agents hub says what the engine checks, when, and how to pick a setup.

• Beta: the extension registers ubCode's MCP server for Copilot Chat. Its six tools give an assistant your project's needs graph (get_graph_schema, query_cypher), its references (search_references, resolve_reference), and the public ubCode and Sphinx-Needs documentation (search_docs, fetch_doc_page).
• Experimental: Pharaoh, ubCode's agentic engineer: you describe your process once, AI does the writing and ubc agent computes what is done and what comes next. In VS Code it has its own panels (Pharaoh Agent, Workflows, Gaps, Intent from Code and Changes), CodeLenses on every need, and workflow gaps in the Problems panel.
• Experimental: @pharaoh in Copilot Chat answers questions about Sphinx-Needs and ubCode from their documentation.

ubc itself never calls a language model. The model that writes and scores is the one you run: your assistant, the runner ubc agent run starts, the agent in the Pharaoh Agent panel, or the model Run Quality Analysis scores with.

Beyond VS Code

The extension runs the same native ubc engine that you can download as a standalone binary for the terminal and CI, with the same ubproject.toml:

• ubc check gates pull requests on the project-wide diagnostics the editor shows (ubc in CI).
• Beta: ubc build html and ubc build pdf build a static site and a single PDF from the same sources, without Sphinx (HTML, PDF).
• Beta: ubc diff compares two states of a project, such as two Git branches, and with --impact follows the links from each changed need to the needs it may affect (diff and impact analysis); ubc query runs filters and Cypher queries.
• ubc serve lsp brings diagnostics, hover, completion, navigation, quick-fixes and formatting to any editor with a Language Server Protocol client.

The extension is also published on Open VSX, for Cursor, Kiro and VSCodium.

Licensing

ubCode is free for open-source projects: a project whose Git repositories are publicly reachable is detected automatically and needs no key (the license terms say which projects qualify). A private project needs a commercial license; an active license of either kind unlocks every feature. Without one, the editor still indexes and checks a project of any size, and the other features work within limits, or need a license. Request a free enterprise trial to evaluate it on your own private project; ubCode for teams covers licensing, CI, offline use and support.

Feedback and support

• Report an issue or share feedback
• Private support