# bailycase/shepherd architecture

> Architecture diagram of the GitHub repository bailycase/shepherd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bailycase/shepherd
- Repository: https://github.com/bailycase/shepherd

## Overview

Shepherd is a native macOS supervisor for pi coding agents: the user organizes agents in spaces, starts and selects them, and works in their live terminal panes while monitoring status. The main runtime path runs through the app’s view model and terminal-session manager to the in-process session server and PTY processes. Separate branches cover extension-driven status and pane control, automations, fleet search, and optional remote access. The README documents these capabilities; sampled excerpts confirm key session, PTY, protocol, and search behavior, but not every app-to-server call.

Main entry points: [`Sources/ShepherdSessions/SessionServer.swift`](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/SessionServer.swift) (Session server), [`Sources/ShepherdApp/ShepherdViewModel.swift`](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel.swift) (Workspace model), [`Sources/ShepherdSessions/PTYSession.swift`](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/PTYSession.swift) (PTY session), [`Sources/ShepherdProtocol/ExtensionMessage.swift`](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdProtocol/ExtensionMessage.swift) (Extension protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_root["App interface<br/>[RootView.swift]"]
  node_viewmodel["Workspace model"]
  node_creation["Agent creation"]
  node_terminalstore["Terminal sessions"]
  node_surface["Terminal surface"]
end

subgraph group_runtime["Agent runtime"]
  node_server["Session server"]
  node_pty["PTY session<br/>[PTYSession.swift]"]
  node_pi["pi agent"]
  node_screen["Screen replay"]
  node_state[("Workspace state<br/>[StateStore.swift]")]
  node_core["Domain model<br/>[Models.swift]"]
end

subgraph group_extensions["Pi extensions"]
  node_extensionproto["Extension protocol"]
  node_status["Status extension<br/>[shepherd-status.ts]"]
  node_namer["Naming extension<br/>[shepherd-namer.ts]"]
  node_panes["Pane tools<br/>[shepherd-panes.ts]"]
  node_pi_theme_ext["Theme extension<br/>[shepherd-theme.ts]"]
end

subgraph group_remote["Remote access"]
  node_remoteclient["Remote client"]
  node_remotehost(("Remote Mac"))
end

subgraph group_features["Supervision features"]
  node_automations["Automations"]
  node_search["Transcript search"]
  node_themes["Pi themes"]
end

node_user(("User"))

node_user -->|"uses"| node_root
node_root -->|"forwards actions"| node_viewmodel
node_viewmodel -->|"creates agents"| node_creation
node_creation -->|"starts sessions"| node_terminalstore
node_terminalstore -->|"manages sessions"| node_server
node_server -->|"creates PTYs"| node_pty
node_pty -->|"runs process"| node_pi
node_terminalstore -->|"mounts panes"| node_surface
node_surface -->|"sends input"| node_pty
node_pty -->|"feeds output"| node_screen
node_server -->|"snapshots screen"| node_screen
node_server -->|"persists state"| node_state
node_server -->|"uses domain types"| node_core
node_pi -->|"loads extension"| node_status
node_pi -->|"loads extension"| node_namer
node_pi -->|"loads tools"| node_panes
node_status -->|"sends messages"| node_extensionproto
node_namer -->|"sends messages"| node_extensionproto
node_panes -->|"sends requests"| node_extensionproto
node_extensionproto -->|"dispatches messages"| node_server
node_remotehost -->|"connects"| node_remoteclient
node_remoteclient -.->|"sends TCP requests"| node_server
node_viewmodel -->|"manages runs"| node_automations
node_viewmodel -->|"searches transcripts"| node_search
node_viewmodel -->|"configures theme"| node_themes
node_themes -.->|"syncs appearance"| node_pi_theme_ext

click node_root "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/RootView.swift"
click node_viewmodel "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel.swift"
click node_creation "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel%2BCreation.swift"
click node_terminalstore "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/TerminalSessions.swift"
click node_surface "https://github.com/bailycase/shepherd/blob/master/Sources/TerminalSurfaceKit/TerminalSurfaceModel.swift"
click node_server "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/SessionServer.swift"
click node_pty "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/PTYSession.swift"
click node_screen "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/SessionScreen.swift"
click node_state "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/StateStore.swift"
click node_core "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdCore/Models.swift"
click node_extensionproto "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdProtocol/ExtensionMessage.swift"
click node_status "https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-status.ts"
click node_namer "https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-namer.ts"
click node_panes "https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-panes.ts"
click node_remoteclient "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdRemote/RemoteHostClient.swift"
click node_automations "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel%2BAutomations.swift"
click node_search "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/PaletteContentSearch.swift"
click node_themes "https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ThemeExtension.swift"
click node_pi_theme_ext "https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-theme.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_viewmodel,node_creation,node_terminalstore,node_surface,node_user toneBlue
class node_server,node_pty,node_pi,node_screen,node_state,node_core toneAmber
class node_extensionproto,node_status,node_namer,node_panes,node_pi_theme_ext toneMint
class node_remoteclient,node_remotehost toneRose
class node_automations,node_search,node_themes toneIndigo
```

## Components

### App workflow

- [App interface](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/RootView.swift): `Sources/ShepherdApp/RootView.swift`
- [Workspace model](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel.swift): `Sources/ShepherdApp/ShepherdViewModel.swift`
- [Agent creation](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel%2BCreation.swift): `Sources/ShepherdApp/ShepherdViewModel+Creation.swift`
- [Terminal sessions](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/TerminalSessions.swift): `Sources/ShepherdApp/TerminalSessions.swift`
- [Terminal surface](https://github.com/bailycase/shepherd/blob/master/Sources/TerminalSurfaceKit/TerminalSurfaceModel.swift): `Sources/TerminalSurfaceKit/TerminalSurfaceModel.swift`

### Agent runtime

- [Session server](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/SessionServer.swift): `Sources/ShepherdSessions/SessionServer.swift`
- [PTY session](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/PTYSession.swift): `Sources/ShepherdSessions/PTYSession.swift`
- **pi agent**
- [Screen replay](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/SessionScreen.swift): `Sources/ShepherdSessions/SessionScreen.swift`
- [Workspace state](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdSessions/StateStore.swift): `Sources/ShepherdSessions/StateStore.swift`
- [Domain model](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdCore/Models.swift): `Sources/ShepherdCore/Models.swift`

### Pi extensions

- [Extension protocol](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdProtocol/ExtensionMessage.swift): `Sources/ShepherdProtocol/ExtensionMessage.swift`
- [Status extension](https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-status.ts): `Extensions/shepherd-status.ts`
- [Naming extension](https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-namer.ts): `Extensions/shepherd-namer.ts`
- [Pane tools](https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-panes.ts): `Extensions/shepherd-panes.ts`
- [Theme extension](https://github.com/bailycase/shepherd/blob/master/Extensions/shepherd-theme.ts): `Extensions/shepherd-theme.ts`

### Remote access

- [Remote client](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdRemote/RemoteHostClient.swift): `Sources/ShepherdRemote/RemoteHostClient.swift`
- **Remote Mac**

### Supervision features

- [Automations](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ShepherdViewModel%2BAutomations.swift): `Sources/ShepherdApp/ShepherdViewModel+Automations.swift`
- [Transcript search](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/PaletteContentSearch.swift): `Sources/ShepherdApp/PaletteContentSearch.swift`
- [Pi themes](https://github.com/bailycase/shepherd/blob/master/Sources/ShepherdApp/ThemeExtension.swift): `Sources/ShepherdApp/ThemeExtension.swift`

### Other components

- **User**

## Connections

- User → App interface: uses
- App interface → Workspace model: forwards actions
- Workspace model → Agent creation: creates agents
- Agent creation → Terminal sessions: starts sessions
- Terminal sessions → Session server: manages sessions
- Session server → PTY session: creates PTYs
- PTY session → pi agent: runs process
- Terminal sessions → Terminal surface: mounts panes
- Terminal surface → PTY session: sends input
- PTY session → Screen replay: feeds output
- Session server → Screen replay: snapshots screen
- Session server → Workspace state: persists state
- Session server → Domain model: uses domain types
- pi agent → Status extension: loads extension
- pi agent → Naming extension: loads extension
- pi agent → Pane tools: loads tools
- Status extension → Extension protocol: sends messages
- Naming extension → Extension protocol: sends messages
- Pane tools → Extension protocol: sends requests
- Extension protocol → Session server: dispatches messages
- Remote Mac → Remote client: connects
- Remote client → Session server: sends TCP requests
- Workspace model → Automations: manages runs
- Workspace model → Transcript search: searches transcripts
- Workspace model → Pi themes: configures theme
- Pi themes → Theme extension: syncs appearance