hologram-gltf 0.6.0

Live observability, guided skills, and an agent (MCP) surface for Blender -> glTF asset pipelines.

◇ Hologram

Live observability, guided skills, and an agent (MCP) surface for Blender → glTF pipelines.

Part of akaOSS — https://www.akaoss.dev/projects/hologram

_{The live dashboard against examples/minimal — warm-paper light and warm-near-black dark, following your system theme. Screens: light · dark.}

Hologram watches a glTF asset pipeline and streams what's happening to a local dashboard in real time — including the tool calls your AI coding agent is making right now. It also exposes the pipeline to agents through a small MCP server, so Claude (or any MCP client) can enumerate, introspect, render, and health-check your exported .glb assets — and the Claude Code plugin wraps all of it in guided skills (/hologram:start, inspect, check, status, create-skill) so you can drive the pipeline in plain language.

It stays deliberately read-only / non-destructive: it observes, introspects, validates, and previews your pipeline — but it never modifies your assets, and the MCP server imports none of your project code. No framework, no build step, no database — a stdlib HTTP server, a JSONL event log, and pure-Python glTF parsing.

Why it's different: plenty of tools inspect a .glb. Hologram is the only one that puts a live feed of your agent's pipeline activity next to the assets it's producing, and hands that same pipeline to the agent as MCP tools — now including a render so the agent can see an export, not just count its nodes.

---

Why I built this

I build games with my friend, and the bulk of my asset work runs through Blender into glTF — characters, props, weapons, the lot. At some point my AI coding agent became a real part of that pipeline: it writes the Blender scripts, runs the exports, and rearranges the .glb files I ship. That was a huge speed-up, right up until I realised I had no real idea what it was doing. Assets changed, exports appeared, and I'd be scrolling back through a terminal trying to reconstruct which step touched which file.

Hologram is what I built to close that gap. It tails a single event log and shows the agent's live activity — edits, shell commands, exports — right next to the assets those actions produce, in one local dashboard. Then it hands the agent that same pipeline back as a few MCP tools, so we end up looking at the same picture instead of talking past each other.

It started life as pipeline-specific glue buried inside one game's repo. This is the clean-room version: none of that project's code and none of its assumptions — just the pattern, pulled out and made generic, in case it's useful to anyone else wiring an agent into a Blender → glTF workflow.

Features

• Live activity feed — a Server-Sent-Events dashboard that tails an append-only event log. Sessions, shell commands, file edits, MCP calls, and slash-command invocations stream in as they happen — failures and in-flight work included.
• Asset visualizer — browse exported GLBs grouped by category, click any one to introspect its glTF structure, and see an in-browser preview of the model.
• MCP tool surface — four read-only tools (list_assets, inspect_asset, tail_events, pipeline_status) plus one non-destructive render_asset give an agent structured access to your pipeline.
• Guided skills — the plugin bundles five Claude Code skills as a natural-language front door: /hologram:start (onboard + launch the dashboard), inspect, check, status, and create-skill (scaffold your own).
• Agent vision (render_asset) — render a GLB to an image through your live Blender, so the agent can see an export. Non-destructive (a throwaway scene, your scene restored) and degrades to a clear error when Blender isn't running.
• Read-only checks — hologram check runs assertions you author in .hologram/checks.py over each asset (naming, root count, whatever you like); findings show in the terminal and the dashboard. Checks can't modify anything and never run inside the MCP server.
• Regression diffing — each hologram check fingerprints every asset, so the dashboard and pipeline_status can answer "what changed since the last check" (materials/meshes/animations gained, lost, or changed).
• pipeline_status — one MCP read of "what's wrong right now": recent failures, the last check summary, and recent asset diffs, straight from the log.
• Pure-Python glTF introspection — nodes, hierarchy, animations, materials, skins, and meshes, parsed with pygltflib. No Blender required.
• hologram watch — a terminal companion that streams the same event log, no browser needed.
• Generic by config — a single hologram.toml describes your paths and an optional category taxonomy. Flat projects need no categories at all.
• Blender MCP awareness — the dashboard probes for a Blender MCP add-on (TCP :9876) and shows whether it's live; render_asset drives that add-on.
• Claude Code activity hook — a generic event-logging hook (ships as a plugin) feeds the dashboard with your agent's real activity.

Requirements

• uv — it fetches Hologram (and a matching Python 3.10+) on demand, so there's nothing to install or build. brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh.
• Claude Code — optional, but it's what the plugin (live activity feed + MCP tools) plugs into.
• Blender — optional. Needed for render_asset (and the live-status probe), via the Blender MCP add-on listening on :9876. Hologram itself never imports bpy — it drives Blender over a socket, so its import purity stays intact.

Run it

No install, no build step — uv fetches and runs Hologram on demand, then caches it. There are two entry points:

1 · The dashboard — point it at any project that has exported GLBs:

uvx --from git+https://github.com/akaieuan/Hologram hologram dashboard

It serves http://127.0.0.1:7870. (Once Hologram is on PyPI this shortens to uvx --from hologram-gltf hologram dashboard.)

2 · The Claude Code plugin — the live activity feed + MCP tools. Inside Claude Code:

/plugin marketplace add akaieuan/Hologram
/plugin install hologram

That wires up three things: the activity hook (your agent's edits, shell commands, and MCP calls stream into the dashboard), the MCP tools (four read-only plus a non-destructive render), and a set of guided skills (/hologram:start and friends). The MCP server runs through uvx too — installing the plugin needs no pip step.

Commands

Command	What it does
hologram dashboard	Run the live SSE dashboard (--host, --port, --project).
hologram watch	Stream the event log to the terminal — no browser (--limit, --interval, --no-color).
hologram check	Run read-only checks over the exported assets (--json, --init to scaffold).
hologram mcp	Run the MCP server over stdio (Claude Code launches this for you).
hologram init	Scaffold hologram.toml + .mcp.json in a project (--force).

Skills (Claude Code)

Bundled with the plugin — type /hologram: in Claude Code to reach them:

Skill	What it does
/hologram:start	Onboard: explain Hologram, init the project, launch the dashboard, hand off.
/hologram:inspect	Resolve an asset, read its structure, render a preview.
/hologram:check	Run the checks, read failures back plainly, help author new ones.
/hologram:status	"What's wrong right now" — a log-only catch-up via pipeline_status.
/hologram:create-skill	Scaffold a new project skill, pre-wired to Hologram's tools.

How it's delivered

Hologram is four pieces, and each reaches you without a manual install:

Piece	What it is	How it runs
Activity hook	a stdlib-only Claude Code hook logging sessions, shell commands, edits, and MCP calls	bundled in the plugin; runs on your system python3, zero dependencies
MCP server	four read-only tools + a non-destructive render over your GLBs	launched by uvx straight from this repo — Claude Code starts it per session
Skills	five guided Claude Code skills (start, inspect, check, status, create-skill)	bundled in the plugin; auto-discovered, no install
Dashboard	the live SSE web UI	a server you start with uvx hologram dashboard (from a clone or, once published, --from hologram-gltf)

uv downloads the code (and a matching Python) the first time and caches it, so there's no release to download and no environment to maintain. The marketplace install wires the hook, MCP tools, and skills in one step.

The dashboard is the one piece you launch yourself — by design. A Claude Code plugin contributes hooks, commands, and MCP servers, not long-running web servers, so the dashboard stays a uvx hologram dashboard you run in a terminal when you want eyes on the pipeline. Same UI, same command — only the delivery is install-free.

Prefer a classic install? From a clone, pip install -e . (or uv pip install -e .) still gives you a plain hologram command. And publishing to PyPI (uv build && uv publish) turns every uvx --from git+… hologram here into a tidy uvx hologram.

Try the bundled examples

Want to poke at it with real assets first? Clone the repo and run the dashboard against the example project — still no install:

git clone https://github.com/akaieuan/Hologram.git
cd Hologram
uvx --from . hologram dashboard --project examples/minimal

Open http://127.0.0.1:7870 — three sample assets grouped into lootables, weapons, and props. Click any asset to introspect its glTF structure and preview the model; switch to Debug for copy-pastable JSON state.

To watch the live feed move, append an event to the log:

echo '{"ts": '"$(date +%s)"', "type": "tool_use", "tool": "Bash", "command": "blender --background bake.blend"}' \
  >> examples/minimal/.hologram/events.jsonl

It shows up in the Live tab within a second.

Use it in your own project

From your pipeline's root:

uvx --from git+https://github.com/akaieuan/Hologram hologram init

That writes a hologram.toml (edit export_root to point at wherever your .glb files land) plus a .mcp.json. Then launch the dashboard the same way:

uvx --from git+https://github.com/akaieuan/Hologram hologram dashboard

To author your own validation rules, scaffold a checks file and edit it:

uvx --from git+https://github.com/akaieuan/Hologram hologram check --init

The MCP server

Installing the plugin wires the MCP server up for you — there's nothing else to do. If you'd rather register it by hand (no plugin), hologram init drops a .mcp.json that points Claude Code at the server through uvx:

{
  "mcpServers": {
    "hologram": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/akaieuan/Hologram", "hologram", "mcp"]
    }
  }
}

uvx fetches and caches the server on first use, so this needs no pip step. (Once Hologram is on PyPI the args shorten to just ["hologram", "mcp"].) Either way, an agent gets five tools:

Tool	What it does
list_assets(category?)	Enumerate exported GLBs, grouped by category.
inspect_asset(path)	Parse one GLB into the flat Asset struct (nodes, animations, materials, skins…).
render_asset(path)	Render a GLB to a PNG via the live Blender — see an export, not just its node counts. Non-destructive; returns a clear {error, hint} if Blender isn't reachable.
tail_events(limit?)	Read recent pipeline activity from the shared event log.
pipeline_status(limit?)	"What's wrong right now" — recent failures + the last check summary + recent asset diffs, from one read of the log.

The server imports no project code — it only reads files and your config (never .hologram/checks.py). render_asset drives a separate, running Blender over a socket, which isn't importing your code, so that purity holds.

Live agent activity (the plugin)

The dashboard's feed renders activity that something has to log. Hologram ships a generic Claude Code hook (under hologram/plugin/) that records session lifecycle, shell commands, edits to .glb / .gltf / .py / .toml files, and mcp__hologram* / mcp__blender* tool calls — then the dashboard streams them.

Installing the plugin wires the hook, the MCP server, and the skills in one step:

/plugin marketplace add akaieuan/Hologram
/plugin install hologram

Or, if you keep your own hook setup, copy hologram/plugin/hooks/log_event.py into it. The hook is stdlib-only and writes straight to your configured events_log.

Configuration

hologram.toml lives at your project root:

[project]
name = "my-project"

[paths]
export_root = "export/gltf"            # root for GLB discovery (required)
source_root = "blender/scripts"        # optional; links a script to its GLB
events_log  = ".hologram/events.jsonl" # optional; default shown

[dashboard]
host = "127.0.0.1"                      # optional
port = 7870                             # optional

# [categories] is OPTIONAL. Omit it entirely and every GLB under export_root
# becomes one flat "all" list. Otherwise each category is a glob:
[categories.props]
glb_pattern    = "props/**/*.glb"       # relative to export_root
script_pattern = "props/*.py"           # optional, relative to source_root

See examples/minimal/ (categorized) and examples/flat-layout/ (no categories) for both shapes running on the same dashboard.

Export manifest convention

Hologram works on nothing but your .glb files. But if your Blender pipeline also writes a small manifest next to its exports, Hologram reads it and the dashboard gets richer: each asset shows its version, generator, build params, triangle count, and thumbnail, plus a version-history flip-through that diffs any prior snapshot against the current export. This is entirely optional — no manifest means zero change, and nothing here is ever written by Hologram (the core stays read-only; the writer is a template you copy).

The convention is one exports/ tree (point export_root at it):

exports/
  manifest.json                 # index of every asset (see schema below)
  audit.jsonl                   # append-only ledger, one JSON object per line
  <category>/<id>.glb           # the current export
  .history/<id>/vN.glb          # prior versions (keep-N rotation)
  thumbnails/<id>.vN.png        # optional per-version thumbnail

manifest.json is {"assets": {<id>: <entry>}}, where each entry is:

{
  "id": "hero",
  "name": "Hero",
  "category": "characters",
  "glb": "characters/hero.glb",
  "thumbnail": "thumbnails/hero.v3.png",
  "version": 3,
  "params": { "height": 0.9, "rig": "biped" },
  "tris": 3000,
  "generator": "pipeline/characters/hero.py",
  "createdAt": "2026-07-04T12:01:26-04:00",
  "updatedAt": "2026-07-07T11:31:18-04:00",
  "status": "pending-review"
}

audit.jsonl records one line per export (ts, action, assetId, version, params, generator, tris, note, thumbnail) — extra keys (a review decision, an actor) are preserved as-is. .history/<id>/ keeps the most recent few versions so the dashboard can flip through them.

A copyable, documented writer for exactly this layout — atomic manifest upsert, audit append, keep-N history rotation, and a thumbnail render — ships as examples/export_helper.py. It imports bpy and is never imported by the Hologram package; paste it into your Blender pipeline and call export_asset(...). hologram init points you at it.

Once the manifest is in place, the dashboard's Assets view surfaces this metadata inline, and two read-only endpoints back it: GET /api/manifest (the whole sidecar) and GET /api/history?asset=<id>[&v=N] (snapshot introspection + a fingerprint diff against the current export, reusing the same diff machinery as hologram check).

How it works

your pipeline ──┐
Claude Code  ───┼──> .hologram/events.jsonl ──> dashboard (SSE live tail)
MCP server   ──┘                                    │
                                                    └─> /api/inspect ─> pygltflib
live Blender ──(socket :9876)── render_asset ─> PNG

• hologram/events.py — append-only JSONL log; the dashboard tails it by watching byte size and emitting each new line over SSE.
• hologram/gltf.py — the stable Asset public API (bpy-free).
• hologram/config.py — loads hologram.toml; categories are optional.
• hologram/checks.py — the read-only checks engine + per-asset diff baseline (refreshed only on hologram check, so reads stay pure).
• hologram/diff.py — asset fingerprint + diff ("what changed since last check").
• hologram/blender.py — stdlib socket client for the Blender MCP add-on (liveness probe + the non-destructive render).
• hologram/dashboard/ — stdlib ThreadingHTTPServer + SSE + vanilla JS.
• hologram/mcp/ — FastMCP server: four read-only tools + a non-destructive render.

Project layout

.claude-plugin/marketplace.json   # makes the repo installable via /plugin
hologram/
  gltf.py  events.py  config.py  cli.py
  checks.py  diff.py  blender.py  watch.py
  dashboard/   server.py + static/{index.html,app.js,style.css}
  mcp/         server.py (list_assets, inspect_asset, render_asset,
               tail_events, pipeline_status)
  plugin/      Claude Code hook + plugin manifest + .mcp.json (uvx)
    skills/    start · inspect · check · status · create-skill
examples/
  minimal/      categorized: export/gltf/{lootables,weapons,props}/*.glb
  flat-layout/  no categories: assets/*.glb
tests/          pytest suite

Roadmap

Hologram stays scoped to observe, introspect, validate, and preview — all read-only / non-destructive. Shipped so far: the live dashboard + MCP surface (v0.1), failures + GLB previews + hologram watch (v0.2), the read-only checks engine + asset visualizer (v0.3), agent vision + regression diffing + pipeline_status (v0.4), and guided skills as the plugin's front door (v0.5). Still on the table, built on the stable Asset API: an offline/headless render path (no running Blender), render thumbnails on disk, asset/scene templates, and export orchestration.

License

MIT