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:
- 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.
- 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.
- 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 |
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
| 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. |
| 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:
- Fidelity. Terminal conformance matches the upstream Ghostty revision.
- 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.
- Secrets. A settings export contains no API key, access key, or saved
credential. The outbound scanner blocks a planted secret.
- Persistence. Kill-and-relaunch restores windows, tabs, splits, working
directories, sessions and open sidebar tabs.
- Performance. No main-thread block over the watchdog threshold during a
streaming turn with the sidebar open.
- Distribution. The DMG is signed with the Developer ID identity, notarised,
and staples successfully.
- Docs.
docs/ matches shipped behaviour; the Help tab renders every topic
without a missing-resource error.