Skip to content

About

Live, repo-aware OBS overlays for coding streams: what you're building, progress and test status. npx code-stream-overlay

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

code-stream-overlay

Live, repo-aware overlays for OBS and other streaming software. Run it inside any git repository and add the printed URLs as browser sources. Viewers see what you're building, how far along it is, whether tests pass, and what your coding agent is doing.

  • One command, zero config: npx code-stream-overlay
  • Adds no files to your tracked tree; everything lives in .git/code-stream-overlay/
  • Every widget works as its own OBS browser source, plus one composed layout

Requires Node.js 22+ and git on your PATH.

Composed layout over a code editor

Quick start

cd your-repo
npx code-stream-overlay
code-stream-overlay · my-repo · maven (passive)
  Layout   http://127.0.0.1:4747/
  Widgets  http://127.0.0.1:4747/w/<now|timer|git|tests|goals|commits|file|agent|custom>
  Control  http://127.0.0.1:4747/control

code-stream-overlay init walks you through the options: test trigger mode, goals, Claude Code hooks and OBS sources. init --yes accepts the defaults.

Commands

Command What it does
code-stream-overlay / start Start the overlay server for this repo
init [--yes] Setup wizard; writes .git/code-stream-overlay/config.json (or the shared code-stream-overlay.json)
pause · resume · next · stop Control the running session; stop ends it and saves the summary
test Trigger a test run
summary [--json] Current session, or the last saved one
hooks install · hooks uninstall Claude Code hooks
obs install · obs uninstall OBS browser sources
uninstall [--purge] Remove hooks and OBS sources; --purge also deletes .git/code-stream-overlay/

Global flags: --port, --host, --config <path>, --theme, --tone, --tests-mode, --no-open, --verbose, --trust-repo-config.

Ending a session (with stop, Ctrl+C or SIGTERM) prints a Markdown summary covering time, phases, lines changed, commits, test runs, goals and agent activity. The JSON version is saved in .git/code-stream-overlay/sessions/.

The control page (/control) has Pause / Resume / Next phase / Run tests / End session buttons. Add it to OBS as a custom browser dock.

Control dock

Session timer

The timer widget counts down the current phase. Presets (session.preset):

Preset Phases
90min Scope 10 · Build 60 · README 15 · Ship 5
pomodoro 4 × (Focus 25 · Break 5)
freeform no phases, stopwatch

Past the last phase the timer counts up in overtime. Custom phases: { "session": { "phases": [{ "name": "Build", "minutes": 45 }] } }.

Repo awareness

  • now: title (config title, else the GOALS.md heading, else the branch, else the repo name), subtitle and detected stack.
  • git: branch, lines added and removed, and files changed since the session started. Commits, staged, unstaged and untracked changes all count, so committing never resets the numbers.
  • file: the file you're editing and how long ago.

Privacy

Everything shown on stream passes through one filter. Files that match privacy.ignore (default .env*, **/secrets/**, *.pem, *.key, id_*) show as "a hidden file", and their contents are never read. privacy.redactPaths: true shows basenames only, and privacy.hideFileNames: true hides every name. Commands and messages are scrubbed of passwords, tokens, SECRET=-style assignments, Authorization: headers and long key-like strings.

Tests

Tests are detected from your repo. The first match wins unless tests.adapter pins one ("off" disables tests).

Stack Detected by Command Default mode
maven pom.xml ./mvnw -q test or mvn -q test passive
gradle build.gradle(.kts), settings.gradle(.kts) ./gradlew test or gradle test passive
node package.json with a test script npm test (pnpm / yarn / bun by lockfile) save
python pyproject.toml, pytest.ini, setup.cfg, tox.ini pytest -q --junitxml=.git/code-stream-overlay/pytest.xml save
go go.mod go test -json ./... save
rust Cargo.toml cargo nextest run if installed, else cargo test save
dotnet *.sln, *.csproj, *.fsproj dotnet test --logger trx … commit
make Makefile with a test: target make test manual

Trigger modes (tests.mode or --tests-mode):

  • passive: never runs anything. It watches report files and shows the results of whatever ran the tests: you, your IDE, or your agent. Recommended whenever an agent runs tests itself, because two concurrent builds fight over target/ or build/.
  • save: runs after you save a file (debounced; one follow-up run is queued at most).
  • commit: runs after each commit.
  • interval: runs every tests.intervalSec seconds (min 30).
  • manual: runs on code-stream-overlay test or POST /api/tests/run.

Override anything with tests.command, tests.reports (JUnit or TRX globs) and tests.timeoutSec. For example, jest with jest-junit:

{ "tests": { "command": "npx jest --ci --reporters=default --reporters=jest-junit", "reports": ["junit.xml"] } }

Goals

Put a task list in GOALS.md (or set goals.file; .git/code-stream-overlay/goals.md keeps it private):

# CSV export for orders

- [x] Scope the feature
- [ ] Export endpoint
  - [x] Header row
  - [ ] Quote fields with commas
- [ ] Tests for edge cases

## Stretch

- [ ] Streaming for large exports

The first # heading becomes the title. Top-level items count toward progress, and a parent counts only when its own box is checked. Items under a Stretch heading are dimmed and don't affect the percentage. Checking an item on stream strikes it through and slides it out.

goals.source can also be "claude-todos" (the coding agent's todo list), "both", or "off".

Coding agent

Claude Code

npm i -g code-stream-overlay        # a stable path for the hook
code-stream-overlay hooks install   # merges hooks into .claude/settings.local.json

The agent widget then shows what Claude is doing ("Editing src/Order.java", "Running ./mvnw test", "Waiting for you"), with counters for edits, commands and reads. Its task list can feed the goals widget (goals.source: "claude-todos" or "both").

The hook is built to be invisible. It never prints, always exits 0, takes about 50 ms, and gives up after 300 ms if the overlay isn't running. File contents and tool output never leave the hook. Prompts are never shown unless agent.showPrompts: true. code-stream-overlay hooks uninstall restores your settings file.

Any other agent

curl -X POST http://127.0.0.1:4747/api/agent -H "Authorization: Bearer $TOKEN" \
  -d '{"type":"action","text":"Refactoring parser","tool":"aider"}'

Event types: action (text, tool), thinking, waiting, done, todos ([{ "content": "...", "status": "in_progress" }]). The token is in .git/code-stream-overlay/server.json.

OBS

Automatic

OBS 28+ ships obs-websocket. Enable it under Tools → WebSocket Server Settings, then:

code-stream-overlay obs install              # one browser source per widget, in the current scene
code-stream-overlay obs install --single     # one full-canvas source for the composed layout
code-stream-overlay obs install --scene Coding
code-stream-overlay obs uninstall            # removes exactly the sources it created

Sources are named so · <widget> and positioned by their layout slot, scaled to your canvas. Running install again updates them without creating duplicates. The password is taken from --obs-password, then CODE_STREAM_OVERLAY_OBS_PASSWORD, then obs.password in .git/code-stream-overlay/config.json, and otherwise you're prompted.

Add the control page as a dock by hand: View → Docks → Custom Browser Docks → http://127.0.0.1:4747/control.

Manual

Sources → + → Browser, paste a URL from the start banner, and use the width and height from the table under Look and feel. Browser sources are transparent by default. Leave "Shutdown source when not visible" off so animations and reconnects keep working.

Look and feel

Layout. / is a 1920×1080 stage scaled to the source size. Widgets sit in slots, and widgets that share a slot stack:

Widget Default size Default slot
now 900×90 top-left
timer 360×120 top-right
git 360×140 right-middle
tests 360×140 right-middle (below git)
goals 420×320 left-middle
agent 1000×70 bottom-center
commits 1920×48 bottom-bar
file 600×200 off by default
custom 360×80 off by default

Choose widgets with display.widgets. Move them with display.layout, either { "goals": { "slot": "bottom-left" } } or { "goals": { "x": 40, "y": 600, "w": 420, "h": 320 } }.

Themes. terminal (dark panels, monospace) and minimal (no panels, outlined text for any background). You can also give a path to your own .css file, which overrides the tokens from web/css/base.css (--so-fg, --so-bg, --so-accent, --so-pass, --so-fail, --so-radius, …). display.css appends extra CSS after the theme.

Tone. plain or playful ("All green, ship it", "3 gremlins loose"). Override any label with display.labels, e.g. { "tests.pass": "All green" }. Keys are listed in web/i18n/plain.json.

Per-source URL params change only that browser source:

Param Example Effect
theme theme=minimal theme for this source
tone tone=playful label set
font font=Fira%20Code any Google Fonts family
scale scale=1.5 0.5 – 3
align align=right left, center, right
bg bg=solid solid background instead of transparent
hide hide=message,counts hide sub-elements
label.<key> label.tests.pass=Ship%20it override one label
confetti confetti=0 no confetti

Example: http://127.0.0.1:4747/w/tests?theme=neon&scale=1.5&label.tests.pass=Ship%20it

Animations. Tests going green flash and throw confetti (display.confetti: false turns that off), and tests going red shake. A checked goal strikes through and slides out, new commits slide into the ticker, a new timer phase is announced for 3 s, and the agent widget pulses while it waits for you. If the server goes away, widgets fade to 40% and recover on their own.

Configuration

Settings are merged in layers, later ones winning. Objects merge deeply and arrays replace.

  1. Built-in defaults
  2. Global: ~/.config/code-stream-overlay/config.json (%APPDATA%\code-stream-overlay\config.json on Windows)
  3. Shared repo file: code-stream-overlay.json (meant to be committed)
  4. Private repo file: .git/code-stream-overlay/config.json
  5. CLI flags
  6. URL params (display only, per browser source)
{
  "port": 4747,
  "host": "127.0.0.1",
  "title": null,                  // default: GOALS.md heading, then branch, then repo name
  "subtitle": null,
  "session": { "preset": "90min", "phases": null, "autoStart": true },
  "tests": { "adapter": "auto", "command": null, "reports": null, "mode": null,
             "debounceMs": null, "intervalSec": 300, "timeoutSec": 600 },
  "goals": { "source": "file", "file": "GOALS.md", "stretchHeading": "Stretch" },
  "agent": { "enabled": true, "idleAfterSec": 120, "showPrompts": false, "showCommands": true },
  "privacy": { "ignore": [".env*", "**/secrets/**", "*.pem", "*.key", "id_*"],
               "redactPaths": false, "hideFileNames": false },
  "display": { "theme": "terminal", "tone": "plain", "font": null, "css": null, "labels": {},
               "widgets": ["now", "timer", "git", "tests", "goals", "agent", "commits"],
               "layout": {}, "confetti": true },
  "obs": { "host": "127.0.0.1", "port": 4455, "password": null, "scene": null, "mode": "widgets" }
}

Unknown keys and wrong types are errors, and the message names the file and the path.

Security

  • The server binds to 127.0.0.1 by default. --host 0.0.0.0 prints a warning and requires the token on every route, and the printed URLs include it.
  • Write routes (POST /api/*) always need the per-start token from .git/code-stream-overlay/server.json.
  • Requests whose Host header isn't the server's own are rejected (DNS-rebinding guard). There are no CORS headers, and JSON bodies are capped at 64 KB.
  • The test command comes only from local config or the detected adapter, never from an HTTP request.

Files it writes

Everything lives in .git/code-stream-overlay/ (server.json, private config, session summaries, obs.json, test reports for pytest and .NET). The only exception is .claude/settings.local.json after hooks install, a local file that is excluded from git automatically. The only tracked files it writes are code-stream-overlay.json and GOALS.md, and only if you choose them in init.

Releasing (maintainers)

Releases are published by GitHub Actions (.github/workflows/release.yml) through npm trusted publishing, so no npm token lives in the repo.

npm version patch        # bumps package.json + src/constants.ts, commits, tags vX.Y.Z
git push --follow-tags   # the tag triggers the release workflow

License

MIT

About

Live, repo-aware OBS overlays for coding streams: what you're building, progress and test status. npx code-stream-overlay

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages