The Problem
MacOS users need a reliable, free tool for quick screenshots, scrolling captures, and screen recordings. Commercial alternatives (CleanShot X, Cap) charge a license, and existing open‑source utilities often lack a modern SwiftUI UI, modular architecture, or support for macOS 15 features such as native PiP camera.
What This Does
Capso is a native macOS 15+ application written in Swift 6.0 that bundles the full workflow from capture to export. The main app entry point lives in App/Sources/CapsoApp.swift, which launches the menu‑bar controller (App/Sources/MenuBar/MenuBarController.swift). Core capabilities are split into reusable Swift‑PM packages:
CaptureKit – low‑level screen and scrolling capture (Packages/CaptureKit/Sources/CaptureKit/ScreenCaptureManager.swift, Scrolling/). AnnotationKit – vector‑based annotation objects (Packages/AnnotationKit/Sources/AnnotationKit/Objects/.swift). OCRKit – text recognition (Packages/OCRKit/Sources/OCRKit/TextRecognizer.swift). RecordingKit – video/GIF encoding (Packages/RecordingKit/Sources/RecordingKit/ScreenRecorder.swift).
The UI layer (App/Sources/…) composes these packages into windows and panels (e.g., AnnotationEditorView.swift, RecordingToolbar.swift). All assets and entitlements are under App/Resources/ and App/Entitlements/Capso.entitlements.
How To Use It
Setup
The repo is a Swift‑PM project with an Xcode workspace generated by project.yml. Build locally with either Xcode 15 or the command line:
Clone and resolve packages
git clone https://github.com/lzhgus/Capso.git cd Capso
Build the app (debug)
swift build -c debug
Or build and archive for release (macOS 15+)
xcodebuild -scheme Capso -configuration Release -destination 'platform=macOS,arch=arm64' clean build
The CI workflow .github/workflows/ci.yml runs the same swift build step, confirming that the project compiles on GitHub runners.
Configuration
No external configuration files are required. Permissions are declared in App/Entitlements/Capso.entitlements (screen‑recording, camera, microphone). The app will request them on first use; developers can modify entitlements if they need a custom sandbox profile.
Running
After a successful build, the executable appears under .build/debug/Capso. Run it directly or launch from Xcode:
.open .build/debug/Capso # macOS opens the app bundle
The menu‑bar icon (App/Resources/Assets.xcassets/MenuBarIcon.imageset/menubar.png) appears, and all capture actions are accessible via the dropdown or global shortcuts defined in App/Sources/Preferences/Tabs/ShortcutSettingsView.swift.
Real‑World Use
A development team can embed CaptureKit and AnnotationKit into a custom internal tool. For example:
import CaptureKit import AnnotationKit
let manager = ScreenCaptureManager() manager.captureFullScreen { image in var doc = AnnotationDocument(image: image) doc.addObject(ArrowObject(start: .zero, end: CGPoint(x: 200, y: 200))) // Export annotated PNG try? doc.export(to: URL(fileURLWithPath: "/tmp/screenshot.png")) }
This reuses the same battle‑tested code base that powers the Capso UI.
Code Health & Issues
Bugs / Risks
Medium – Permission handling – UI code checks permissions (App/Sources/Permissions/ not present); failures rely on macOS prompts, which may lead to silent denial in headless CI. Low – Scrolling capture edge cases – Scrolling/ScrollStitcher.swift stitches images without explicit error recovery; large pages could cause memory spikes.
SDLC & Code Violations
Low – UI test coverage – 12 test files cover only the Swift‑PM packages; no XCTest UI tests for the menu‑bar flow. Low – Documentation gaps – README describes usage but lacks a “contribute” guide for adding new capture modes; however CONTRIBUTING.md exists. None – License & CI – BSL 1.1 license present, CI builds on each PR, lockfiles (Package.resolved) are committed.
Overall the repo compiles cleanly, packages are unit‑tested, and CI validates builds. No secrets or hard‑coded keys are visible.
The Bottom Line
Capso delivers a fully native, modular screenshot and recording suite for macOS 15+, with a well‑structured Swift‑PM architecture and functional CI. It is best suited for teams that need a free, extensible base or for solo users comfortable building from source. The primary limitation is the lack of UI‑level automated tests and minimal handling of permission failures in headless environments.