{"id":50126207,"url":"https://github.com/maximizegpt/supervisor","last_synced_at":"2026-05-23T20:03:39.610Z","repository":{"id":359845795,"uuid":"1247352908","full_name":"maximizeGPT/supervisor","owner":"maximizeGPT","description":"Redirects Claude Code in real time. Native macOS safety harness with two-process architecture, kqueue session tailing, and structured LLM triage.","archived":false,"fork":false,"pushed_at":"2026-05-23T17:51:54.000Z","size":394,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T19:24:20.853Z","etag":null,"topics":["agent-supervision","anthropic","claude-code","developer-tools","llm-safety","macos","mcp","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximizeGPT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T07:39:38.000Z","updated_at":"2026-05-23T17:51:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maximizeGPT/supervisor","commit_stats":null,"previous_names":["maximizegpt/supervisor"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maximizeGPT/supervisor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fsupervisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fsupervisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fsupervisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fsupervisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximizeGPT","download_url":"https://codeload.github.com/maximizeGPT/supervisor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximizeGPT%2Fsupervisor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33410349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-supervision","anthropic","claude-code","developer-tools","llm-safety","macos","mcp","swift"],"created_at":"2026-05-23T20:03:23.860Z","updated_at":"2026-05-23T20:03:39.594Z","avatar_url":"https://github.com/maximizeGPT.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- DEMO_GIF_PLACEHOLDER: ~10s recording showing launch → rm-rf trigger → banner + hover red, target docs/demo.gif \u003c5 MB, swap this comment for: ![Supervisor demo](./docs/demo.gif) --\u003e\n\n![Supervisor — Redirects Claude Code in real time.](./branding/supervisor-social-card.png)\n\n\u003e **Redirects Claude Code in real time.**\n\n[![CI](https://github.com/maximizeGPT/supervisor/actions/workflows/ci.yml/badge.svg)](https://github.com/maximizeGPT/supervisor/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/maximizeGPT/supervisor?include_prereleases\u0026sort=semver)](https://github.com/maximizeGPT/supervisor/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Platform: macOS 13+](https://img.shields.io/badge/Platform-macOS%2013%2B-lightgrey)](https://www.apple.com/macos/)\n\n\u003c/div\u003e\n\nSupervisor is a native macOS safety harness for [Claude Code](https://www.anthropic.com/claude-code) sessions. It tails the session's JSONL transcript as the assistant generates tool calls, runs a two-stage LLM triage against a structured rubric, and surfaces a flag — a notification, and (from v0.1.2) an intervention — when the next action looks destructive or unsafe. The harness runs entirely on your Mac. It uses your own Anthropic API key. No data leaves your machine except the same `messages` call you'd send Claude yourself.\n\n## What it does\n\nClaude Code writes a JSONL transcript of every session to `~/.claude/projects/\u003cproject\u003e/\u003csessionId\u003e.jsonl`. Each turn appends one record at a time: the user message, the assistant message, every `tool_use` block, every `tool_result`. Supervisor watches that file via `kqueue`, parses each new event into a typed `SupervisorEvent`, and feeds the recent window into a triage prompt.\n\nThe triage runs Claude Haiku 4.5 against a structured rubric. The rubric covers a small set of well-defined failure modes — destructive shell actions against non-temp paths, edits that would clobber unrelated work, calls into Cowork's sealed repos, fixture-replay loops, prompt-injection-shaped tool outputs. Haiku returns a structured `record_triage` call: severity, category, evidence UUIDs, free-text reasoning. When severity ≥ medium, Supervisor persists a flag, posts a macOS notification, and (v0.1.2+) routes the case into one of four intervention types. The hover window in the top-right corner of your screen pulses to show the current session's most recent flag at a glance.\n\nThe whole observation+triage path is built to keep cost predictable — every Claude API call goes through a redaction layer first (Anthropic keys, GitHub tokens, AWS pairs, JWTs, URL credentials, shell exports), and Haiku's per-flag cost is bounded by a rolling-window prompt cap. Token use is logged to a local SQLite store so you can see your spend per session, per day, per category. The trace log at `~/Library/Logs/Supervisor/supervisor.log` records every state transition for diagnosability.\n\n## Known limitations\n\nThese are real and shipped as-is. The roadmap section pairs each with the version that closes the gap.\n\n**Post-write timing limit.** Supervisor catches the next destructive action before it lands. For fast tools that complete before triage returns, the flag arrives after the action has already executed; you'll see the notification but the action will already be done. v0.2's hook channel will close this gap by integrating with Claude Code's tool-use hooks directly.\n\n**Main-app liveness detection.** Main-app death is detected via a 30-second heartbeat freshness window. If the main app dies via SIGTERM (rather than a clean Quit from the menu bar), the heartbeat child orphans and detection fails until v0.1.1's mach-port liveness check lands.\n\n**Bring your own Anthropic API key.** Supervisor has no server component and no usage-based revenue model — every triage call goes straight from your Mac to `api.anthropic.com` with your key. At my actual usage (~6 hours of Claude Code per day, mixed exploration and build), Haiku triage runs ~$80/month. Cost grows linearly with session activity; the in-app cost view shows your real spend. You can also set a hard daily cap that pauses triage when hit.\n\n**Unsigned for v0.1 MVP.** No Apple Developer ID, no notarization. macOS Gatekeeper will warn on first launch — right-click → Open through the \"unidentified developer\" warning. v0.1.x adds Apple Developer ID signing once the harness has dogfood miles. Until then, macOS may also invalidate the Accessibility grant after OS updates; Supervisor catches that and prompts a re-grant.\n\n## Roadmap\n\n**Intervention surface.** Four types, ordered by escalation:\n\n| Type    | Version | What it does                                                       |\n|---------|---------|--------------------------------------------------------------------|\n| notify  | v0.1.0  | macOS banner notification when the rubric flags an action. **Shipping.** |\n| inject  | v0.1.2  | Send corrective text into the terminal where Claude Code is running. |\n| pause   | v0.1.2  | Send `SIGSTOP` to the Claude Code process so it freezes in place.    |\n| kill    | v0.1.2  | Send `SIGTERM` to the Claude Code process so it shuts down cleanly.  |\n\n**Other near-term work:**\n\n- **v0.1.1** — mach-port liveness check that catches main-app SIGTERM-orphan within ~1s instead of relying on a 30s heartbeat window. Sonnet 4.6 escalation for ambiguous Haiku decisions.\n- **v0.1.2** — the three non-notify interventions above.\n- **v0.1.3** — Apple Developer ID signing + notarization.\n- **v0.1.4** — user-editable rubric (`~/Library/Application Support/Supervisor/rubric.yaml`).\n- **v0.1.7+** — expanded hover panel with click-through flag history, in-app cost dashboard, per-session intervention preferences.\n- **v0.2** — direct integration with Claude Code's tool-use hook channel, closing the post-write timing gap above.\n\n## Installation\n\nSupervisor builds from source on macOS 13+. The build script asks for nothing beyond what Xcode Command Line Tools provide (the first `swift build` will auto-prompt to install CLT if you've never opened Xcode).\n\n```bash\ngit clone https://github.com/maximizeGPT/supervisor.git\ncd supervisor\n./Scripts/build-app.sh debug\n```\n\nThat produces three bundles under `build/`:\n\n- `Supervisor.app` — the main app. Menu-bar-only (no Dock icon).\n- `SupervisorStatusBar.app` — the menu-bar health indicator.\n- `SupervisorHeartbeat.app` — companion process that proves the main app is alive.\n\n**First launch.** Right-click `Supervisor.app` → Open → confirm the Gatekeeper warning (unsigned MVP). The onboarding window walks you through three steps:\n\n1. **Anthropic API key.** Paste your key from [console.anthropic.com](https://console.anthropic.com). Supervisor validates it against the API with a one-token test call before storing it in Keychain — invalid / rate-limited / network-error states surface inline with retry.\n2. **Accessibility permission.** macOS routes you to System Settings → Privacy \u0026 Security → Accessibility. Toggle Supervisor on. Skip is fine — v0.1.0's only intervention is `notify`, which doesn't use Accessibility. The popover re-surfaces when Inject ships in v0.1.2.\n3. **Notification permission.** macOS asks once. Allow shows full banners; deny still lets flags appear in Notification Center.\n\n**Running.** Start the status-bar companion alongside:\n\n```bash\nopen ./build/Supervisor.app\nopen ./build/SupervisorStatusBar.app\n```\n\nIf everything's working you'll see:\n\n- The hover window in the top-right corner of your active screen — 240×40, a green dot meaning \"watching, no flag\".\n- A green checkmark in your menu bar (right side) — Supervisor's brand mark, template-tinted to match your menu bar's foreground.\n- The first time Claude Code does something the rubric flags, a macOS banner notification slides in and the hover dot turns amber or red depending on severity.\n\n**Resetting.** To wipe the API key and start over:\n\n```bash\nsecurity delete-generic-password -s live.supervisor.api\nrm -rf ~/Library/Application\\ Support/Supervisor\nrm -rf ~/Library/Logs/Supervisor\n```\n\n## Architecture\n\n![Architecture diagram](./docs/architecture.svg)\n\nThe brief version. [DESIGN.md](./DESIGN.md) has the full 1,184-line design doc — every decision is traceable.\n\n- **Two-process companion architecture.** The main `Supervisor.app` does observation, triage, intervention, UI. `SupervisorHeartbeat` writes a heartbeat file every 5 seconds. `SupervisorStatusBar` reads that file every 2 seconds and reports green/amber/red based on freshness. A crash of the main app turns the menu-bar icon red within 30 seconds — the user always has an honest health signal in their menu bar.\n- **`kqueue` JSONL tailing.** Per-session `DispatchSourceFileSystemObject` watching each active session log, with byte-offset checkpoints in SQLite so a restart resumes from exactly where it left off. Verified via Phase 0 spikes against active real-world sessions.\n- **Two-stage LLM triage** (Haiku 4.5 today; Sonnet 4.6 escalation lands v0.1.1). Forced `record_triage` tool call returns a structured verdict — severity, category, evidence UUIDs, free-text reasoning. The two-stage pattern is modeled on the cheap-model-triage / strong-model-escalation pattern common in production eval pipelines — Haiku triages every event, Sonnet only re-runs ambiguous medium-severity decisions where the cheap model's confidence is low.\n- **Structured rubric.** A small fixed YAML rubric in v0.1.0; user-editable in v0.1.4. Every category has a deterministic schema (the example: `destructive_action_pending` matching `rm -rf`/`Trash`/`git reset --hard` against non-temp paths).\n- **Redaction in front of every API call.** `Redactor.swift` strips nine pattern families before any string leaves the Mac (Anthropic keys, GitHub tokens in three formats, AWS access-key + secret pairs, JWTs, URLs with embedded credentials, shell-export lines). The Anthropic client refuses to send a request without a redactor wired in — fail-closed by construction.\n\n## Development\n\n```bash\nswift build               # full compile of all 6 targets\nswift test                # 130 tests across SupervisorCore\n./Scripts/build-app.sh    # rebuild + sign all three .app bundles\n```\n\nThe trace log at `~/Library/Logs/Supervisor/supervisor.log` is append-only and rolling (1 MiB segments). Every state transition — onboarding, AX grants, key validation, triage start/end, flag persistence, notifier outcome, heartbeat health — emits a single line with a timestamp and a tag. It's the first thing to look at when something's off.\n\n**Filing an issue.** Useful issues include:\n\n- The last ~50 lines of `~/Library/Logs/Supervisor/supervisor.log` covering the surprising moment.\n- Your macOS version (`sw_vers -productVersion`).\n- What you were doing — what Claude Code action led into the surprise.\n- Whether the surprise was a false positive (Supervisor flagged something safe), false negative (Supervisor missed something destructive), or behavioral (the app misbehaved in a way unrelated to flags).\n\nIf the issue involves an API call going wrong, scrub the trace snippet for anything sensitive before pasting — the redactor handles the API path but the trace log is local-only and isn't redacted by default.\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fsupervisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximizegpt%2Fsupervisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximizegpt%2Fsupervisor/lists"}