🧞 Agent Genie

A lightweight floating desktop genie that surfaces your GitHub Copilot agent-session updates.

Run 5-6 agents behind the scenes. When one finishes, needs you, or is grinding away, a transparent genie drifts onto whatever screen you're on, puffs colored smoke, flashes a message, and chimes - then fades away.

---

Why

When you supervise several Copilot agents at once, you lose track of who needs you. Agent Genie is a tiny always-on overlay that watches your sessions and gets your attention only when it matters:

Level	When	The genie
🟢 green	a session finished its task	rises, green smoke, success chime
🔴 red	a session needs your input / errored	shakes, red smoke, urgent buzz, lingers
🟡 yellow	a session is actively working	soft chime, yellow smoke
🔵 info	any other update	gentle cue

It floats above everything (even full-screen apps) and hops to the monitor your cursor is on, so the flash lands where you're already looking.

How it works

Copilot sessions (~/.copilot/session-state/)        optional: Copilot SDK
                 │  file watcher                                │ session events
                 └──────────────► http://127.0.0.1:4343/event ◄─┘
                                          │ IPC
                                  Electron genie overlay 🧞  (smoke + flash + speech + sound)

• A frameless, transparent, always-on-top Electron window renders the genie.
• A tiny local HTTP server on 127.0.0.1:4343 accepts POST /event with { level, agent, message }.
• The default driver is a watcher over ~/.copilot/session-state/ - no SDK, no network, works today.
• An optional Copilot SDK driver (GENIE_SDK=1) subscribes to the SDK session event stream instead. The SDK is in technical preview, so the genie always falls back to the file watcher if it isn't available.

Quick start

npm install      # installs Electron
npm start        # launch the floating genie

In another terminal, fire test events (great for rehearsal / on stage):

npm run demo                                  # issue -> pr -> merge -> conflict (distinct sounds)
node scripts/emit.js pr "agent-1 opened PR #42"
node scripts/emit.js conflict "merge conflict in app.js"
node scripts/emit.js green "agent-1 finished"

Each action kind plays a distinct notification sound (no text-to-speech):

Kind	Sound	Mood
issue	light double blip	blue
pr	bright ascending arpeggio	amber
merge	triumphant resolved run	green
conflict	urgent dissonant buzz	red
commit / push	short ticks	blue / amber

Wire them to real git events (so a real git commit / git merge / git push auto-plays the sound), from inside any repo you want to watch:

node scripts/install-hooks.js     # adds non-blocking post-commit/post-merge/pre-push hooks
node scripts/uninstall-hooks.js   # removes them cleanly

The hooks curl the genie with a 1s timeout and || true, so they never slow down or fail a git command even if the genie isn't running. PRs and issues are GitHub (server) events, not local git events, so wire those via a GitHub Actions step that POSTs { "kind": "pr", ... }, or fire them manually with emit.js.

Enable the optional LLM one-liner summaries (crisp "what it's doing now" text):

# uses @github/copilot-sdk with a warm, reused client (cold start paid once at
# launch ~6s; each summary ~5s with claude-haiku-4.5). Falls back to the raw
# activity line if the SDK is unavailable or a call times out.
npm install @github/copilot-sdk
GENIE_SUMMARIZE=1 npm start

Configuration

Env var	Default	Meaning
GENIE_PORT	4343	local event server port
GENIE_IDLE_DONE_MS	20000	quiet-after-active gap that counts as "finished"
GENIE_CHECK_MS	2000	how often quiet sessions are checked for "finished"
GENIE_REARM_MS	1500	min gap before re-announcing a session as working
GENIE_SUMMARIZE	unset	set to 1 for LLM one-liner summaries (warm Copilot SDK)
GENIE_SUMMARIZE_MODEL	claude-haiku-4.5	light model for summaries (e.g. gpt-5-mini, gemini-3.5-flash)
GENIE_SUMMARIZE_TIMEOUT	12000	per-summary timeout (ms); falls back to raw line on timeout
GENIE_SDK	unset	set to 1 to also drive events from the Copilot SDK stream

Messages reflect the agent's current activity (its latest narration), not the first prompt. With GENIE_SUMMARIZE=1 that line is refined to a ~5-word LLM summary. The cold start is one-time; the CLI (copilot -p) is deliberately not used for summaries because it cold-starts a new process (~60s) on every call.

Build it with us, live 🎤

This repo doubles as a live demo. Tell us what to build:

👉 Open the feature form and submit an idea. The wilder the better.

Your issue joins our live backlog. On stage we pick one, hand it to the Copilot CLI agent, and go from idea to merged PR in real time.

Project layout

agent-genie/
  src/
    main.js                      # Electron window + /event server + display follow
    preload.js                   # secure IPC bridge
    renderer/
      index.html
      renderer.js                # event -> show orchestration
      style.css                  # genie, smoke glow, color flash, shake
      features/sound.js          # procedural Web Audio cues (no assets)
      features/smoke.js          # canvas smoke puffs, tinted per level
    watchers/session-watcher.js  # default driver: session-state poller
    sdk/sdk-emitter.js           # optional driver: Copilot SDK event stream
  scripts/emit.js                # fire test events at a running genie
  .github/ISSUE_TEMPLATE/        # the audience feature/bug forms

License

MIT - see LICENSE.