Backpack Viewer

See your learning graph. A web-based visualizer for Backpack learning graphs with force-directed layout, interactive navigation, and live reload.

Quick start

Tell Claude:

"Show me my learning graph"

Or run it directly:

npx backpack-viewer

Opens http://localhost:5173. Click any learning graph in the sidebar to visualize it.

Using Claude Code? The backpack-ontology-plugin bundles the MCP server with usage skills (backpack-guide, backpack-mine) and is the recommended install path. The viewer works against whatever backpack data the plugin or standalone MCP writes, no extra wiring needed.

Features

Exploration

• Live reload — add knowledge via Claude and watch it appear in real time
• Pan and zoom — click-drag to pan, scroll to zoom
• Focus mode — select nodes and isolate their N-hop subgraph
• Walk mode — traverse the graph node-by-node with a highlighted trail
• Path finding — select two nodes, shortest path highlighted
• Search — filter by name in the sidebar, filter by type with chips
• Node history — back/forward navigation through inspected nodes
• Graph snippets — save walk trails as named, reusable subgraphs

Editing

• Inspect — click any item to see properties, connections, and metadata
• Inline edit — rename graphs, change node types and properties, add/remove items
• Star nodes — mark important nodes with a gold star indicator

Collaboration awareness (0.3.0+)

• Lock heartbeat badge — each graph in the sidebar shows editing: <author> when another writer is actively editing (within the last 5 minutes). Backed by a batched /api/locks endpoint.
• Remote graphs section — subscribe to learning graphs hosted at HTTPS URLs and view them read-only alongside your local graphs.

Knowledge base

• KB panel — a tabbed panel for managing documents alongside your graphs
• Mount selector — switch between local, cloud, and extension-provided document sources
• Document list — browse, search, and manage documents with a three-dot context menu
• Markdown rendering — documents render with tables, code blocks, and task lists

Cloud cache

• Cloud backpack switching — switch between local and cloud backpacks via the sidebar indicator
• Write-through cache — CloudCacheBackend stores graphs locally and syncs to BackpackApp cloud
• Sync controls — push (encrypted BPAK upload) and pull (cache refresh) with per-item status results

Knowledge Graph (requires backpack-connector)

The sidebar's Knowledge Graph section shows a live, unified view of every learning graph you have projected into ArcadeDB — all backpacks, all graphs, all nodes in one canvas. This is the cross-graph resolution layer: you can see connections that span graphs and backpacks that would be invisible inside any single graph.

To enable it:

# 1. Install the connector
npm install -g backpack-connector

# 2. Start ArcadeDB (Java 21 required)
cd ~/arcadedb-26.4.2
JAVA_OPTS="-Darcadedb.server.rootPassword=arcadedb" ./bin/server.sh

# 3. Project your graphs (run once; incremental on subsequent runs)
backpack-connector project --graph my-graph

# 4. Start the viewer — the Knowledge Graph section becomes active
npx backpack-viewer

When ArcadeDB is running and graphs have been projected, the Knowledge Graph entry at the top of the Graphs tab shows live node and graph counts. Click it to load the unified graph into the canvas.

Scope selector — if you have multiple backpacks projected, a scope pill appears: "All" loads every projected node across every backpack; picking a specific backpack name scopes the view to that backpack's slice. The scope is sticky and independent of the backpack picker.

Query panel — clicking the Knowledge Graph entry also opens the Graph Query panel (⚙ for settings, then execute Cypher directly against ArcadeDB). The panel shows a connection indicator and has query templates for common traversals.

The viewer connects to ArcadeDB using these environment variables (or their defaults):

Variable	Default
ARCADEDB_URL	http://localhost:2480
ARCADEDB_USERNAME	root
ARCADEDB_PASSWORD	arcadedb

See backpack-connector for the full connector documentation, ArcadeDB setup, and the unified MCP server that combines graph management with Cypher query tools.

Extensions

• Extension system — third-party extensions with sandboxed API (graph reads/writes, events, UI panels, network proxy)
• kb-local — local document storage mount for the KB panel
• share — graph sharing extension
• chat — chat extension

Versioning

• Branches and snapshots — the underlying storage is event-sourced; the viewer exposes branch switching and snapshot/rollback UI via the MCP tools.

How it works

The viewer reads learning graph data from the same local event log that the MCP server writes to. Changes appear automatically, no refresh needed.

backpack-ontology (MCP) ──writes──> ~/.local/share/backpack/graphs/<name>/
                                         │  branches/<branch>/events.jsonl
                                         │  branches/<branch>/snapshot.json
backpack-viewer ──reads──────────────────┘

Old-format graphs (pre-0.3.0) are migrated automatically on MCP startup — the viewer reads the new format on first launch after upgrade, no manual step.

Configuration

The viewer reads an optional config file for customizing keybindings and other settings. The config file follows the XDG Base Directory convention:

~/.config/backpack/viewer.json

Override with environment variables:

• $XDG_CONFIG_HOME/backpack/viewer.json
• $BACKPACK_DIR/config/viewer.json

Keybindings

Create ~/.config/backpack/viewer.json and override any binding. Unspecified keys keep their defaults.

{
  "keybindings": {
    "search": "s",
    "focus": "g",
    "panLeft": "a",
    "panDown": "s",
    "panUp": "w",
    "panRight": "d"
  }
}

Available actions

Action	Default	Description
search	/	Focus the search bar
searchAlt	ctrl+k	Focus the search bar (alternate)
undo	ctrl+z	Undo last edit
redo	ctrl+shift+z	Redo last edit
help	?	Toggle keyboard shortcuts help
escape	Escape	Exit focus mode or close panel
focus	f	Focus on selected nodes / exit focus
toggleEdges	e	Toggle edge visibility
center	c	Center view on the graph
nextNode	.	Cycle to next node in view
prevNode	,	Cycle to previous node in view
nextConnection	>	Cycle to next connection in info panel
prevConnection	<	Cycle to previous connection in info panel
historyBack	(	Go back in node inspection history
historyForward	)	Go forward in node inspection history
hopsIncrease	=	Increase hops in focus mode
hopsDecrease	-	Decrease hops in focus mode
panLeft	h	Pan camera left
panDown	j	Pan camera down
panUp	k	Pan camera up
panRight	l	Pan camera right
panFastLeft	H	Pan camera left (fast)
panFastRight	L	Pan camera right (fast)
zoomIn	K	Zoom in
zoomOut	J	Zoom out
spacingDecrease	[	Decrease node spacing
spacingIncrease	]	Increase node spacing
clusteringDecrease	{	Decrease type clustering
clusteringIncrease	}	Increase type clustering

Binding format

Bindings are strings with optional modifier prefixes separated by +:

• Single keys: "f", "/", "?", "Escape"
• With modifiers: "ctrl+z", "ctrl+shift+z", "alt+s"
• ctrl and cmd/meta are treated as equivalent (works on both Mac and Linux)

Network binding

The viewer binds to loopback only (127.0.0.1) by default — its API exposes read/write access to your learning graphs, so it must never be reachable from other machines on your network without explicit opt-in. To change the bind host or port, edit ~/.config/backpack/viewer.json:

{
  "server": {
    "host": "127.0.0.1",
    "port": 5173
  }
}

Setting host to anything other than 127.0.0.1, localhost, or ::1 prints a startup warning because the API becomes reachable from other machines on the network. Only do this for devcontainer / VM scenarios where you understand the trust boundary, and consider putting a reverse proxy with auth in front of it.

Environment variables override the config file:

• BACKPACK_VIEWER_HOST — bind host (use 0.0.0.0 for all interfaces)
• PORT — bind port

Reference

Variable	Effect
PORT	Override the default port (default: 5173 or server.port in config)
BACKPACK_VIEWER_HOST	Override the bind host (default: 127.0.0.1 or server.host in config)
XDG_CONFIG_HOME	Override config location (default: ~/.config)
XDG_DATA_HOME	Override data location (default: ~/.local/share)
BACKPACK_DIR	Override both config and data directories

Support

Questions, feedback, or partnership inquiries: support@backpackontology.com

Privacy

See the Privacy Policy. The viewer itself collects no data.

License

Licensed under the Apache License, Version 2.0.