Skip to main content
WARDEN ships two ways to look at a knowledge base without writing Python. Both are read-only. Neither changes a single row. They share the same data the CLI and the library see, so anything the Oracle, the agent crew, or your own set-name calls produced shows up the moment you open them.
  • The terminal diff view renders a cross-version diff as a colored table in your shell.
  • The HTTP dashboard serves a single page on localhost with a confidence heatmap and a small JSON API behind it.
Both surfaces are strictly read-only. They open a fresh KnowledgeBase, answer the question, and close it. The HTTP server puts the connection into query_only mode for the whole request, so no route can write. The diff endpoint serves the stored diff, or computes one as a pure read that writes nothing. The terminal view renders diffs with carry=False, so it never ports an annotation forward either. To change annotations, use the CLI (warden set-name, warden agent) or the MCP server.

​
The terminal diff view

The terminal view lives in warden.ui.terminal. It turns a diff into a compact, colored table you can scan in a shell, the same data that backs the semantic changelog but laid out for the eye instead of for a file. It imports rich lazily, inside the functions that render. Importing warden.ui never pulls rich into the import path, so the standard-library HTTP server stays dependency-free.

​
Functions

Build a rich table comparing two versions function by function. One row per change. Each row shows the classification (unchanged, moved, modified, new, deleted), the from and to indices, the function name, the provenance, the confidence, and whether the change is runtime or toolchain churn.Rows are styled by classification, so genuine application deltas stand out from carried-over and unchanged rows. The provenance cell is colored by source, matching the heatmap. Driven by diff_versions(kb, a, b, carry=False), so it is a pure read.Returns: a rich.table.Table. Pass it to a console, or render it yourself.
Print the diff to the terminal. Builds the table with diff_table, prints it, then prints the semantic changelog underneath.Pass your own rich.console.Console to control width or capture the output; omit it and a default console is created.
Render a coverage summary for one version as a rich renderable: total defined functions, how many are named, the coverage percentage, and the split by source (oracle, human, agent). This is the same data warden coverage prints, formatted to read at a glance next to a diff.Returns: a rich renderable (a Table).
from warden.kb import KnowledgeBase
from warden.ui import render_diff

kb = KnowledgeBase("project.db")
render_diff(kb, from_version_id=1, to_version_id=2)
kb.close()
These functions back a warden ui diff CLI command that is being wired in. The command is read-only: it renders a diff as the terminal table instead of the plain-text changelog. It never carries annotations forward; use warden diff for that.

​
The HTTP dashboard

The dashboard lives in warden.ui.server. It is a small, standard-library-only HTTP server: it uses http.server, json, urllib, and html, with no third-party dependencies. It serves one self-contained page plus a handful of JSON endpoints.

​
Starting it

In Python, call serve directly: 
from warden.ui import serve

serve("project.db")  # blocks; serves on 127.0.0.1:8787
serve(db_path, *, host="127.0.0.1", port=8787) starts a ThreadingHTTPServer, prints the URL once, and serves forever. Use make_handler(db_path) to wire the handler into your own server.
The dashboard is read-only and meant for local use. It binds to 127.0.0.1 by default and has no authentication. Do not bind it to a public interface. If you change the host, you are exposing your knowledge base to that network with no access control.

​
The single-page dashboard

The page is one self-contained HTML document with inline CSS and vanilla JavaScript, no external assets and no build step. It lists every ingested version, shows coverage for the selected version, and renders the confidence heatmap: every function as a cell tinted by who claimed its name and how sure that claim is. This is the same heatmap the static warden report produces, served live from the database so it always reflects the current state. It also has a from/to diff view that calls the diff endpoint. The tint follows the provenance economy. Higher-authority sources read as cooler, more trustworthy hues; lower-authority guesses read as warm amber so they invite a second look.
ProvenanceTintMeaning
humanEmeraldSovereign, human-verified name.
oracleBlueMatched against a known corpus signature.
exportCyanA free fact read straight from the binary.
diff-carryAmberCarried across a version bump.
agentDarker amberModel guess, the lowest-trust source.
(unnamed)ZincNo symbol at all.
Within a color, the cell gets more opaque as confidence rises, so a strong claim is bright and a weak one is faint. Switch versions to recolor the whole grid.

​
The JSON API

The page is driven by a small read-only JSON API. The whole surface is the pure function handle_route(db_path, path, query), which opens a fresh KnowledgeBase, answers, and closes it, so you can test it without opening a socket. Every response below / is JSON. There is no write endpoint.
Method and pathReturns
GET /The single-page dashboard (HTML).
GET /api/versionsAll versions: id, label, emscripten_version, functions, shared_memory, coverage_pct.
GET /api/versions/{id}/functionsEvery defined function: index, name, provenance, confidence, type, stable_id. This is the data the heatmap draws.
GET /api/versions/{id}/coverageCoverage for one version: defined, named, coverage_pct, oracle_named, human_named, agent_named.
GET /api/diff?from={a}&to={b}The diff report as a dict (the same shape as DiffReport.as_dict()). It serves the stored diff if one exists, otherwise it computes the diff as a pure read (carry=False, store=False) that writes nothing. A 404 only means an unknown version id.
GET /api/symbol/{stable_id}The full annotation record for one function, or 404 if no symbol exists.
anything else404 with a JSON {"error": "..."} body.
The {id} path segment is the numeric version id from /api/versions. Unknown version ids and unknown routes both return a 404 JSON body. The ids are the same ones the library and the MCP server use, so a client can move between surfaces without remapping anything. 
import json
from warden.ui import handle_route

# Test the API in process, no socket required.
status, content_type, body = handle_route("project.db", "/api/versions", {})
assert status == 200
versions = json.loads(body)
The query argument is the parsed query string, a dict[str, list[str]] as produced by urllib.parse.parse_qs. 
# Read the API directly with curl once the server is running.
curl http://127.0.0.1:8787/api/versions
curl "http://127.0.0.1:8787/api/versions/1/coverage"
curl "http://127.0.0.1:8787/api/versions/1/functions"

CLI reference

Every warden command, including the diff and coverage commands these views build on.

MCP server

The same read surface for agents and IDEs, plus the one economy-gated write tool.
Last modified on June 9, 2026