How egekibar/shotcue works
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: RunCoordinator.swift Run queue · LibraryStore.swift Task library · CaptureFlowController.swift Capture flow · QuickPanelController.swift Quick panel
Components 23
App orchestration
- Capture flow
Sources/ShotcueApp/CaptureFlowController.swift - Permissions
Sources/ShotcueCapture/SystemPermissionService.swift - Quick panel
Sources/ShotcueApp/QuickPanelController.swift
Capture and notes
- Region capture
Sources/ShotcueCapture/ScreencaptureService.swift - Voice recording
Sources/ShotcueNotes/EngineAudioRecorder.swift - Transcription
Sources/ShotcueNotes
Task library
- Task library
Sources/ShotcueUI/Stores/LibraryStore.swift - Library interface
Sources/ShotcueUI/Views/LibraryView.swift - Task domain
Sources/ShotcueCore/Models/ShotTask.swift - Task repositories
Sources/ShotcuePersistence/GRDBTaskRepository.swift - App database
Sources/ShotcuePersistence/AppDatabase.swift
Agent execution
- Run queue
Sources/ShotcueClaudeBridge/RunCoordinator.swift - Scheduling rules
Sources/ShotcueCore/Logic/SchedulerRules.swift - Agent selection
Sources/ShotcueCore/Models/AgentKind.swift - Coding agent CLI
- Agent event parsing
Sources/ShotcueCore/Logic/AgentStreamParsers.swift - Run events
Sources/ShotcueCore/Models/RunEvent.swift
Review and handoff
- Live run log
Sources/ShotcueUI/Views/RunLogView.swift - Diff review
Sources/ShotcueCore/Logic/UnifiedDiffParser.swift - Run notifications
Sources/ShotcueClaudeBridge/UserNotificationNotifier.swift - Desktop handoff
Sources/ShotcueClaudeBridge/DesktopHandoffService.swift
Other components
- User
- Terminal or Desktop
Connections 24
- User → Capture flow: starts capture
- Capture flow → Permissions: checks access
Sources/ShotcueApp/CaptureFlowController.swift - Capture flow → Region capture: captures region
Sources/ShotcueApp/CaptureFlowController.swift - Capture flow → Task library: creates task
Sources/ShotcueApp/CaptureFlowController.swift - Capture flow → Quick panel: opens panel
Sources/ShotcueApp/CaptureFlowController.swift - Quick panel → Voice recording: records note
- Voice recording → Transcription: transcribes audio
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
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
Sources/ShotcueCore/Logic/AgentStreamParsers.swift - Agent event parsing → Run events: produces events
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