How Preview Bundles and trajectory.json Enable Live Preview for AI Agents in CLI‑Anything

CLI‑Anything uses immutable preview bundles combined with an append‑only trajectory.json log to create a stateless, queryable history of command‑to‑visual mappings that AI agents can consume without maintaining external state.

The HKUDS/CLI‑Anything framework solves the visibility problem for AI‑driven CLI workflows by implementing a durable live‑preview protocol. At the core of this system are two artifacts—preview bundles and the trajectory.json log—that allow agents to inspect intermediate results, rewind states, and make deterministic decisions without touching the underlying application directly.

The Preview Bundle: Immutable Command Snapshots

A preview bundle is a self‑contained directory that serves as an immutable snapshot of a single preview run. According to docs/PREVIEW_PROTOCOL.md lines 90‑103, each bundle contains:

• manifest.json – Machine‑readable metadata describing the bundle schema, software version, and file inventory.
• summary.json – Human‑readable and LLM‑friendly condensed results (render times, scene statistics, error flags).
• Asset files – Actual preview content such as PNG frames, MP4 clips, or JSON dumps generated by the command.

The canonical helper that creates these bundles is implemented in cli-anything-plugin/preview_bundle.py. Harness‑specific wrappers (e.g., in blender/agent-harness/cli_anything/blender/utils/preview_bundle.py) import this helper to ensure uniform layout across Blender, FreeCAD, Shotcut, RenderDoc, and other supported tools.

Because bundles are immutable once written, agents can cache them indefinitely and reference consistent artifact sets even if the live session advances.

trajectory.json: The Append‑Only Replay Log

While bundles store the what, trajectory.json stores the when and why. This file lives next to the live‑session directory and functions as an append‑only journal. As specified in docs/PREVIEW_PROTOCOL.md lines 30‑43 and 48‑57, every entry appended to the log records:

• step_id – Unique identifier for the step (e.g., step-0003).
• command – The full CLI invocation that generated the preview.
• bundle_id and bundle_dir – Pointers to the immutable bundle created by this step.
• publish_reason – Trigger metadata (e.g., live‑push, capture).
• Timestamps – ISO‑8601 timestamps for deterministic ordering.

The append‑only design means agents can safely cache the file and stream only new suffixes for low‑latency updates, or replay the entire session later without risk of mutation.

How Live Preview Works: The Agent Workflow

Starting a Live Session

When an agent or user executes cli‑anything‑<software> preview live start, the system initializes a fresh session directory containing two critical files:

• session.json – The mutable head that tracks current_bundle_id and active configuration.
• trajectory.json – An empty append‑only log ready for the first step.

This initialization logic is documented in docs/PREVIEW_PROTOCOL.md lines 67‑76.

Publishing Preview Bundles

Each time the agent triggers preview live push (or when preview capture automatically pushes), three operations occur atomically:

1. A new preview bundle is generated in the standardized layout.
2. manifest.json and summary.json are written to the bundle directory.
3. A step object is appended to trajectory.json linking the command to the new bundle location.

This flow ensures that trajectory.json remains the canonical replay log while the heavy‑weight rendering stays isolated in the immutable bundle.

Querying Session State

Agents inspect the live session using the generic viewer:

cli-hub previews live status /tmp/preview-session --json

The JSON payload returned (as defined in docs/PREVIEW_PROTOCOL.md lines 49‑61) contains:

• _session_dir – Absolute path to the session root.
• _trajectory_path – Relative path to the trajectory log.
• current_bundle_id – Identifier of the latest bundle.
• trajectory_summary – Array of the most recent steps without downloading the full log.

Because the response includes both the current head and the trajectory path, agents can decide “Has the state changed since I last checked?” with a single read operation.

Architectural Benefits for AI Agents

The combination of immutable bundles and append‑only logs provides four concrete advantages for autonomous agents:

• Stateless querying – Agents read session.json for the current head and trajectory.json for history. No external database or stateful connection to the target software is required.

• Deterministic replay – The full trajectory.json preserves every command‑to‑preview mapping, enabling agents to reconstruct any intermediate state idempotently.

• Uniform contract – Both artifacts follow the same JSON schema across all harnesses (Blender, FreeCAD, Shotcut, etc.), allowing a single agent implementation to operate any CLI‑Anything compatible tool.

• Cheap incremental updates – When monitoring a live session, agents only fetch the new tail of trajectory.json rather than re‑processing the entire history or re‑downloading unchanged bundles.

Practical Implementation

1. Start a Live Preview Session

cli-anything-blender preview live start \
    --recipe quick \
    --root-dir /tmp/preview-session

Resulting session.json:

{
  "protocol_version": "preview-live/v1",
  "software": "blender",
  "recipe": "quick",
  "status": "active",
  "current_bundle_id": "20260423T101007Z_deadbeef_quick",
  "trajectory_path": "trajectory.json"
}

2. Push a New Preview Bundle

cli-anything-blender preview live push \
    --recipe quick \
    --output-dir /tmp/preview-session

trajectory.json after the push (simplified):

{
  "protocol_version": "preview-trajectory/v1",
  "software": "blender",
  "recipe": "quick",
  "session_name": "blender-quick-20260423",
  "step_count": 3,
  "steps": [
    {
      "step_id": "step-0003",
      "command": "cli-anything-blender preview live push ...",
      "bundle_id": "20260423T101007Z_deadbeef_quick",
      "bundle_dir": "/tmp/preview-session/20260423T101007Z_deadbeef_quick",
      "manifest_path": ".../manifest.json",
      "summary_path": ".../summary.json",
      "publish_reason": "live-push"
    }
  ]
}

3. Agent‑Side Status Query

cli-hub previews live status \
    /tmp/preview-session \
    --json

Returned snippet processed by cli-hub/cli_hub/preview.py:

{
  "_session_dir": "/tmp/preview-session",
  "_trajectory_path": "trajectory.json",
  "current_bundle_id": "20260423T101007Z_deadbeef_quick",
  "trajectory_summary": [
    {"step_id":"step-0003","publish_reason":"live-push","status":"ok"}
  ]
}

An AI agent can now determine that the latest preview succeeded and suppress redundant re‑renders.

Summary

• Preview bundles are immutable directories containing manifest.json, summary.json, and rendered assets that capture a single command’s output.
• trajectory.json is an append‑only log that records the chronological link between CLI commands and their resulting bundles.
• Together they enable stateless, deterministic live preview where agents query session.json for the current state and trajectory.json for historical context.
• The protocol is implemented in cli-anything-plugin/preview_bundle.py and consumed by cli-hub/cli_hub/preview.py, providing a cross‑harness contract for Blender, FreeCAD, and other supported tools.

Frequently Asked Questions

What is the difference between session.json and trajectory.json?

session.json acts as the mutable head of a live session, tracking the current active bundle and configuration. trajectory.json is the append‑only archive that preserves every step taken during the session, creating a permanent audit trail that agents can replay or cache without locking the current state.

How does the append‑only nature of trajectory.json benefit AI agents?

Because old entries are never mutated, agents can safely cache the file locally and only fetch new suffixes when polling for updates. This reduces bandwidth and eliminates race conditions when multiple agents or UI components monitor the same live session simultaneously.

Can agents use this protocol with any software harness?

Yes. The bundle and trajectory schemas defined in docs/PREVIEW_PROTOCOL.md are harness‑agnostic. Whether the backend is Blender, FreeCAD, Shotcut, or RenderDoc, the same cli-hub viewer and agent logic applies because preview_bundle.py enforces a uniform directory layout and JSON schema across all implementations.

How does cli-hub render previews without software‑specific code?

cli-hub reads the standardized manifest.json and summary.json inside each preview bundle. These files describe the content type (image, video, JSON) and metadata generically, allowing the viewer to render thumbnails and summaries without installing Blender or other heavy dependencies.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}