Installation

Damson runs on macOS 13 Ventura or later — check the release notes for the architectures included in each build. Most people should just grab the signed release; building from source is for contributors and the curious.

Requirements

macOS 13 Ventura or later
For building from source: Swift 5.9+ (Xcode toolchain) and Swift Package Manager

Install the release (recommended)

Download the latest `.dmg`

Download Damson.dmg — always the newest build. Prefer release notes and checksums? Browse GitHub Releases .

Drag Damson into Applications

Open the .dmg and drop Damson.app into your Applications folder.

Launch it

Open Damson from Launchpad or Spotlight. It’s Developer ID signed and notarized by Apple, so Gatekeeper lets it through without a fuss.

Choose how to check for updates

Automatic update checks are off by default. Enable Settings → Advanced → Automatic Updates to check in the background, or use Check for Updates… manually.

App updates also update the bundled CLIs. Separately installed agent plugins need to be updated independently.

(Optional) Install the `damson-cli`

Damson ships a small command-line client, damson-cli, that drives a running instance — handy for scripts and AI orchestration. It lives inside the app bundle; add its directory to your current shell’s PATH:


export PATH="/Applications/Damson.app/Contents/Resources:$PATH"
damson-cli --help

See damson-cli for the full command reference.

Build from source

The engine library has zero external dependencies (Metal, CoreText, AppKit only); the app pulls in Sparkle for auto-updates.

Clone the repository


git clone https://github.com/hulryung/damson.git
cd damson

Run a development build

The fastest way to try your changes:


swift run damson

Or build a real `.app` bundle


./scripts/build-app.sh
# produces dist/Damson.app

Useful environment variables: MARKETING_VERSION, BUILD_NUMBER, CLEAN=1.

Install a local build for dogfooding


./scripts/install-local.sh

This builds a release .app, ad-hoc code-signs it (this Mac only), installs it to /Applications, strips the quarantine flag, and launches it.

An ad-hoc signed build can’t auto-update via Sparkle and isn’t suitable for distribution. For a real signed/notarized build, see docs/RELEASE.md in the repository.

Run the tests


swift test

The repository carries a large test suite covering the VT parser, terminal grid, control IPC, and the orchestration engine.

Next steps

Now that Damson is running, head to Getting Started for the key shortcuts and a quick tour.