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 document sources (extensions can register additional providers)
• Document list — browse, search, and manage documents with a three-dot context menu
• Markdown rendering — documents render with tables, code blocks, and task lists

Local-only as of 1.0.0

The OSS viewer is local-only. Cloud sync, the cloud picker, the share extension, and the auto-sync daemon were removed. For cross-device personal sync, point BACKPACK_DIR at a synced folder (Google Drive desktop, iCloud, Dropbox). For collaboration and cross-user access, use BackpackApp directly. Use backpack_move_to_cloud and backpack_export_from_cloud MCP tools (in backpack-ontology) to migrate individual graphs between OSS-local and BackpackApp one-shot.

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
• 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: [email protected]

Privacy

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

License

Licensed under the Apache License, Version 2.0.