cortex-viz

cortex-viz

The visualization layer for Cortex. A standalone MCP that turns Cortex's memory store, your Claude Code session history, and your codebase graph into six live reading angles over the same data: a galaxy of every project, that same graph rendered inside a 3D anatomical brain, a per-session execution trace, a consolidation kanban, a curated knowledge browser, and a wiki. It reads Cortex's shared PostgreSQL store read-only plus the ~/.claude artifacts; it renders, it never remembers.

Launch with the open_visualization tool (or /cortex-visualize). One launcher opens six reading angles; the default landing view is Trace.

The whole UI ships on the AI Architect design system: a paper-first reading surface with a persistent ink (night) toggle, greyscale chrome, and a data palette resolved from design tokens at runtime, flipping the surface re-inks every view in place without disturbing a settled layout, and every count on screen is exact and streamed, never rounded.

Getting Started

The plugin marketplace is the supported install path. cortex-viz ships in the same cortex-plugins marketplace as Cortex:

claude plugin marketplace add cdeust/Cortex
claude plugin install cortex-viz

cortex-viz is a read-only companion to Cortex. Install Cortex first (claude plugin install cortex): cortex-viz reads its shared PostgreSQL store and never writes to it. Point both at the same database: the database_url plugin setting defaults to postgresql://127.0.0.1:5432/cortex; set it to the same value you gave Cortex.

Restart your Claude Code session, then launch the visualizer:

/cortex-visualize

One launcher opens all six reading angles (Graph · Brain · Trace · Knowledge · Wiki · Board) in the browser, served live from the Cortex store, your session JSONL, the code graph, and git.

Works without Cortex

No Cortex, no PostgreSQL, no setup: cortex-viz is still useful on its own. The Trace view (the default landing view) reads only ~/.claude/projects/*.jsonl and your local git: every Claude Code session becomes a navigable domain → session → prompt → action → file chain, with per-file diffs and commit history. If you use Claude Code, the data is already on your disk.

• Just install the plugin and run /cortex-visualize. When Cortex's database isn't reachable, the server logs one line and starts in no-DB mode automatically: Trace is fully live; the five DB-backed views (Graph, Brain, Knowledge, Wiki, Board) appear greyed out with an install pointer instead of erroring.
• To skip the database probe entirely, set CORTEX_VIZ_NO_DB=1 (or pass --no-db when running the standalone server directly).

Installing Cortex later lights up the other five views against the same UI (no reconfiguration).

git clone https://github.com/cdeust/cortex-viz.git && cd cortex-viz
pip install -e .
DATABASE_URL=postgresql://127.0.0.1:5432/cortex python3 -m cortex_viz
# Without Cortex/Postgres (Trace view only):
CORTEX_VIZ_NO_DB=1 python3 -m cortex_viz

The views

Graph: the Claude workflow map

Each project becomes a cloud of nodes around one gold domain hub. Inside every cloud, nodes sit in six concentric levels by the Claude surface (or the code itself) that produced them: