# egekibar/shotcue architecture

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

- Interactive diagram: https://gitdiagram.com/egekibar/shotcue
- Repository: https://github.com/egekibar/shotcue

## Overview

Shotcue is a native macOS app that turns a screen capture and typed or spoken note into a project-scoped coding task, runs a coding-agent CLI, and lets the user review the result. The principal flow is documented in the README; the capture controller excerpt confirms the capture-to-task-to-panel steps. Other branches, including scheduling, transcription, and review, are retained from the README. Unsampled implementation details are represented only at paths supported by the tree.

Main entry points: [`Sources/ShotcueClaudeBridge/RunCoordinator.swift`](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/RunCoordinator.swift) (Run queue), [`Sources/ShotcueUI/Stores/LibraryStore.swift`](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Stores/LibraryStore.swift) (Task library), [`Sources/ShotcueApp/CaptureFlowController.swift`](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/CaptureFlowController.swift) (Capture flow), [`Sources/ShotcueApp/QuickPanelController.swift`](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/QuickPanelController.swift) (Quick panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App orchestration"]
  node_capture_flow["Capture flow"]
  node_permissions["Permissions"]
  node_quick_panel["Quick panel"]
end

subgraph group_capture["Capture and notes"]
  node_capture_service["Region capture"]
  node_voice_recording["Voice recording"]
  node_transcription["Transcription"]
end

subgraph group_library["Task library"]
  node_task_library["Task library<br/>[LibraryStore.swift]"]
  node_library_views["Library interface<br/>[LibraryView.swift]"]
  node_task_models["Task domain<br/>[ShotTask.swift]"]
  node_repositories["Task repositories"]
  node_database[("App database<br/>[AppDatabase.swift]")]
end

subgraph group_execution["Agent execution"]
  node_run_queue["Run queue"]
  node_schedule_policy["Scheduling rules"]
  node_agent_kind["Agent selection<br/>[AgentKind.swift]"]
  node_agent_cli["Coding agent CLI"]
  node_stream_parser["Agent event parsing"]
  node_run_events["Run events<br/>[RunEvent.swift]"]
end

subgraph group_review["Review and handoff"]
  node_live_log["Live run log<br/>[RunLogView.swift]"]
  node_diff_review["Diff review"]
  node_notifications["Run notifications"]
  node_desktop_handoff["Desktop handoff"]
end

node_user(("User"))
node_external_apps["Terminal or Desktop"]

node_user -->|"starts capture"| node_capture_flow
node_capture_flow -->|"checks access"| node_permissions
node_capture_flow -->|"captures region"| node_capture_service
node_capture_flow -->|"creates task"| node_task_library
node_capture_flow -->|"opens panel"| node_quick_panel
node_quick_panel -->|"records note"| node_voice_recording
node_voice_recording -->|"transcribes audio"| node_transcription
node_quick_panel -->|"saves or sends"| node_task_library
node_task_library -->|"reads and writes tasks"| node_repositories
node_repositories -->|"stores records"| node_database
node_task_library -->|"organizes tasks"| node_task_models
node_user -->|"manages tasks"| node_library_views
node_library_views -->|"views library"| node_task_library
node_task_library -->|"dispatches tasks"| node_run_queue
node_task_library -->|"schedules runs"| node_schedule_policy
node_run_queue -->|"selects agent"| node_agent_kind
node_run_queue -->|"runs task"| node_agent_cli
node_agent_cli -->|"emits stream"| node_stream_parser
node_stream_parser -->|"produces events"| node_run_events
node_run_queue -->|"streams run log"| node_live_log
node_run_queue -->|"enables diff review"| node_diff_review
node_run_queue -->|"notifies result"| node_notifications
node_run_queue -->|"supports resume"| node_desktop_handoff
node_desktop_handoff -->|"hands off session"| node_external_apps

click node_capture_flow "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/CaptureFlowController.swift"
click node_capture_service "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCapture/ScreencaptureService.swift"
click node_permissions "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCapture/SystemPermissionService.swift"
click node_quick_panel "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/QuickPanelController.swift"
click node_voice_recording "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueNotes/EngineAudioRecorder.swift"
click node_transcription "https://github.com/egekibar/shotcue/tree/main/Sources/ShotcueNotes"
click node_task_library "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Stores/LibraryStore.swift"
click node_library_views "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Views/LibraryView.swift"
click node_task_models "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/ShotTask.swift"
click node_repositories "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcuePersistence/GRDBTaskRepository.swift"
click node_database "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcuePersistence/AppDatabase.swift"
click node_run_queue "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/RunCoordinator.swift"
click node_schedule_policy "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/SchedulerRules.swift"
click node_agent_kind "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/AgentKind.swift"
click node_stream_parser "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/AgentStreamParsers.swift"
click node_run_events "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/RunEvent.swift"
click node_live_log "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Views/RunLogView.swift"
click node_diff_review "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/UnifiedDiffParser.swift"
click node_notifications "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/UserNotificationNotifier.swift"
click node_desktop_handoff "https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/DesktopHandoffService.swift"

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_capture_flow,node_permissions,node_quick_panel,node_user toneBlue
class node_capture_service,node_voice_recording,node_transcription toneAmber
class node_task_library,node_library_views,node_task_models,node_repositories,node_database toneMint
class node_run_queue,node_schedule_policy,node_agent_kind,node_agent_cli,node_stream_parser,node_run_events toneRose
class node_live_log,node_diff_review,node_notifications,node_desktop_handoff,node_external_apps toneIndigo
```

## Components

### App orchestration

- [Capture flow](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/CaptureFlowController.swift): `Sources/ShotcueApp/CaptureFlowController.swift`
- [Permissions](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCapture/SystemPermissionService.swift): `Sources/ShotcueCapture/SystemPermissionService.swift`
- [Quick panel](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueApp/QuickPanelController.swift): `Sources/ShotcueApp/QuickPanelController.swift`

### Capture and notes

- [Region capture](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCapture/ScreencaptureService.swift): `Sources/ShotcueCapture/ScreencaptureService.swift`
- [Voice recording](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueNotes/EngineAudioRecorder.swift): `Sources/ShotcueNotes/EngineAudioRecorder.swift`
- [Transcription](https://github.com/egekibar/shotcue/tree/main/Sources/ShotcueNotes): `Sources/ShotcueNotes`

### Task library

- [Task library](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Stores/LibraryStore.swift): `Sources/ShotcueUI/Stores/LibraryStore.swift`
- [Library interface](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Views/LibraryView.swift): `Sources/ShotcueUI/Views/LibraryView.swift`
- [Task domain](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/ShotTask.swift): `Sources/ShotcueCore/Models/ShotTask.swift`
- [Task repositories](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcuePersistence/GRDBTaskRepository.swift): `Sources/ShotcuePersistence/GRDBTaskRepository.swift`
- [App database](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcuePersistence/AppDatabase.swift): `Sources/ShotcuePersistence/AppDatabase.swift`

### Agent execution

- [Run queue](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/RunCoordinator.swift): `Sources/ShotcueClaudeBridge/RunCoordinator.swift`
- [Scheduling rules](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/SchedulerRules.swift): `Sources/ShotcueCore/Logic/SchedulerRules.swift`
- [Agent selection](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/AgentKind.swift): `Sources/ShotcueCore/Models/AgentKind.swift`
- **Coding agent CLI**
- [Agent event parsing](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/AgentStreamParsers.swift): `Sources/ShotcueCore/Logic/AgentStreamParsers.swift`
- [Run events](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Models/RunEvent.swift): `Sources/ShotcueCore/Models/RunEvent.swift`

### Review and handoff

- [Live run log](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueUI/Views/RunLogView.swift): `Sources/ShotcueUI/Views/RunLogView.swift`
- [Diff review](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueCore/Logic/UnifiedDiffParser.swift): `Sources/ShotcueCore/Logic/UnifiedDiffParser.swift`
- [Run notifications](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/UserNotificationNotifier.swift): `Sources/ShotcueClaudeBridge/UserNotificationNotifier.swift`
- [Desktop handoff](https://github.com/egekibar/shotcue/blob/main/Sources/ShotcueClaudeBridge/DesktopHandoffService.swift): `Sources/ShotcueClaudeBridge/DesktopHandoffService.swift`

### Other components

- **User**
- **Terminal or Desktop**

## Connections

- User → Capture flow: starts capture
- Capture flow → Permissions: checks access (evidence: `Sources/ShotcueApp/CaptureFlowController.swift`)
- Capture flow → Region capture: captures region (evidence: `Sources/ShotcueApp/CaptureFlowController.swift`)
- Capture flow → Task library: creates task (evidence: `Sources/ShotcueApp/CaptureFlowController.swift`)
- Capture flow → Quick panel: opens panel (evidence: `Sources/ShotcueApp/CaptureFlowController.swift`)
- Quick panel → Voice recording: records note
- Voice recording → Transcription: transcribes audio (evidence: `Sources/ShotcueNotes/EngineAudioRecorder.swift`)
- Quick panel → Task library: saves or sends
- Task library → Task repositories: reads and writes tasks
- Task repositories → App database: stores records (evidence: `Sources/ShotcuePersistence/GRDBTaskRepository.swift`)
- Task library → Task domain: organizes tasks
- User → Library interface: manages tasks
- Library interface → Task library: views library
- Task library → Run queue: dispatches tasks
- Task library → Scheduling rules: schedules runs
- Run queue → Agent selection: selects agent
- Run queue → Coding agent CLI: runs task
- Coding agent CLI → Agent event parsing: emits stream (evidence: `Sources/ShotcueCore/Logic/AgentStreamParsers.swift`)
- Agent event parsing → Run events: produces events (evidence: `Sources/ShotcueCore/Logic/AgentStreamParsers.swift`)
- Run queue → Live run log: streams run log
- Run queue → Diff review: enables diff review
- Run queue → Run notifications: notifies result
- Run queue → Desktop handoff: supports resume
- Desktop handoff → Terminal or Desktop: hands off session