AgentBar: Instructions file for Claude Code

AgentBar — AI Instructions

Context for AI coding assistants working on this repository.

Project

AgentBar is a native macOS status app (Swift, AppKit, SPM) showing live status of AI coding agents (Claude Code & Cowork, Codex, Cursor, Gemini, Copilot, Antigravity, Qwen Code, OpenCode, Devin). Node.js hook scripts in Scripts/hooks/ write per-session JSON to ~/.agentbar/state.d/; the app watches that folder. Cloud-only runs (Cursor cloud agents, Devin, Codex cloud) have no hook to install: the optional external poller in Scripts/cloud/ writes the same rows with entrypoint: "cloud". It presents itself as a menu bar item, a Dynamic Island panel under the notch, or both — the user picks in the welcome window. State file protocol (normative): docs/protocol.md; original design spec (a 1.0.0 snapshot, read its header note): docs/specs/2026-07-23-agentbar-design.md; presentation modes: docs/plans/2026-07-28-presentation-modes-and-island.md.

Build & run

./Scripts/build.sh          # builds build/AgentBar.app
open "build/AgentBar.app"

Rules

1. One file, one responsibility — keep the unit layout from the spec; don't grow a god-object controller.
2. Stay out of the way: no dock icon, no heavy dependencies, nothing that unfolds over the screen on its own. Two surfaces only — the menu bar item (StatusItemController) and the island (IslandController) — both fed from the same stores through MascotDriver / AgentActions; never render one from the other's code. Native notifications are the one thing that may appear over the screen, and three conditions earn it, not one: the user switched them on (off by default, like sounds), the banner is the system's surface rather than one AgentBar draws, and what is being announced either wants an answer or happened while the user was away. That last one is a rule, not a preference — 1.17.0 fired on every done, Claude Code enters done after every turn, and a fifty-turn conversation posted fifty banners. An agent finishing is not news. See Notifier. Approvals on the phone (PhoneRelay) are a surface off the Mac and the one thing that sends work off it, so they are fenced harder than banners: off until switched on in Settings ▸ Phone (no link, rule or agent output may), only what wants an answer, by default only while the person is away, Allow only with a shell command that went along whole and readable, and that reaches nothing BlastRadius calls high (everything else is Deny or the Mac), and a reply answers exactly the one request its push was for, once. A tap is the person's own answer through AgentActions.answer, written via: "phone" — a click made elsewhere, not a rule 3 exception. Windows are the exception, not the pattern: only WelcomeWindow, SettingsWindow and WrapWindow (Your Day), all small, all opened by the user — Your Day from a menu row or an agentbar://day|week|month link, never on a schedule: a recap nobody asked for is a window unfolding on its own. A Replay (ReplayTurn, WrapWindow+Replay) plays inside that same window and only from a click — a row's Replay Last Turn… or Your Day's Share menu — never from a link or a turn ending. UpdatePrompt answers a click on Check for Updates… (the click closes the menu that would have shown the answer) and nothing else: the daily check and the automatic install never open it. Settings is a sidebar of pages (SettingsChrome is its furniture), not a scroll: a new preference joins a page or earns one, and never lengthens a column until the last section falls off the screen. The approval queue (IslandController+Queue) is the island taking the keyboard on a deliberate shortcut (off until switched on), the way a note does: never when a request arrives, and it hands the keys back on Esc, an empty queue, or the panel losing focus. Return on a far-reaching request is held like the button (HoldButton); nothing in it answers without a key pressed. LauncherPanel is the third surface and the only one summoned by a keystroke. It earns that by the same test the banners do: it takes no space until asked, it appears only on a deliberate keypress, a menu click (Continue in…, the Handoff of a session to another agent, is one), or an agentbar://new-task link (Shortcuts, Raycast — see URLCommands; a link only fills it in, Return is still yours), and it closes the instant it loses focus. No link may approve, deny, answer, defer, write a rule or change a setting: any web page can open one. A surface that can appear without being asked for, or that stays once you look away, does not belong here. The Claude Code mod's band (Scripts/mods/claude) is drawn by Claude Code inside its own terminal, not by AgentBar, and only earns its line the same way: off unless the person turns it on (mods/config.json), one line, only while another session waits on them, gone the moment none does — and its one button focuses that session, never answers it. The mod itself observes and answers nothing (see SECURITY.md); a hook in it that returned anything but next's result would be a rule 3 violation, not a feature. Take a break (BreakGame, HuntGame, IslandController+Game) is the island itself, opened into one of two small games (GameChoice: the space bugs, or Bug Hunt) — not a new surface — and only from a click on the island's ⋯ menu or its joystick. Both are IslandGames under the same contract. It takes the keyboard the way a denial note does and gives it back on Esc or Close; it pauses the moment the panel loses the keyboard, and it steps aside the instant something new waits on the person, showing the rows with that request in them. Closed, paused or yielded, its clock does not run. The Office (Office, OfficeView) opens the same way and is under the same contract, but it is no game: a desk for each session on screen, everyone in the pose they are in, no score. It makes one exception to the yield, and only one: a session that already has a desk and starts waiting raises its hand there instead of stepping the room aside, because the hand is the signal and the pill still turns amber. Anything waiting from a session without a desk steps it aside, as it would a game (Office.yields). A click on a desk leads somewhere and answers nothing. On a raised hand it closes onto the rows with that request in them, and never focuses the session, because a focus defers the request. On any other desk it brings that terminal forward. RuleSheet is a sheet on Settings, not a fourth surface: it is modal to a window the user already opened and it closes when it is answered. Keep Mac Awake (KeepAwake) is the cup in the island's footer and a row in the shared menu, not a surface: it changes how the Mac sleeps, so a click, its shortcut (off until switched on) or a trigger the person set up turns it on, and no link may. Since 1.51.0 the triggers in Settings ▸ Awake Triggers — an agent working, the charger, an external display, an app running, an app asking macOS to stay awake — may start it without a click, the way a rule the human wrote may answer: each is off until switched on there, every hold names its trigger in the menu and the cup's tooltip, turning it off snoozes the trigger until its condition goes away, and no link, rule or agent output can create one (KeepAwakeTriggers). Its closed-lid mode — the one root command in the app — asks for the password inside a click and never on its own, never from a trigger or the shortcut (SECURITY.md). Hand a file to an agent (DropToAgent) is the one place AgentBar puts text into a terminal, and it is fenced the way keystroke approval is: only on a drop the person made, only the dropped paths (escaped, no line breaks), pasted only into a tab TerminalFocus verified, and never a Return — anywhere else it copies and says ⌘V. The screenshot chip (ScreenshotShelf) lives only inside an island that is already open, and is off until switched on, because reading the screenshot folder is what macOS asks permission for.
3. AgentBar answers nothing by itself — only what the user wrote down. For six releases the rule was absolute: every decision came from a click, and DecisionLedger said so in three places. Since 1.28.0 one thing answers without a click, and the amendment is deliberate, the way 1.18.0's was for notifications: a rule the human typed in Settings ▸ Rules may answer a permission request, and four conditions earn that, not one. The rule was written by the person and never derived from anything the agent produced (a ruleSuggestion may never become one); every firing writes a ledger row naming the rule, so what a rule did is a question with an answer; a rule that refuses may be broad while a rule that approves names one directory; and before any approval is written the live command is checked again, not its shape — RuleEngine.refusal(for:). That table may only ever grow, it has no setting, and anything it does not understand falls through to the human. The whole feature is one guard away from the product that existed before it: no match, a malformed rules file, a command that will not tokenise, and nobody answers. Allow all N (ApprovalBatch) is a click, not a rule: it answers only the identical requests on screen when it was drawn, each as the person's own row. Try an approval (DemoApproval) is a request on screen only — it answers nothing because nothing waits on it. A rule has three modes and the middle one is the point: watching matches, works out the answer, writes it down and answers nothing, so an approving rule can be judged on a week of what it would have done before it speaks. New rules start there. Rules own a Settings page (RulesView, RuleSheet), and that sheet spends most of its room on the rule's edges rather than on its fields.
4. Hooks must never block the host agent: async, atomic writes, exit fast. Sole exception: permission.js blocks while the session is already waiting on the human, and must always time out silently to the normal terminal prompt.
5. Adding an agent: entry in Agents.swift, sprite in Sources/AgentBar/Sprites/, optional hook dir in Scripts/hooks/<agent>/ plus its installer step in HookInstaller.swift AND the Linux CLI's install-hooks, and the agent id in the docs/protocol.md list, the README agent table, and the agent list above. If it gets hooks it also needs a row in the Diagnostics.integrations table AND the Linux doctor's — otherwise diagnostics reports a clean bill of health for an integration it never looked at — and its events in HookWiring.swift, the CLI's HOOK_WIRING and Tests/Fixtures/hook-wiring/cases.json, the one table each installer writes from and each doctor checks against. Nothing else should need touching. An agent without an entry renders generically (a monogram plus its agent_name), so a third-party bridge via agentbar report needs none of the list above.
6. Third-party marks stay listed in THIRD_PARTY_NOTICES.md.