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/model id 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 /v1 for 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 claude and codex prefer an API key from their environment when one is there, and TRMNLY inherits whatever shell launched it — so TRMNLY unsets ANTHROPIC_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.json pre-approves Write or Bash. TRMNLY withholds its tool bridge for the turn, because a harness denied its native Write will simply reach for mcp__trmnly__write_file instead. 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 a trmnly server 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 trmnly command. 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.

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-Enter adds 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 (⌃⇧⌘S drops the screenshot's path into the focused terminal instead).
  • Type @path/to/file (with autocomplete) or #Symbol to inline a file's or symbol's content into the turn.
  • Each tab has its own conversation; bodies are shared across windows via AgentSessionStore so 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 ⌘Z undoes the recall.
  • Dictation inserts at the caret instead of replacing the draft, and one ⌘Z removes 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:

  1. ax_menu_invoke first, 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's Archive and Archive… each stay reachable rather than colliding.
  2. ax_find when it doesn't. Searches the tree and returns path strings you hand straight to ax_action or ax_set_value. Prefer it over ax_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_contains is 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-run ax_find.
  3. ax_wait_for after 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.
  4. ax_focused before key_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 cd into 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
    user Who you are, your role, how you like to collaborate
    feedback Behaviors to repeat or avoid (corrections + confirmations)
    project Current initiatives, deadlines, stakeholders for this project
    reference Pointers 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 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.