native macOS codings agent orchestrator
docs: refresh architecture and ssh notification notes
+42
-9
+23
-7
AGENTS.md
+23
-7
AGENTS.md
···
31
31
32
32
```
33
33
AppFeature (root TCA store)
34
-
├─ RepositoriesFeature (repos + worktrees)
34
+
├─ RepositoriesFeature (repos, worktrees, PR state, archive/delete flows)
35
35
├─ CommandPaletteFeature
36
-
├─ SettingsFeature (appearance, updates, repo settings)
36
+
├─ SettingsFeature (general, notifications, coding agents, shortcuts, github, worktree, repo settings)
37
37
└─ UpdatesFeature (Sparkle auto-updates)
38
38
39
39
WorktreeTerminalManager (global @Observable terminal state)
···
42
42
└─ TerminalTabManager (tab/split management)
43
43
└─ GhosttySurfaceState[] (one per terminal surface)
44
44
45
-
GhosttyRuntime (shared singleton)
45
+
WorktreeInfoWatcherManager (global worktree watcher state)
46
+
├─ HEAD watchers per worktree
47
+
└─ debounced branch / file / pull request refresh events
48
+
49
+
GhosttyRuntime (shared runtime)
46
50
└─ ghostty_app_t (single C instance)
47
51
└─ ghostty_surface_t[] (independent terminal sessions)
48
52
```
···
57
61
Reducer ← .terminalEvent(Event) ← AsyncStream<Event>
58
62
```
59
63
60
-
- **Commands**: `createTab`, `closeFocusedTab`, `prune`, `setSelectedWorktreeID`, etc.
61
-
- **Events**: `notificationReceived`, `tabCreated`, `tabClosed`, `focusChanged`, `taskStatusChanged`
62
-
- Wired in `supacodeApp.swift`, subscribed in `AppFeature.task`
64
+
- **Commands**: tab creation, initial-tab setup, blocking scripts, search, Ghostty binding actions, tab/surface closing, notification toggles, and lifecycle management
65
+
- **Events**: notifications, dock indicator count changes, tab/focus changes, task status changes, blocking-script completion, command palette requests, and setup-script consumption
66
+
- Wired in `supacodeApp.swift`, subscribed in `AppFeature.appLaunched`
67
+
68
+
Worktree metadata refresh uses `WorktreeInfoWatcherClient` in parallel:
69
+
70
+
```
71
+
Reducer → worktreeInfoWatcher.send(Command) → WorktreeInfoWatcherManager
72
+
↓
73
+
Reducer ← .repositories(.worktreeInfoEvent(Event)) ← AsyncStream<Event>
74
+
```
75
+
76
+
- **Commands**: `setWorktrees`, `setSelectedWorktreeID`, `setPullRequestTrackingEnabled`, `stop`
77
+
- **Events**: `branchChanged`, `filesChanged`, `repositoryPullRequestRefresh`
78
+
- Wired in `supacodeApp.swift`, subscribed in `AppFeature.appLaunched`
63
79
64
80
### Key Dependencies
65
81
···
78
94
79
95
## Code Guidelines
80
96
81
-
- Target macOS 26.0+, Swift 6.2+
97
+
- Target macOS 26.0+, Swift 6.0
82
98
- Before doing a big feature or when planning, consult with pfw (pointfree) skills on TCA, Observable best practices first.
83
99
- Use `@ObservableState` for TCA feature state; use `@Observable` for non-TCA shared stores; never `ObservableObject`
84
100
- Always mark `@Observable` classes with `@MainActor`
+19
-2
docs/ssh-notifications-over-ssh.md
+19
-2
docs/ssh-notifications-over-ssh.md
···
4
4
5
5
Show Supacode notifications when a coding agent is running on a remote machine over `ssh`.
6
6
7
+
## Status
8
+
9
+
This is still a design doc, not shipped behavior.
10
+
11
+
The current codebase remains socket-only for agent hooks:
12
+
13
+
- `AgentHookSettingsCommand` only generates Unix-socket commands
14
+
- `ClaudeHookSettings` and `CodexHookSettings` only install those socket commands
15
+
- there is no `SUPACODE_REMOTE_NOTIFICATIONS`, `SSH_CONNECTION`, or `SSH_TTY` transport switch in the app
16
+
7
17
## Decision
8
18
9
19
This is feasible.
···
53
63
54
64
- `supacode/Features/Terminal/Models/WorktreeTerminalState.swift`
55
65
- `supacode/Features/Settings/BusinessLogic/AgentHookSettingsCommand.swift`
66
+
- `supacode/Features/Settings/BusinessLogic/ClaudeHookSettings.swift`
67
+
- `supacode/Features/Settings/BusinessLogic/CodexHookSettings.swift`
56
68
- `supacode/Infrastructure/AgentHookSocketServer.swift`
57
69
58
70
The installed hook commands send either busy-state updates or raw JSON payloads to a local Unix domain socket under `/tmp/supacode-<uid>/pid-<pid>`.
···
65
77
66
78
## Existing Signals In The Repo
67
79
68
-
There is already a local helper for the terminal-notification path:
80
+
There are already local helpers for the terminal-notification path:
69
81
70
82
- `bins/osc9-notify.sh`
83
+
- `bins/osc777-notify.sh`
71
84
72
-
There are already tests that verify the deduplication behavior between hook notifications and OSC notifications:
85
+
There are already tests that verify command generation, desktop notification delivery, and deduplication behavior:
73
86
87
+
- `supacodeTests/GhosttySurfaceBridgeTests.swift`
74
88
- `supacodeTests/AgentBusyStateTests.swift`
89
+
- `supacodeTests/AgentHookCommandTests.swift`
75
90
76
91
This means the local app side is already prepared to accept terminal-originated notifications and coalesce them against richer hook notifications.
77
92
···
103
118
### Implementation shape
104
119
105
120
Add a second hook command builder that emits terminal notifications instead of writing to the local socket.
121
+
122
+
The current command-generation choke point is `AgentHookSettingsCommand`. `ClaudeHookSettings` and `CodexHookSettings` only embed those generated commands into their respective settings files, so the remote path should be added there rather than duplicated per agent.
106
123
107
124
The hook command should:
108
125