{"id":49811376,"url":"https://github.com/rob-balfre/notch-agents","last_synced_at":"2026-05-13T01:16:08.367Z","repository":{"id":348117000,"uuid":"1196493515","full_name":"rob-balfre/notch-agents","owner":"rob-balfre","description":"Native macOS notch overlay showing live Codex and Claude agent status","archived":false,"fork":false,"pushed_at":"2026-03-30T20:45:32.000Z","size":53,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T22:22:23.358Z","etag":null,"topics":["experimental","macos","menubar","notch","swift"],"latest_commit_sha":null,"homepage":null,"language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rob-balfre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-03-30T18:51:48.000Z","updated_at":"2026-03-30T20:45:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rob-balfre/notch-agents","commit_stats":null,"previous_names":["rob-balfre/notch-agents"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rob-balfre/notch-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob-balfre%2Fnotch-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob-balfre%2Fnotch-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob-balfre%2Fnotch-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob-balfre%2Fnotch-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rob-balfre","download_url":"https://codeload.github.com/rob-balfre/notch-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rob-balfre%2Fnotch-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32963331,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"ssl_error","status_checked_at":"2026-05-12T23:30:18.191Z","response_time":102,"last_error":"SSL_read: 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":["experimental","macos","menubar","notch","swift"],"created_at":"2026-05-13T01:16:07.133Z","updated_at":"2026-05-13T01:16:08.359Z","avatar_url":"https://github.com/rob-balfre.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!WARNING]\n\u003e **Experimental** — This project is in early development. APIs, behaviour, and visual design may change without notice.\n\n# NotchAgents\n\nNative macOS overlay that extends the black of a MacBook Pro notch and shows Codex on the left and Claude on the right. Each side renders a live state indicator:\n\n- spinner while work is running\n- tick when work has finished recently\n- question bubble when input is required\n- count badge when more than one task is active for the same agent\n\nThe app reads live local state directly from Codex and Claude when it can, and the companion CLI can still inject or override richer task metadata.\n\n## Build the app bundle\n\n```bash\n./scripts/install-app.sh\n```\n\nThat creates:\n\n```text\nbuild/NotchAgents.app\n```\n\nIt also installs:\n\n```text\n~/Applications/NotchAgents.app\n~/.local/bin/notchagentsctl\n```\n\nTo build and launch it immediately:\n\n```bash\n./scripts/install-app.sh --open\n```\n\n## Live detection\n\nThe app now refreshes primarily from filesystem events instead of a hot polling loop.\n\nCodex state is watched from:\n\n- `~/.codex/state_5.sqlite`\n- `~/.codex/.codex-global-state.json`\n- `~/.codex/sessions/**/rollout-*.jsonl`\n\nClaude state is watched from:\n\n- `~/.claude/tasks`\n- `~/.claude/sessions`\n- `~/.claude/projects`\n\nClaude Code hooks are also installed into `~/.claude/settings.json` and write directly into the NotchAgents status snapshot through:\n\n- `~/.local/bin/notchagentsctl claude-hook`\n\nIf that state is unavailable or ambiguous, the app falls back to root-process detection for `codex`, `claude`, and `claude-code`.\n\n## Publish task state\n\nStart a task:\n\n```bash\nnotchagentsctl start --agent codex --id feature-123 --title \"Build notch overlay\"\n```\n\nMark it as needing an answer:\n\n```bash\nnotchagentsctl ask \\\n  --agent claude \\\n  --id review-9 \\\n  --title \"Review overlay polish\" \\\n  --question \"Ship the current visual treatment?\" \\\n  --url \"https://example.com/thread/review-9\"\n```\n\nFinish it:\n\n```bash\nnotchagentsctl finish --agent codex --id feature-123 --title \"Build notch overlay\"\n```\n\nWrap a real command so the app tracks it automatically:\n\n```bash\n./scripts/run-agent-task.sh \\\n  codex \\\n  feature-123 \\\n  \"Build notch overlay\" \\\n  -- \\\n  codex run\n```\n\nRemove it entirely:\n\n```bash\nnotchagentsctl remove --agent codex --id feature-123\n```\n\nInspect the current snapshot:\n\n```bash\nnotchagentsctl show\n```\n\nInspect only the live inferred state:\n\n```bash\nnotchagentsctl live\n```\n\nInspect the merged live + manual state:\n\n```bash\nnotchagentsctl merged\n```\n\nWrite sample data:\n\n```bash\nnotchagentsctl sample\n```\n\nClear everything:\n\n```bash\nnotchagentsctl clear\n```\n\n## Status file\n\nTask state is stored at:\n\n```text\n~/Library/Application Support/NotchAgents/status.json\n```\n\nThe overlay merges live agent state with anything you publish to the status file. Explicit status entries and Claude hook updates override inferred live entries when they use the same task id.\n\n## Interaction\n\n- Click an agent pill to open its `actionURL` when one exists.\n- Click anywhere else on the notch wings to open the monitor window.\n- Right-click either wing for refresh, sample data, reveal status file, and quit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frob-balfre%2Fnotch-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frob-balfre%2Fnotch-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frob-balfre%2Fnotch-agents/lists"}