Configuration

Everything you change in Yardarm is written to Mastra Code's own config files — atomically, preserving keys the app doesn't know about — so the mastracode CLI picks up the same configuration.

Slash commands

Type / in the composer to see everything available — the full Mastra Code command surface plus app commands. Highlights:

You can define your own commands as plain Markdown files: ~/.mastracode/commands/**/*.md (global) or .mastracode/commands/**/*.md (per project). They appear in the autocomplete like built-ins. A few terminal-only commands (e.g. /voice) are listed in /help and point you to the CLI tab.

Settings reference

Open with Cmd+, (Ctrl+,).

MCP servers (Settings → MCP Servers)

MCP servers (~/.mastracode/mcp.json globally, or a project's .mastracode/mcp.json, merged over global) are edited as raw JSON (/mcp opens this tab). The editor defaults to the Global scope — servers available in every project; switch to Project and pick one of your projects to manage servers for that project only. Saving restarts the affected agent processes.

The tab also shows each server's live status (connected + tool count, connecting, or an error) — for the global scope this works even without a chat open; for a project it needs a chat open in that project. Servers that use OAuth show Needs authentication with an Authenticate button: the sign-in opens in your browser, and the server connects when it completes. A Reconnect button revives servers that dropped.

Each server row also has an enable/disable switch — turn a server off without touching the JSON (persisted in mastracode's state and shared with the CLI); flipping it back on reconnects the server immediately.

The Global scope adds two server discovery switches: opt in to also load the MCP servers you've already configured for Claude Code or Codex, so you don't have to duplicate them in mastracode's config. Running agents pick the change up after a restart (a banner offers one).

Custom subagents (Settings → Agents)

Custom subagents (~/.mastracode/agents/*.md globally, or a project's .mastracode/agents/*.md) are helpers the main agent can delegate tasks to via the subagent tool (/subagents opens this tab). The editor defaults to the Global scope — agents available in every project; switch to Project and pick one of your projects to manage agents for that project only. Your agents are listed below the create field; creating an agent (or clicking one in the list) opens its editor in a dialog. Each file has a frontmatter block (name, description — required, model, maxSteps, forked) and the body is the subagent's instructions. Saving restarts the affected agent processes; the ids explore, plan, execute and general are reserved.

A collapsible Templates section on the same screen holds 18 ready-made subagents — 12 team roles (product manager, architect, developer, QA engineer, security engineer, tech writer, …) and 6 domain specialists (SaaS, Shopify, mobile, Chrome extensions, AI apps, e-commerce); expand it to browse them. Click Add on any of them (or Add all per group) and it's written as an ordinary .md file into the selected scope, so you can edit it like any other agent afterwards. Added templates disappear from the list, and adding never overwrites an existing file, so your customizations are safe. On an id collision, a project-scoped agent overrides the global one.

Per-project configuration

Click the gear next to the project name in the sidebar to configure a single project:

• General — rename, archive, or remove the project. Archived projects move to an "Archived" group at the bottom of the project picker, from where they can be reopened and unarchived. Removing a project deletes its chats and worktrees but keeps the project folder on disk unless you tick the option to delete it too.
• Lifecycle hooks (.mastracode/hooks.json, appended after global hooks)
• Custom slash commands (.mastracode/commands/**/*.md)
• Agent instructions (.mastracode/agent-instructions.md) — standing guidance the agent reads on every run
• Memory resource id (.mastracode/database.json)
• Installed skills and plugins — plugins that declare a configuration schema get a generated settings form (toggles, text fields, and model pickers), written back to the plugin's config. A Create plugin button scaffolds a new plugin (name, id, and target directory, in global or project scope) ready to fill in
• Workflows (/workflows) — list, run (with optional JSON input and per-step results), and delete the agent's stored workflows (see Workflows)

Project-specific MCP servers and custom subagents are managed in Settings → MCP Servers and Settings → Agents (pick the project there). Edits restart the affected agent processes, so they take effect immediately.

Configuration paths (shared with the mastracode CLI)

Global:

• ~/.mastracode/settings.json — model defaults per mode, subagent models, goal judge, Observational Memory defaults, custom providers, preferences
• ~/.mastracode/mcp.json — global MCP servers
• ~/.mastracode/hooks.json — global lifecycle hooks
• ~/.mastracode/commands/**/*.md — global custom slash commands
• ~/.mastracode/database.json — global memory resourceId
• App-data dir (~/Library/Application Support/mastracode on macOS, %APPDATA%\mastracode on Windows, $XDG_DATA_HOME/mastracode on Linux): auth.json (API keys + OAuth credentials), agent database

Per project (Project Settings gear in the sidebar):

• .mastracode/mcp.json — project MCP servers
• .mastracode/hooks.json — project hooks (appended after global)
• .mastracode/commands/**/*.md — project slash commands
• .mastracode/agent-instructions.md — project agent instructions
• .mastracode/database.json — project memory resourceId

Edits made in the app are written atomically and preserve unknown keys, so the same files stay usable from the CLI. Config edits restart the affected agent processes so changes take effect.

App data

The app's own state (projects, chats, transcripts, checkpoints) lives in a SQLite database (yardarm.db) in Electron's userData directory — separate from mastracode's files:

• macOS: ~/Library/Application Support/yardarm/
• Windows: %APPDATA%\yardarm\
• Linux: ~/.config/yardarm/

Chat worktrees live under worktrees/<projectId>/<chatId> in the same directory. The database runs in WAL mode with periodic maintenance (vacuum/optimize, size-bounded transcripts) so long-lived installs don't degrade.

Optional language-server packs downloaded from Settings → Languages are stored under lsp-servers/<pack>/<version> in the same directory (e.g. ~/Library/Application Support/yardarm/lsp-servers on macOS). Removing a pack from Settings → Languages deletes its folder; deleting the whole app-data directory removes them along with everything else.

Keeping Yardarm updated

Settings → About → Updates:

• Check for updates queries the project's GitHub Releases.
• If a newer version exists, Install downloads and stages it in the background; an amber "Restart to finish" banner appears when it's ready. The restart is always your click.
• Automatically update (on by default in release builds) checks shortly after launch and every few hours, staging updates silently.

Self-install works on packaged macOS builds. Elsewhere (or in dev builds) the app offers a View release link instead. Update checks and the optional language-server pack downloads you trigger yourself (Settings → Languages) are the only network traffic Yardarm itself makes — everything else goes to the model providers you configured.