Docs

Install

Get the build for your system from the download page. On a Mac, the first open takes a few extra clicks (the steps are on the download page). On first launch the app registers its hooks and turns on Open at Login, which you can switch off from the tray menu and it will stay off.

Restart any Claude Code sessions that were already running so they pick up the hooks.

What it adds to Claude Code

Plexiform appends its own entries to ~/.claude/settings.json and never touches anything else in that file. It checks every ten minutes that they're still there. If you move the app, use Reinstall hooks in the tray menu, because the hook commands point at the app's path.

Hooks always exit cleanly, so a problem in Plexiform can't block a Claude Code session.

The lamps

• Green: at least one session is working.
• Amber: your turn. A session finished, is waiting for your next prompt, or a turn failed.
• Red: blocked until you act. A permission prompt, a usage limit, or no network.
• Off: no sessions are running.

Click the widget to jump to the session that needs you. With several waiting, each click goes to the next.

Rules

Every event is a signal, and a rule says which lamp, eye colour, pose, sound or costume it triggers. Open Lights from the widget's menu to edit them. Rules can be scoped to one tool or folder, reordered, and previewed live with Try on widget. The permission and usage-limit rules are locked above the rest so a stray rule can't hide a real block.

MCP tools

Plexiform ships a read-only MCP server so a session can ask about what the widget is showing. The tools:

• buddy_status: what the widget shows now, and why.
• buddy_sessions: every session the widget sees.
• buddy_why: why a rule is or isn't firing.
• buddy_rules: the configured rules in order.
• buddy_recent_transitions: the latest state changes.
• buddy_model_mix: which models your turns ran on, and what they cost.
• buddy_git_status: pull request and build signals.
• buddy_spend: today's and this week's spend against your budget.
• buddy_usage_history: spend and tokens over any range up to 400 days, grouped by day, model, family, project or source.
• buddy_pending_requests: permission requests waiting for an answer.

Where your data lives

Your rules, settings, usage record and cameo photos are in a folder in your home directory, ~/.claude-traffic-light. That folder may move in a later release, and the app will migrate it for you. Nothing in it is uploaded. The privacy notice lists every file and every flow that leaves your machine.