Overlays
How to add Dirework overlays to OBS
Dirework provides two overlays that you add as browser sources in OBS (or any streaming software that supports them).
Overlay URLs
After signing in, go to your Dashboard. In the Overlay URLs card you'll find two URLs:
- Timer Overlay —
/overlay/t/{token} - Task List Overlay —
/overlay/l/{token}
Each overlay has its own private URL. Use the copy button next to each one to grab the full overlay URL.
Keep your overlay tokens private. Anyone with the URL can view your overlay. If a token is compromised, click the regenerate button to create a new one.
Adding to OBS
- In OBS, click the + button under Sources
- Select Browser
- Name it (e.g. "Dirework Timer" or "Dirework Tasks")
- Paste the full overlay URL (e.g.
http://localhost:3001/overlay/t/YOUR_TOKEN) - Set the dimensions:
- Timer: 320 x 320 (the timer scales to fill the browser source, so any size works)
- Task List: 360 x 720
- Check "Shutdown source when not visible" (recommended — the source reloads cleanly when you switch scenes)
- Click OK
Timer overlay
The timer overlay shows:
- Current phase label (defaults are wolf-themed and editable in Theme Center — e.g. "Gathering the Pack", "On the Hunt", "Den Rest", "Pack Slumber", "Paws'd", "Hunt Complete")
- Countdown timer with configurable font
- Cycle count (e.g. 1/4)
- Progress ring (circle or rounded rectangle shape)
While the timer is idle, the overlay shows a full preview — the configured work length plus a full progress ring — rather than appearing blank, so you can position it during setup.
The timer automatically transitions through phases: Starting (5s countdown) → Focus → Break → Focus → … with a Long Break replacing the regular Break every few cycles (4 by default), ending in Done after the final Focus. The timer moves forward whenever something is watching it: an open timer overlay in OBS checks in every few seconds and advances the timer on its own — no dashboard tab needs to stay open. The dashboard or an incoming chat command will nudge it forward too.
Progress ring shapes
The timer supports two progress ring shapes:
- Circle — Standard circular ring using SVG
<circle> - Rounded Rectangle (Squircle) — macOS-style rounded corners, drawn as an SVG
<path>. The corner radius comes from the Background border radius setting (default 22%), which is shared with the container — there is no separate ring radius. Set that value to50%to switch the ring to a full circle instead.
Task list overlay
The task list overlay shows:
- Header with "Tasks" title and completion count
- Tasks grouped by author — each author gets a styled card with a tinted header row showing their name and done/total count
- Individual tasks render inside their author's group container
- Checkboxes (or bullets) for task status
- Completed tasks with strikethrough text
When scroll is enabled, the task list loops in a smooth, continuous scroll so every task gets screen time. You can turn scroll off in the Theme Center to show a fixed list instead.
Dashboard preview
The dashboard includes live preview iframes for both overlays. Use the Preview toggle button on each card to show or hide the preview. Previews are hidden by default to keep the page fast.
Customization with Theme Center
Both overlays are fully customizable through the Theme Center at /dashboard/styles. This is a visual editor with a live preview panel.
Timer overlay settings
| Category | Options |
|---|---|
| Dimensions | Width, height |
| Background | Color, opacity, border radius |
| Progress Ring | Enabled/disabled, track color, fill color, track/fill opacity, width, gap |
| Text | Color, outline color, outline size, font family |
| Font Sizes | Phase label, countdown time, cycle count |
| Labels | Custom text for each of the seven phases — Idle, Starting, Focus, Break, Long break, Paused, Done. Defaults are wolf-themed: "Resting", "Gathering the Pack", "On the Hunt", "Den Rest", "Pack Slumber", "Paws'd", "Hunt Complete". |
The progress ring has no dedicated shape control — its shape follows the Background border radius. Set the border radius to
50%for a circle; any other value (e.g.22%) renders a rounded rectangle (squircle).
Task list overlay settings
| Category | Options |
|---|---|
| Display | Show completed tasks, show count, use checkboxes, strikethrough on done, number of visible lines |
| Fonts | Header font, body font |
| Scroll | Enabled/disabled toggle, pixels per second, gap between scroll loops |
| Header | Height, background color/opacity, border color/width/radius, font size, font color, padding |
| Body | Background color/opacity, border color/width/radius, padding |
| Task Items | Background color/opacity, border, font size, font color, username color, padding, margin, max width |
| Done State | Background color/opacity, font color |
| Checkboxes | Size, background, border, margin, tick character, tick size, tick color |
| Bullets | Character, size, color, margin |
Theme presets
The Theme Center includes 6 built-in presets to get you started:
- Default — Clean dark style
- Ocean Depths — Deep blue aquatic
- Liquid Glass Dark — Translucent dark glass
- Cozy Cottage — Warm earth tones
- Minimal Light — Clean white minimal
- Twitch Purple — Twitch brand colors
Apply a preset as a starting point, then customize individual settings to match your stream.
Transparent background
The overlays render with a transparent background by default. In OBS, the browser source will show only the timer or task list widget without any background, making it easy to layer over your stream.
How updates work
Both overlays check for changes every few seconds. When you start the timer, add a task, or make any change on the dashboard, the overlay picks it up within a few seconds.
The timer countdown itself doesn't wait for those checks — it ticks down smoothly on the overlay, computed from the timer's end time. Your viewers never see a stuttering clock.