Navigating the UI

Trinity's interface is built around a sidebar on the left with contextual pages for each major feature area. This page is a tour of what's where.

The sidebar has a fixed header (Trinity logo + user menu), then two pickers — the workspace switcher and the project selector — and three collapsible sections underneath. The sections are sorted by how far their rows reach, narrowing inward the way the pickers above them do:

Workspace — pages that span the whole workspace, always available.
Project — pages tied to a project. The section stays with you when you step out to a workspace page like Activity or Metrics, or to an account page like your Inbox: its rows keep pointing back into the project you were last in, so it doubles as the way back. It is absent only when you have not opened a project yet, or when you have just switched workspace — the project you were in belongs to the workspace you left. Rows unlock progressively as the project advances through its phases (onboarding → imported / planning → structured → executing). While a project is being set up, which rows show depends on how it started: a new project shows Architect, where its setup happens, and a project you're importing shows Import instead, until you confirm the import.
Help — the User Guide, Help Assistant, and Report Bug rows, always available.

Only one section is open at a time — opening one folds whichever was open before it, and clicking the open section's own header folds it too, so all three can be closed at once. The section open when the sidebar first appears is whichever one holds the page you're on; landing anywhere else opens Workspace. Once you click a header yourself, your choice sticks regardless of where you navigate next. The Inbox entry, a task indicator, and the Trinity version label sit at the bottom of the sidebar.

The avatar in the sidebar's top-right corner opens your account: your name, your @handle, your email, and your plan, then Account settings (/account) directly under them, above the accounts you can switch between and Add account. Seeing your handle here is what tells you apart from the workspace named after it. Account settings follow you into every workspace, which is why they hang off the person rather than off a nav section — see App Settings.

Workspace switcher

Directly above the project selector, the workspace switcher names the workspace you are working in — projects, settings, and data plane all scope to it — and is the surface for everything the workspace itself is. Click it and the menu lists every workspace you belong to, with a crown beside the ones you own and a shield beside the ones you manage; click one to switch into it. Beneath that list, separated by a rule, sit Members, Settings, and New workspace — actions on the workspace named above rather than a way to pick a different one. The menu is there whether you belong to one workspace or five.

A dot beside a workspace name means something there is waiting on you, so you can see it without switching in — see Inbox.

Project selector

Names the project you are in — and, on a page that belongs to no single project, the one you were last in, so it stays the way back. It reads No Project only when you have not opened one in this workspace yet. Click to switch projects or open the Create New Project / Add Existing Project flow. Projects from the current workspace only.

Workspace section

Always visible, regardless of project state. Every row here reads the whole workspace, so none of them needs a project in focus:

Activity — global activity feed with filters (project, category, actor)
Recaps — activity summaries and PDF report export
Metrics — execution analytics and AI cost tracking, across every project in the workspace or narrowed to one

Project section

Rows in order of appearance (some only unlock later):

Dashboard — release-scoped view with a release selector, per-PRD progress bars, and stats
Code — read-only code browser for your project's repos: file tree, branch switcher, syntax-highlighted files with Cmd+P search, a commit history graph with per-commit diffs, line-by-line blame, and markdown preview
Stories — browse and filter stories for the active release
Run — execution control, active stories, gate approvals
Releases — create releases, wire dependencies, track lifecycle state
Design — gallery of the project's Architect-generated prototypes, shown as a grid of thumbnail cards
Import — only while you're importing an existing codebase: takes you back to the import wizard at the step you left it on, until you confirm the import (see Importing an Existing Project)
Architect — add features or edit stories through a conversational interface. A project you're importing gets it once you confirm the import
Share — every share link live in the project — prototypes, reports, roadmap and PRD, recaps — in one filterable, bulk-revocable list
Runtime — manage the project's agent runtime: browse, add, and remove skills, view installed commands and hooks, and review AI-authored or imported drafts before they go live
Settings — per-project configuration (general, business, git, AI models, secrets, stack, worktrees, danger zone)

Inbox

At the foot of the sidebar, Inbox carries a single count for everything waiting on you across every workspace you belong to — unread notifications, the invitations addressed to you, and the requests you are able to act on. It sits outside the sections because it reaches your whole account rather than any one workspace, so the count is right without switching workspace first.

Clicking it opens a quick-look popover rather than taking you straight to the full page: a requests waiting row when anything needs your yes or no, then your five newest notifications, each opening straight to where it happened. See all at the bottom takes you to the full inbox. See Inbox.

Task indicator

The sidebar shows a task indicator for background work you're tracking: a story edit, an import, an execution run, a runtime item generation, and every architect run — PRD generation, a roadmap update, prototype or stack generation, research, and diagnosis. Opening it lists each one with its current phase and a live elapsed-time counter (12s, 2m 14s, 1h 4m), so a stalled or long-running task is visible at a glance from wherever you're working.

An architect run also has a home on the Architect's own run bar and in its Agents panel (see Architect), live and steerable from inside the session — the sidebar row is a second, always-visible way to see it's going without opening Architect. What an architect run dispatches along the way doesn't get its own row here: one research wave alone can spawn a dozen near-identical dispatched steps, so only the run they belong to shows, and the fan-out shows in the Agents panel as one summary under the run that dispatched it.

System Tray

Whenever Trinity is running, a status icon sits in your system tray (the menu bar on macOS) — even while the window is closed or in the background. It reports across every account you're signed in on this device, not just the one you're currently viewing, so a failure or a waiting gate on a project or account you aren't currently looking at still shows up here.

The status line reads, in priority order: a waiting-gate count when anything on any of your accounts needs your input (Gate waiting (N)), otherwise how many stories are currently running (N stories running), otherwise a count of failures (N failed), or Idle when there's nothing to report. The icon shifts alongside it — flagged for attention when something's failed or a gate is waiting, filled in while work is actively running, and idle the rest of the time. Click the status line to bring Trinity to the front and jump straight to your Inbox — the tray tells you something needs attention, the Inbox is where you find out which one. The same menu offers Open Trinity and Quit.

Key Page Layouts

Planning Dashboard

Your command center for the active release's plan:

Release selector at the top right — switch between the project's releases
Progress bars — one for the release as a whole and one per PRD inside it
Stats cards — story counts, completion rates, dependency status

New PRDs are created by talking to the Architect, not from the dashboard.

Story Graph

The dependency graph visualizes relationships between stories in the active release:

Nodes represent stories, colored by status (pending, running, complete, failed)
Edges show dependencies
Zoom and pan to navigate large graphs
Click a node to open the story detail panel
Save layouts to preserve custom arrangements

Run Page

Shows execution state for the active release:

Coordinator status — one coordinator per (project, release) pair; running, draining, or idle
Active stories — currently executing with pipeline phase indicators
Gate queue — stories paused at gates awaiting your input
Worker status — how many workers are active and what they're doing

Releases Page

The Releases page has two views, toggled at the top right — Board (one column per status) and Staging Targets (your target branches with the release holding each one). The Board columns are:

Not Started — created; no stories have started yet
In Progress — in_progress; at least one story merged, more pending
Ready to Release — ready; every story terminal, awaiting a promote
Promoting — promoting; a promote hop is in flight
Promote Failed — promote_failed; a hop errored
On Dev — integrated; landed on your dev branch, not yet on main
Partially Shipped — partially_shipped; some repos reached production, others pending
Shipped — shipped; completed releases (historical record)

Click any release card to open its detail panel:

Release Dashboard — five tactical tiles (Run Project, Run SEO, Run Audit, Check Changes, Generate Notes) sit at the top. They run their standalone agents against the current release worktree without advancing the lifecycle. Check Changes previews the per-repo version bumps from what changed. While a promote is in flight or the release holds live staging placements, every tile except Run Project and Check Changes (both read-only) shows a Locked badge.
Promote panel — the three-way mode control (Ship / Integrate / Ship Now) and its action: stage targets — typing a new branch adds it to the list for next time too — and Ship (Ship), Integrate to Dev (Integrate), or Ship Now (Ship Now).
Staging Drift + CI tiles — while staging is active, scoped to a selectable dimension (the Dev row or one staging target).
Status — a two-level accordion: staging placements (one per target), each expanding to that target's per-repo promotion ledger.
PRDs list — every PRD assigned to the release. Each row has a Move action (reassign to another unshipped release) and a Reparent action (set a different release as parent without moving the PRD); both are available only while the release is created or in_progress.
Dependency Editor — manage release dependencies.
Automation overrides — per-release deleteReleaseBranch.

Promotion is always started manually — from the Promote panel here, or from the "Ready to release" card on the Run page once all stories are terminal.

Story Detail

Click any story (from the list, graph, or run page) to see:

Description and acceptance criteria
Metadata — difficulty, surface area, dependencies, tags, targets, display ID (a stable 8-character code like A3F9K2XQ that names the story wherever it's referenced)
Pipeline status — which agent phase it's in
Agent handoffs — reports from each agent in the pipeline
PR and merge status — for completed stories
Comments + activity timeline — who changed what, when

The sidebar's Help section holds three rows — User Guide, Help Assistant, and Report Bug.

User Guide

The User Guide row opens this guide full-window, right inside Trinity — no browser needed. A table of contents on the left lists every section and chapter; pick one to read it in the main pane, or step through the guide in order with the Previous / Next buttons at the foot of each page. Back to Trinity in the top-left returns you to wherever you were working.

Help Assistant

Opening the Help Assistant surfaces a draggable chat panel pinned to the bottom-right: a real conversation where you ask anything about using Trinity and replies stream in live; a history toggle lets you start new chats and revisit or delete past ones. The assistant answers from this user guide and won't make changes to your project, and you can paste screenshots to ask about specific UI elements.

Working in AI conversations

Every AI chat surface — Help Chat, the Architect (where greenfield project setup also happens), and the runtime agent on a project's Runtime page — shares the same composer and behaves the same way:

Keep typing while the agent works — the input never locks. Anything you send mid-reply is queued for the next turn and shown as a chip above the composer; remove a queued message with the × on its chip before it's picked up.
Stop button — while a reply is streaming, the send button becomes a Stop that interrupts the agent and clears anything still queued.
Leaving mid-reply doesn't cancel it — move to another screen, or close the panel, while the agent is still answering and it keeps going; the finished reply is waiting for you when you come back, and picking the conversation back up mid-answer drops you into the one already running rather than starting it over. Stop is the only thing that cancels a reply — that, or quitting Trinity, which ends anything in flight the way it ends everything else.
A reply that goes quiet surfaces a retryable error — if the agent stops producing anything for a few minutes, Trinity gives up waiting and shows an error you can dismiss and retry from, instead of leaving the composer showing "thinking…" with no way out but Stop. This applies no matter how you arrived at the wait, including picking a conversation back up mid-reply.
Solo vs. shared — a chip shows whether the conversation is solo (the agent answers every message) or coop (shared with other members, where the agent only replies when you tag it with @agent). A short banner appears when the mode changes as people join or leave.
When this device isn't hosting — exactly one device runs the agent for a conversation at a time. When that isn't the one you're on, a notice above the composer says so: your messages still land and are answered as soon as a host picks them up. If your device drops off — it slept, or its connection cut out for longer than the hosting window — it takes hosting back on its own and the notice clears, without you reopening anything.
Two agent handles, offered ahead of the people — typing @ lists @agent (tag the surface's own agent — the same wake word coop mode uses) and @research (dispatch a background research run: Trinity plans the investigation, works it in rounds, and can hand back a report or a prototype) before the people in your project. Both are wake words rather than routes, so picking one doesn't notify anybody the way tagging a person does.
Readable replies — the agent's work renders as cards you can scan: assistant text, its reasoning, plans, file changes, and tool/command runs. Tool steps collapse by default — expand one to see the details.
Pick the model for the conversation — a model button in the composer opens a picker where you choose the model and reasoning effort for that conversation, overriding your defaults just for this thread. Reset it any time to fall back to the configured default.
New messages don't yank you around — if you've scrolled up to read while the agent keeps replying, Trinity leaves you where you are. A New messages button appears instead and jumps you down only when you choose to.
A long conversation keeps going — every model can only hold so much of a conversation at once, and quality drops off well before it runs out. When a conversation approaches that, Trinity summarizes its earlier part between turns and the agent carries on from the summary plus everything since. You'll see a marker drop into the conversation where each summary picks up, collapsed and labelled with what it covers — open it to read the summary itself and how much of the conversation it accounts for. Nothing is removed: every message stays exactly where it is and stays readable, and the agent can search and re-read the real history whenever the summary isn't enough, so it looks up what was actually said rather than guessing. Any skills it loaded are put back in front of it after each summary, so it keeps following the instructions it started with. The summarizing happens between turns rather than while you wait, so you shouldn't notice it beyond the marker appearing.

Common Actions

Creating a Release

Releases are usually auto-created (the first one gets minted when you generate your first PRD), but you can also create them manually:

Navigate to Releases
Click Create Release
Enter a name and optional description (Trinity suggests a readable two-word name like "Brave Otter")
Link one or more PRDs (or leave empty and move PRDs in later)
Go to Run to start execution for the release

Adding a Feature

Navigate to Architect
Describe what you want in the chat
Review the plan or changeset the Architect surfaces — talk it into shape, including which release the work should land in
Tell the Architect to commit — it lands the stories and confirms what was created and where

Approving a Gate

Navigate to Run
Look for stories with a gate indicator
Click the gate to review the agent's request (deviation, missing secret, missing assets, etc.)
Choose Approve, Skip, or provide Feedback (re-runs the feedback pipeline)

Exporting a Report

Navigate to Recaps
Click the Export Report button
Choose report type (Executive or Technical)
Select the time period
Click Download to get a PDF

Setting Up a Project on This Device

Trinity owns its own clone of every project at ~/.trinity/projects/ — you don't pick a folder. You'll hit this flow in two situations:

Switching devices — projects you created on another machine show up in the project list but aren't yet cloned here. Click Set up on the project row to clone the workspace into Trinity's managed location.
Repairing a broken workspace — if you (or something else) deletes the workspace folder or one of its repos, a yellow Workspace incomplete banner appears at the top of every project page, listing the missing repos. Click Repair workspace and Trinity re-clones only the missing pieces, leaving valid clones alone.

In both cases there's nothing to configure — Trinity handles the clone location, materializes any project secrets and service-config files, and refreshes workspace-doc assets so the trunk is whole when it returns.

Sidebar switches between major sections
Browser back/forward works for navigation history
URLs are deep-linkable, and every one of them says which workspace — and, where it applies, which project — you are reading. A project page starts /w/{workspace}/p/{project}/, a workspace page starts /w/{workspace}/: stories (/w/{workspace}/p/{project}/stories/{id}), activity (/w/{workspace}/activity) — which belongs to the workspace rather than one project. Releases are selected from a side panel within /w/{workspace}/p/{project}/releases rather than addressed by URL. That is why a link you paste to a teammate opens the same thing for them.
A few pages reach your whole account rather than one workspace, and their addresses carry no workspace at all: your Inbox (/inbox), one notification inside it (/inbox/n/{id}), and Account settings (/account). They would read the same under any workspace, so naming one would be a fiction — and a notification raised in a workspace you are not currently in still has an address you can open. The sidebar keeps its place while you are on one: the workspace switcher goes on naming the workspace you were working in rather than jumping to another you belong to, and the project selector and Project section still point back where you came from.
An address that names no page in Trinity says so, and shows you the address it could not place — a stale link rather than a page that failed to load.

Responsive Design

Trinity is designed primarily for desktop use. The interface works best on screens 1280px or wider. On smaller screens (below 1024px) the sidebar collapses into a drawer with a sticky header at the top.