Getting started

Smalti is the control surface for a software factory (see Concepts). This guide covers the macOS app, which is the part available today. It needs macOS 15 or later. Until the first release build is published, you compile it from source.

Requirements

  • macOS 15 (Sequoia) or later.
  • Claude Code, if you want sessions to appear. Smalti reads the transcripts Claude Code writes to ~/.claude/projects. Terminals, browsers and notes work without it.
  • To build from source: a Swift 6 toolchain, from Xcode 16 or later or the matching Command Line Tools. swift --version prints the installed version.

Install a release

No release has been published yet; this is how it will work.

  1. Download the latest Smalti-<version>-macOS.zip from the download page.
  2. Unzip it and move Smalti.app to /Applications. The release is signed with a Developer ID and notarized by Apple.
  3. Open it. The first launch indexes every transcript under ~/.claude/projects, which can take a few seconds if you have many sessions. Later launches read the cache.

Running in the background

Smalti.app includes smaltid (the per-machine daemon) and the Conductor. On the first launch, a sheet asks to Keep Smalti running in the background, on by default. Confirm it, and both run at login and keep running after you quit the app, so your phone can approve requests and the governor keeps watching. There is nothing to install from a terminal.

  • If macOS asks for approval, the status bar at the bottom left says approve in Login Items; click it to open System Settings, General, Login Items, and turn Smalti on.
  • Next, Smalti offers to add smaltid's hooks to Claude Code's ~/.claude/settings.json, which lets you approve and deny permission prompts from Smalti and your phone. It shows the exact change first, and writes a backup. You can say no and add them later with Install Claude Code Hooks in the palette.
  • To turn background running off, use Run in the Background in the palette. smaltid then runs only while the app is open.

To add a build box or server to your fleet, see Shards.

Build from source

The macOS app is a Swift package. Its only dependency is SwiftTerm, which SwiftPM fetches on the first build.

git clone <repository URL> smalti
cd smalti
swift build
.build/debug/Smalti

For an optimised binary, build with swift build -c release and run .build/release/Smalti. scripts/bundle.sh builds a release Smalti.app with its icon and zips it under dist/. The source repository is private at the moment, so cloning requires access.

First steps

  1. Press ⌘O and choose a project folder. It becomes the root of the file tree, and new terminals start in it.
  2. Press ⌘L (Claude Here) to open a terminal running claude, or ⌘T for a plain terminal. Within about a second a Claude panel shows a claude badge and links itself to its session.
  3. Existing sessions are listed in the sidebar under their project. Clicking one resumes it with claude --resume in a new terminal, or focuses the terminal it is already running in.
  4. Press ⌘K for the command palette. It finds every command, panel, session and file, and shows each command's shortcut. ⌘/ shows all shortcuts at once.
  5. When a session stops to wait for you, its panel gets an amber ring and appears under Needs you in the sidebar. ⌘J jumps to it.
  6. Right-click a folder in the file tree for Open Terminal Here and Start Claude Here.

All shortcuts are listed in the keyboard reference.

The layout is saved as you work. Quitting and reopening the app restores the panels, the camera position and the file tree root. Terminals start a fresh shell in the directory they were last in; programs that were running in them are not restored.