All pages

Specification

Functional specification

The behavioural contract: what each surface is for, what you can do with it, and the acceptance criteria it is held to. Requirements are numbered FR-<AREA>-n with a priority from P0 to P3. For how-to, see the docs.

Version: 1.1 · Status: Baseline (requirements audited against app 0.1.42 build 43; tool counts refreshed against 0.1.108) · Date: 3 August 2026, counts 19 October 2026 · Owner: Will Schulz

This document specifies what TRMNLY does. It is the behavioural contract: what each surface is for, what the user can do, and what must be true for a feature to be considered correct. It deliberately avoids implementation detail — that lives in the Technical Specification.

Companion documents:

  • Technical Specification — architecture and implementation
  • Appendix A — Agent tool catalog — the full 420-tool surface
  • docs/ — user-facing help (the in-app Help tab)
  • MARKET-POSITIONING.md — market analysis and USP

1. Product definition

1.1 One-line definition

TRMNLY is the agent-native terminal for people who run the whole machine, not just the repo.

1.2 What it is

TRMNLY is a native macOS terminal emulator, forked from Ghostty, that adds a first-class AI agent runtime and the operational surfaces that agent needs to be useful beyond a single git repository: remote hosts, containers, ports, processes, a real browser, an LSP bridge, git worktrees, and the desktop itself.

Three claims define the product:

  1. Machine scope. The agent's reach is the machine, not the working directory. 420 built-in tools span the terminal, filesystem, git, browser, SSH/Mosh, SFTP, containers, ports, processes, and macOS accessibility.
  2. Host, not rival. The same tool surface is re-exported over MCP, so an external agent (Claude Code, or any MCP client) gains TRMNLY's reach without the user switching assistants.
  3. Safety as a product surface. Posture, READ/WRITE classification, host-scoped approval rules, a destructive-verb gate, a signed audit log, and an HID-level lock are user-visible features, not internal guardrails.

1.3 What it is not

Explicit non-goals. Each is a decision, not a gap:

Non-goal Rationale
A better code generator than Claude Code We do not compete on reasoning quality; we host whichever model the user prefers
A cloud agent platform Execution is local, on the user's machine, under their credentials
A reinvented terminal UX Ghostty compatibility and fidelity are load-bearing; we add surfaces, we do not replace the emulator
A minimal terminal Deliberately feature-dense; users wanting minimalism are anti-ICP
Cross-platform today macOS first; Linux is an active branch, Windows is unscheduled
Enterprise-procurement ready No SSO, no RBAC, no central policy server yet

2. Users and scope

2.1 Primary persona — the full-stack operator

A staff-plus engineer or technical founder who owns both application code and the infrastructure it runs on. Juggles 3–10 projects. Already pays for AI tooling. Lives in a terminal. Their agent failures are rarely "wrong code" and usually "the agent couldn't see the failing host / the port conflict / the dead container."

Design consequence: every feature must be reachable without leaving the terminal window, and the agent must be able to reach anything the user can.

2.2 Secondary personas

Persona Need Primary surfaces
Parallel-agent operator Run several agents on several branches, review as a human Workspaces, sessions, Kanban, safety posture
Infra engineer Reach remote hosts and containers from one place Connections, Docker/containers, ports, background jobs
Claude Code user Keep their assistant, gain machine reach MCP server bridge, conversation import
Mobile operator Check on and steer a long-running agent away from the desk iOS companion, remote control, notifications

2.3 Anti-personas

Users on non-macOS platforms (until the Linux tier ships), organisations requiring SSO/central policy today, GUI-first developers, and terminal minimalists.


3. Glossary

Term Definition
Project A named folder shortcut with its own environment, theme, startup command, agent settings and sidebar state. Not a window group.
Workspace A git worktree belonging to a project — a parallel branch checkout with its own directory.
Session One agent conversation. Sessions are bound per terminal tab and stored globally, so the same session can be opened in several windows.
Surface One terminal pane (a Ghostty surface). Splits are trees of surfaces.
Tool A capability the agent can invoke. Built-in, plugin-contributed, or MCP-contributed.
Posture The session's tool-approval stance: Approve, Auto-accept, or Observe.
READ / WRITE A tool's effect classification. WRITE tools are approval-gated by default.
Scope The project (or global) context an operation resolves against.
Bridge TRMNLY's MCP server, which re-exports its tool surface to external clients.
Cred The hosted wallet that meters agent turns for users who do not bring their own key.

4. Surface map

┌──────────────────────────────────────────────────────────────────────────┐
│ TRMNLY window                                                            │
│ ┌────────────┬───────────────────────────────────┬────────────────────┐  │
│ │ LEFT       │ TERMINAL AREA                     │ RIGHT SIDEBAR      │  │
│ │ SIDEBAR    │                                   │                    │  │
│ │            │  tabs → splits → surfaces         │  Agent   Prompts   │  │
│ │ projects   │  (Ghostty panes, native render)   │  Jobs    Queue     │  │
│ │ workspaces │                                   │  Conn    Files     │  │
│ │ tabs       │                                   │  Web     Notes     │  │
│ │ sessions   │                                   │  Tasks   Flows     │  │
│ │ archives   │                                   │  Keys    Docker    │  │
│ │            │                                   │  Plugins Activity  │  │
│ │            │                                   │  Devices Help      │  │
│ └────────────┴───────────────────────────────────┴────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
   Global overlays: Quick Terminal · Command Palette · Settings · Agent Lock

Right sidebar tabs (17): Agent, Prompts, Jobs, Queue, Conn, Files, Plugins, Web, Notes, Tasks (Kanban), Flows (Workflows), Local LLM, Activity, Help, Devices, Docker, Keys. Tabs are split into a primary strip and an overflow menu; the assignment is user-configurable.

Settings panes (16): General, Account, Appearance, Font, Keybindings, Shortcuts, API Keys, AI Agent, Notifications, Updates, Profiles, Security, Permissions, Containers, VibeHub, TestFlight.


5. Terminal foundation

TRMNLY inherits Ghostty's emulator wholesale. The requirements here are about preserving that inheritance while layering TRMNLY surfaces on top.

ID Requirement Priority Status
FR-TERM-1 The terminal must remain a faithful Ghostty surface: same VT parsing, same GPU renderer, same font stack, same escape-sequence support, same shell integration. TRMNLY features must not alter emulation semantics. P0 Shipped
FR-TERM-2 Upstream Ghostty configuration (~/.config/ghostty/config) must continue to load and apply. TRMNLY's native Settings UI writes an override layer that is loaded last, so hand-edited config remains authoritative except where the user has explicitly set a value in the UI. P0 Shipped
FR-TERM-3 Windows contain tabs; tabs contain a tree of splits; each split hosts one surface. Splits support directional creation, focus movement, equalisation, and zoom. P0 Shipped
FR-TERM-4 Split layouts can be saved as named presets and re-applied to any tab. Built-in grid layouts are provided. P2 Shipped
FR-TERM-5 Input can be broadcast to multiple panes simultaneously. P2 Shipped
FR-TERM-6 A global Quick Terminal overlay must be summonable from any application via a hotkey, and dismiss without stealing the user's window focus permanently. P1 Shipped
FR-TERM-7 A command palette must expose every app action, keybinding and project by fuzzy search. P1 Shipped
FR-TERM-8 Session contents may be exported as an asciinema .cast transcript and shared. Exported transcripts must pass through a sanitiser that strips credentials. P2 Shipped
FR-TERM-9 Tabs, splits and their working directories must be restorable across app restarts. P1 Shipped
FR-TERM-10 Terminal text must remain selectable, searchable, and copyable with standard macOS semantics, including in the agent transcript. P0 Shipped

5.1 Acceptance criteria

  • A Ghostty user's existing config produces an identical terminal experience in TRMNLY with all TRMNLY surfaces collapsed.
  • vttest and the Ghostty conformance suite produce identical results to upstream at the same core revision.
  • Closing and reopening the app restores the prior window/tab/split structure and each pane's working directory.

6. Projects and workspaces

6.1 Projects

A project is a folder shortcut with attached configuration. It is the unit of scoping for nearly every other feature: agent settings, tool policy, egress allowlist, notes, Kanban, prompts, ports, and browser state all resolve against the active project.

ID Requirement Priority Status
FR-PROJ-1 A project binds: a folder, a display name, an icon, an optional theme, an optional startup command, environment variables, and per-project agent settings. P1 Shipped
FR-PROJ-2 Opening a project opens a terminal in its folder. Projects are not window groups — a project may be open in many windows and tabs simultaneously. P1 Shipped
FR-PROJ-3 A project's .env file is auto-detected and merged into the environment of agent-run shell commands. P2 Shipped
FR-PROJ-4 Projects support ordering, search, inline rename, templates for new projects, and monorepo sub-package detection. P2 Shipped
FR-PROJ-5 Projects surface live git state (branch, dirty count) in the sidebar without blocking the UI. P2 Shipped
FR-PROJ-6 Port aliases may be defined per project (e.g. myapp.3000) and resolved by the agent's port tools. P3 Shipped
FR-PROJ-7 Switching or activating a project must never silently spawn a new window when no host window resolves; the action must fail visibly instead. P1 Shipped

6.2 Workspaces (git worktrees)

ID Requirement Priority Status
FR-WS-1 A project may own multiple workspaces, each backed by a git worktree on its own branch. P1 Shipped
FR-WS-2 Workspaces can be created, switched, renamed, removed, adopted (from an existing worktree), and cleaned up after merge — from the UI and from agent tools. P1 Shipped
FR-WS-3 A workspace selector sits above the tab list; switching workspace rebinds new terminals and the agent's working directory to that worktree. P1 Shipped
FR-WS-4 External agents (over MCP) can create workspaces, enabling "give this agent its own branch" without the user leaving their assistant. P2 Shipped
FR-WS-5 Removing a workspace must refuse to destroy uncommitted work without explicit confirmation. P0 Shipped

6.3 Acceptance criteria

  • Creating a workspace produces a valid git worktree whose branch is checked out and whose directory is immediately usable as a terminal cwd.
  • Per-project agent settings (model, posture, tool policy, egress mode) persist across relaunch and do not leak between projects.

7. The agent

7.1 Conversation model

ID Requirement Priority Status
FR-AGENT-1 The agent panel is bound per terminal tab: switching tabs swaps the visible conversation. Two tabs in one project may hold independent conversations against different models. P1 Shipped
FR-AGENT-2 Session bodies are shared process-wide by id, so opening one session in two windows shows one transcript. P1 Shipped
FR-AGENT-3 The user can send text, attach images (drag, drop, paste, or a global screenshot hotkey), and attach files as text or image content. P1 Shipped
FR-AGENT-4 An @-menu inserts context references: pinned files, the scratchpad, notes, memory, and the active prompt set. P2 Shipped
FR-AGENT-5 Prompts typed while a turn is streaming are queued and drained in order as each turn settles. Cancelling a run clears the queue. P1 Shipped
FR-AGENT-6 The transcript must render markdown, tool-call cards with expandable input/output, diffs, and images; and all of it must be selectable text. P1 Shipped
FR-AGENT-7 A turn can be cancelled at any point; cancellation must flush buffered output into the transcript rather than losing the tail. P0 Shipped
FR-AGENT-8 A panic/lockdown control freezes the agent: no new sends, no pending approvals run, the run loop refuses to start. It clears on relaunch. P1 Shipped
FR-AGENT-9 Voice input (dictation) and spoken responses (TTS) are available, including a hands-free mode that runs a continuous listen/respond loop. P3 Shipped
FR-AGENT-10 Sessions are searchable, exportable, archivable, and deletable. P2 Shipped

7.2 Models and providers

ID Requirement Priority Status
FR-MODEL-1 The user may bring their own key for Anthropic, OpenAI, Google Gemini, OpenRouter, or point at any OpenAI-compatible /v1 endpoint (including LM Studio), or run locally via Ollama. P0 Shipped
FR-MODEL-2 API keys are stored in the macOS Keychain, never written to disk in plaintext, and deliberately excluded from settings export. P0 Shipped
FR-MODEL-3 Model selection is available globally, per project, and per session. A project may pin a local model without disturbing the user's default. P1 Shipped
FR-MODEL-4 The model catalog is open, not a closed enum: unknown model identifiers are usable, and a / in an identifier implies OpenRouter routing. P1 Shipped
FR-MODEL-5 Token usage and cost are tracked per turn and per session, with a visible budget and a cap that blocks (and offers to raise) rather than silently overspending. P1 Shipped
FR-MODEL-6 The BYOK commitment must be visible during onboarding, not hidden behind the hosted wallet. P1 Partial
FR-MODEL-7 Local models must be discoverable and manageable in-app (pull, list, remove) via the Local LLM tab. P2 Shipped

7.3 Tools

The full catalog is Appendix A. Summary:

Domain Tools Domain Tools
Browser 144 Docker & containers 13
Terminal & panes 56 Filesystem & search 13
Knowledge & collaboration 47 Orchestration 13
OS & desktop 34 Safety & policy 12
Automation & workflows 26 Code intelligence 10
Git & GitHub 12 Projects & worktrees 9
Ports 10 Build, test & jobs 7
Remote & connections 6 Terminal intelligence 6
Web & network 2 Total 420
ID Requirement Priority Status
FR-TOOL-1 Every built-in tool must declare a display name and a READ/WRITE classification in exactly one place, so the dispatcher, the approval policy and the Safety panel cannot disagree. P0 Shipped
FR-TOOL-2 READ tools run silently under the default posture. WRITE tools surface an approval card. P0 Shipped
FR-TOOL-3 Tool results must be truncated and summarised so that a single call cannot blow the context window; the model must be told when truncation occurred. P1 Shipped
FR-TOOL-4 Tool calls run concurrently where safe, with per-tool retry policy and deadline trimming. P2 Shipped
FR-TOOL-5 Failed tool calls return a machine-readable reason the model can act on — never a bare failure. P1 Shipped
FR-TOOL-6 Adding a built-in tool must require touching one group file plus one enum case — no edits to four parallel switch statements. P1 Shipped

7.4 Context and memory

ID Requirement Priority Status
FR-CTX-1 The system prompt is assembled from labelled blocks: base prompt, project context, pinned files, AGENTS.md/AGENT.md, notes, scratchpad, memory, recalled memories, and git state. P1 Shipped
FR-CTX-2 A context inspector must show the user exactly what the next request will contain, block by block, with token counts. P2 Shipped
FR-CTX-3 Only the stable prefix is marked cacheable, so prompt caching is effective without invalidating on every turn. P1 Shipped
FR-CTX-4 Context assembly must not block the main thread: disk reads and subprocess calls happen off-main during streaming. P0 Shipped
FR-CTX-5 Long sessions auto-summarise, and stored transcripts are trimmed with snapshot sidecars under a fixed disk cap. P1 Shipped
FR-CTX-6 The agent has a durable memory store, scoped per project, that it can read and write via tools. P2 Shipped

7.5 Orchestration

ID Requirement Priority Status
FR-ORCH-1 The agent can create and execute a plan — a task graph with checkpoint/resume, cost preview and deadline trimming. P2 Shipped
FR-ORCH-2 The agent can spawn sub-agents for parallel work. P2 Shipped
FR-ORCH-3 Parallel-hypothesis debugging and judge-panel solution search are available as tools. P3 Shipped
FR-ORCH-4 A counterfactual dry-run overlay stages writes in memory; the user can inspect the aggregate diff and then commit or discard without disk having been touched. P2 Shipped
FR-ORCH-5 Self-critique, escalation to a stronger model, and anytime-answer behaviour are available and configurable. P3 Shipped
FR-ORCH-6 Agent runs can be scheduled and triggered without the user present. P3 Shipped

8. Agent safety

Safety is a product surface with its own panel, its own vocabulary and its own audit trail. This section is the trust contract.

8.1 Posture

ID Requirement Priority Status
FR-SAFE-1 Every session has one of three postures: Approve (default; WRITE tools prompt), Auto-accept (all tools run), Observe (read-only; writes and shell commands blocked at the runner, not merely hidden in the UI). P0 Shipped
FR-SAFE-2 Posture is per project and survives restart. It is visible at all times in the sidebar header and cycles with a single keystroke. P0 Shipped
FR-SAFE-3 A per-session read-only flag can freeze one conversation into an audit pass without changing the project default. P1 Shipped

8.2 Gates

Gates run in a fixed order before any tool executes, stopping at the first denial and accumulating force-prompt reasons:

outbound secret scan → project tool policy → session read-only
   → destructive-verb gate → branch guard → multi-file edit gate
ID Requirement Priority Status
FR-SAFE-4 Outbound content is scanned for secrets before it leaves the machine; a hit denies the call with a reason the model receives. P0 Shipped
FR-SAFE-5 Per-project tool policy resolves in order: hard deny → project unlock → session unlock → default prompt. A hard deny never prompts and cannot be overridden by Auto-accept. P0 Shipped
FR-SAFE-6 Any individual tool may be marked always prompt, forcing an approval card even under Auto-accept. P1 Shipped
FR-SAFE-7 A destructive-verb gate fires a one-shot prompt the first time each irrecoverable shell verb appears in a session, even under Auto-accept. Verbs cover recursive delete, force push, hard reset, git clean, DROP/TRUNCATE, dd, mkfs, shutdown/reboot, broad kill, and recursive chmod on /. The gate can be re-armed. P0 Shipped
FR-SAFE-8 A branch guard requires two-key confirmation for writes touching protected branches (main, master, plus a user-configured list). Declining keeps the branch read-only for the session. P1 Shipped
FR-SAFE-9 A multi-file edit gate refuses to approve sibling writes individually when a single logical edit spans several files, so the user approves the whole change or none of it. P2 Shipped
FR-SAFE-10 Filesystem access is bounded by an allowed-folders sandbox; commands are additionally filtered by user-editable regex rules. P1 Shipped

8.3 Approval rules

ID Requirement Priority Status
FR-SAFE-11 An approval card offers: allow/deny once, allow/deny scoped to the call's host or path origin, and always-allow/always-deny for the tool. P1 Shipped
FR-SAFE-12 Rules persist per project. Specificity wins: a host-scoped rule beats a tool-wide rule. P1 Shipped
FR-SAFE-13 Network egress is governed by a per-project allowlist with Open and Allowlist modes. Denials must offer the agent a recovery path that requests one specific exception rather than disabling allowlisting. P1 Shipped

8.4 Audit

ID Requirement Priority Status
FR-SAFE-14 Every tool call, approval, denial and rule change is appended to a durable NDJSON audit log. P0 Shipped
FR-SAFE-15 Audit entries are chained with an HMAC signature; the user can verify the chain from the UI, and tampering must be detectable. P1 Shipped
FR-SAFE-16 Any logged tool call or granted approval can be revoked in one click, which locks the tool for the project and clears related rules. P1 Shipped
FR-SAFE-17 The Safety panel shows a live badge counting tool calls in the last five minutes. P2 Shipped
FR-SAFE-18 Any tool write to a file can be reverted from a write-snapshot, from the UI or by the agent. P1 Shipped

8.5 Agent Lock

ID Requirement Priority Status
FR-LOCK-1 While armed, Agent Lock blocks physical keyboard and mouse input at HID level and overlays every attached display, so an unattended agent run cannot be disturbed or hijacked. P1 Shipped
FR-LOCK-2 Unlock requires the Mac account password or Touch ID. P0 Shipped
FR-LOCK-3 Synthetic input generated by the agent's own tools must continue to work while locked. P0 Shipped
FR-LOCK-4 If TRMNLY dies while armed, an out-of-process watchdog must lock the real screen rather than leaving the machine open. P0 Shipped
FR-LOCK-5 A bypass watch must detect and report attempts to defeat the lock. P2 Shipped

8.6 Acceptance criteria

  • With posture set to Observe, no write tool, shell command, or browser mutation reaches the system, verified at the runner and not just the UI.
  • Killing TRMNLY (SIGKILL) while Agent Lock is armed results in a locked screen within the watchdog's detection window.
  • Editing one byte of the audit log causes chain verification to fail and name the first broken entry.

9. Machine-scope surfaces

This section is the moat: capabilities the agent reaches that stop at the repo boundary in competing products.

9.1 Connections — remote hosts

ID Requirement Priority Status
FR-CONN-1 Saved SSH and Mosh hosts are listed in a sidebar tab and connectable in one click. P1 Shipped
FR-CONN-2 The agent can execute commands on a saved host, and read/write files over SFTP. P1 Shipped
FR-CONN-3 Port-forward presets can be saved and applied per host. P2 Shipped
FR-CONN-4 tmux and screen sessions on a host are discoverable and attachable. P2 Shipped
FR-CONN-5 Host credentials are never placed in the agent transcript. P0 Shipped

9.2 Containers

ID Requirement Priority Status
FR-CTR-1 TRMNLY can drive an existing Docker daemon: list/start/stop/restart/remove containers, view logs, list/pull images, run containers, and manage Compose projects. P1 Shipped
FR-CTR-2 On macOS 26+ (arm64), TRMNLY runs containers itself as Virtualization.framework microVMs from OCI images, with no Docker Desktop, OrbStack or Colima installed. P2 Shipped
FR-CTR-3 Built-in containers are explicitly app-lifetime: quitting TRMNLY stops them. Their filesystems persist, so a stopped container resumes with its writes intact. This trade-off must be stated in the UI. P1 Shipped
FR-CTR-4 Published container ports are relayed from the host so localhost:<port> works as users expect. P1 Shipped
FR-CTR-5 The microVM kernel is downloaded on demand, not bundled. P2 Shipped
FR-CTR-6 The agent can open a shell inside any container. P1 Shipped

9.3 Ports and processes

Running several projects on one machine makes ports a scarce shared resource. The panel exists to answer "whose is this?" and "where do I put the next one?"

ID Requirement Priority Status
FR-PORT-1 Listening ports can be listed, reserved, released, and suggested-free; a listener can be killed by port. The table unifies host processes, container publishes, active SSH tunnels, and reservations. P2 Shipped
FR-PORT-2 Project port aliases resolve to concrete ports for both the user and the agent. Slugs are assigned at project creation and survive renames. P3 Shipped
FR-PORT-3 Every listener must name its owning project where one can be determined — host processes by working directory (deepest project root wins), containers via the Compose project's directory. Attribution is best-effort and must report "unattributed" rather than guess. P1 Shipped
FR-PORT-4 A conflict badge must mean genuine contention. Specifically not conflicts: one process holding IPv4 and IPv6 sockets; a container plus its host-side proxy; two listeners on disjoint bind addresses; a project bound to its own reservation. A wildcard bind overlaps every address. P1 Shipped
FR-PORT-5 A conflict row must name both sides, not merely flag that something is wrong. P2 Shipped
FR-PORT-6 A suggested port must be verified bindable by the kernel at suggestion time, not merely absent from the last scan. Privileged ports and ports commonly claimed by other services (macOS AirPlay's 5000/7000, database defaults) are skipped by default, with the reason reported and an override available. P1 Shipped
FR-PORT-7 Finding a free port and reserving it must be available as one action, so the assignment is recorded and later suggestions steer around it. Contiguous blocks are supported for projects running several services. Re-claiming a port the project already reserved is idempotent. P2 Shipped
FR-PORT-8 Killing a listener must never take down a container's runtime plumbing, and must report permission failures rather than claiming a kill that did not happen. P1 Shipped
FR-PORT-9 Agent tools must not mutate the user's visible panel state — filters passed to a tool apply to that call's result only. P1 Shipped
FR-PORT-10 A project's declared ports must be readable from its own configuration before anything runs — .env* keys, Compose published ports (with variable interpolation resolved), package.json script flags, and framework config files. Declarations are classified listen versus connect; outbound targets (mail, relays) are never reservation candidates. P2 Shipped
FR-PORT-11 Ports that two or more projects both declare must be reportable as collisions before either project starts, and importable as reservations with automatic remapping of the ones already spoken for. A remap must state that the project's own config still needs updating. P2 Shipped
FR-PORT-12 A port-forward preset may name the project its local listeners serve, so tunnel-held ports are attributed like any other. Presets saved before the field existed must continue to load. P3 Shipped
FR-PROC-1 An Activity Monitor tab lists running processes by CPU and memory, with recorded history and saved time periods. P2 Shipped
FR-PROC-2 Process enumeration must use a single ps invocation and one parser — not per-row shell-outs. P1 Shipped

9.4 Browser

The browser is the largest single tool domain (144 tools) because agent-driven web work is a first-class use case, not a convenience.

ID Requirement Priority Status
FR-BROW-1 An in-sidebar browser tab renders pages with system WebKit at Safari parity — no bundled Chromium. P1 Shipped
FR-BROW-2 Every page-facing configuration (user-agent suffix, HSTS, fullscreen policy, fraud warnings) must route through one shared configuration path. P0 Shipped
FR-BROW-3 The agent can navigate, click, type, scroll, drag/drop, upload, screenshot, evaluate JS, read DOM and accessibility trees, and locate elements by CSS, XPath, text, natural language, pixel coordinate, or accessibility fallback. P1 Shipped
FR-BROW-4 Console messages and network requests are captured continuously and drainable by the agent, with pattern filtering. P1 Shipped
FR-BROW-5 Playwright-parity primitives are provided: auto-waiting assertions, route mocking and blocking, cookies/storage control, viewport and user-agent override, environment emulation (geolocation, colour scheme, timezone, locale, offline), permission grants, HAR record/replay/diff, and PDF export. P2 Shipped
FR-BROW-6 Tab lifecycle includes pinning (survives close-all), hibernation (drops page state, keeps the pill), undo-close with TTL, and duplication. P2 Shipped
FR-BROW-7 Named session buckets isolate cookies and storage, and can be cloned, expired, exported and imported. P2 Shipped
FR-BROW-8 Saved credentials autofill inside the page: the plaintext password must never enter the agent transcript, and lookup returns metadata only. P0 Shipped
FR-BROW-9 Browser actions can be recorded, saved, replayed, and exported as Playwright or Puppeteer source. P3 Shipped
FR-BROW-10 Visual regression is supported: screenshots compare against a baseline stored in the project. P3 Shipped
FR-BROW-11 Composed ergonomics tools must collapse common 3-call sequences (click → wait → verify) into single round-trips. P2 Shipped
FR-BROW-12 Browser scope defaults to per-tab; per-project browser settings must resolve through the project resolver, never a raw scope identifier. P1 Shipped

9.5 Desktop and OS automation

ID Requirement Priority Status
FR-OS-1 The agent can list, launch, activate, hide and quit applications; synthesise mouse and keyboard input; read and act on the accessibility tree; and capture screen regions. P2 Shipped
FR-OS-2 AppleScript/osascript execution is available as a tool. P2 Shipped
FR-OS-3 All OS-automation tools are WRITE-classified and gated by macOS TCC permissions, whose status must be visible and repairable from Settings → Permissions. P0 Shipped
FR-OS-4 Screenshots taken for the agent must be transient and size-bounded; full-resolution bitmaps must never be retained. P0 Shipped

9.6 Terminal intelligence

ID Requirement Priority Status
FR-TI-1 The agent can query live shell state (cwd, env, last exit code) without sending keystrokes. P1 Shipped
FR-TI-2 Command history is recorded with provenance (who ran it — user or agent), and errors and statistics are queryable. P1 Shipped
FR-TI-3 Pane output can be piped between panes; sessions can be recorded and replayed. P2 Shipped
FR-TI-4 Long job output can be digested rather than returned in full. P1 Shipped
FR-TI-5 Provenance is stamped at send time only — never inferred retroactively. P1 Shipped

10. Knowledge and workflow surfaces

10.1 Files, Notes, Tasks

ID Requirement Priority Status
FR-FILE-1 A project file tree supports preview, inline edit, and pinning files into agent context, with a live filesystem watch. P1 Shipped
FR-FILE-2 The tree must never render blank when a listing is in flight; in-flight listings must not be dropped. P0 Shipped
FR-NOTE-1 Each project has a markdown scratchpad that is injected into the agent's system prompt and readable/writable by tools. P2 Shipped
FR-KAN-1 Each project has a Kanban board whose cards are addressable as #N and mutable by both the user and any agent, including external agents over MCP. P2 Shipped

10.2 Prompts, Queue, Jobs

ID Requirement Priority Status
FR-PROMPT-1 Saved prompts support variables, autofill, recents, snippet expansion, folders, importable packs, and three run targets: send to agent, queue as a command, or paste-and-run in the terminal. P2 Shipped
FR-QUEUE-1 Each split has a command queue with auto-run and attachments; the agent can enqueue, list, clear, and advance it. P2 Shipped
FR-JOB-1 Long-running commands can be launched as background jobs that survive the pane, with progress reporting and output digests. P2 Shipped

10.3 Workflows

ID Requirement Priority Status
FR-FLOW-1 Runbooks are recorded, named, parameterised sequences of steps that the user or agent can replay. P2 Shipped
FR-FLOW-2 Tab-monitor rules fire actions when terminal output matches a pattern, or on cron / file change / idle / git events. P2 Shipped
FR-FLOW-3 Workflows, browser actions and monitor rules share one tab, one tagging model, and one run log. P2 Shipped
FR-FLOW-4 Workflows can be exported, imported, and shared by URL. P3 Shipped
FR-AWAKE-1 The Mac can be kept awake for the duration of a command or agent run, acquired and released by tool or by preference. P2 Shipped
FR-NOTIF-1 The agent can post user-facing notifications, and end-of-turn notifications fire when the app is backgrounded. P2 Shipped

10.4 Access keys

ID Requirement Priority Status
FR-KEY-1 A Keys tab stores integration API keys: metadata on disk, values in the Keychain. P1 Shipped
FR-KEY-2 The preferred consumption paths are environment injection and {{key:…}} placeholders. Direct retrieval by the model is the escape hatch, not the default. P1 Shipped
FR-KEY-3 Keys are excluded from settings export. P0 Shipped

11. Extensibility and interop

11.1 MCP server (TRMNLY as host)

ID Requirement Priority Status
FR-MCPS-1 TRMNLY exposes every agent tool — built-in, plugin-contributed, and MCP-client-contributed — to external MCP clients. P1 Shipped
FR-MCPS-2 External calls route through the same runner, so the same approval rules, audit log and project context apply. There must be no privileged back door. P0 Shipped
FR-MCPS-3 The bridge is disabled by default; enabling it is an explicit user action, persisted across relaunch. P0 Shipped
FR-MCPS-4 Connected clients auto-bind to the focused project. P2 Shipped
FR-MCPS-5 An external agent can persist its transcript into TRMNLY's session store, badged as imported and idempotent on external id, so it appears in the sidebar UI. P2 Shipped
FR-MCPS-6 Setup must be a copy-paste of one path into the client's config — no manual protocol work. P1 Shipped

11.2 MCP client (TRMNLY as consumer)

ID Requirement Priority Status
FR-MCPC-1 External MCP servers can be configured and their tools, prompts and resources merged into the agent's surface. P2 Shipped
FR-MCPC-2 MCP-contributed tools carry their own approval classification and are subject to the same gates and audit. P0 Shipped
FR-MCPC-3 Server schemas are validated; malformed tool definitions must be rejected, not crash the agent. P1 Shipped

11.3 Plugins

ID Requirement Priority Status
FR-PLUG-1 JavaScript plugins can register agent tools, status-bar widgets and sidebar views. P2 Shipped
FR-PLUG-2 Each plugin runs in an isolated JS context with declared permissions. P0 Shipped
FR-PLUG-3 A plugin that errors repeatedly is quarantined: its timers stop, its tools refuse, and its last error is preserved until manual reload. P1 Shipped
FR-PLUG-4 Plugin tools use the same registration surface as MCP tools, so the agent cannot tell them apart and safety applies uniformly. P1 Shipped

11.4 Scripting and automation interfaces

ID Requirement Priority Status
FR-SCRIPT-1 TRMNLY exposes an AppleScript dictionary and App Intents / Shortcuts actions. P3 Shipped
FR-SCRIPT-2 Custom keyboard shortcuts can bind a chord to a built-in action, a saved prompt, a runbook, or send-text. P2 Shipped
FR-SCRIPT-3 Global keybinds work while TRMNLY is not focused. P2 Shipped

12. Companion clients

12.1 trmnly-code CLI

A native terminal coding agent built on the same agent runtime, installable as a standalone command.

ID Requirement Priority Status
FR-CODE-1 trmnly-code runs an interactive REPL agent in any terminal, with slash commands, tab completion, a vi-mode line editor and streaming output. P2 Shipped
FR-CODE-2 Model, provider and reasoning effort are settable by flag, by .trmnly/code.toml, or at runtime, with a fallback chain. P2 Shipped
FR-CODE-3 The same safety surface applies: approval, allowlists, risk classification and a diff review flow before writes land. P0 Shipped
FR-CODE-4 It is the delivery vehicle for platforms where the full app is unavailable. P1 Partial

12.2 Remote control and iOS

ID Requirement Priority Status
FR-REM-1 A Mac can be paired to a trmnly.dev account with a short human-typable code, without pasting a long-lived token. P1 Shipped
FR-REM-2 Once paired, a remote client can drive TRMNLY over an authenticated tunnel using the MCP surface. P1 Shipped
FR-REM-3 The iOS companion provides terminal viewing, prompt sending, conversation review and approval handling. P2 Partial
FR-REM-4 Remote approvals must present the same information as local ones — a remote user must not be approving blind. P0 Partial
FR-REM-5 Pairing can be revoked per device from either end. P0 Shipped

13. Configuration, accounts and lifecycle

13.1 Settings

ID Requirement Priority Status
FR-SET-1 A native Settings UI covers 16 panes and writes an override layer applied after the user's hand-written Ghostty config. P1 Shipped
FR-SET-2 Every setting is searchable, shows its current versus default value, and can be reset inline. P2 Shipped
FR-SET-3 Named profiles capture a settings snapshot and can be restored. P3 Shipped
FR-SET-4 Settings export/import moves configuration between Macs. The export must redact secrets — API keys, access keys and credentials are never included. P0 Shipped
FR-SET-5 Import must detect and surface conflicts rather than overwrite silently. P1 Shipped

13.2 Accounts and billing

ID Requirement Priority Status
FR-BILL-1 Users who do not bring a key may buy metered credits (the Cred wallet); balance and spend are visible in-app. P2 Shipped
FR-BILL-2 The wallet must not be positioned as a precondition for using the agent — BYOK must be equally prominent at first run. P1 Partial — see §16
FR-BILL-3 The release client must never hold a provider-side billing key; all metered traffic goes through a server-side proxy. P0 Shipped
FR-BILL-4 Per-turn metering must be visible before the spend, not only after. P1 Shipped

13.3 Onboarding, help and updates

ID Requirement Priority Status
FR-ONB-1 First run offers a guided tour that names the surfaces and gets the user to a working provider. P1 Shipped
FR-ONB-2 A What's New sheet summarises changes after an update. P2 Shipped
FR-HELP-1 The in-app Help tab renders the repository's user docs, searchable, and readable by the agent through help tools. P1 Shipped
FR-UPD-1 The app self-updates via a signed Sparkle appcast, with a visible update pill and release notes. P1 Partial — appcast not yet hosted
FR-UPD-2 Distribution is a Developer ID-signed, notarised DMG. P0 Shipped

13.4 Diagnostics

ID Requirement Priority Status
FR-DIAG-1 Crash and hang reports are captured locally and mirrored where the user can find and share them. No diagnostic payload leaves the machine without consent. P0 Shipped
FR-DIAG-2 Logs are retained under a bounded policy and rotate. P1 Shipped
FR-DIAG-3 A repro-bundle export collects the state needed to file a useful bug. P2 Shipped
FR-DIAG-4 A main-thread watchdog detects and reports UI hangs. P1 Shipped

14. Cross-cutting requirements

14.1 Performance

ID Requirement Budget
NFR-PERF-1 Terminal input latency must remain indistinguishable from upstream Ghostty No measurable regression
NFR-PERF-2 The main thread must never block on disk, network or subprocess I/O Zero blocking calls on main
NFR-PERF-3 Agent streaming must not degrade terminal responsiveness 60fps sustained during stream
NFR-PERF-4 Sidebar rendering must not re-layout per streamed token Coalesced updates only
NFR-PERF-5 Steady-state memory must not grow with pane-screenshot or transcript history Bounded caches, transient bitmaps
NFR-PERF-6 App bundle stays a fraction of Electron-class competitors Native Swift/Zig, no bundled browser engine

14.2 Privacy and data handling

ID Requirement
NFR-PRIV-1 Agent execution happens on the user's machine under the user's credentials. No code or terminal content is sent anywhere except the model provider the user selected.
NFR-PRIV-2 Secrets live in the Keychain. Nothing in the export path may contain them.
NFR-PRIV-3 Transcripts, audit logs and recordings stay local unless the user explicitly shares or syncs them.
NFR-PRIV-4 Outbound content is scanned for secrets before transmission.
NFR-PRIV-5 Telemetry, if enabled, must be opt-in and inspectable.

14.3 Reliability

ID Requirement
NFR-REL-1 A crash must not lose an in-flight transcript beyond the last coalesced flush.
NFR-REL-2 Corrupt persisted state must be backed up and replaced with defaults, never fatal at launch.
NFR-REL-3 A misbehaving plugin, MCP server or tool must degrade to an error, never take down the app.
NFR-REL-4 Concurrent writes to shared stores must be ordered, not last-writer-wins-by-race.

14.4 Accessibility and localisation

ID Requirement
NFR-A11Y-1 Sidebar surfaces expose accessibility labels; the agent transcript is navigable by VoiceOver.
NFR-A11Y-2 Voice input and spoken output provide a non-keyboard path to the agent.
NFR-I18N-1 User-facing strings route through the localisation layer. English ships; the mechanism must not require refactoring to add a locale.

14.5 Platform strategy

ID Requirement Status
NFR-PLAT-1 macOS 15.0+ is the supported baseline; built-in containers require macOS 26+ on Apple Silicon Shipped
NFR-PLAT-2 Linux is a branch of this repository sharing the Zig core, not a fork In progress
NFR-PLAT-3 Cross-platform reach is served first by trmnly-code and the MCP boundary, not by porting the full UI Partial
NFR-PLAT-4 Windows is unscheduled and gated on libghostty compiling for Windows at all Not started

15. Release acceptance gates

A build is releasable when all of the following hold:

  1. Fidelity. Terminal conformance matches the upstream Ghostty revision.
  2. Safety. Observe posture blocks 100% of WRITE tools at the runner. The destructive-verb gate fires on every listed verb. The audit chain verifies. Agent Lock's watchdog locks the screen on forced termination.
  3. Secrets. A settings export contains no API key, access key, or saved credential. The outbound scanner blocks a planted secret.
  4. Persistence. Kill-and-relaunch restores windows, tabs, splits, working directories, sessions and open sidebar tabs.
  5. Performance. No main-thread block over the watchdog threshold during a streaming turn with the sidebar open.
  6. Distribution. The DMG is signed with the Developer ID identity, notarised, and staples successfully.
  7. Docs. docs/ matches shipped behaviour; the Help tab renders every topic without a missing-resource error.