How it works

One pipeline, all local: agent events are appended to a file on your Mac, and the app assembles session state from it. No server is involved at any point.

Claude Code session
  └─ hooks (SessionStart / UserPromptSubmit / PermissionRequest / PostToolUse / Stop / SessionEnd)
       └─ appends one JSON line per event to ~/.butler/events.jsonl
            └─ Silicon Workers watches the file and assembles per-session state
                 └─ menu bar panel updates in real time

The six Claude Code hook events

Silicon Workers listens through Claude Code's official hooks mechanism. The hook script only writes a log line; it always exits 0 with zero output, which for PermissionRequest means "no opinion" — approval prompts reach you exactly as before.

Hook event	What it means in the panel
SessionStart	Session lifecycle bookkeeping (no card yet — avoids noise from warm-up sessions)
UserPromptSubmit	You sent a message → card created / back to Running; your first message becomes the title
PermissionRequest	Agent needs your approval → Waiting for you (strong signal, counted on the menu bar badge)
PostToolUse	A tool finished = still working → back to Running (after you approve, the panel flips back automatically)
Stop	A response turn ended → Waiting for you (weak signal: "take a look")
SessionEnd	Session over → the card leaves the panel

Strong signals vs. weak signals

• Strong — "needs your approval": the agent is truly blocked. Solid orange edge, counted on the menu bar badge, pushes a macOS notification (once per wait).
• Weak — "finished, take a look": can wait. Soft orange edge, not counted on the badge. If it sits unread for over 1 hour it fades to Idle.

Timeouts and edge cases

• A Running session silent for 30 minutes is flagged as possibly stuck — the card turns orange and you get one notification.
• A killed terminal never sends SessionEnd; a Running session with no events for 2 hours is treated as dead.

Known limitations (accepted by design)

• There is no universal "the AI is waiting for your input" event — only approval requests are precise. Stop is an approximation of "your turn".
• State is assembled by inference, so edge cases can be slightly off. The principle: better to nudge you once too often than pretend to be omniscient.

Next: Connect Codex · Uninstall