Getting started

Yardarm is a desktop app for the Mastra Code coding agent. You describe what you want in plain language; the agent reads your code, proposes a plan, edits files, runs commands, and helps you review and ship the result — all inside one window. The mastracode runtime is bundled with the app: there is no separate install, no account, and no telemetry.

This guide covers installation through your first chat. Inside the app, the help button beside the theme toggle (or Cmd+9) opens a built-in guide and FAQ covering the same ground.

Install

Install script (macOS, Apple Silicon — recommended)

curl -fsSL https://raw.githubusercontent.com/JJJ-Mo3/yardarm/main/scripts/install.sh | sh

This downloads the latest release and installs it to /Applications.

Download a release manually (macOS, Apple Silicon)

Grab the .dmg (or .zip) from the latest release and drag Yardarm.app into /Applications.

Release builds are not code-signed, so macOS quarantines browser downloads and Gatekeeper refuses to open them — "Yardarm is damaged and can't be opened" — and on macOS 15+ that dialog has no bypass (right-click → Open no longer works). Clear the quarantine flag once and it opens normally: 
xattr -dr com.apple.quarantine /Applications/Yardarm.app

The install script above avoids this entirely (curl downloads are never quarantined). If the dmg itself refuses to open, clear it there too: xattr -d com.apple.quarantine ~/Downloads/Yardarm-*.dmg.

Build from source (all platforms)

Requirements: Node 22+, pnpm 10, and git. 

git clone https://github.com/JJJ-Mo3/yardarm.git
cd yardarm
pnpm install
pnpm dist        # installers into dist/ (dmg/zip, nsis, AppImage/deb)
# or
pnpm package     # unpacked app bundle, e.g. dist/mac-arm64/Yardarm.app

Targets: macOS (arm64). Windows/Linux electron-builder config exists but is untested, and the bundled agent runtime is staged for the build machine's platform — build on the platform you're targeting. Apps you build yourself are not quarantined and open normally.

First launch: the setup wizard

The first time you open Yardarm, a setup wizard walks you through the same onboarding the mastracode CLI uses. Nothing is written to disk until the final step, and you can skip any part of it.

  1. Welcome — a reminder that everything runs locally and no account is created.
  2. Connect a provider — sign in with an existing subscription (Claude, OpenAI Codex, or GitHub Copilot via OAuth), paste an API key, or skip and add a local model later.
  3. Choose your models — choose which models power the Build / Plan / Fast modes. Pick a preset pack or choose per-mode.
  4. Observational Memory — optionally choose the model used for the agent's background memory.
  5. Connect your tools — optional one-click connector sign-ins (GitHub, GitLab, Supabase, Netlify, Vercel, Sentry).
  6. Add subagents — optionally pick ready-made subagents from the templates catalog.
  7. Agent sandbox — choose whether new chats run shell commands under OS-level isolation by default.
  8. Token compression — optionally shrink stale tool outputs to cut token costs.
  9. Tool approvals — decide whether the agent may run tools without asking each time (yolo). You can change this later per chat.
  10. Review your setup — review, then finish.

The wizard writes mastracode's own settings.json, so the CLI is configured at the same time. Re-run it any time from Settings → About → Run setup again.

Connecting a model

Yardarm can drive models from subscriptions, API keys, or your own machine. All of these are managed in Settings (Cmd+, / Ctrl+,):

Model dropdowns throughout the app only list models that are actually usable right now (key present, login active, or server reachable), so an empty dropdown means "connect something first".

Local model context windows matter. The agent's base prompt is roughly 30k tokens before you type anything. Configure at least a 64k context window — 128k+ if you have the memory. Ollama defaults to ~4k; raise it in the Ollama app (Settings → Context length) or start the server with OLLAMA_CONTEXT_LENGTH=65536 ollama serve. Yardarm never imposes idle timeouts, so a big local model can think for minutes without being cut off.

Your first project and chat

  1. Click Add project in the sidebar and pick a folder. It doesn't need to be a git repository yet — Yardarm will initialize what it needs. Yardarm also offers to write agent instructions (an AGENTS.md) so the agent knows the project's conventions from the first prompt — skip it or edit the file later in Project Settings.
  2. Create a chat (Cmd+N). By default each chat gets its own git worktree: a private checkout of your repo on a yardarm/… branch, stored under the app's data directory. The agent edits, builds, and commits there without touching your working copy — and several chats can work on the same repo in parallel without conflicts.
  3. Type what you want and press Enter. That's it.

A few notes on worktrees:

Where to get help