agterm: Instructions file for Claude Code

agterm project notes

agterm is a native macOS SwiftUI terminal on libghostty with a workspace-to-session sidebar. Read site/docs.html for product behavior and ARCHITECTURE.md for modules, surface ownership, and C-boundary concurrency before changing the bridge. README.md is the product synopsis, not the reference.

Working norms

• For nonstandard or risky UI requests, first explain the AppKit/SwiftUI cost and offer the standard alternative. Proceed if the user still prefers the custom behavior.
• Design every UI behavior to be consistent and unsurprising: a key or gesture does one thing for what the user is looking at and never reaches a layer hidden behind the visible one. A rule whose exceptions depend on state the user cannot see on screen is a defect: propose the single rule, and ask before adding a case. Existing behavior next to the change that breaks this rule is a defect to fix with it, not a pre-existing one: name it with its fix as a question, never as out of scope. A control that already exists elsewhere in the app (a search bar, a button, a picker) looks and behaves the same in the new place: reuse its component, and show the user the rendered result before writing tests.
• Judge any change that can leave a long-standing visual artifact by what the user is left looking at, never by whether the mechanism is sound. A panel, badge, marker or overlay that outlives the thing it describes is a defect however correct the code that posted it. Give it a way to clear itself, and put that in the control API rather than in a private timer inside one caller, or every other caller ships the same artifact.
• For every new capability, propose useful control API/CLI coverage: protocol command and arguments, dispatch, agtermctl, read-back, and tests. Control-native features count; skip only chrome with nothing meaningful to drive.
• For each hideable titlebar/sidebar element, ask whether it should join host-free InterfaceElement and Settings > Interface. Never add that preference without approval. A control enabled there stays visible and is disabled when it cannot act; never show or hide it by state.
• The HTML overlay displays HTML over a session; it is not a browser. Following links, history and back are the browser's job, so link features that turn the overlay into one are declined. What a mouse-capturing program does with a click is that program's, not agterm's.
• A decline of a feature request that a custom command covers explains the extension model with the request as the worked example: README's "bind X yourself", site/docs.html#extend, the agent skill, the cookbook. It also points "can you add X" requests to Discussions ▸ Ideas instead of issues.
• When adding a process that runs user commands or reparents a session, weigh its effect on macOS TCC attribution per service, up front. The responsible process is not always TCC's authorization subject: the #574 microphone test recorded agterm-session-host as responsible, com.umputun.agterm as the subject, and access allowed. Check each service rather than assuming one answer covers all of them. A passive AXIsProcessTrusted false can also be a stale grant, not a code bug: a stored grant may require a specific old cdhash (an ad-hoc build's requirement is a bare cdhash), so verify the row's full requirement against the running binary before suspecting attribution.
• Start Swift work with the relevant skills: swiftui-expert for UI/AppKit/Observation/rendering, swift-testing-expert for tests, and swift-concurrency for actors, Sendable, async, and C callbacks.
• “Show me” means build and launch a separate interactive Debug instance, not a screenshot. Use isolated state and socket paths, leave it running, and explain how to reach the feature.
• An isolated state dir also redirects config to <stateDir>/config. Copy keymap.conf, ghostty.conf, and restore-denylist.conf when real custom behavior is required. Set only a short /tmp AGTERM_STATE_DIR so app and inherited CLI derive the same socket. Prepend the Debug app's Contents/MacOS to PATH for custom commands; login shells may restore the deployed CLI, so manual commands should use the Debug binary's full path.
• open -n passes the caller's environment to the app, including inherited CLAUDE* markers and live-terminal AGTERM_*/GHOSTTY_* variables; a claude started in that instance warns that transcript saving is off. Launch through env -u NAME ... naming every such variable, which drops AGTERM_STATE_DIR too, so pass the isolated one back with open -n --env AGTERM_STATE_DIR=...; verify with ps eww -p <pid>.
• A fresh isolated state dir reads as a first launch and opens the welcome alert. mkdir -p "$AGTERM_STATE_DIR/windows" before launching to skip it: FirstRunWelcome.hasPriorState looks for settings.json, workspaces.json, or windows before the app writes anything. Leave the marker out only when the welcome itself is under test.
• The control socket binds from the window scene's task, so a backgrounded open -n -g can leave the app running with no socket until a window renders. If the socket is still absent 10 s after launch, activate the instance; never leave a socket wait unbounded.
• agtermctl never reads AGTERM_SOCKET; it resolves --socket, then AGTERM_STATE_DIR, then ~/Library/Application Support/agterm. A shell inside the live terminal therefore defaults onto the live socket, and exporting a short AGTERM_STATE_DIR is what keeps inherited commands off it.
• After launching an instance for manual testing, do not touch it. For an assisted experiment, announce every action. Ask before acting when unclear.
• Put nontrivial work in an isolated worktree and remove it after merge. See the build section for artifact links and cleanup.
• Comments and docs are liabilities kept short. Keep only non-obvious constraints, rejected alternatives, or reasons the obvious implementation fails. Never narrate code, repeat a fact across surfaces, use a paragraph where a clause works, or preserve change history. Own each contract once and cross-reference it. If 25 lines of logic seem to need 100 lines of comment, fix the code.
• A doc comment longer than the body it documents is wrong. The usual cause is writing it to justify a review fix rather than to document the code, which belongs in the commit message.
• Test comments are rare and one line. Add one only when neither the test name nor setup reveals the goal. Never label arrange/act/assert, restate an assertion, or explain why a test exists.
• Review severity follows user-visible consequences: critical for data loss or broken primary paths, major for wrong results or broken secondary paths, minor otherwise. Documentation inaccuracies are never critical or major. Documentation-heavy review findings usually call for less prose.