How bailycase/shepherd works
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: SessionServer.swift Session server · ShepherdViewModel.swift Workspace model · PTYSession.swift PTY session · ExtensionMessage.swift Extension protocol
Components 22
App workflow
- App interface
Sources/ShepherdApp/RootView.swift - Workspace model
Sources/ShepherdApp/ShepherdViewModel.swift - Agent creation
Sources/ShepherdApp/ShepherdViewModel+Creation.swift - Terminal sessions
Sources/ShepherdApp/TerminalSessions.swift - Terminal surface
Sources/TerminalSurfaceKit/TerminalSurfaceModel.swift
Agent runtime
- Session server
Sources/ShepherdSessions/SessionServer.swift - PTY session
Sources/ShepherdSessions/PTYSession.swift - pi agent
- Screen replay
Sources/ShepherdSessions/SessionScreen.swift - Workspace state
Sources/ShepherdSessions/StateStore.swift - Domain model
Sources/ShepherdCore/Models.swift
Pi extensions
- Extension protocol
Sources/ShepherdProtocol/ExtensionMessage.swift - Status extension
Extensions/shepherd-status.ts - Naming extension
Extensions/shepherd-namer.ts - Pane tools
Extensions/shepherd-panes.ts - Theme extension
Extensions/shepherd-theme.ts
Remote access
- Remote client
Sources/ShepherdRemote/RemoteHostClient.swift - Remote Mac
Supervision features
- Automations
Sources/ShepherdApp/ShepherdViewModel+Automations.swift - Transcript search
Sources/ShepherdApp/PaletteContentSearch.swift - Pi themes
Sources/ShepherdApp/ThemeExtension.swift
Other components
- User
Connections 26
- 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