First run

Four ways to start it, in increasing order of how much of a conversation you want. They share everything that matters — the same agent, the same tools, the same session records — and differ in who is holding the keyboard, or whether anybody is holding one at all.

If mecha tools does not yet list what you expect, or a provider is not configured, go back to Setting up first.

1. mecha run — one task, one answer

mecha run "summarize what changed in this repo today"

The working directory is the workspace: the agent may read anything inside it, and every model-supplied path is canonicalized and proven to sit inside it before anything touches disk. .., symlinks out, and absolute paths elsewhere are refused. -w /some/dir points it somewhere else. Start in a project directory: a workspace containing the mecha home (~/.mecha by default) is refused because it would expose credentials and internal stores.

By default the agent reads freely and asks before it writes or runs a command. Two flags change that:

mecha run --yes "fix the failing test in src/parse.rs"     # approve everything
mecha run --read-only "explain how the retry logic works"  # refuse anything that isn't a read

--yes is what unattended runs need. --read-only is the right default for anything pointed at a repository you have not read.

Useful additions:

mecha run -v "..."                    # narrate tool calls, results and token usage
mecha run --json "..."                # one JSON object instead of prose
mecha run --resume <session-id> "..." # continue a saved conversation
mecha run --max-cost 0.50 "..."       # stop once the run has cost this much
echo "long prompt" | mecha run -      # read the prompt from stdin

Exit codes are distinct so a script can tell the cases apart:

Code	Meaning
0	Completed
1	Error
2	The model refused
3	It produced no answer at all

Exhaustion is deliberately not a failure code. A run stopped by a turn, token or cost ceiling that still answered exits 0 — the work it left behind is graded on its own terms, and --json's stop_cause names the ceiling for callers that care which one it was.

Note that --json implies non-interactive: nothing can answer an approval prompt when output is being piped or parsed, so those runs use the configured permission mode instead of asking.

2. mecha chat — a REPL

mecha chat
mecha chat --resume 20260805T091500   # continue a saved session by id or unique prefix

Readline history, and slash commands:

/tools          list available tools
/model          show the active model and provider
/usage          tokens used this session
/clear          forget the conversation so far
/session        show the transcript path
/exit           quit

One conversation runs for the whole session, and that is a security property rather than a convenience: taint travels with the conversation, so a hostile page read on turn one still arms the interlock on turn five. /clear starts a new conversation, taint included — nothing the old one read is in context any more, so nothing it read should still apply.

3. mecha tui — full-screen, and steerable

mecha tui

Same shape as chat, so switching between them is muscle memory — --resume and --no-session work identically. The difference is that the input line stays live while the agent is working.

That is what makes steering possible. Text typed mid-run does not stop the run and does not wait for it: it is folded into the message that carries the tool results, so the model sees the results and the new instruction as one user turn and keeps going. Cancelling (Ctrl-C) is the other thing, and is deliberately different — it stops the run at the next safe point and keeps the partial answer.

The TUI supports steering because it keeps control of terminal input while a run streams. Web chat and task controls also support steering; the readline chat REPL waits for the run to finish.

The TUI has additional controls. Use /help for its full command list; common commands include:

/help  /tools  /triggers  /outbox  /frontdoor  /polls  /review
/model  /provider  /mode  /mcp  /usage  /clear  /session  /todo
/exit

/mode ask|allow|read-only changes the permission mode without restarting. /mcp <server> on|off toggles one server. /triggers, /outbox and /frontdoor open the scheduled-prompt, staged-send and inbound-request managers. /review now|later|auto decides what happens to drafts a run stages — set only by slash command, never inferred from the prompt, because release policy must not be decidable by anything sharing a context window with third-party text. When context_window is configured, the status line becomes a fuel gauge — context 29.3k/32.8k (89%) — instead of a token count with nothing to compare it against.

4. mecha serve — the same agent, in a browser

mecha serve

The web surface, on your phone or another machine on your tailnet. It will not start until two things are true. The web app is a feature, switched on in [features] like every other — mecha setup asks about it, or:

mecha features enable web

And it needs an owner, because a door with no owner check should not open:

[web]
owner_login = "you@example.com"    # your tailnet identity
port = 63242
assets = "~/.mecha/web/dist"

The pages are a build artifact, not part of cargo install, so they come from a git checkout:

cd <checkout>/web && npm ci && npm run build
rsync -a --delete dist/ ~/.mecha/web/dist/
tailscale serve --bg 63242                     # what makes it reachable

Then open home, chat, review queues and settings, plus mail, the graph and tasks once their features are on — a page whose feature is off is not shown. They share the CLI stores and the same approval rules. A session there starts read-only: reads run, and anything that would send stages in the outbox instead.

It is also the only door voice opens through.

There is a live, clickable copy of the whole app on the web surface — worth a minute before you build it, to see whether it is what you want.

Keep track of the next step

When you delegate a board task, mecha creates a workflow connecting its conversation, questions, and drafts. Start with these views:

mecha workflow today
mecha questions
mecha outbox

Answer a parked question with mecha questions answer, or review a draft with mecha outbox review. The browser offers the same decisions: drafts under Review → Outbox, questions in the task board's waiting view. See Workflows and Today to add commitments, reminders, and explicit completion checks.

Where things are written

Every run writes an append-only JSONL transcript to ~/.mecha/sessions (MECHA_SESSION_DIR overrides it, --no-session opts out).

mecha sessions list
mecha sessions show <id>
mecha sessions path <id>

The transcript is the record, and several other features read it back rather than keeping a second copy that could disagree with it. See Sessions and replay.

When something goes wrong

mecha doctor                         # inspect local stores and setup problems
MECHA_LOG=debug mecha run "..."     # internal tracing, on stderr
mecha config show                   # the merged configuration actually in effect
mecha config path                   # which files are being read, and whether they exist

mecha config show is usually the fastest answer to "why is it using that model": it prints the result of every layer merged together, not the contents of any one file.

Next

• Configuration — the layered TOML and the settings that matter early.
• Interfaces — run, chat, tui, serve and batch in depth, and which of them can redirect a run without stopping it.
• The web surface — the browser one, live on the page.
• Security — what the harness refuses to do, and why.