Installation

Damson runs on macOS 13 Ventura or later (Apple Silicon or Intel). 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`

Grab the newest build from 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.

Stay up to date automatically

From then on the app keeps itself current with Sparkle. You can also trigger a check anytime from Settings → Advanced → Check for Updates.

Damson is in active beta and ships frequent updates. Automatic updates mean you’ll always be on the latest polish without re-downloading anything.

(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; symlink it onto your PATH:


ln -s "/Applications/Damson.app/Contents/Resources/damson-cli" /usr/local/bin/damson-cli
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.