⚡ cue-type

Live teleprompter for recording flawless product demos, AI agent sessions, and technical screencasts.

Reads step-by-step scripts (cue.json) and types text character-by-character with human cadence into real terminals, code editors, and desktop applications, advancing on demand via global hotkey (F9) without blind timeouts (Sleep 60s).

---

📑 Table of Contents

• 🎯 Why cue-type?
• ✨ Key Features
• 🚀 Quick Start
• 🎬 Recording Workflow with OBS / ShareX
• 🛠️ Script Format (cue.json)
• 🛡️ Security, Antivirus, and UIPI
• 🔒 Script Privacy
• 💻 Development & Building
• 🤝 Contributing
• 📄 License

---

🎯 Why cue-type?

Traditional terminal demo automation tools (like VHS .tape scripts) generate synthetic videos in headless containers and rely on rigid wait times (Sleep 10s, Sleep 60s). If an AI agent (Claude Code, OpenCode, Aider, or an MCP tool), compiler, or network request takes 5 seconds longer or finishes early, your demo breaks or dead air ruins the screencast.

cue-type is not a video renderer—it is your live recording prompter. It pairs seamlessly with your real recording tools (OBS Studio, ShareX, ScreenToGif, Loom, Camtasia) by putting you in total control of live input:

• Human-driven pacing: You decide when to trigger the next command or text block by pressing F9 (or clicking in the UI) once the previous task or output finishes.
• Universal target support: Types into any focused window—not just terminals (PowerShell, Windows Terminal, CMD, Git Bash), but also code editors (VS Code), browser inputs/forms, REPLs, and desktop GUI applications.
• Natural typing animation: Character-by-character injection with configurable base speed (10–120ms) and random jitter, perfectly simulating a human developer typing live.
• Mid-typing abort (Esc): If you notice an unexpected state or need to pause, pressing Esc immediately aborts typing before executing the command.
• OBS Canvas-agnostic: The control window sits comfortably on a secondary monitor or outside the capture area while injecting cleanly into your focused window.

---

✨ Key Features

• ⚡ Zero-Install Standalone Binary: Precompiled as a single standalone executable (cue-type-portable-x64.exe) with native WebView2 integration.
• 🎯 Target Auto-Detection: Interactively picks and blinks target windows matching your criteria (Windows Terminal, PowerShell, VS Code, Browser, CMD, etc.).
• 🎙️ Live Recording Companion: Purpose-built to work alongside OBS, ShareX, ScreenToGif, or Loom—your final recording stays clean and free of prompter clutter.
• ⌨️ Safe Win32 Input Simulation: Powered by RegisterHotKey and SendInput without low-level hooks (SetWindowsHookEx) to avoid antivirus heuristic triggers.
• 🛡️ UIPI Awareness: Detects elevation mismatches (e.g. standard app vs. Administrator terminal) and alerts you before keystrokes are rejected.
• 📋 Automatic Clipboard Fallback: Automatically falls back to Ctrl+V pasting if character injection encounters complex Unicode strings.

---

🚀 Quick Start

1. Download cue-type-portable-x64.exe from Releases.
2. Open your target application (Windows Terminal, PowerShell 7, VS Code, Browser, or CMD).
3. Launch cue-type-portable-x64.exe.
4. Select your target window in the [Detect ▼] dropdown and click ⚡ Test to verify focus.
5. Focus your target window and press F9 to inject and run commands step by step!

---

🎬 Recording Workflow with OBS / ShareX

flowchart LR
    A[OBS / ShareX / Loom Capture Area] -->|Records Clean Window| B(Terminal / VS Code / App Window)
    C[Secondary Monitor / Off-Canvas] -->|Runs| D(cue-type Live Prompter)
    D -.->|Global F9 Hotkey| B

Loading

1. Configure Capture:
   • In OBS Studio (or ShareX, ScreenToGif, Loom), add a Window Capture or Crop Source targeting only your terminal, code editor, or app window.
2. Position cue-type:
   • Move the cue-type window to your secondary screen or outside the recorded area.
3. Trigger:
   • Focus your recorded window.
   • Press F9: cue-type receives the global shortcut in the background, animates keystrokes live on camera, and executes the completion action (e.g. ENTER).
   • Your recording captures natural, error-free typing without showing the prompter window or risking typos in live presentations.

---

🛠️ Script Format (cue.json)

Scripts are simple, human-readable JSON files:

{
  "target": {
    "windowTitleRegex": "pwsh|Windows Terminal|opencode",
    "mode": "any-console"
  },
  "defaults": {
    "typingSpeedMs": 35,
    "jitterMs": 25
  },
  "steps": [
    {
      "id": 1,
      "text": "cargo run --release",
      "actionAfter": "ENTER"
    },
    {
      "id": 2,
      "text": "curl http://localhost:8080/health",
      "actionAfter": "ENTER"
    }
  ]
}

⚙️ Parameter Reference (Click to expand)

Field	Type	Default	Description
target.windowTitleRegex	string	".*"	Regex pattern matching the title of the target application window.
target.mode	string	"any-console"	Target mode filter ("any-console", "exact-hwnd").
defaults.typingSpeedMs	number	35	Base delay in milliseconds between keystrokes.
defaults.jitterMs	number	25	Random variance added/subtracted to base delay for natural cadence.
steps[].text	string	(required)	Text to type into the target console.
steps[].actionAfter	string	"ENTER"	Action upon completing typing ("ENTER", "NONE").

---

🛡️ Security, Antivirus, and UIPI

1. Windows SmartScreen

Unsigned open-source binaries may trigger the standard "Windows protected your PC" message. Click "More info" and "Run anyway". The entire source code is auditable in this repository.

2. Antivirus Heuristics

• cue-type uses standard RegisterHotKey Win32 APIs instead of intrusive low-level keyboard hooks (SetWindowsHookEx), avoiding keylogger flags.
• Binaries are distributed cleanly without UPX compression or packers.

3. User Interface Privilege Isolation (UIPI)

If your terminal runs As Administrator and cue-type runs as a standard user, Windows security blocks keystroke injection. cue-type detects this condition automatically and warns you to run cue-type with matching Administrator permissions.

---

🔒 Script Privacy

Your demo scripts remain 100% private and local:

• Save your custom scripts in cues/ or anywhere on your filesystem.
• Git ignores *.cue.json automatically (except sanitized public samples in examples/).

---

💻 Development & Building

The repository includes a Windows-ready Makefile:

# View all available make targets
make

# Start live development environment (Vite + Tauri)
make dev

# Build standalone portable binary (dist-portable/cue-type-portable-x64.exe)
make build

# Run unit tests
make test

# Type-check TypeScript and check Rust syntax
make check

# Clean build artifacts
make clean

---

🤝 Contributing

Contributions are warmly welcome! Please read our Contributing Guide and Code of Conduct before submitting Pull Requests.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.