Understanding the Previews Folder in HKUDS/CLI-Anything Generated .sketch Files

The previews folder in CLI-Anything stores timestamped JSON descriptors and visual assets for every workflow step, enabling real-time monitoring, trajectory replay, and clean separation between command logic and UI rendering.

When HKUDS/CLI-Anything generates a .sketch file—the preview bundle that agents fetch—it creates a sibling previews directory within the workspace. This folder serves as the persistent storage layer for visual snapshots produced while CLI commands execute, bridging the gap between JSON-centric command logic and the visual feedback required for agent supervision. According to the README’s preview stack section (lines 995-1002), this architecture implements a three-part preview system comprising static previews, live previews, and trajectory history.

What the Previews Folder Contains

The previews directory functions as a chronological cache where each command execution generates discrete, timestamped artifacts. Every step in a workflow produces two distinct file types that collectively describe the system’s visual state at that moment.

JSON Preview Descriptors

For each command, CLI-Anything writes a JSON preview descriptor that records execution metadata and state references. These files follow a strict naming convention using Unix timestamps and command identifiers (e.g., 1708423912_render_scene.json). The descriptor contains the command name, UTC timestamp, serialized state snapshot, and relative paths to associated image assets, allowing agents to parse workflow history without parsing binary files.

Visual Asset Storage

Alongside each JSON descriptor, the harness persists actual renderings of the current state as PNG or SVG files. The JSON descriptor’s image field points to these binary assets, creating a loose coupling that allows agents to retrieve either lightweight metadata or full visuals independently based on bandwidth constraints or analytical requirements.

Core Functions of the Previews System

The previews folder implements the three-part preview system—static preview, live preview, and trajectory history—enabling sophisticated agent interactions with long-running CLI processes.

Live Preview Streaming

Agents or human operators can request real-time visual feedback via the preview sub-command. When executing cli-anything-blender preview latest, the REPL-skin queries the previews directory for the most recent JSON descriptor, locates the associated image asset, and streams it back to the requester. This mechanism allows headless agents to pull visual updates on-demand without blocking the command execution pipeline or requiring continuous polling of the main process.

Trajectory Reconstruction

By maintaining a chronological sequence of preview bundles, the harness supports full session replay through trajectory.json. Agents can analyze the complete history of state transitions, enabling reasoning about causality and previous actions. This historical context proves critical for autonomous systems making iterative refinements based on prior execution steps, as the agent can examine "what happened before" to inform current decisions.

Decoupling UI from Business Logic

The architectural separation between CLI command logic and visual representation allows the core system to remain pure—handling JSON output, undo/redo operations, and state management—while visual rendering occurs in parallel. Agents operating in headless environments can ignore the previews folder entirely, while GUI-dependent workflows can lazily load visual data only when needed. This separation prevents visual rendering overhead from interfering with the CLI’s core JSON-centric operations.

Implementation in utils/repl_skin.py

The actual serialization logic resides in utils/repl_skin.py, specifically within the write_preview function. This routine generates the directory structure, creates timestamped JSON descriptors, and copies image assets into the previews folder.

# Inside utils/repl_skin.py

def write_preview(command_name: str, state: dict, image_path: Path):
    """Create a preview bundle for the given command."""
    preview_id = f"{int(time.time())}_{command_name}"
    preview_dir = Path(".sketch") / "previews"
    preview_dir.mkdir(parents=True, exist_ok=True)

    # 1️⃣ JSON descriptor

    preview_meta = {
        "id": preview_id,
        "command": command_name,
        "timestamp": datetime.utcnow().isoformat(),
        "state_snapshot": state,
        "image": f"{preview_id}.png",
    }
    (preview_dir / f"{preview_id}.json").write_text(json.dumps(preview_meta, indent=2))

    # 2️⃣ Image asset (PNG, SVG, …)

    shutil.copy(image_path, preview_dir / f"{preview_id}.png")

The function constructs a unique preview_id combining Unix timestamps and command names, ensuring filesystem uniqueness while maintaining chronological sortability. It then persists both the structured metadata and the binary image asset to .sketch/previews/, creating the directory tree if absent.

Summary

• The previews folder stores timestamped JSON descriptors and associated image assets for every workflow step in CLI-Anything generated .sketch files.
• Located as a sibling to the .sketch file, this directory enables real-time preview streaming via the REPL-skin’s write_preview function in utils/repl_skin.py.
• The three-part preview system—detailed in README.md lines 995-1002—supports live monitoring, trajectory reconstruction, and clean separation between command logic and visual representation.
• Agents interact with this system through the preview sub-command, fetching the latest state without disrupting headless execution flows.

Frequently Asked Questions

What file types are stored in the CLI-Anything previews folder?

The directory contains JSON preview descriptors with metadata and state snapshots, alongside binary image assets typically formatted as PNG or SVG files. Each command execution generates a matching pair of files sharing a timestamp-based identifier.

How do agents access live previews during command execution?

Agents invoke the preview sub-command (e.g., cli-anything-blender preview latest) to retrieve the most recent snapshot. The CLI reads the newest JSON file from .sketch/previews/, extracts the image path reference, and streams the associated visual asset back to the requesting agent.

Why does CLI-Anything separate JSON metadata from image files?

This decoupling allows headless agents to parse lightweight JSON state information without downloading heavy image assets, while GUI agents can selectively fetch visuals. It also maintains clean architectural boundaries between the core CLI logic and presentation layers.

Can developers replay entire workflow sessions using the previews folder?

Yes. The chronological sequence of preview bundles enables full trajectory reconstruction through trajectory.json. By iterating through the timestamped entries in the previews directory, the system can replay the complete execution history, allowing agents to analyze prior states and decision points.

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