/pstack-pulse

name: pstack-pulse
description: Show every Claude Code and Codex session on the iPhone lock screen through ActivitySmith and in the Mac menubar, with each plan page's pipeline, and buzz when a session needs you, ships or fails.
argument-hint: install [--auto-update] | update | doctor | status | menubar | uninstall
disable-model-invocation: true

pstack pulse

A daemon on this Mac turns hook events from every Claude Code and Codex session into ActivitySmith Live Activities. It shows only pstack sessions: those whose title starts with a pstack stage or state emoji, as the Session title rule sets it, such as "🚧 scrub (2/5)". It shows one card per project, then fills the rest of the phone's five cards with one card per session. A session card shows the stage and the (n/total) count from the session's title as a stage bar, its stage name in the subtitle, an Open button and a Plan button while the session's plan is still open. Sessions that need you, through a question or a permission prompt, get a card first, then working ones; idle sessions get none. A question turns the session's card orange and puts the question in its subtitle, without ending the card. A session that finishes its turn keeps its card for fifteen minutes before a working session can take it, because every new card spends one of the remote starts iOS allows. A project is every clone and worktree of one git origin, so two clones of plate share a card. A repository without an origin is its own project, and sessions outside any repository share one called other. A project card lists each session that needs you, failed or is working. Each one shows the session's name with its stage emoji in large type, as on its session card, and under it, in small type, the stage from its title, or Needs you or Failed, in its state color. Sessions that need you come first, then failed and working ones. After them come, in yellow, sessions whose turn ended while their title still shows a stage. Such a run is not finished and waits for you to resume it, and each one shows its stage too. A run whose title is back to its bare name is finished and leaves the card. A card with more than eight sessions shows seven and a more value. While a session needs you, the card's subtitle shows its question and the card's one button opens that session. Otherwise the subtitle counts the failed, working and to-resume sessions, and the button opens the session list. A card never changes type, so a question starts no new card. A project card keeps its slot until a project with a more urgent session needs it. It pushes a notification when a session needs you, ships or fails, and sets the app badge to the number of sessions that need you. You answer in the vendor's own app. It also writes two lock screen widget metrics, which you create once in ActivitySmith's web app as String metrics. `pstack.summary` counts the sessions waiting on you and the working ones, such as "2 your turn · 3 working". `pstack.waiting` names the sessions waiting on you, questions first, folding names past 64 characters into a count. iOS refreshes a widget about every 15 minutes, and the daemon sends a metric only when its text changes. Tapping a push opens the session: a Claude session's Remote Control link opens it in the Claude app, and a Codex push opens the ChatGPT app. A push's Plan button opens the session's plan page while that plan is open. A Claude session with Remote Control off has no link the phone can open, so tapping its push opens its plan page instead, and a card that asks for it opens the session list. ActivitySmith takes links only for a card's button, not for a tap on the card itself. That button takes only web and Shortcuts links, so a card that asks for a Codex session opens the session list too. `<skill>` below is this skill's base directory, and every command is `node <skill>/scripts/pulse.mjs <command>`.

What it reports

• Claude sessions buzz for:
• a question or plan approval, at once;
• a permission prompt left unanswered for about six seconds. Claude reports it through its `permission_prompt` notification, which desktop sessions send from Claude Code 2.1.233 on; in a terminal, typing restarts the six seconds. A call that a rule allows, or that another hook allows within six seconds, stays silent. The push shows Claude's own notification text, which may not name the tool. Your next prompt or the end of the turn clears the card. No hook says when a prompt is answered, so the card stays on needs you for the rest of the turn after you answer. While one prompt or question waits, a second prompt does not buzz. After you deny a prompt, Claude stops and waits, so the card stays on needs you until your next prompt;
• a push the remote branch has;
• a required check still failing when the turn stops;
• an API error;
• a session that died while working.
• Codex sessions from the app or the CLI buzz for questions and permission prompts, and show their plan. Codex pushes, failed checks and lost processes are not observed, because Codex hooks carry no git result or tool failure.
• A required check counts only when the Bash command is the check itself, optionally with flags, such as `bun check --bail`. Any other form, such as `bun check | tail`, a chain or a second line, records nothing, because its exit status is not the check's. A configured check that is itself a chain never counts.
• A session is working while a turn runs. It stays working after the turn while a background shell, subagent or monitor it started still runs, because that work wakes it with a new turn. An open artifact page watch does not count, because it never wakes the session. A dev server left running in the background keeps the session working until the server stops.
• Panel seats, smoke runs, headless `claude -p` runs, subagents and Codex exec and review threads never show. A session started with `PSTACK_PULSE_OFF=1` in its environment never shows either.
• A turn that hands back