agterm CLAUDE.md

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.
• 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.
• 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.
• 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. Activate the instance when the socket never appears.
• 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.