demoforge

DemoForge

agent-demo is an installable macOS CLI for producing truthful, inspected product demos from an explicitly approved browser window.

The agent manually explores, rehearses, and operates the product with its browser tool. The CLI never executes a storyboard or drives the browser. It owns durable state, capture safety, semantic timing, non-destructive rendering, verification, inspection, comparison, and acceptance.

Requirements

• macOS 13 or newer with an interactive desktop
• Python 3.12+
• Screen Recording permission for the terminal or agent host
• ffmpeg, ffprobe, and agent-browser on PATH
• Swift 5.9+ to build the bundled ScreenCaptureKit helper

Install

From a release checkout or downloaded wheel:

uv tool install ./dist/agent_demo-0.1.0-py3-none-any.whl
agent-demo helper build
agent-demo doctor

doctor reports every failed check with an exact remediation. The helper source, license, and provenance are bundled in the wheel and build outside the repository.

Claude Code plugin and Codex skill

The repository is a self-contained Claude Code marketplace and plugin. Install it directly from GitHub:

/plugin marketplace add JoaquinCampo/demoforge
/plugin install demoforge@demoforge

The plugin contributes the canonical demoforge skill from skills/demoforge/. Install the executable once with uv tool install git+https://github.com/JoaquinCampo/demoforge.git, then run agent-demo helper build and agent-demo doctor.

For Codex, clone the repository and run the bundled local installer:

git clone https://github.com/JoaquinCampo/demoforge.git
cd demoforge
./scripts/install-codex.sh

The installer uses only files from the checkout: it installs the Python CLI with uv tool install, copies the canonical skill and Codex metadata into ${CODEX_HOME:-~/.codex}/skills/demoforge, and runs the environment doctor. Both integrations use the same skill source; .agents/skills/demoforge/SKILL.md is a compatibility symlink rather than a competing copy.

One guided workflow

agent-demo init "Northstar customer plan" \
  --url http://127.0.0.1:8765/ \
  --audience "Product and customer leaders" \
  --takeaway "Customer evidence becomes an owned, publishable plan" \
  --opening "The weekly command center highlights expansion risk" \
  --action "Open the highest-impact reporting insight" \
  --expected-result "Evidence and revenue impact are revealed" \
  --action "Add the insight to the action plan" \
  --expected-result "The insight becomes a Q3 commitment" \
  --action "Assign an owner and publish the plan" \
  --expected-result "The plan reaches full ownership and is published" \
  --closing "The leadership update is published with every priority owned"

agent-demo sample reset <run-id>
agent-demo sample serve <run-id> --port 8765  # keep this process running
agent-demo guide <run-id>

Follow the returned next command. During exploration and rehearsal, the agent uses its browser tool manually. Reset the deterministic fixture before the clean take.

agent-demo target list
agent-demo target preview <run-id> --target-id <window-id>
# Inspect the previewed title, application, bounds, and target ID.
agent-demo target approve <run-id>
agent-demo ready <run-id> \
  --starting-url http://127.0.0.1:8765/ \
  --viewport-width 1440 --viewport-height 900 --scale 1 \
  --checkpoint "The reporting insight shows evidence and ARR impact" \
  --checkpoint "The Q3 plan has four owners" \
  --checkpoint "The leadership update is published"
agent-demo capture start <run-id>

While manually operating the browser, append semantic events using the capture nonce:

agent-demo event add <run-id> --attempt-nonce <nonce> --at 1.2 \
  --kind action --label "Open feedback summary"
agent-demo event add <run-id> --attempt-nonce <nonce> --at 2.1 \
  --kind expected_result --label "Top theme is visible" --relates-to <event-id>
agent-demo capture stop <run-id>

Create a versioned edit plan, then run:

agent-demo render <run-id> --plan edit.json --candidate candidate-001
agent-demo inspect <run-id> --candidate candidate.mp4 --output inspection/
# Inspect contact-sheet.png, event evidence, scene frames, and framing diagnostics.
agent-demo verify <run-id> --candidate candidate.mp4 \
  --inspection inspection/index.json --review quality-review.json \
  --output verification.json

If verification finds a problem, preserve the failed candidate, make one evidence-based correction, and render again. Compare no more than three candidates:

agent-demo compare <run-id> --candidates candidates.json
agent-demo accept <run-id> --candidates candidates.json \
  --comparison comparison.json \
  --reproduction-command "agent-demo render <run-id> --plan edit.json"