All pages
Docs · AI features
Agent
Availability: macOS. The GTK app's Agent pane and the cloud workspace run the same tool names against separate, smaller backends — see Platforms.
The Agent panel (right sidebar, Agent tab) is the AI assistant. It reads
your terminal, runs commands with your approval, edits files, drives the
browser, and stitches together long-running workflows from saved prompts,
notes, and memory.
Agents are bound per tab: switching tabs swaps the conversation in the sidebar. Two tabs in the same project can hold two independent threads running against different models.
Picking a provider
Open Settings → API Keys and paste a key for any one of:
- Anthropic (Claude Opus / Sonnet / Haiku)
- OpenAI (GPT-5.x, GPT-4o)
- Google Gemini (Gemini 2.5 Pro / Flash)
No key at all is also fine on a Mac paired with trmnly.dev: the model menu's Pay with section switches a model between Your API key and TRMNLY credits, and on credits the turn runs on TRMNLY's own keys and is paid from your balance. A turn on your own key never spends credits. See Cred wallet.
Three more providers need no entry there:
OpenRouter — paste the key in the Providers sheet (gear menu → Providers, routing & spend…). Any
vendor/modelid on openrouter.ai works, listed in the picker or not — a/in a model id always means OpenRouter.Ollama / LM Studio — local, no key. Point the endpoint at a bare Ollama host, or append
/v1for any OpenAI-compatible server (LM Studio, vLLM, llama.cpp). A local model gets a core set of 15 tools rather than the full catalog, unless the project or persona names its own. See Local LLM.CLI Agents — pick Claude Code (CLI), Codex (CLI), or Gemini CLI from the Your CLI subscription (no API credits) section of the model picker to drive an installed coding CLI as the model. The CLI signs its own requests, so the turn bills against the Claude or ChatGPT plan you already pay for and TRMNLY never holds a key. A CLI that isn't installed is labelled as such in the picker.
Two things are worth knowing about this mode:
- It really does use your subscription. Both
claudeandcodexprefer an API key from their environment when one is there, and TRMNLY inherits whatever shell launched it — so TRMNLY unsetsANTHROPIC_API_KEY/OPENAI_API_KEY(and friends) for the subprocess. Turn that off with Bill to my CLI login, not API keys in the gear menu if you'd rather the key won. - The CLI runs its own tools. Its edits and shell commands are its own, so they don't pass through TRMNLY's approval gate — only the tools it calls back through TRMNLY's MCP bridge do. The gear menu's CLI agent section sets how much it may do unattended: Read-only, Accept edits (the default — with anything less these CLIs refuse to write at all), or Full access (no sandbox). Putting the agent in Observe or Dry-run mode forces read-only regardless.
- Accept edits asks instead of refusing. For Claude Code, a tool that
still needs a yes in Accept edits — a
brew install, say — opens TRMNLY's approval sheet (and a notification) rather than being denied. Approve runs it; Deny, or two minutes without an answer, tells the agent you declined. Remember skips the sheet for that tool for the time you pick. The same sheet covers TRMNLY tools the agent calls through the bridge, with no paired phone needed. Codex and Gemini have no such hook, so for them Accept edits still refuses what it can't auto-approve.
Read-only is enforced in three places, because no one of them is enough. The CLI's own write tools are denied outright — a deny rule, so it holds even if your
~/.claude/settings.jsonpre-approvesWriteorBash. TRMNLY withholds its tool bridge for the turn, because a harness denied its nativeWritewill simply reach formcp__trmnly__write_fileinstead. And for the turn's duration TRMNLY's tool runner treats calls scoped to that project as observe-mode, which is what covers Codex and Gemini: they read their MCP servers from your own config files, not from TRMNLY, so atrmnlyserver you registered there is reachable however the CLI was launched — and now lands on a closed gate.That last gate is not harness-specific. Setting a project's Mode to Observe now also applies to tool calls arriving from external MCP clients, the iOS app, and a pane's
trmnlycommand. Those used to run with full access regardless of the project's mode.The CLI runs in the active project's folder, and refuses to start if there isn't one — a CLI agent resolves files and git state relative to its working directory, and a TRMNLY launched from Finder would otherwise hand it
/. Each conversation resumes its own CLI session, so follow-up turns keep the context the first turn built.- It really does use your subscription. Both
Keys are stored in the macOS Keychain. They are never written to disk in plaintext. Settings export/import deliberately omits them — you have to re-paste on a new Mac.
Switch model from the picker at the bottom of the panel. Per-tab agents can run different conversations against different models. Project-scoped overrides let you pin (e.g.) Ollama or LM Studio for one project without disturbing your default. The Providers sheet also holds per-session routing (a separate tool model, an auto-routed small model, a fallback provider), daily/per-session spend caps, a per-model Context window override, and Extended thinking (Anthropic) — a slider that reserves output tokens for the model's reasoning (below 1024 turns it off). The model's reasoning is carried through a tool-using turn, and the cost meter and spend caps price the model a request actually ran on. The current Claude family (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1, Opus 4.8) is in the list with its real prices and million-token windows.
Done writes only what you changed: a key you edited (clearing one deletes it) and the settings you actually touched. A chat's own tool model and thinking overrides aren't copied into the project by saving, and changing one project setting doesn't freeze every app-wide value into that project — the settings you didn't set keep following your app-wide choice, including later changes to it.
The default model
New conversations start on the default model. Set the app-wide one in Settings → AI Agent → Default model; pin a different one for a single project with Default for new chats in that project's Providers sheet (blank inherits the app-wide choice). Claude Code, Codex and Gemini CLI are on both lists beside the API models, so "new chats run on my Claude Code subscription" is one setting. The header's model menu still switches only the conversation in front of you; its Use as default for new chats item promotes that model to the default in one click.
The default reaches every place a conversation starts without you
choosing: the sidebar's new chat, Auto-Answer,
conversations saved over MCP with conversation_save, and trmnly-code
when .trmnly/code.toml names no model. Nothing chosen anywhere means
Claude Opus 5.5.
Allowance
The spend footer under the transcript carries what the session has cost and how many tokens it used. Beside those sits the allowance pill — something like 82% · 4m: how much of the current provider's limit is left, and how long until it refills.
It costs nothing to show and nothing extra to sign in to. API providers report their rate limit in the headers of requests the agent has already made, so the pill fills in once a turn has run; Anthropic and OpenAI both report it. A provider that reports nothing reads as unknown rather than as full, and a reading old enough to be history is dimmed and dated rather than shown as current.
Claude Code, Codex and Gemini CLI sign in with their own subscription, which reports nothing in a response header. There the pill is a button instead: click it to read the allowance on that login.
The agent can read the same figures itself with usage_read — worth a
call before starting something long, and after a turn fails in a way
that smells like a limit.
Accounts
Gear menu → Providers, routing & spend… → Accounts, directly under the API keys. Keep more than one key per provider and pick which one this project sends: a menu of the slots you have stored (Default key, Account 2, Account 3, …), an Add another key field, and Add.
Anthropic, OpenAI, Gemini and OpenRouter get a picker. Ollama needs no key and a CLI harness signs itself in, so neither has one.
The choice belongs to the project the sidebar is bound to, and it takes effect on the next turn — nothing in flight changes account. This is the same storage a fleet rotates through when one account hits its rate limit.
The conversation
- Type a prompt; hit Enter to send.
Shift-Enteradds a newline. - Drag, drop, or paste images into the input — they attach to the next turn as image content.
- The camera button next to the input runs an interactive screenshot
(drag a region, or Space for a window) and stages it in the composer.
The same flow is on a global hotkey,
⌃⌘S, which works from any app (⌃⇧⌘Sdrops the screenshot's path into the focused terminal instead). - Type
@path/to/file(with autocomplete) or#Symbolto inline a file's or symbol's content into the turn. - Each tab has its own conversation; bodies are shared across windows via
AgentSessionStoreso the same session can be opened in multiple windows. ⇧⌘N(or the+in the chat tab strip) starts a fresh session.
Prompt queue
If you type while a turn is streaming, hit Enter to queue the prompt as the next user turn. The queued prompts drain in order as each turn settles, so you can stack follow-ups without waiting.
⌘⏎ always sends, whatever is running, which is the dependable way
to queue a follow-up mid-turn. ⌘. stops the turn — and clears the
queue with it, since a turn you stopped usually makes its follow-ups
wrong. A turn that fails is treated differently: the error stays on
screen and the queue parks rather than draining every queued prompt into
the same failure. Resume on the queue strip drains it once you've
fixed the cause.
Double-click or right-click a queued prompt to edit, reorder, or drop it. A prompt you are editing is held, so the old text can't go out while you're rewriting it.
The agent has matching tools (prompt_queue_add, prompt_queue_list,
prompt_queue_remove) so it can plant its own follow-ups for itself —
useful for "run, then summarize" — and retract one that later work made
obsolete.
What one turn does
A chat runs exactly one agent loop at a time. ⌘. ends it, and a
tool call that reaches dispatch after you stop is marked canceled
rather than started — the transcript shows you what didn't run.
A reply's length ceiling is the model's own output limit; there is no
flat 4,096-token cap. A reply that hits the ceiling says so and tells
you to send continue to pick up where it left off.
Spend caps are checked at every step of a tool loop, not only the turn you typed, and side calls count against them: auto-summaries, the planner, the auto-router, and self-critique are all metered.
Those side calls stay on the chat's own provider. A chat running on a local model never sends its transcript to a cloud provider to be summarized, planned over, or escalated — which is also why Escalate model on trouble in the gear menu is disabled for a local or CLI chat, with the reason in its tooltip.
Failover to the fallback provider is not Anthropic-only. It fires on a 5xx from the primary mid-turn for OpenAI, Gemini, OpenRouter, and Ollama too, and the transcript notes the switch where it happened.
Reading a reply
Hover an assistant reply for its action bar: copy it as Markdown, retry from the prompt that produced it (in a new branch), or branch from here. Retry needs a user turn above it and refuses while a turn is streaming. Right-click gives the same actions plus pinning and tagging; a user message's context menu adds Edit and resend… and Replay with model….
Links in a reply open directly only when they are http or https.
Anything else — trmnly://, file://, a scheme you didn't expect —
shows you the full address and asks first, because opening it can run an
action in TRMNLY or another app.
Gear menu → Text size scales the whole transcript: replies, code blocks, tables, and diffs alike. Message times show just the time for today and the date for anything older. Restoring a file from an inline snapshot asks first, and names the file and the write it is undoing.
⌃J and ⌃K step through the turn's tool cards; see
Agent safety for approving and denying from the keyboard.
Smart actions
Once the conversation has messages, a chip row above the composer offers
one-tap prompts: fix last error, explain last command, and
review diff. Each sends a pre-built prompt whose first move is a
tool call — read the terminal, run git diff — rather than a clarifying
question. The same actions live in a small global palette on ⌘⌥A,
which works from any app; toggle or rebind the hotkey in the Providers
sheet.
The composer
The draft belongs to its chat. Switch chats, close the window, or quit the app, and it is still there — staged image attachments included. The box grows to fit what you type.
↑in an empty composer brings back this chat's previous prompt, and keeps stepping back while the recalled text is untouched;↓walks forward again to your empty draft. It fires only from the first or last line, so arrows still move the caret inside a multi-line draft, and one⌘Zundoes the recall.- Dictation inserts at the caret instead of replacing the draft, and one
⌘Zremoves the whole utterance. Type inside what it dictated and it stops following. - Pasting keeps the text when the clipboard holds both text and an image. The exception is text that is only the image's own URL.
- An image too large to send is scaled down rather than dropped; one that still won't fit is refused by name. Either way the composer says which and why.
- An
@mention takes a quoted path, so@"src/My Folder/file.swift"works.
Vim mode in the composer
Click the vim pip next to the input (or gear menu → Vim mode for
input) for modal editing in the composer: Esc to normal mode, the
usual motions, registers, and macros, plus ex-commands — :w sends,
:q clears, :e opens the draft in your external editor. Ctrl-V from
normal mode enters transcript mode: j/k walk the conversation's
blocks, v selects, y yanks, dap deletes a tool call, gx opens
its URLs, and Enter quotes the selection into a follow-up.
Visual mode works as it does in vim: v selects characterwise and V
linewise, the selection extends in either direction from where you
started it, and d, y, and c act on what's selected. A plain arrow
key extends the selection like its h/j/k/l twin; Return, Home,
End, Page Up/Down, and Shift-Tab hand the caret back to the text view
and end the selection, so Return still sends and Shift-Tab still cycles
the posture. Control chords pass through to the text view's own
bindings — Ctrl-V is the one exception. Motions, x, and Esc move
over a whole character, so an emoji is one step rather than several, and
Esc reaches your input method first while it still has text in
composition.
Tools
The model has access to a wide built-in tool surface plus anything plugins or MCP servers add. Built-in categories:
| Category | Examples |
|---|---|
| Terminal | read_terminal, send_keys, terminal_press_key (a real keystroke: ctrl+c, escape, an arrow), run_command, bash, spawn_and_read |
| Terminal history | terminal_history_search, terminal_history_read — see Terminal history |
| Files | read_file, write_file, edit_file, apply_patch, list_dir, glob, search_files; file_download / file_upload move binary files in 1 MiB base64 chunks (same sandbox, uploads snapshotted for revert); notebook_read / notebook_edit for Jupyter cells; open_in_editor opens a file at a line in $EDITOR, VS Code, Cursor or Zed |
| Search | grep, find_files, code_search, symbol_search, ast_rename |
| Git | git_status, git_diff, git_log, git_blame, git_log_line; writes: git_stage / git_unstage (paths, matched literally), git_apply (a single hunk — cached stages it, cached + reverse unstages it, reverse discards it), git_discard (unstaged changes to paths; can't be undone, untracked files refused), git_commit (what's staged; hooks run) |
| Worktrees | worktree_list, worktree_create, worktree_switch, worktree_rename, worktree_remove, worktree_adopt, worktree_merge_cleanup |
| Notes | notes_read, notes_write, notes_list, notes_add, notes_rename, notes_delete, notes_select |
| LSP | lsp_goto_definition, lsp_find_references, lsp_hover, lsp_diagnostics |
| Build & test | run_tests, xcodebuild |
| Web | web_fetch, web_search |
| Browser | See Browser for the full Playwright-shaped tool surface |
| Connections | ssh_exec, sftp_read, sftp_write, port_forward_apply, container_exec |
| Docker | docker_compose_up / docker_compose_down (remove_volumes also drops named volumes) / docker_compose_list, docker_container_list (every runtime, stopped ones included), docker_container_start / _stop / docker_container_restart / _logs / _remove, docker_pull, docker_images_list — see Docker |
| Ports | ports_list, ports_reserve, ports_release, ports_kill_listener, ports_resolve_alias |
| Tabs & jobs | list_tabs, list_all_tabs (compact by default; verbose: true for the full rows), attach_to_tab, open_tab (a shell tab in a project with none open), run_in_new_tab, run_in_pane, run_background_job, process_info (processes running under the tab's folder) |
| Images | image_generate — see Image generation |
| Feedback | feedback_submit — file a bug or feature request, see Feedback |
| Help | help_list, help_search, help_read — these help pages, so the agent can look up where something is instead of guessing |
| Conversations | conversation_list, conversation_get, conversation_send, agent_stop_turn (stop a running turn in any conversation, as the Stop button does — queued messages are dropped too) — see Messages from your phone |
| Projects | project_list, project_create (a folder shortcut, idempotent by name, so kanban_add has a board to land on) — see Projects |
| Design | figma_export — export Figma node images (png / jpg / svg / pdf) into the project; needs a Figma token in FIGMA_TOKEN or token |
| Prompts & queue | list_prompts, run_prompt, prompt_queue_add, prompt_queue_list, prompt_queue_remove |
| Schedules | schedule_create, schedule_list, schedule_update, schedule_delete, schedule_run_now — see Scheduled runs |
| GitHub | gh_pr_view, gh_pr_diff, gh_pr_comments, gh_pr_comment, gh_pr_files, gh_pr_create, gh_pr_merge |
| Subagents | spawn_subagent — delegate a focused side task with a narrow tool allowlist |
| Orchestration | plan_create, plan_execute, plan_list (saved plans; a plan interrupted mid-run shows paused and resumes with plan_execute), debug_hypotheses, judge_panel; dry_run_begin stages writes in an overlay, dry_run_diff shows the would-be change set, dry_run_apply writes it (snapshotted for undo) and dry_run_discard drops it — see Agent safety |
| Terminal intel | shell_state, command_provenance, get_command_errors, pipe_panes, session_record, session_replay |
| Kanban | kanban_list, kanban_add, kanban_update, kanban_move, kanban_boards — the per-project Tasks tab and its boards |
| Issue tracker | tracker_issue_context — the GitHub, Linear or Kavanah issue behind a card, see Kanban |
| Races | race_start, race_status, race_pick — one prompt, several agents, see Fleet |
| Allowance | usage_read — how much of the account's allowance is left and when it resets |
| Access keys | access_key_list, access_key_get, access_key_set — the Keys tab's vault |
| OS automation | app_launch, app_list (running apps; include_background for menu-bar ones), app_activate, app_hide, app_quit (graceful; force skips save prompts), mouse_click, mouse_drag, mouse_move, mouse_scroll, key_type, ax_dump, ax_action, ax_window_list, screen_list_displays (display frames, to aim input at a second screen), screen_capture_region (a region, or an app's window by name / bundle_id / pid — no window id needed), osa_exec |
| Clipboard & images | clipboard_read, clipboard_write (asks first — it replaces what you copied), image_describe (on-device OCR of an image file or the clipboard image) |
| Driving other apps | ax_find, ax_wait_for, ax_focused, ax_menu_list, ax_menu_invoke, ax_window_set — see below |
Tools are classified READ (blue badge) or WRITE (orange badge) in the Safety panel. WRITE tools surface an approval card by default; READ tools run silently. See Agent safety for the full posture and approval model.
Driving another Mac app
The agent can operate any running application — not just terminals and the
in-app browser. It needs Accessibility permission (System Settings → Privacy &
Security → Accessibility); every ax_* tool checks first and says so if it's
missing.
The reliable loop is find → act, not dump-and-guess:
ax_menu_invokefirst, when the command exists in a menu. Every command an app exposes to a user is in its menus, named in plain language, whether or not the toolbar button has an accessibility label."File > Export…"beats clicking a coordinate. Matching ignores case, spacing, and the trailing ellipsis, but prefers an exact title — so Xcode'sArchiveandArchive…each stay reachable rather than colliding.ax_findwhen it doesn't. Searches the tree and returnspathstrings you hand straight toax_actionorax_set_value. Prefer it overax_dump: the control you want is usually deeper than a sensible dump depth, and a dump spends context on a tree you then have to parse.title_containsis the field to reach for first, since it also matches AXDescription, AXLabel and AXHelp — frameworks disagree about where a control's label lives. Window segments carry both index and title (AXWindow[0]@"Settings"): index and title together, then the title, then the app's only window, so a path survives an app retitling its only window between the find and the action. With several windows open and none carrying the title, the path is refused rather than guessed by index (windows reorder as focus moves) — re-runax_find.ax_wait_forafter anything that changes the UI. A sheet animating in, a build finishing, a button enabling once a field validates. The alternative is guessing a sleep, which is slow or flaky and usually both.ax_focusedbeforekey_type. Typed text goes wherever focus happens to be; confirming the field took focus is how you avoid typing into whatever was behind the dialog.
Falling back to coordinates: ax_find matches carry a frame, so an element
with no press action can still be clicked. mouse_click takes modifiers
(⌘-click to multi-select, ⇧-click to range-select) and mouse_drag holds the
button across an interpolated path — sliders, reordering, and drag-and-drop
need the intermediate drag events, so a move-click-move sequence won't do.
Searches of another app run in the background, so a slow or busy app can't
freeze TRMNLY. ax_find stops after 10 seconds and ax_dump after 15,
returning what they found so far and saying why they stopped; an app that
stops answering entirely is reported as such. ax_wait_for with
until_gone never reports an element gone just because a search timed out
before reaching it, and a window_index that doesn't exist is an error that
gives the number of windows. ax_window_list lists an app's windows with
their titles, frames and minimized state.
ax_menu_list is worth a call on its own: it reports each item's keyboard
shortcut, and once you know Export is ⌘E, key_press does the job in one call
with no menu left open if it fails.
Posture chip
The chip in the agent sidebar header cycles with ⇧Tab:
- Approve — WRITE tools prompt, READ tools run silent (default)
- Auto-accept — every tool runs without confirmation
- Observe — read-only enforcement; writes blocked at the runner
Posture is per-project and persists across sessions. The destructive-verb gate and the per-tool always-prompt carve-out still fire even on Auto-accept.
The panel header
The header row is deliberately thin — the sidebar has a 320 pt minimum width, and anything that would crowd it lives elsewhere.
- The model badge, the session price, and the "add a key" banner all follow the model your requests actually use. Pick a persona with a model override and they follow the persona's model, not the one still showing in the picker.
- The header's model menu is the same sectioned list as the Providers sheet — Your CLI subscription (no API credits) first, then a section per provider.
- Session cost and token counts appear once, in the spend footer under the transcript, beside the allowance pill.
- The working-directory chip names the folder the agent's tools run
in. For TRMNLY's own agent, choosing a folder from it types
cdinto the focused pane, but only at an idle shell prompt: if something is running there it says so ("The focused pane is busy") and types nothing. With Claude Code, Codex or Gemini CLI as the model the chip shows the folder that CLI actually runs in (the project folder, or the one you chose) and choosing a folder moves the CLI there for its next turn — nothing is typed into a pane. A chat pinned to a worktree always runs in that worktree; the chip says so instead of changing it. - The gear menu holds the transcript exports — plain text, Markdown, and JSON — along with Copy as Markdown and Share session…. Its Observability section has Turn traces…, Eval harness… and Tool telemetry… (see When a turn fails).
The context meter
The thin row under the header reads Context, a bar, and a figure
like 36% · 95.1k / 262k (just the percent when the sidebar is narrow).
It is how full the model's context window will be on the next request,
and the token-budget bar below the transcript reads the same number.
- The window is the model's real one — a per-chat override, what a CLI reports, the model catalog, then a family default — never a flat guess. Hover the meter to see which, plus the last request the provider reported and TRMNLY's estimate of the next one.
- Once a provider has reported a request's size, that report is shown
while it is current; before that it is TRMNLY's estimate.
—means nothing is known yet,<1%a sliver. - The bar turns orange past 75% and red past 90%, with a warning icon. Past 100% is real: the next request won't fit — compact the chat or remove pinned context.
- For Claude Code and Codex the meter shows what the CLI reported for its last request against the window it reports, because the CLI manages its own context (system prompt, tools, project instructions, auto-compact). Their tool calls also appear as cards, marked as run by the CLI, and their reported cost is shown but kept out of TRMNLY's daily spend and caps.
- A size no model window could hold (a whole run's total saved by an older version as the last request) reads as unknown rather than 100%.
Which tools a request carries
The agent has several hundred tools, but a request doesn't send all of
their schemas. Claude models (4.5 and later) get a core set of about 30
tools up front, and Anthropic's tool search finds the rest when the
conversation needs one. OpenAI, Gemini and OpenRouter models get the same
core set plus a find_tools tool that loads more by keyword, and the
tools a chat has loaded stay loaded for it (at most 128). That takes a
request's tool schemas from roughly 94k tokens to about 7k. A persona or
project with its own tool allowlist, a local Ollama model (15 core tools)
and a CLI harness are unaffected. If the agent says it has no tool for
something, asking it to search its tools usually finds it.
Personas
The persona picker at the top of the gear menu gives the session a named role: a system-prompt addendum plus a narrowed tool allowlist (intersected with the project's) and an optional model override. Built-ins: Reviewer, Tester, Planner, PR reviewer, Infrastructure, Incident, and Security — Reviewer and Security are read-only, Tester keeps its edits to test files. Plugins can register their own; Default switches personas off.
Worktree pinning
When a project has multiple worktrees, the agent's tool
context is pinned to the active worktree. File writes, git_*,
bash, and project-scoped tools all target the worktree's folder, not
the project's primary folder. Switching worktrees mid-turn re-pins on
the next tool call.
Context: notes, scratchpad, memory
Three persistent surfaces feed the system prompt:
Notes — per-project markdown; flip Project notes on in the agent scope settings and the active note rides every turn. See Notes.
Scratchpad — per-session working notes the agent writes to and re-reads instead of restating context every turn; view or edit it from the gear menu → Scratchpad….
Memory — persistent across conversations, four types:
Type Use userWho you are, your role, how you like to collaborate feedbackBehaviors to repeat or avoid (corrections + confirmations) projectCurrent initiatives, deadlines, stakeholders for this project referencePointers to external systems (dashboards, trackers)
Browse / edit memory, the scratchpad, and pinned files from the gear
menu in the panel header. What the model sees… (⇧⌘I, same menu)
opens the Context Inspector — the exact assembled context for the next
turn.
Sessions, replay, sharing
- Sessions are persisted automatically. Switch between them from the session list button.
- Replay scrubs through a finished session message-by-message, like a video timeline — useful for "why did the agent decide to do X".
- Session diff compares two sessions side-by-side — e.g. the same prompt run against Opus in one tab and Sonnet in another.
- Share session… (gear menu) creates a redacted bundle of the
conversation + tool calls for handing off to a teammate. You preview
every redaction; API keys and detected secrets are stripped first, and
the file goes wherever you send it from the share sheet — nothing is
uploaded for you. (TRMNLY → Share Session… is a different thing: it
uploads the focused terminal's scrollback, sanitized, as a secret
GitHub gist via
gh.)
Right-click a chat in the tab strip to Rename it (double-click works too), Archive it, Stick to top so it stays at the head of the list, or Delete permanently…, which asks first. All of it holds across tab switches, saves, and a second window with the same chat open.
Edit-and-resend, Replay with model…, and Branch from here carry the chat's persona, context scope, and model settings into the new branch. A replay is the one deliberate exception: it clears the per-chat tool model, so the model you picked answers at every step.
A tool call TRMNLY stopped mid-flight is marked canceled when the chat reopens, with a note saying which it was — running, so it may have partly happened and is worth checking before you run it again, or still waiting for approval, so it never started.
A chat file this build can't read says why — damaged, or written by a newer version of TRMNLY — and leaves the file untouched rather than opening blank. Sending with no chat loaded doesn't lose the message either: it says so, and your text and attachments stay in the composer.
New chats left empty and untouched for a day (still the default title, no message) are cleared away at launch. A chat with any message, a queued prompt, a summary, an open tab or a fork is never pruned.
When a turn fails
A turn that ends without a reply shows a banner saying why. For the
record, gear menu → Observability → Turn traces… lists recent turns
with their timing and token counts; select one to see its events, its
stop: reason and, for a failed turn, the error it ended on in red. A
turn that never reached the model reads stop: no_request. This covers
turns sent from the phone or over MCP too, which have no banner on the
Mac to look at.
Tool telemetry… in the same section counts, on this Mac only, how often each tool succeeds, fails or is denied (off by default), and holds the switch for Send error reports to trmnly.dev with a Send test report button — see Troubleshooting.
Each turn also leaves a short trail in the system log (which chat, which
model, how it ended — never what was said):
/usr/bin/log show --last 1h --predicate 'subsystem == "com.willschulz.trmnly" AND category == "agent-run"'.
Messages from your phone (and other clients)
conversation_send posts a message into any agent conversation, by id,
and runs a turn — or starts a new conversation in a project you name. It is
what the iOS app's chat uses, and any MCP client can call it (behind the
approval tier). conversation_list with all: true lists every
conversation in every project, archived included, whatever window or tab is
open or in front. Blank chats (never written to, default title; each
project's sidebar keeps one open) are left out unless you pass
include_empty: true; hidden_empty says how many.
- A conversation open in a sidebar shows the turn there, as if you had typed it. One that isn't open anywhere runs in the background and is in the sidebar's history afterwards. Nothing is focused or switched on the Mac.
- A conversation that is mid-turn queues the message behind the turn.
- Imported Claude Code transcripts (
conversation_save) are read-only: their next save would replace anything added in TRMNLY. - A deleted conversation, one whose project was removed, a locked-down agent, a full queue and a cost cap each refuse with one sentence saying which.
- The agent's own tool calls still ask for approval under the project's settings, on the Mac and on the paired phone.
- While a background turn runs, a window opened on the same conversation won't start a second run in it; send again once it finishes.
conversation_get reports can_send, and a status block (busy,
queued, pending_approvals, last_error) that a client polls for the
reply, plus the conversation's token usage and estimated cost. With
tool_detail it also returns each tool call's input and output, cut to
that many characters. conversation_send takes up to four images
(base64), saved on the Mac and sent with the turn like a pasted screenshot.
conversation_archive archives or unarchives a conversation;
conversation_delete deletes one (refused while it is running a turn).
Scheduled runs
Gear menu → Automation → Scheduled jobs… manages recurring agent prompts. Each schedule has a name, a prompt, an optional project filter, and an interval (minutes to daily); when due, the prompt lands in an open agent sidebar as a regular user turn — posture and approvals apply as usual. Schedules fire only while TRMNLY is running; if no matching window is open, delivery retries instead of dropping. Run fires one immediately.
Auto-Answer for interactive prompts
The Auto-Answer engine watches the terminal for TUI prompts like
"Continue? [y/N]" or arrow-key menus and responds without your input.
Toggle it per pane from View → Auto-Answer Prompts in This Pane
(⇧⌘A); the on-pane chip's menu sets the global safety mode
(confirmation-style only / banner / all — default is confirmation-style
only) and saves per-prompt answers to an allowlist.
Auto-Answer can pin a fast cheap model for prompt detection so your main agent stays on the model you picked.
Agent Lock
For long unattended runs, Agent Lock blocks all physical input and overlays your screens until you unlock with your Mac password or Touch ID. See Agent lock.
Web search
web_search searches through the first provider with a key in Settings →
API Keys → Web Search (Brave Search, Tavily, Exa, Serper or Perplexity),
then DuckDuckGo, which needs no key but may refuse automated searches. Pin
one provider in Settings → AI Agent → Web search. A search that fails says
why and names every provider tried; it never comes back silently empty.
Results are wrapped as untrusted content, like web_fetch output.
The globe under the message box turns search on or off for one chat (new
chats follow the Settings default, on), and /search turns it on and starts
a search. With it off, the agent isn't offered web_search at all.
Claude models use Anthropic's own web search instead: the search runs on Anthropic's side, the reply shows a "Searched: …" row per search, and the pages it cited are listed under it as Sources. Anthropic bills $10 per 1,000 searches on top of tokens, and the session cost includes it. Settings → AI Agent → Web search caps searches per request (5 by default) or switches Claude chats to the app's search. If an organization has turned web search off in the Anthropic Console, the chat says so once and uses the app's search.
Claude Code and Codex use their own search: Claude Code's WebSearch is
allowed or denied for the run, and Codex gets web_search="live" or
"disabled".
The search query goes to the provider's fixed API host and isn't checked
against the egress allowlist; a query that looks like it contains a
credential is refused before anything is sent. Opening a result with
web_fetch still goes through the allowlist.
Image generation
Ask for a picture — a logo, a diagram, a placeholder hero, an icon — and the
agent calls image_generate, which draws it with OpenAI's image model
(gpt-image-2.5-flare). The file lands in the project at
.trmnly/images/<slug>-<timestamp>.webp (or png when you ask for a
transparent background), the reply names it, and the image shows in the
chat under the tool call. The agent picks a square unless you ask for wide
or tall, and medium quality unless you ask for high; up to two images per
call.
It pays one of two ways. With an OpenAI key in Settings → API Keys the
request goes to OpenAI directly and costs no credits. Without one, a Mac
paired with trmnly.dev runs it on TRMNLY's key for credits: 2 for a
low-quality square, 8 for medium, 31 for high; wide or tall images are
3 / 12 / 45. The result says which was used and what it cost. With neither
a key nor a pairing, the tool says which one to set up. pay_with in the
request forces a choice.
A prompt OpenAI refuses comes back as an error naming the reason, and the
agent rephrases rather than retrying. Claude Code and Codex in a pane reach
the same tool over MCP. On Linux and Windows the own key is OPENAI_API_KEY
in the environment; the cloud workspace's agent always draws on credits.
Egress and safety
The agent's network tools (web_fetch, browser_navigate) go through an
app-wide egress policy. New installs default to Allowlist mode
with a short seed list (github.com, apple.com, stackoverflow.com, …);
localhost dev servers are always reachable, and web_fetch refuses
loopback/private addresses outright. Manage the mode and hosts in
Settings → Security or the Safety panel's Network tab.
Destructive shell verbs fire a one-shot prompt the first time each appears in a session, even on Auto-accept. See Agent safety → Destructive verb gate for the full list.