# 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.