Promptly

Know when Claude needs you — without alt-tabbing.

Promptly is a tiny, movable, always-on-top status light for macOS & Linux.
By default it's a slick spinner — it spins while busy, pulses when it needs you,
and settles into a ✓ when it's done:

Spinner	State	Meaning
	Busy	working
	Needs you	needs your input
	Ready	ready / idle

Prefer something else? Switch looks in one click — orb, breathing gradient, classic
traffic light, or a little Tamagotchi (see Skins).

It's driven by a dead-simple local HTTP server, so anything that can run a
shell command or hit a URL can control it — Claude Code, shell scripts, CI, cron,
a Slack bot, your imagination. Red while it works, yellow when it needs you, green
when it's done. Click it to jump straight back to where Claude is running.

The colors are just states — wire them to whatever you like.

Install

One line — fetches Promptly, sets up a private virtualenv (PySide6 won't touch your
system Python; uses uv if it's installed, with live
download progress), and puts promptly on your PATH:

curl -fsSL https://raw.githubusercontent.com/AssenDimitrov/promptly/main/install.sh | bash

Then just run it:

promptly                 # starts in the background, parks bottom-right
promptly --skin orb      # pick another look (see "Skins")

promptly launches detached — it won't hold your terminal — and prints how to
connect it to Claude Code. Logs go to $TMPDIR/promptly.log; stop it with the
printed kill <pid>, or right-click the light → Quit.

Installs into ~/.local (override with PROMPTLY_PREFIX). Re-run to update.
Uninstall with rm -rf ~/.local/share/promptly ~/.local/bin/promptly.

Prefer to read before you pipe to a shell? It's a tiny script —
install.sh. Or run from source (below).

Or with pipx / uv:

pipx install git+https://github.com/AssenDimitrov/promptly      # then: promptly
uv tool install git+https://github.com/AssenDimitrov/promptly   # (uv alternative)

Quick start (from source)

git clone https://github.com/AssenDimitrov/promptly && cd promptly
pip install -r requirements.txt         # just PySide6-Essentials (or: pip install PySide6-Essentials)

python promptly.py                 # spinner skin (default), parks bottom-right
python promptly.py --skin orb      # pick another look (see "Skins")
python promptly.py --skin tamagotchi --scale 1.4
python promptly.py --vertical      # classic vertical stoplight
python promptly.py --state red --port 7654

Then flip it from anywhere:

curl -s localhost:7654/red
curl -s 'localhost:7654/yellow?flash=1&label=Needs+your+input'
curl -s localhost:7654/green

• Left-click → jumps to the window where Claude is running (see Claude Code).
• Drag (press and move) → reposition it anywhere.
• Right-click → all the options (skin, size, orientation, opacity, always-on-top,
  show-over-fullscreen, and more).

It floats above other windows and stays out of the Dock/taskbar.

Linux note: needs a Qt platform plugin. On a normal desktop session it works out
of the box; on Wayland you may want QT_QPA_PLATFORM=wayland (or xcb to force X11).

Skins

Same three states, five different vibes. Switch any time via right-click → Skin,
or start with --skin <name>:

A skin is purely a render strategy over the state — the HTTP server and your
Claude Code hooks are identical for every skin. Adding your own is one class
(see How it's built).

👉 See them move at the bottom of this page.

Control it (the extension point)

Talk to Promptly over http://127.0.0.1:7654. Simple path endpoints:

curl -s localhost:7654/red
curl -s 'localhost:7654/yellow?flash=1&label=Needs+your+input'
curl -s localhost:7654/green
curl -s localhost:7654/off
curl -s localhost:7654/state                       # read current state as JSON
curl -s 'localhost:7654/focus?app=iTerm'           # macOS: set click target
curl -s 'localhost:7654/focus?title=claude-code'   # Linux/X11: set click target

Or richer JSON via POST:

curl -s localhost:7654/state \
  -d '{"state":"yellow","flash":true,"label":"Running tests"}'

That HTTP endpoint is the whole extensibility story: GitHub Actions, a deploy
script, a long-running job, a Slack bot — any of them can flip the light with one
line.

Connect it to Claude Code

Claude Code fires lifecycle hooks you can map straight onto the light. Open
claude-code-settings.json (installed at ~/.local/share/promptly/claude-code-settings.json),
copy its hooks block into either:

• ~/.claude/settings.json — applies to every project, or
• <project>/.claude/settings.json — just this repo.

The mapping:

Each hook is just curl -s -m 1 localhost:7654/<color> || true, run with
async: true — so if Promptly isn't running, Claude Code is never blocked or
slowed. Start Promptly, start Claude Code, and the light tracks it live.

Left-click → jump to where Claude is running

Left-clicking the light raises the window Claude Code lives in. The SessionStart
hook runs register-claude-window.sh, which auto-detects where to focus:

• macOS — detects the terminal from $TERM_PROGRAM. For Terminal.app and
  iTerm2 it captures the exact window Claude started in (it's the frontmost
  one at session start) and re-raises precisely that window — handy when several
  terminal windows are open. Other terminals (VS Code, Ghostty, WezTerm, Hyper, …)
  fall back to focusing the app by name. The first click triggers a one-time macOS
  prompt — "Python wants to control Terminal/iTerm" — click Allow.
• Linux/X11 — focuses a window by matching its title with wmctrl/xdotool
  (apt install wmctrl or xdotool). If your terminal has no useful title, set one
  in your shell rc with printf '\033]0;claude-code\007' and
  export CLAUDE_WINDOW_TITLE=claude-code. Wayland generally blocks one app
  from focusing another's window — there it may not work.

Edit /path/to/trafficlight in the SessionStart hook to point at this folder
(after the one-line install that's ~/.local/share/promptly). You can also set the
target by hand any time: right-click → Claude window → Set target…, and test it
with Claude window → Focus now.

The right-click menu

Everything is configurable here:

• Skin → Spinner / Orb / Breathing gradient / Traffic light / Tamagotchi
• Orientation → Horizontal / Vertical (for skins that support it)
• Size → Small / Medium / Large / Extra large
• Opacity → 100% / 85% / 70% / 50%
• Attach to top bar → snaps flush to the top edge and locks it there
• Always on top → float above other windows
• Sound → play a short sound on each state change — started (red), needs you
  (yellow), done (green). Off by default; start with --sound to enable at launch
• Show on all Spaces & over fullscreen apps (macOS) → appear on every Space and
  over other apps' fullscreen windows (on by default)
• Claude window → Focus now, Set target…, and the current target
• Quit

macOS behavior & environment variables

To behave like a proper always-visible status indicator, on macOS Promptly reaches
past Qt to the native NSWindow/NSApplication (via ctypes against the
always-present libobjc — no extra dependency) and:

• stays above other apps at a high window level,
• rides along to every Space/desktop (CanJoinAllSpaces),
• stays visible when another app is frontmost (Qt's Qt.Tool would otherwise
  hide it on deactivation),
• drops its Dock icon by running as an accessory app — which is also what
  lets it float over other apps' fullscreen Spaces.

Overlaying another app's native fullscreen is the one thing public macOS APIs
won't do, so it uses a private Spaces API — undocumented and may change across
macOS releases. It's on by default; turn it off with right-click → Show on
all Spaces & over fullscreen apps, or PROMPTLY_FORCE_ALL_SPACES=0. Everything
else uses public APIs only.

# floats over everything (incl. other apps' fullscreen) out of the box;
# pass =0 to keep it off other apps' fullscreen Spaces
PROMPTLY_FORCE_ALL_SPACES=0 python promptly.py --skin spinner

These knobs are macOS-only and harmless elsewhere. On Linux the window manager
governs always-on-top / across-desktops behavior directly.

How it's built

        any tool (Claude Code hook, script, CI…)
                       │  HTTP GET/POST  →  /red /yellow /green /off /state
                       ▼
   ┌──────────────────────────────────────────────┐
   │  promptly.py                                 │
   │  ┌────────────┐   Qt signal   ┌────────────┐ │
   │  │ HTTP server│ ────────────► │  widget    │ │
   │  │ (thread)   │  (thread-safe)│  + skin    │ │
   │  └────────────┘               └────────────┘ │
   └──────────────────────────────────────────────┘

• The HTTP server runs on a background thread and hands updates to the GUI thread
  through a Qt signal (Bridge.apply) — the safe way to touch the UI from another
  thread.
• Adding a new trigger = make something call the endpoint. No app changes needed.
• Adding a new look = add a Skin subclass (size + paint, optionally
  animating) and list it in SKIN_LIST. The control layer is untouched.
• Adding a new state (e.g. a 4th lamp) = extend VALID_STATES, then handle it
  in the skins you care about.

Built in PySide6 (Qt) because it's one pip-install, one file, no build step,
and looks good on both OSes. The same local-HTTP design ports cleanly to Electron,
Tauri, or a rumps menu-bar app if you'd rather — and your Claude Code hooks
wouldn't change.

The skins, side by side

Same three states (busy → needs you → ready), five different personalities. The
spinner is up top; here are the other four, each shown live in a different state
so you can see how they read at a glance:

Orb a single breathing glossy sphere	Tamagotchi a creature that works, calls you, and rests
Traffic light the classic three lamps	Breathing gradient an ambient bar — great snapped to the top edge

Switch between them any time via right-click → Skin, or start with
--skin orb / gradient / traffic / tamagotchi.

License

MIT — do whatever you like.