Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ So trust can't come from the agent's account of itself. It has to come from outs

## Why perch exists

That's perch, built to exactly that spec: a macOS notch and menu bar monitor for Claude Code and Codex sessions, watching on two axes. Actions: every tool call is risk-scored offline the instant it fires — when an agent runs something dangerous, a red card drops from the notch with the exact command and why it was flagged, even when the call was auto-approved. The riskiest calls are exactly the ones nobody asks you about. And footholds: a live scan of the persistence surface — config, hooks, memory files, MCP servers, LaunchAgents — read straight from disk, so it also catches what happened before perch launched. That payload from three sessions ago? This is the scan that catches it. Sessions, rate limits, and token usage ride along in the same glance.
That's perch, built to exactly that spec: a macOS notch and menu bar monitor for Claude Code and Codex sessions, watching on two axes. Actions: every tool call is risk-scored offline the instant it fires — when an agent runs something dangerous, a red card drops from the notch with the exact command and why it was flagged, even when the call was auto-approved. The riskiest calls are exactly the ones nobody asks you about. And footholds: a live scan of the persistence surface — config, hooks, memory files, MCP servers, LaunchAgents — read straight from disk, so it also catches what happened before perch launched. That payload from three sessions ago? This is the scan that catches it. Sessions, rate limits, and token usage ride along in the same glance — and a monitoring-health strip applies the same skepticism to perch itself: it won't call an agent's coverage *verified* until a real event from that agent has actually arrived.

![Perch in the notch: security score, a Bash call flagged dangerous, live agent sessions, rate-limit gauges](/assets/img/perch-notch.png)
![Perch in the notch: verified monitoring coverage, security score, a Bash call flagged dangerous, live agent sessions, an Insights shortcut, rate-limit gauges](/assets/img/perch-notch.png)

What matters is *where it stands*: outside the agent's process. Agent content reaches it only as data to display: there's no model inside to prompt-inject, and a transcript is something it draws, not something it obeys. And what it shows isn't the agent's story about itself: session state, flagged commands, and token counts come from the harness's own records — which tools actually fired, what they actually ran. The model can narrate whatever it likes; the record is written by the harness, not by the narration. When the agent claims it's idle, the notch either agrees or it doesn't.

Expand All @@ -83,7 +83,7 @@ Threat model, stated bluntly: perch trusts the local OS account boundary and the

At the scale of one person and a handful of sessions, perch is enough. Picture four hundred engineers, each running coding agents all day. One agent going wrong is an incident. A fleet going wrong is a breach.

At fleet scale, the risks worth catching are only visible *across* machines: one agent tripping a curl-pipe-bash rule is noise; nine endpoints tripping it within the hour is a campaign. So the events have to flow somewhere central. That's [crowsnest](https://github.com/theMobiusStrip/crowsnest). Every endpoint ships its tool-decision events — what the agent asked to do, how risky it was, what got approved — to one place, where they land in ClickHouse. Deterministic SQL rules decide what looks suspicious, and a dashboard turns the hits into fleet views and incidents you can drill into. It's local-first: one machine today, multi-endpoint tomorrow, no rewrite in between.
At fleet scale, the risks worth catching are only visible *across* machines: one agent tripping a curl-pipe-bash rule is noise; nine endpoints tripping it within the hour is a campaign. So the events have to flow somewhere central. That's [crowsnest](https://github.com/theMobiusStrip/crowsnest). Every endpoint ships its tool-decision events — what the agent asked to do, how risky it was, what got approved — to one place, where they land in ClickHouse. Deterministic SQL rules decide what looks suspicious, and a dashboard turns the hits into fleet views and incidents you can drill into. It's local-first: one machine today, multi-endpoint tomorrow, no rewrite in between. And perch now meets it halfway: deduplicated detections land in a compact local SQLite record — metadata only, never commands, paths, or prompts, 30 days — behind a [versioned read-only view](https://github.com/theMobiusStrip/perch/blob/main/docs/detection-storage.md) built for a future crowsnest adapter to poll.

And yes, crowsnest is a watcher everything phones home to — the difference is whose home: your ClickHouse, your rules, your infrastructure, not a vendor's black box. Same caveat as perch, one level up: a compromised endpoint can go quiet (which the fleet view surfaces) or lie convincingly (which no dashboard fixes). Its LLM triage is optional, advisory, and off by default — the verdict belongs to deterministic rules, because if another LLM gets the final say, you're back to agents supervising agents.

Expand Down
Binary file modified assets/img/perch-notch.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified perch/img/icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added perch/img/insights.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified perch/img/integrity.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified perch/img/notch.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified perch/img/usage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified perch/img/worktrees.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading