diff --git a/CLAUDE.md b/CLAUDE.md index a06dc3e..4dad7c6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -59,13 +59,15 @@ events. SwiftPM only — there is no Xcode project. ## Conventions - Commits: imperative subject ≤50 chars; body only when the why isn't - obvious. No tool attributions/footers, no process narrative, no + obvious. Codex-authored commits end with the official + `Co-authored-by: Codex ` trailer, and Codex-authored PRs + include `Generated with Codex.` exactly once. No process narrative, no conversation-context leak (sources, durations, prompts), and no - machine-derived measurements — real worktree/token/file counts, disk - sizes, timings, local paths from the dev machine — in commit or PR - text. Describe behavior generically ("count · total · reclaimable"), - never with this machine's numbers. This class caused a full history - squash once; it is the leak, not just the examples in parentheses. + machine-derived measurements — real worktree/token/file counts, disk sizes, + timings, local paths from the dev machine — in commit or PR text. Describe + behavior generically ("count · total · reclaimable"), never with this + machine's numbers. This class caused a full history squash once; it is the + leak, not just the examples in parentheses. - Public repo: never commit or push private data — no PLAN.md, machine details, credentials, or internal paths. - Releases are built by CI from `v*` tags (`release.yml`); never hand-build diff --git a/README.md b/README.md index a673af2..55722f5 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ turns dangerous. Never gets in the way. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Local only](https://img.shields.io/badge/telemetry-zero-brightgreen)](#security-model) -Perch's notch panel: monitoring active for Claude Code and Codex, security score 75 (Elevated), a Bash call flagged dangerous, plus live sessions, worktree and token glance lines, and rate-limit gauges +Perch's notch panel: monitoring verified for Claude Code and Codex event delivery, security score 75 (Elevated), a Bash call flagged dangerous, plus live sessions, worktree and token glance lines, and rate-limit gauges @@ -55,13 +55,13 @@ and what they've **left behind**: |---|---| | ⚡ **Actions** — risk on every tool call | Offline heuristic scoring of each tool call as it happens: `rm -rf`, `sudo`, `curl \| sh`, credential reads, force-pushes, raw-IP traffic, and writes to the agent's own brain (`CLAUDE.md`, `~/.claude` settings/hooks). Danger fires an OS notification; every rule is in one readable file: [`RiskAssessor.swift`](Sources/PerchCore/RiskAssessor.swift). | | 🧭 **Footholds** — the persistence surface, live | A separate notch page scans the files an agent would use to *survive* a session — config/hooks, MCP servers, `CLAUDE.md`/memory, `LaunchAgents`, shell profiles — and shows their current state: recently changed, carrying a hook that isn't Perch's, or unreadable. Straight from disk, so it covers changes made before Perch launched. | -| 📡 **Monitoring health** | A separate coverage strip verifies the deployed bridge, local event socket, Claude wiring, and Codex hook trust. Guided setup installs or repairs integrations and makes a disconnected-but-quiet app visibly different from a healthy one. | -| 🔔 **Alerts even when nothing prompts** | Danger fires an OS notification — including calls auto-approved by allow rules or relaxed permission modes. The riskiest calls are exactly the ones nobody asks you about. | +| 📡 **Monitoring health** | A separate coverage strip checks the deployed bridge, local event socket, Claude wiring, and Codex hook trust, then waits for a real event from each configured agent before reporting delivery as verified. Its state also colors the collapsed notch and menu-bar bird; guided setup installs or repairs integrations. | +| 🔔 **Alerts even when nothing prompts** | Danger fires an OS notification — including calls auto-approved by allow rules or relaxed permission modes. Notification actions jump straight to the exact detection, session, or usage view instead of leaving you to hunt for context. | | 📊 **Explainable security score** | A rolling 0–100 posture score in the notch and menu bar: −25 per danger, −5 per caution over the last hour. Open the strip for the formula and retained recent detections; dismissing an alert card does not erase its history. | | 🐦 **Every session at a glance** | Live list of all Claude Code and Codex sessions — running / waiting / idle, last message, context gauge, red badge on any session that just ran something dangerous. | | 🎫 **Token usage** | Today / 7-day / 30-day totals in the notch, rate-limit gauges with reset countdowns, and a full per-day / per-model / per-project dashboard (menu bar → **Token Usage…**). | | 🌳 **Worktree housekeeping** | A read-only cross-project audit of the git worktrees agent sessions leave behind — classified `reclaimable` (clean, merged, stale), `review` (dirty or ahead of the default branch), `active` (a live session or recently touched), or `orphaned` — with disk sizes and a *Copy cleanup commands* button (menu bar → **Worktrees…**). Perch scores and reports; it never deletes. | -| 🪶 **Zero footprint** | No dependencies, no telemetry, ~13k lines of auditable Swift. If Perch dies, your agents don't even notice. | +| 🪶 **Zero footprint** | No dependencies, no telemetry, and an auditable all-Swift codebase. If Perch dies, your agents don't even notice. |
🧭 Footholds · 🌳 Worktrees · 📊 token dashboard screenshots @@ -165,14 +165,16 @@ Perch bird in the menu bar → **Monitoring Setup…**. Install Claude Code and/ Codex monitoring there (your existing settings are parse-merged, backed up, and fully restorable — see [Security model](#security-model)). -**4.** Restart any running agent sessions and verify everything with **Run -Doctor** in setup or the menu bar. Doctor and hook installation run in the -background, so the menu and setup window stay responsive. Codex requires its hooks to be explicitly trusted before -it will run them; the installer records that trust automatically (the same -write the Codex CLI's `/hooks` screen performs — see +**4.** Start or restart each configured agent, then wait for **Live +verification** in **Monitoring Setup…** to show that a real hook event was +received. Use **Run Doctor** for bridge, socket, hook wiring, and trust +diagnostics; Doctor and hook installation run in the background, so the menu +and setup window stay responsive. Codex requires its hooks to be explicitly +trusted before it will run them; the installer records that trust automatically +(the same write the Codex CLI's `/hooks` screen performs — see [Security model](#security-model)). If auto-trust fails (e.g. an old Codex -CLI), the install report says so — run `/hooks` once in the terminal -`codex` TUI instead (the desktop app has no `/hooks` command). +CLI), the install report says so — run `/hooks` once in the terminal `codex` +TUI instead (the desktop app has no `/hooks` command). **5.** In **Monitoring Setup…**, allow notifications and choose which event categories should interrupt you. To keep alerts visible but silent diff --git a/docs/img/notch.png b/docs/img/notch.png index 5dec471..da2aaec 100644 Binary files a/docs/img/notch.png and b/docs/img/notch.png differ