SPB Git

Repository Public

PLAN.md 3.2 KB

# NEXTERM — Implementation plan

Target: a native macOS terminal + agentic workspace (see CLAUDE.md). This plan is the ordered list of milestones; docs/PROGRESS.md tracks verified state.

# Environment (inspected 2026-11-01)

Item Value
Machine MacBook Pro, Apple M5 Max, 18 cores, 48 GB
macOS 27.0 (26A5425a)
Xcode / Swift Xcode 27.2 (27B52), Swift 6.4.2, SDK macOS 26
Displays 5120×2880 external (main) + built-in 3456×2234
Claude CLI /opt/homebrew/bin/claude 2.1.316 (--session-id, --settings <file-or-json> available)
Signing Developer ID Application: Simon-Pierre Boucher (3YM54G49SN); Apple Development identities
Notarization notarytool keychain profile MacLustr-Notarize (history: MacLustr-5.0.0.dmg Accepted 2026-09-29)
Tools xcodegen 2.45.4, git 2.x, tmux (brew, installed for tests), sqlite 3.54, zig 0.17 (spike only)
Known toolchain issue Xcode 27.2 CoreDevice/CoreSimulator plug-ins fail to load on macOS 27.0 — noise only, macOS builds succeed

# Architecture (see docs/ARCHITECTURE.md)

  • NEXTERMKit/ Swift package, Swift 6 strict concurrency: WorkspaceCore (layout tree, models) · TerminalCore (SwiftTerm adapter, sessions, registry) · PersistenceCore (SQLite) · GitCore · RemoteCore · ClaudeIntegration.
  • Sources/NEXTERM/ SwiftUI + AppKit app: workspace controller, windows, tabs, pane canvas, sidebar, inspector, Mission Control, settings, command palette, design system.
  • Xcode project generated by xcodegen from project.yml.

# Milestones

# Phase Scope Exit criteria
0 Discovery & spike Toolchain inspection, engine ADR, PTY proof in a native window Build + launch + typed command round-trips (DONE)
1 Terminal MVP Sessions, tabs, nested splits, focus, close semantics, shortcuts, windows, appearance, clipboard, find Acceptance tests 1–3 pass
2 Workspace system SQLite persistence, session registry independent of views, multi-window, pane move across windows, display recovery, templates Acceptance 4–6 pass
3 Claude Code CLI discovery, interactive sessions, labels, opt-in verified hooks via --settings, notifications, Mission Control Acceptance 7 pass
4 SSH, tmux, Git ssh config hosts, host-key handling, reconnect, tmux attach, git status/diff/log/worktrees with safety Acceptance 8–10 (9/10 BLOCKED if no host)
5 Polish & release Accessibility, settings, palette, perf measurements, docs, tests, Release build, Developer ID signing, notarization Acceptance 11–12 pass; notarized DMG

# Key design rules

  • Session ownership: SessionRegistry owns TerminalSessions; SwiftUI only reparents the long-lived NSView. Layout edits never touch the PTY.
  • Stable IDs for workspace/window/tab/pane/session/split.
  • Restoration = re-creating processes from saved profiles (cwd, kind). Only tmux-backed and claude --resume sessions reattach; the UI says which.
  • Claude hooks: scoped per launch through claude --settings <nexterm-hooks.json> (verified CLI flag), never by editing ~/.claude/settings.json.
  • All child processes are launched with argument arrays; no shell string concatenation.
Files main
Menu

Theme