ACE - Demo

Record terminal sessions as proof-of-work evidence for pull requests. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates

ace-demo demo

ace-demo records terminal sessions as proof-of-work evidence for agent-driven workflows. Tapes define what to capture — either as simple VHS scripts (.tape) or as YAML specs (.tape.yml) with sandbox setup, scenes, and teardown.

Recordings attach directly to GitHub pull requests as reviewable evidence. Requires vhs, chromium, and ttyd for deterministic rendering (see setup requirements).

How It Works

  1. Define a tape — inline commands, a VHS .tape script, or a .tape.yml with sandbox setup, recording scenes, and teardown cleanup.
  2. Record — ace-demo compiles the tape to VHS, executes in an isolated sandbox, and produces a GIF, MP4, or WebM artifact.
  3. Deliver evidence — attach the recording to a GitHub pull request with --pr, where it serves as proof-of-work for code review or assignment verification.

Tape Format

A .tape.yml file defines a self-contained recording scenario:

setup:
- sandbox            # create isolated working directory
- git-init           # initialize a git repo in the sandbox
- copy-fixtures      # copy fixture files from adjacent fixtures/ dir

scenes:
- name: Main flow
  commands:
  - type: ace-demo list
    sleep: 4s
  - type: ace-demo record hello
    sleep: 6s

teardown:
- cleanup            # remove sandbox directory
  • setup — sandbox isolation, git init, fixture copying, or arbitrary shell via run: <cmd>
  • scenes — named command sequences compiled to VHS directives (Type, Enter, Sleep)
  • teardown — cleanup directives that always run (even on failure)
  • settings — optional font_size, width, height, format overrides

Legacy .tape files use raw VHS syntax directly. See the Usage Guide for the full tape specification.

Use Cases

Deliver proof-of-work for agent tasks — pair with ace-assign for scoped task workflows that require demo evidence, using ace-bundle for loading workflow context that drives repeatable demo scenarios.

Attach visual evidence to pull requests — record a tape with ace-demo record --pr or attach an existing file with ace-demo attach so reviewers see actual terminal output. Use /as-demo-record for agent-driven recording sessions.

Future: web interaction recording is planned alongside terminal capture.

Testing Contract

Run deterministic package coverage with:

ace-test ace-demo
ace-test ace-demo all

Run deterministic feature coverage only when test/feat/ exists:

ace-test ace-demo feat

Run retained workflow scenarios in E2E:

ace-test-e2e ace-demo

Getting Started | Usage Guide | Handbook - Skills, Agents, Templates | Part of ACE