Using the app

The chat screen piece by piece, plus everything built around it: modes, approvals, sandboxing, review and shipping, checkpoints, goals, stored workflows, and parallel conversations.

The chat screen, piece by piece

The header

• Mode selector — three color-coded buttons: Plan Build Fast. See Modes.
• Model selector — switch the active model for this chat.
• think — extended-thinking level (off / low / medium / high / xhigh / max). Higher levels are slower but better on hard problems; which levels apply depends on the selected model.
• auto-approve — the "yolo" switch. On, the agent runs tools and edits files without asking; off, you approve each sensitive action.
• sandbox — run this chat's shell commands inside an OS-level sandbox. While it's on, a green shield chip appears next to the switch — click it to configure network access and allowed paths. See Full sandbox.
• goal chip — set an objective the agent works toward across runs. The chip is color-coded once a goal is set: blue while active, amber when paused, green when done. See Goals.
• review chip — have the agent code-review this chat's changes or an open PR. See Agent code review.
• Threads (Cmd+P) — switch, rename, clone, or delete conversation threads. See Threads and subchats.

The transcript

• Tool calls appear as expandable cards — click one to see the exact command, file diff, or output.
• Approval prompts appear inline when the agent wants to do something sensitive, with Allow once / Always allow / Deny buttons.
• Plan approval: in Plan mode the agent ends with a plan card — approve it to let the agent start building, or edit/deny it.
• Questions from the agent appear as answer cards with options or a free-text field.
• Task checklist — when the agent breaks work into tasks, a collapsible "Tasks n/m" strip appears under the header showing live progress. It hides itself when everything is done.
• Marker lines — actions triggered from buttons (like reviews) don't post a user bubble; the transcript shows a compact muted one-liner (e.g. "Review: PR #42 — fix auth") instead. Hover it to roll back, like any message.

The composer

• Enter sends; Shift+Enter inserts a newline.
• / opens slash-command autocomplete (arrow keys to navigate, Tab to complete, Enter to run).
• @ searches project files and inserts a mention so the agent looks at that file.
• Attachments — click the paperclip, or paste/drag-and-drop files straight into the composer. Images and PDFs are sent to the model directly; text/code files (markdown, logs, CSV, source files, …) are inlined into the prompt so any model can read them.
• Mic button — voice dictation, if enabled. See Voice dictation.
• While the agent is running, the send button becomes Queue: messages you send are queued in a strip above the composer (each with a dismiss button) and delivered in order when the current run finishes. The red square button stops the current run.

Modes: Plan, Build, Fast

Switch with the header buttons or /plan, /build, /fast. Each chat remembers its own mode across restarts, and each mode can have its own default model (Settings → Models).

A good rhythm for nontrivial work: start in Plan, let the agent explore and propose, approve the plan, and let it flip to Build to execute.

Approvals and permissions

Unless auto-approve is on, the agent asks before sensitive actions (running commands, editing files, calling MCP tools). Each prompt offers:

• Allow once — just this call.
• Always allow — this tool for the rest of the session.
• Deny — block it and tell the agent why, if you like.

For finer control, run /permissions to open the permissions panel: per category (read / edit / execute / MCP / other) and per tool, set allow / ask / deny for the session.

The auto-approve switch in the header is the blunt instrument: everything runs without asking. Recommended only in isolated worktrees (the default) and projects you can afford to roll back.

Full sandbox (OS isolation)

Approvals control whether a command runs; the full sandbox controls what it can touch once it does. Flip the sandbox switch in the chat header (or run /sandbox) to execute the agent's shell commands inside an OS-level sandbox — seatbelt on macOS, bubblewrap on Linux (install the bwrap package first). Not available on Windows.

What it does — and, honestly, what it doesn't:

• Writes are contained. Sandboxed commands can only write inside the chat's worktree, the sandbox allowed paths, and temp directories; writes anywhere else fail.
• Reads are not restricted. The sandbox limits damage, not what the agent can look at.
• Network is all-or-nothing. Allowed by default; the Allow network switch blocks it entirely (installs, fetches, and pushes will fail while blocked).

If the agent needs to write somewhere else, it asks with a sandbox access request card — approving adds that directory to the allowed paths, and the grant applies to sandboxed commands immediately, no restart needed.

The setting persists per chat, and a green shield chip appears in the header while it's active (with "no net" when the network is blocked) — click it to reconfigure. Defaults for new chats live in Settings → Preferences → Agent sandbox. Pairs well with auto-approve: yolo speed, contained blast radius.

The same /sandbox dialog holds the rest of the session's settings: smart editing, completion notifications, and a skip global instructions switch that leaves your ~/.mastracode global agent instructions out of this one session (project instructions still apply).

Token compression

Long sessions accumulate big tool outputs the model keeps re-reading on every turn. Flip Token compression in Settings → Preferences to shrink stale tool outputs in the prompt sent to the model:

• duplicate results are replaced with a stub pointing at the first occurrence
• big homogeneous JSON arrays are crushed to their head and tail (error-like items are preserved), including arrays nested one level inside objects
• noisy text is cleaned: ANSI color codes stripped, repeated log lines collapsed
• outputs are compressed by what they are: build/server logs lose progress bars, repeated lines, and the middle of deep stack traces; unified diffs are compacted without dropping a single +/- line (only context and, if needed, whole trailing hunks); HTML is stripped to its text
• anything still long is reduced to a head+tail excerpt

Recent turns are never touched, and compression is reversible: every replacement names its toolCallId, and the agent can fetch the original via the built-in retrieve_full_output tool (or just re-run the original tool). The toggle is global and applies to all chats immediately, no restart needed. Stored chat history is never modified: compression happens transiently per model call, so transcripts, rollbacks, and threads are unaffected. The estimated tokens saved show up as a green Saved by compression line in the cost popover (/cost) and as a green figure next to the usage counter in the chat header while compression is on.

The separate Verbosity steering switch in the same card appends a short constant instruction to the system prompt asking the agent not to restate tool outputs and to keep replies brief — it works with or without output compression and doesn't disturb provider prompt caching.

Reviewing and shipping changes

The Changes tab (Cmd+4) is a full review-and-ship surface for the chat's worktree:

• Diffs — side-by-side Monaco diffs of every changed file.
• Stage / unstage files and commit with a message.
• Commit history for the worktree branch.
• Push, pull, and merge into base — merge the yardarm/… branch back into the branch you started from, or use the CLI integration for PR/MR flows: gh for GitHub repos, glab for GitLab. The host is auto-detected from the origin remote; for self-hosted instances set it explicitly in Project Settings → General → Repository host.
• Agent review — the magnifier button asks the chat's agent to review the branch's local changes. See Agent code review.
• Compare against any branch — the compare button in the header diffs the worktree against another branch (from their merge-base), read-only: staging and committing come back when you switch back to Current (HEAD).

Nothing the agent does in a worktree touches your own checkout until you merge it.

Agent code review

Click the review button in the chat header (next to the goal chip) to open the review picker:

• Review local changes — reviews the branch's committed work against its base branch, plus anything uncommitted.
• Open PRs / MRs — pick any open pull request (GitHub, requires the GitHub CLI, gh) or merge request (GitLab, requires the GitLab CLI, glab) from the list to review it.
• The optional focus field steers the review toward a specific concern ("error handling", "security", a file name, …).

Reviews run silently: no user message is posted — the transcript just shows a compact "Review: local changes" or "Review: PR #42 — …" marker line (hover it to roll back, like any message). If a run is already active, the review queues behind it.

When the review finishes, a follow-up bar appears above the composer:

• Post review as PR/MR comments — the agent posts its findings on the PR with gh (or the MR with glab; comment only — it never approves or requests changes). Offered after PR/MR reviews, and after local reviews when the branch has an open PR/MR.
• Build a plan to execute — switches to Plan mode and turns the findings into a prioritized implementation plan for approval.

If the agent performed the review but never wrote the findings out, the bar says so and offers a one-click nudge that asks the agent to share the review it just did — the comment/plan follow-ups appear once it does.

The same review can be started from the magnifier button on the Changes tab or from the keyboard: /review changes (local), /review <pr-number> (a PR or MR), /review alone (list open PRs/MRs to pick from); append a focus to either form, e.g. /review 42 security.

Checkpoints and rollback

Every message you send pins a checkpoint: a real git ref (refs/yardarm/checkpoints/*) snapshotting the worktree at that moment.

To rewind, hover over one of your messages and click the circular-arrow pill next to it (it only appears when there is actually something to roll back). Confirming will:

1. Restore all files to the snapshot taken just before that message.
2. Remove that message and everything after it from the conversation.
3. Put the message text back in the composer so you can edit and resend it.
4. Tell the agent (on your next message) that a rollback happened, so it doesn't act on stale memory.

A fork pill may appear beside the rollback pill — that branches the conversation into a new subchat tab instead of rewinding it. See Threads, forking, and split view.

The checkpoint manager

The checkpoints panel in the Changes tab gives you the full picture: every checkpoint of the chat — the automatic per-message ones and any you created yourself — in one list. From there you can:

• Create a named checkpoint now, before trying something risky.
• Rename or tag checkpoints so the important ones stand out.
• Compare any two checkpoints as a read-only diff to see exactly what changed between two moments.
• Prune stale automatic checkpoints that are no longer referenced by any message (rollback targets are never pruned).

Checkpoints are ordinary git refs inside the repository — they never leave your machine and don't appear on your branches.

Goals: let the agent run to completion

For bigger objectives, click the goal chip in the header (or use /goal) and describe the outcome you want. The agent keeps working across runs until an independent judge model agrees the goal is met — not just until the agent claims it is.

By default Set goal & start kicks off a run toward the goal immediately. Untick Start working right away if you'd rather set the goal first and launch it with your own detailed prompt — the judge then starts evaluating from your next message. If a run is already in progress, the goal simply attaches to it. Resuming a paused goal also picks the work back up right away when the agent is idle.

In the goal popover you can:

• set or edit the objective,
• choose the judge model,
• cap the number of runs,
• pause/resume, or clear the goal.

A banner above the transcript shows live goal status: blue while active, amber when paused, green when the judge signs off.

The popover also keeps an evaluation history: every past objective with its per-iteration pass/fail verdicts and the judge's reasoning, so you can see how a goal converged (or why it kept failing) long after it finished.

Workflows: save and re-run multi-step processes

When you find yourself asking the agent for the same multi-step process again and again, ask it to save the process as a workflow. The agent builds the workflow in chat, and from then on it's a stored, repeatable procedure you can run on demand — no re-explaining, no forgotten steps. Stored workflows are shared with the mastracode CLI.

Where workflows shine:

• Release checklists — bump the version, run the test suite, build the installers, draft the release notes, tag: one workflow, the same way every time.
• Repeated multi-step refactors — apply the same mechanical transformation (rename a pattern, migrate an API, update imports) across the codebase, module by module, whenever the next batch is ready.
• Codebase audits — a standing security / dependency / dead-code audit you re-run before every release and get comparable results each time.
• PR-review pipelines — fetch the PR, review it with your team's checklist, summarize the findings, and post the comments — the same rigor for every review.
• Scaffolding routines — "new API endpoint", "new React feature folder", "new microservice": generate the files, tests, and docs your conventions require, fed with a JSON input for the parts that vary (names, paths, options).

Manage stored workflows in Project Settings → Workflows (or run /workflows): the tab lists each workflow with its description and lets you run one — optionally with a JSON input for workflows that take parameters — watching per-step results appear as it executes, or delete ones you no longer need. To change a workflow, just ask the agent in chat and have it save the workflow again.

Threads, subchats, forking, and split view

Each chat can hold multiple threads — independent conversation histories over the same worktree. Press Cmd+P or use /threads to switch, rename, clone, or delete threads, or open one in a new subchat (its own agent process, running in parallel). The cost popover (/cost) breaks token usage down per thread.

Forking. To branch a conversation at a specific point, hover one of your messages and click the fork pill next to it. The agent's memory is cloned as a new Mastra thread — truncated to just before that message — and opens as a new subchat tab over the same worktree. The original conversation continues unchanged, so you can explore an alternative direction without losing anything. (Rollback pills in the forked transcript only cover messages sent after the fork.)

Split view. The columns button at the right of the tab bar opens a second chat pane beside the current one — pick any other chat in the project and both run side by side (drag the divider to resize). Useful for watching one agent work while briefing another. Cmd+P and other global shortcuts stay with the left (primary) pane.