Workspace

Beyond the chat, each conversation carries a full workspace scoped to its worktree: a real terminal, a light IDE, the embedded Mastra Code CLI, a localhost preview browser, and usage analytics — plus an app-level harness and native work client for Mastra Factory.

Terminal

The Terminal tab (Cmd+5, or toggle with Cmd+J) is a real shell that opens in the chat's worktree. Build, test, poke around; you and the agent are looking at the same files.

The + button in the tab strip opens extra sessions in other locations — the project root or another chat's worktree — shown as tabs beside the default one. Sessions keep running while you switch tabs; closing a tab ends its shell.

Press Cmd+F while the terminal is focused to search its scrollback: a small overlay shows a match counter, Enter / Shift+Enter step through matches (highlighted in place), and Esc closes the search and returns focus to the shell.

IDE

The IDE tab (Cmd+3) is a file tree + Monaco editor scoped to the worktree. Open multiple files as tabs and save with Cmd+S.

• Quick open — press Cmd+O anywhere in the app to fuzzy-search every file in the worktree and open it straight in the IDE.
• Every save is tracked per project/worktree and survives app restarts: each chat working on that root is told about your edit immediately — pushed into the run while its agent is working, or written into the chat's memory while it's idle, no message needed (edits saved during a permission prompt are delivered right after you answer it). The transcript shows a "Told the agent about IDE edits" line either way; brand-new chats with no messages yet get the note alongside your first prompt.
• Clean files the agent changes refresh automatically, and saving over a file the agent just changed prompts you to overwrite or reload.
• Hover a file in the tree and click the + button to insert it into the chat composer as an @-mention.
• A problems panel below the editor shows language-server diagnostics (errors and warnings) for the active file, refreshed as you type (shortly after edits pause), on open and on save — no chat needs to be selected. Click a problem to jump to it, and the same markers appear inline in the editor.
• Language servers come in three tiers. Built in: TypeScript/JavaScript (using your project's own TypeScript when it has one) ships with the app — no setup needed. Downloadable packs: Web (HTML/CSS/JSON, ~15 MB), YAML (~6 MB), Python (~7 MB) and ERB / Rails templates (~19 MB) are one-time downloads from Settings → Languages — or click the Download button the problems panel offers when you open a matching file; they work offline once installed and take effect on the next refresh, no restart. External binaries: Go, Rust and Ruby use gopls / rust-analyzer / ruby-lsp from your PATH (well-known install dirs like ~/go/bin and ~/.cargo/bin are searched too); Rails smarts come from your project's ruby-lsp-rails gem.

CLI

The CLI tab (Cmd+2) runs the interactive Mastra Code terminal UI, embedded, in the same worktree and seeing the same threads as the chat. Handy for CLI-only commands (terminal voice mode, …). Avoid driving the same thread from the chat and the CLI at the same time. On Windows (beta) the CLI tab works but does not live-sync with the chat screen — reopen the chat's thread to see CLI-made turns.

Preview

The Preview tab (Cmd+7) is an in-app browser for localhost dev servers.

• Start your server in the Terminal or CLI tab and its URL appears as a chip within a few seconds (the first detection loads automatically); or type a localhost / 127.0.0.1 URL into the address bar.
• If nothing is running yet, a start chip offers to launch the project's dev server (detected from the project; static sites get a simple fallback server) in a dedicated terminal.
• Dev servers are per chat (each runs in its own worktree) and would clash over the same port, so if another chat's server is still running, the start chip says so and stops it before starting here.
• Back/forward, reload, DevTools, and open-in-browser controls are in the toolbar — the wrench button docks a full Chrome DevTools pane beside the page (elements, console, network) inspecting the previewed app.
• Navigation is locked to localhost — links to anywhere else open in your system browser — and the page survives switching tabs.

Factory

The Factory tab (unnumbered — reach it from the tab bar or Cmd+K) is a harness for Mastra Factory, Mastra's open-source agent-powered software factory: a server that connects to your GitHub org, runs work items through a kanban pipeline with human approval gates, and opens pull requests. The Factory server lives in its own checkout, separate from the repos its agents work on. Using the work board requires signing in with a Mastra account — even when the server runs locally — because its APIs are organization-scoped; the sign-in is identity-only and a local server's data stays on your machine (details under Work below).

• Setup — everything to get a Factory running, on one scrollable page. A guided checklist at the top covers every step from scaffold to a working board: checkout, dependencies, database, required .env keys, dashboard UI, server, dashboard-serving health, and sign-in. Each step shows live pass/fail state with a one-click fix or a scroll to the card below that owns it; the tab opens automatically while setup is incomplete. The setup cards scaffold a new checkout with npm create factory@latest in an interactive terminal, or point Yardarm at an existing one (its mode is auto-detected). Every step streams into its own embedded log terminal, which notes when a command has already finished. Two setups are supported: Mastra platform (sign in during setup; hosted Postgres and cloud sandboxes are provisioned for you) and local self-hosted (--no-platform: Docker Postgres, local sandboxes, manual .env). Below them, the environment card is a guided .env editor that flags missing required keys, generates the credential encryption key, and can seed your model-provider API keys from the ones Yardarm already knows. Comments, quoting, and unknown keys in the file are preserved — including dotenv-style names with dots or dashes. Local mode adds a Docker database card (npm run db:up / db:down) with its own log terminal; the card checks Docker health first and explains exactly what is missing — no CLI, a stopped daemon (with a one-click start when Docker Desktop, OrbStack, or colima is installed), or a missing docker compose plugin.
• Server — start/stop npm run dev, watch its logs, and use the Factory dashboard embedded in-app (persistent session, DevTools, open-in-browser). If DATABASE_URL points at a localhost port nobody is listening on, a warning appears before you start (the server would otherwise crash with a bare ECONNREFUSED). Every start and restart first makes sure the server has a dashboard to serve: Yardarm points MASTRACODE_UI_DIST at the prebuilt dashboard bundled with the checkout's mastra CLI and installs a copy at src/mastra/public/factory (where the server and mastra build look by default) before booting. If an externally started server still answers with only "Welcome to the Mastra API", a banner offers Fix dashboard & restart, which applies the same fix and restarts. Stop and restart also verify the old server process actually released its port — leaked server processes are cleaned up, so a fix can never be defeated by a stale server still answering with its old environment. When the dashboard shows its sign-in page, an info banner explains that the sign-in is identity-only — the server and its data stay on your machine. Once the checkout is scaffolded, Start/Stop controls also live in the Factory header next to the status dot, so the server can be controlled from any tab. The server stops when Yardarm quits — run npm run dev in a standalone terminal for long-lived hosting.
• Work — a native client for the running server's board APIs. Pick or create a Factory project, then use the sub-tabs: Board (kanban over the server's phase pipeline — drag cards along their legal transitions, add cards, and start an agent run with a phase's role), Decisions (approve, dismiss, or retry automation proposals — the human approval gates), Attention (mentions, failures, and waiting agents; unread items badge the Factory tab), and Intake (bind GitHub/Linear/Slack sources to a project and pull incoming issues onto the board). Sign in once via the Server tab's embedded dashboard — the Work tab reuses that session, and Yardarm never stores Factory tokens itself. A local server still asks for a sign-in by design: it is identity-only — the server and all of its data stay on your machine, and the account (the same Mastra account mastracode uses) only establishes who you are, because the board APIs are organization-scoped. A purely local no-auth server can't serve them — sign in via the Mastra platform (the default) or use self-managed auth with WorkOS (WORKOS_API_KEY + WORKOS_CLIENT_ID in .env, which bootstraps a personal organization automatically). Setting MASTRACODE_AUTH_DISABLED=1 never enables the board — it only removes the sign-in screen while the org-scoped APIs keep rejecting requests, leaving the dashboard browsing-only. Settings, integrations, and session transcripts stay in the dashboard.

Sidebar activity indicators

Every chat row in the sidebar carries a live activity dot that reflects the agent's real state: amber = waiting for your input, spinner = working right now, blue = a run finished that you haven't seen yet. Because each chat can run in its own worktree, it's practical to queue up a batch of independent tasks and let several agents work in parallel — the dots tell you at a glance which chats need you. Drag chat rows to reorder them; chats you haven't ordered sort by recency.

While the app is in the background, a desktop notification fires when a run finishes or an agent needs approval or input — clicking it focuses the app and opens that chat. Toggle in Settings → Preferences → Notifications.

When a chat is finished but you want to keep it around, hover its sidebar row and click the archive icon: the chat disappears from the list without deleting its worktree or history. Archived chats collapse into an Archived section at the bottom of the sidebar, where they can be restored or deleted.

Analytics

The chart icon at the right of the tab bar (Cmd+6) opens Analytics: token usage for the current project.

• By day — input/output tokens over time.
• By model and by chat — see where the tokens actually went.
• Compression savings — how many tokens token compression saved.
• CSV export — download the raw numbers for your own analysis.

Figures are token counts, not prices — pricing varies by provider and plan, so Yardarm reports usage and lets you do the math that matches your billing.

Connectors

Settings → Connectors offers one-click sign-ins for common services the agent can use as tools: GitHub, GitLab, Supabase, Netlify, Vercel, and Sentry. Each connector is a hosted MCP server with the OAuth flow handled for you — click Connect, approve in the browser, and every chat in the project can use that service's tools.

The tab shows verified connection status per service (it actually exercises the connection, not just the token), and sign-ins are shared across all of a project's worktrees — one login covers every chat, present and future. For arbitrary MCP servers beyond these, see Settings → MCP Servers.

The same tab hosts two more integrations:

• GitHub signals (/github) — an experimental integration that watches your open PRs through the gh CLI and surfaces their status to the agent.
• Observability (/observability) — local tracing of agent runs, with optional export to Mastra Cloud.

Voice dictation

Yardarm can transcribe your voice straight into the composer using a cloud speech-to-text provider.

1. Open Settings → Voice and enable voice input with the Cloud engine.
2. Pick an STT provider and model — OpenAI (Whisper, GPT-4o Transcribe), Groq (Whisper large v3), Deepgram (Nova-3), and several other Whisper hosts are supported.
3. The provider's API key is a prerequisite: add it under Settings → API Keys if you haven't. The Voice tab shows which providers have keys, and the toggle stays off until one does.

Then, in any chat, click the mic button in the composer:

• Click to start recording (the button pulses red and shows elapsed time), click again to stop and transcribe. Or press-and-hold to talk, release to transcribe.
• Escape cancels a recording and discards the audio.
• Transcribed text is appended to the prompt for you to edit before sending.

Audio is sent only to the STT provider you selected. If dictation isn't enabled (or no provider has a key), the mic button is hidden entirely.