SPB Git

Repository Public

CLAUDE.md 16.9 KB

# CLAUDE.md — NEXTERM

# Mission

Build NEXTERM, a production-grade, native macOS terminal and agentic development workspace optimized for Claude Code. The result MUST be a real, usable macOS application—not a mockup, web wrapper, or decorative terminal. Use Swift 6, SwiftUI, AppKit where needed, and a high-performance terminal renderer. Make it feel like a premium macOS product.

# Non-negotiable operating rules

  1. Inspect the repository, macOS version, Xcode, Swift toolchain, architectures, installed Claude CLI, codesigning environment, and available build tools before choosing dependencies.
  2. Establish a written implementation plan in docs/PLAN.md, architecture decisions in docs/ADR/, and a live task checklist in docs/PROGRESS.md. Work through tasks rather than stopping after scaffolding.
  3. Verify external library APIs, licensing, maintenance, build compatibility, and integration constraints against their actual source and documentation. Never fabricate API methods, terminal features, Claude Code integration capabilities, or test results.
  4. Prefer a maintained Ghostty terminal integration (libghostty or a verified Swift integration) if technically and legally feasible. Build a minimal proof-of-concept before committing. If unsuitable, evaluate alternatives and document the tradeoff; never fake terminal emulation with a TextEditor or text log.
  5. Use SwiftUI for application shell, AppKit for advanced windows and focus/dragging, and a real PTY-backed terminal implementation. Avoid Electron, browser-based UIs, and unnecessary background services.
  6. Build and run after every meaningful milestone. Resolve compilation, runtime, and integration failures. Never declare success on the basis of code inspection alone.
  7. Do not delete user data, kill unrelated processes, overwrite credentials, expose secrets, or run destructive commands without explicit authorization.
  8. Do not store passwords, API keys, access tokens, or SSH private keys in project files, logs, or plaintext databases. Use Keychain and the system SSH agent.
  9. Keep the project independently usable without any optional MacLustr, AKOS, or AgentOS service.
  10. If a capability is blocked by unavailable hardware, credentials, APIs, or signing identities, report the exact blocker and deliver the highest verified working state instead of claiming completion.

# Product identity

  • Name: NEXTERM
  • Tagline: The Agentic Terminal for macOS
  • Platform: macOS, Apple Silicon first; support Intel only if practical and tested.
  • Primary user: a developer operating many Claude Code sessions and remote Mac nodes simultaneously.
  • Visual direction: refined native dark/light macOS aesthetic; precise typography, restrained accents, minimal chrome, responsive animations, high information density, and excellent accessibility.
  • Deliverables: Xcode project, source code, automated tests, documentation, build scripts, and a runnable .app bundle.

# Product requirements

# 1. Real terminal foundation — P0

Implement real local shell sessions backed by macOS pseudo-terminals. Support interactive programs, correct stdin/stdout/stderr behavior through the PTY, resizing and SIGWINCH, scrollback, Unicode, wide characters, combining characters, ANSI/VT escape sequences, alternate screen, cursor movement, bracketed paste, mouse input where supported, keyboard modifiers, selection, clipboard, search, and shell exit status. Validate with zsh, bash, vim/neovim, top/htop where installed, tmux, git, and Claude Code. Confirm terminal renderer behavior using repeatable test fixtures.

Terminal rendering should remain responsive under continuous output. Ensure UI updates do not block the main thread. Treat shell output as untrusted data; terminal escape sequences must never be interpreted as application commands.

# 2. Infinite Workspace — P0

Create a robust tree-based pane layout model supporting horizontal and vertical splits, nested layouts, drag-to-resize, close, swap, move, maximize/restore, and keyboard navigation. Support multiple tabs, independent macOS windows, multiple physical displays, full-screen and native macOS Spaces. A pane must be movable between windows without accidentally killing its underlying process.

Use stable IDs for windows, tabs, panes, sessions, and processes. Decouple terminal session ownership from UI view lifetime. A layout edit must not recreate the PTY or reset the shell.

# 3. Persistence and recovery — P0

Persist workspaces, window geometry, display associations when available, tab and pane topology, working directories, connection profiles, appearance, and user preferences in a versioned local SQLite database. Restore layouts gracefully if an external monitor is missing. Never claim a local process can survive application termination without an explicit persistent session backend. Offer optional tmux-backed sessions for genuine reattachment, with clear status and reconnect behavior.

# 4. Claude Code native experience — P1

Launch the official installed claude CLI in ordinary PTY sessions, respecting the user's existing authentication and configuration. Detect CLI availability and version, display setup guidance when missing, and never silently install or modify Claude Code. Preserve full interactive CLI functionality.

Provide a Claude Session Inspector with session identity, project directory, terminal association, process status, and explicit user-provided labels. Add optional documented Claude Code hooks for supported events (such as notifications, tool activity, or session lifecycle, subject to current official API verification). Hooks must be opt-in, validated, reversible, and scoped to the app where possible. Do not infer agent state solely from terminal text or claim unsupported access to Claude internals.

Display permission requests only when reliably detected via a supported integration. Never auto-approve destructive or sensitive tool calls. Notifications must deep-link to the correct pane and preserve the user's ability to make the decision in the original Claude Code interface.

# 5. Mission Control — P1

Create a native dashboard showing active local and remote sessions, project, machine, session status, last observed activity, and alerts. Distinguish verified telemetry from heuristic estimates. Add filters, search, favorites, grouping by project/node, and one-click navigation to an existing pane. Use accessible status indicators; never rely on color alone.

# 6. SSH and MacLustr — P1

Support secure SSH connections to user-configured hosts, leveraging OpenSSH and the existing SSH agent/config where possible. Provide host discovery from authorized SSH config entries, host-key verification, reconnect handling, remote working directory, and tmux reattachment. Do not bypass host-key checks or accept unknown hosts automatically. Support multiple concurrent remote terminals and distinguish remote sessions clearly.

MacLustr is an optional named host group, not a hardcoded infrastructure assumption. Do not invent hostnames, credentials, ports, or node counts. Allow user-defined node labels and tags, and make the UI usable without remote connectivity.

# 7. Git and parallel development — P1

Integrate Git repository status, branch, changed files, diff viewer, commit history, and worktree management. Use Git CLI as the source of truth. Provide safe creation of per-agent worktrees, clear branch-to-session mapping, and conflict visibility. Never auto-merge, force-push, reset, clean, or delete a worktree containing uncommitted changes. Confirm dangerous operations.

# 8. Professional terminal features — P1

Implement command history search where legitimately available, configurable keybindings, themes, font family/size, ligatures where renderer supports them, zoom, scrollback limits, find-in-terminal, copy as text, paste protection for multiline commands, clickable file paths/URLs with safe validation, and configurable bell/notifications. Offer privacy-aware optional command metadata only when explicitly enabled.

# 9. Multi-monitor Command Center — P1

Provide saved layouts for laptop-only, dual-monitor, and three-monitor arrangements. Allow one display for terminal grids, another for Claude Mission Control, and another for Git/diffs or project files. Support independent fullscreen windows, monitor hot-plugging, and restoration when display topology changes. Test with actual available monitors; simulate topology changes only for unit tests, not as proof of hardware behavior.

# 10. Extensibility — P2

Design stable internal protocols for optional integrations with AgentOS, AKOS, and other services, without requiring them. Document extension points and security boundaries. Do not build remote-control agents, browser automation, or server-side orchestration as prerequisites for the local app.

# Suggested architecture

  • NEXTERMApp: SwiftUI app lifecycle, commands, settings, menus.
  • WorkspaceCore: pane layout tree, tabs, windows, session registry, restoration.
  • TerminalCore: PTY lifecycle, terminal renderer adapter, keyboard/input bridge, output buffering.
  • ClaudeIntegration: CLI discovery, launch profiles, optional verified hooks, notifications.
  • RemoteCore: SSH profiles, connection state, tmux attach/reconnect.
  • GitCore: repository status, diffs, worktrees, safety checks.
  • PersistenceCore: SQLite schema, migrations, settings.
  • MissionControl: observable session projections and dashboards.
  • DesignSystem: reusable native controls, typography, themes, accessibility.
  • NEXTERMTests: unit, integration, UI, performance, and regression tests.

Keep modules cohesive and avoid premature distributed architecture. Prefer structured concurrency with Swift actors for process/session state. Keep observable UI state on the main actor. Use dependency injection and protocols to test without launching real remote connections.

# Interaction design

Create a compact sidebar for workspaces, projects, hosts, and Claude sessions; a tab strip; a central split-pane terminal canvas; an optional right inspector for session details and Git; and a bottom status area for host, branch, shell, activity, and connection health. All panels should be dismissible. Focus mode should hide nonterminal chrome. Provide command palette, keyboard-first navigation, and drag-and-drop where safe.

Core shortcuts (make configurable and resolve conflicts with shell applications): new tab, new window, split horizontal, split vertical, focus next pane, maximize pane, command palette, Mission Control, and workspace switcher. Clearly document the defaults in docs/SHORTCUTS.md.

# Performance and quality gates

Measure, do not invent, cold launch time, terminal input latency, sustained output throughput, memory consumption per pane, CPU at idle, workspace restoration time, and responsiveness with 1, 4, 8, 16, and 32 sessions where the test machine permits. Use Instruments or equivalent profiling tools when available. Record hardware, macOS, build configuration, workload, measured results, and limitations in docs/PERFORMANCE.md.

Test heavy output, rapid pane creation/closure, resize storms, session exits, SSH drops, tmux detach/attach, external display disconnects, app restart, invalid settings, Unicode, alternate-screen applications, and repeated Claude Code sessions. Fix memory leaks, stale observers, process ownership bugs, and UI deadlocks before declaring release-ready.

# Security requirements

  • Respect macOS sandbox/entitlement and process-spawning constraints; document distribution implications.
  • SSH host-key verification is mandatory.
  • Never store raw credentials or shell environment secrets in telemetry.
  • Avoid logging terminal contents by default.
  • Opt-in diagnostic logs with redaction and rotation.
  • Confirm before executing pasted multiline text when configured.
  • Escape/validate filenames and URLs; use argument arrays rather than unsafe shell string concatenation.
  • Require confirmation for destructive Git actions and process termination.
  • Make hooks removable and avoid modifying global Claude configuration without explicit consent.
  • Do not ship a hardcoded password, backdoor, remote command endpoint, or undisclosed telemetry.

# Delivery phases

# Phase 0 — Discovery and technical spike

Inspect machine and repository; verify terminal engine integration and license; prove that a native window can host a real terminal with PTY, keyboard input, resizing, and interactive shell. Build and launch this spike. Document evidence and blockers.

# Phase 1 — Usable terminal MVP

Implement real terminal sessions, tab management, nested split panes, focus handling, close semantics, keyboard shortcuts, window management, appearance, and clipboard. Build and test. This is the first non-negotiable functional milestone.

# Phase 2 — Workspace system

Implement persistent layout tree, session registry independent of views, multiple windows, multi-display geometry recovery, workspace templates, and robust restoration. Validate lifecycle and recovery tests.

# Phase 3 — Claude Code integration

Implement CLI discovery, interactive Claude sessions, session labeling, verified optional hook events, native notifications, and Mission Control. Validate against the installed CLI and actual documented behavior.

# Phase 4 — SSH, tmux, Git

Implement secure remote sessions, reconnect, worktree creation, Git status/diffs, and safe branch/session association. Validate local and authorized remote workflows.

# Phase 5 — Polish and release

Add accessibility, settings, command palette, search, performance profiling, crash recovery, documentation, tests, packaging, and optional signing/notarization if credentials are available.

# Mandatory acceptance tests

  1. Launch a local zsh shell and interact with it normally.
  2. Run an interactive terminal application correctly, including resize behavior.
  3. Open 8 independent terminal panes; type in each without cross-session leakage.
  4. Move a live pane to a different window without restarting its process.
  5. Restore a saved workspace layout after restarting the app.
  6. Demonstrate that restoration distinguishes layout restoration from process reattachment.
  7. Launch installed Claude Code interactively without modifying its authentication.
  8. Create and use two separate Git worktrees in separate terminal panes.
  9. Connect to an explicitly authorized SSH host and verify host-key handling, when such a host is available.
  10. Recover gracefully from an SSH disconnect and a missing external monitor.
  11. Pass unit tests, integration tests, UI smoke tests, and a clean Release build.
  12. Produce an actual .app bundle and verify that it launches on the build machine.

For every acceptance test, mark PASS, FAIL, or BLOCKED with the exact reproduction steps and evidence. Never mark unavailable external hardware, signing identities, or credentials as PASS.

# Deliverable structure

text
NEXTERM/
  CLAUDE.md
  NEXTERM.xcodeproj (or a verified generated Xcode project)
  Sources/
  Tests/
  Resources/
  Scripts/
  docs/
    PLAN.md
    PROGRESS.md
    ARCHITECTURE.md
    PERFORMANCE.md
    SHORTCUTS.md
    SECURITY.md
    RELEASE.md
    ADR/
  README.md

# Working protocol for Claude Code

At the beginning of each execution session:

  1. Read this entire file, docs/PLAN.md, and docs/PROGRESS.md.
  2. Inspect current repository state and available tools.
  3. Select the highest-priority unfinished milestone and implement it end-to-end.
  4. Run the smallest relevant test suite, then a complete build at milestones.
  5. Update progress with exact verified outcomes, blockers, and next steps.
  6. Continue through phases when feasible; do not stop after producing a plan or mock UI.

Before final response, provide a concise implementation report: files changed, features demonstrated, commands used for verification, test results, app bundle path, unresolved issues, and exact next action. Never say the app is complete unless all mandatory acceptance criteria that can be tested have passed and the remaining limitations are explicitly disclosed.

# Definition of done

NEXTERM is done only when it is a genuinely usable native macOS terminal with reliable PTY rendering, multiple panes and windows, safe session ownership, persistent workspaces, working Claude Code launch, documented security behavior, passing tests, and a verified runnable app bundle. Advanced integrations may remain optional, but must never be represented as implemented if only planned.

# Project-specific notes (added by the implementation)

  • Project location on this Mac: ~/Desktop/Cluster/apple/NEXTERM. The Xcode project is generated with xcodegen generate from project.yml; never edit NEXTERM.xcodeproj by hand.
  • Logic modules live in the local Swift package NEXTERMKit/ (swift test --package-path NEXTERMKit runs them without Xcode). The app target is Sources/NEXTERM.
  • Terminal engine: SwiftTerm 1.99.2 (MIT). See docs/ADR/0001-terminal-engine.md for the libghostty spike result.
  • Signing: Developer ID Application (team 3YM54G49SN); notarization keychain profile MacLustr-Notarize. See docs/RELEASE.md and Scripts/release.sh.
Files main
Menu

Theme