ToDo-Overlay

A sleek, local, account-free stream goal and todo overlay for OBS Studio and Streamlabs.

ToDo-Overlay runs a lightweight local loopback server on your machine, opens an interactive editor in your browser, and pushes live updates to your OBS Browser Source in real-time over WebSockets.

⚡ Quick Start (No Install Needed)

Run it directly with npx:

npx todo-overlay

This immediately boots your local overlay server, opens the editor in your browser, and provides your OBS Browser Source link.

📦 Install Globally via NPM

If you prefer to have the command available globally anytime:

# Install globally
npm install -g todo-overlay

# Run anytime
todo-overlay

🎮 CLI Usage & Options

# Start on the default port (45873) and open browser automatically
npx todo-overlay

# Start on a custom port
npx todo-overlay --port 43200

# Start without automatically opening your browser
npx todo-overlay --no-open

# View all options
npx todo-overlay --help

CLI Flags

| Flag | Description | Default | | :--- | :--- | :--- | | --port <number> | Specify the loopback port to bind to | 45873 | | --no-open | Start server without auto-opening the browser | false | | --help | Show command-line help and usage | — |

🎥 OBS Studio & Streamlabs Setup

1. Launch ToDo-Overlay using npx todo-overlay.
2. In OBS Studio or Streamlabs, add a new Browser Source to your scene.
3. Set the URL to:

   http://127.0.0.1:45873/overlay

4. Set your desired dimensions (e.g., Width: 520, Height: 400).
5. (Optional) Check "Shutdown source when not visible" and "Refresh browser when scene becomes active".
6. That's it! As you add, edit, reorder, check off, or re-theme your goals in the editor, your OBS overlay updates instantly with smooth animations.

✨ Features

• ⚡ Instant Real-Time Sync: Low-latency local WebSocket communication between editor and overlay.
• 🎯 Discord-Style Hold-and-Drag: Smooth task reordering with live insertion indicators.
• 🎨 Deep Customization:
  • Custom Card, Text, and Accent colors
  • Glassmorphism backdrop blur & opacity controls
  • Corner roundness, card padding, and item spacing sliders
  • Typography options: Inter, Plus Jakarta Sans, JetBrains Mono, and Classic Serif
  • Display options: Progress bar, fraction counter, density modes (Comfortable / Compact), and completion styles (Strike-through, Tick only, Dimmed)
• 🔒 100% Private & Local:
  • Binds strictly to 127.0.0.1 (loopback only).
  • Zero cloud dependencies, zero telemetry, zero accounts or logins required.

💾 Local State Persistence

Your goals, progress, and custom theme are stored locally as atomic JSON:

• Windows: %LOCALAPPDATA%/todo-overlay/state.json
• macOS: ~/Library/Application Support/todo-overlay/state.json
• Linux: $XDG_DATA_HOME/todo-overlay/state.json or ~/.local/share/todo-overlay/state.json

🛠️ Local Development

To contribute or run from source:

# Clone the repository
git clone https://github.com/raktim-yoddha/todo-overlay.git
cd todo-overlay

# Install dependencies
npm install

# Run the frontend dev server
npm run dev

# Run the test suite
npm test

# Typecheck and lint
npm run typecheck
npm run lint

# Build full project (Web UI + CLI bundle)
npm run build

# Test the local production bundle
npm start

📄 License

MIT © Raktim