Docs
The short version of how Plexiform works and what it touches on your machine.
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
The widget MCP tools below are read-only: a session can ask about observed state. Activity hooks and these status tools alone do not provide a messaging channel. 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.
Team sessions
Overview lists your sessions and the supported sessions shared with your team. Select a session to see its reported work and the controls available for that exact connection.
Supported sessions started in a signed-in team workspace, and Claude terminal channels you deliberately attach there, are automatically shared to that team to watch (terminal channels you attach on purpose also allow sending). The owner can choose Allow sending on a session's share in Overview. Personal sessions stay separate. Current board runs appear for team members even without a private-session share. Viewers can watch; members with write access can message a supported current target. Processing uses the owner's provider quota and permissions.
A terminal channel requires deliberate setup and provider confirmation. It does not attach arbitrary terminals, bypass permissions or make Cursor, Gemini or every other observed provider interactive. You can stop a private-session share in Overview or disable automatic team sharing in Preferences. Membership removal or revocation stops future authorized access; existing team-board history is retained.
Live session messages and replies pass through the hub in readable form without persisting that relay text. Board task-inbox messages, receipts and replies are stored durably on the hub. Agents read that inbox explicitly; queued is not proof of receipt, agent acknowledgement or completion, and sending does not automatically resume an agent. The hub operator can read shared content.
AI collaboration: prepared candidate
The prepared candidate lets a managed Claude Code or Codex task ask another AI for bounded help, exchange messages and read its report. This describes candidate behavior; check the latest published release before expecting it in your installed app.
Start in Tasks with a Git project and a clear request. Helpers work in separate working copies of the same repository and inherit the same or narrower permissions. They start from committed code, so commit any context they need before delegating. Each task family allows up to four helpers across two levels. A task family with a spend cap cannot delegate because a shared aggregate cap is not supported.
Within that family, the AI can use buddy_tasks to inspect related work, buddy_spin_off to request help, buddy_message to send a request or result, and check_messages to read replies. Requests have durable receipts; a stored or delivered message does not mean the other AI has answered or finished. Messages cannot approve tools or raise permissions.
A real local Claude–Codex request, acknowledgement, report and follow-up exchange has been verified. Claude's native Plan mode blocked peer messaging in that check; the successful exchange used normal task permissions with a read-only review request. That request is an instruction, not an enforced read-only sandbox. Independent teammate/device acceptance remains open. This connection reaches related managed Tasks, not arbitrary existing terminals or every observed session.
Saved reports: prepared candidate
The prepared candidate's task Overview includes Saved report and references. Save a response as a report, write a note, or revise the saved context so the result remains with the task when you return. Reports are stored locally with a checkpoint version. File references point to current files; they are not frozen file snapshots. Reported checks remain separate from independent verification.
Windows and WSL
Windows acceptance is still pending, so there is no promise yet about when it is supported or how well it works. Claude Code sessions running inside WSL have not been tested with Plexiform; treat them as unsupported for now.
Where your data lives
Your rules, settings, usage record and cameo photos are stored locally. The usage reader keeps counts and costs rather than a copy of full conversations. Local Tasks also keeps task text, messages, AI activity and replies; pending widget requests can briefly contain tool input, plan text or questions.
Team features send selected content and metadata to your hub under the policy above. Task-inbox history is durable on that hub, and shared content is readable by its operator. The privacy notice distinguishes local storage, automatic team sharing, live relay, durable inboxes and website hosting.