Skip to content

demo.md

Latest commit

 

History

History
83 lines (59 loc) · 2.78 KB

demo.md

File metadata and controls

83 lines (59 loc) · 2.78 KB
Raw

Demo Guide

This guide is for short terminal recordings and quick live walkthroughs.

Best Demo Scenario

Use Security Gate Deny.

Why this scenario works best:

  • It is the default startup scenario.
  • It shows a realistic preToolUse event.
  • The payload contains an obviously destructive shell command string that is easy to explain.
  • Dry-run mode stays safe for recordings and walkthroughs.
  • Local execution returns a clear deny decision from a harmless fixture script.

Demo Setup

Requirements:

  • Node.js 20 or newer
  • A terminal that can show at least 140 columns by 40 rows

Start the demo:

npm install
npm run dev

Optional CLI checks before recording:

npm run dev -- --help
npm run start -- export --scenario security-gate-deny --out ./tracegate-export.json

On launch you should see:

  • Config: Security Gate
  • Event: Pre Tool Use Dangerous Command
  • Mode badge: DRY-RUN
  • Scenario description: Shows a dangerous preToolUse payload flowing into a deny decision.

Suggested Demo Flow

  1. Start in dry-run mode and explain that nothing executes yet.
  2. Move to the payload pane and show the raw event fixture.
  3. Point out the dangerous command string inside toolArgs.
  4. Move to the execution pane and show the planned hook command.
  5. Explain that Tracegate has already validated the config and normalized the payload.
  6. Press m to switch to local execution.
  7. Show the parsed DENY decision and the returned reason.
  8. Press ? if you want to briefly show the built-in keyboard help.
  9. Return to the default scenario before ending the recording.

If you want a shareable artifact after the recording, export the same scenario from the built CLI:

npm run start -- export --scenario security-gate-deny --out ./tracegate-export.json

Terminal Recording Checklist

  • Use a wide terminal. The three-pane layout reads best at roughly 140x40 or wider.
  • Start from a clean npm run dev launch.
  • Do not resize the terminal during the recording.
  • Move slowly enough for pane changes and status messages to settle.
  • Use the default scenario unless you have a specific reason to branch into another one.
  • If you show local execution, explain that it is opt-in and unsandboxed.
  • If you need a short second clip, use Invalid Config rather than a more complex scenario.

Backup Scenarios

  • Invalid Config: best for showing schema validation and error messaging.
  • Logging Post Tool: best for showing a clean non-decision trace.
  • Malformed Output: best for showing parse warnings without a crash.

Recovery Notes

  • If local execution is unavailable, make sure a valid config and event are selected.
  • If the panes look crowded, restart with a wider terminal.
  • If you want to reset to the default path, quit with q and relaunch with npm run dev.