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

> Discover the purpose of the previews folder in HKUDS/CLI-Anything generated .sketch files. Learn how it aids real-time monitoring and replay of workflow steps.

- Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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.

```python

# 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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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.