The Viz Dashboard

A human window onto the mesh

The viz dashboard is a local web app for browsing your project’s mesh by eye. It is a convenience layer, not the main interface: agents read the mesh through the MCP server and most maintenance happens at the CLI. The dashboard exists for the moments a human wants to see the graph - to spot where staleness is spreading, trace how a function connects to its docs, or edit a DocJSON section in a rich editor.

It reads the same indexed database the rest of axiom-graph reads (.axiom_graph/graph.db), so nothing it shows is computed specially for the UI. The graph, the staleness rings, the node details - all of it is the persisted mesh, rendered. Run axiom-graph build at least once before launching so there is an index to read.

Launch it

Start the dashboard from a terminal, pointing at a project root:

axiom-graph viz /path/to/your/project

The server starts on port 8080 and opens your browser automatically. Override the port or suppress the browser as needed:

axiom-graph viz /path/to/your/project --port 9090
axiom-graph viz /path/to/your/project --no-browser

Then visit http://127.0.0.1:8080 (or your chosen port). The dashboard requires the viz extras:

pip install axiom-graph[viz]

It is a local, single-user tool - no authentication, no remote deployment. Launching auto-registers the project in ~/.axiom_graph/projects.json, which is what makes the project switcher (below) work across sessions and across git worktrees of the same repo.

The five tabs

The header has five tabs, each a different view of the same mesh:

Tab

What it is for

Graph

Interactive dependency graph (Cytoscape.js). Best for understanding how components relate.

List

Sortable, filterable table of every indexed node, with a source preview panel. Best for triaging staleness or browsing the full inventory.

Docs

Full DocJSON document manager: folder tree, section editor, link picker, Mermaid diagrams.

Workflows

The annotated orchestration highways - @workflow / @task definitions with their named step sequences.

Tests

Test functions with tier badges and the code nodes each one validates.

The active tab is remembered for the session. The Graph and List views share one set of sidebar filters, so a filter set in one carries into the other.

Graph and List: two views, shared filters

Graph view renders nodes and intent-typed edges (composes, delegates_to, depends_on, validates, documents, consumes) as a node-link diagram. Nodes are colored by subtype - function (green), module (blue), docjson (orange), test (red), entity (purple), external package (grey) - and config nodes pulled from .claude/ get their own distinct color so agent-config files stand out. Staleness shows as a colored border ring, so drift is visible at a glance rather than something you have to query for.

Five layouts are available (Force is the default; also Hierarchy, BFS, Grid, Concentric). Click a node to enter focus mode - a neighborhood-depth slider (1-4 hops) narrows the view to a local ego-network instead of the whole graph, which is the context-reduction idea applied visually: see exactly the connected nodes, not everything. Edge-type toggles and a “hide isolated nodes” checkbox trim the rest. For very large projects the dashboard starts in List view and offers to load the full graph on demand.

List view is the same nodes as a table (Name, Type, Location, Staleness, Tags) with sortable columns, a column-visibility menu, and five grouping modes (Type, Subtype, Module/File, Staleness, Tag). The shared sidebar filters by node type, subtype, staleness status, and tag, plus visibility toggles for private (_) functions and test files (both hidden by default). Markdown config files render an inline preview. Click a row to open the source preview: code nodes show in a Monaco editor with the relevant lines highlighted; a diff toggle compares the current source against a previous commit. Checkboxes drive bulk operations - select several nodes and “Verify Selected” to mark them reviewed, or “View in Graph” to jump to them in focus mode.

The detail drawer

Clicking a node in either Graph or List opens a detail drawer with five tabs:

  • Overview - type, subtype, staleness status, ID, location, tags, one-line summary. If the node is stale, a Staleness Cause block says why (content changed, description changed, a linked node went stale, or a broken link). A Mark Verified button records that you reviewed it.

  • Docs - the node’s description (Level 1) and detailed documentation (Level 2).

  • API - interface info, docstring, and the node’s annotated step sequence if it has one. View Source jumps to the source panel.

  • Relationships - inbound and outbound edges grouped by type, plus test-coverage links. Click any to navigate there.

  • History - the change log with commit SHAs and dates; click a SHA for a diff of that commit against the current source.

The Staleness Cause block is worth dwelling on: it is the same drift signal the rest of the system runs on, made legible (drift is a read on the mesh), and Mark Verified is how you tell the mesh a node is fine again. The drawer also shows verification attribution (who verified, when, and any reason).

Editing docs in the browser

The Docs tab is a full manager for the DocJSON files in your docs/ directory. A folder tree on the left organizes documents; a filter panel narrows by tag, search term, or path. Because each DocJSON section is its own node, the editor works at section granularity:

  • Edit a section in a rich-text editor (headings, bold, lists, tables, code blocks); changes save back to the file on disk.

  • Manage sections - add, reorder by dragging, rename headings and slugs inline, delete. A table-of-contents sidebar tracks scroll position.

  • Attach links - a link picker searches for nodes and attaches them as provenance links, the typed edges that bind a section to the code it documents.

  • Render Mermaid diagrams from section content, with a dedicated Monaco diagram editor and live preview.

  • Raw mode toggles between the rich editor and the underlying JSON.

This is the same editing surface used to maintain the docs you are reading - the docs-honesty loop in practice.

Workflows and tests

Workflows surfaces the semantic layer - the annotated orchestration highways. If your code uses @workflow / @task decorators, the tab lists every discovered workflow and task; selecting one shows its step sequence with step numbers, names, purposes, inputs, outputs, and critical-path flags. Filters narrow by module or show only items with steps, critical steps, or linked nodes. A Monaco viewer highlights the step lines in source. This is deliberately not a full call graph - it is the intentional highways through your orchestration, with their step names attached.

Tests lists every indexed test function with a tier badge (T1 unit, T2 integration, T3 end-to-end) and shows which code nodes each test validates. Filter by module, tier, or step annotations; selecting a test opens its source with relevant lines highlighted, and fixture relationships appear when available.

Search, time travel, and project switching

Search - the header search bar does keyword full-text matching, filtering both Graph and List to the matching nodes at once.

Changed Since - the sidebar narrows the display to nodes that changed after a reference point. Quick presets cover Last Checkpoint, Last Commit, and 24h; for finer control, Browse… opens a commit picker that lists recent commits - pick one to filter since that point, or check two to define a range. “Changed” is a true net diff of the current index against that point: a node you edited and then reverted within the window cancels out and won’t show up. Each changed row carries a change-kind badge - added, content, descriptor, content+descriptor, renamed, or deleted - and a kind filter lets you narrow to just one kind (e.g. only renames). The net kinds are on by default; a link toggle is shown but disabled (links/tags net-membership is deferred). Deleted nodes appear as ghost nodes: dimmed, struck-through rows synthesized from preserved history, so a node disappearing is itself visible rather than silent - and their pre-deletion source is recovered from git so you can still inspect what was removed. Both the since-query and those ghost rows are reads against the history log.

Check and Rescan - two header buttons. Check recomputes staleness for all nodes and writes it back, without re-indexing. Rescan runs a full axiom-graph build to pick up new or changed files. (Staleness shown in the UI reflects the last build or check, not live disk state - Check is how you refresh it on demand.)

Project switching - the project name in the top-left is a dropdown. Switch between registered projects without restarting the server, or register a new one by entering its path. Projects auto-register the first time you launch axiom-graph viz against them - including separate git worktrees of the same repo, which register independently - so the switcher fills in as you work.