App Settings

App-level settings control Trinity's global behavior — preferences that apply across every project. Access them by clicking Settings in the sidebar's Hub section.

The page is organized into five tabs: General, Profile, Git & Branching, AI Models, Membership.

General Tab

The General tab is split into sub-tabs: Appearance (theme), Timezone, Automation, Performance, Storage, and Updates.

Theme

Seven theme options:

Timezone

Affects:

• Recap date groupings (daily / weekly / monthly / etc.)
• Metrics dashboard time axes
• Timestamp displays throughout the UI

Timestamps are stored UTC server-side — timezone conversion happens at display time. Set Auto to use the browser's detected timezone.

Automation Defaults

Defaults applied to every project unless overridden. Full cascade: Global → Team → User per-scope → Project → User per-project → Entity (story/release) → Job. These defaults sit at the Global layer.

Toggles available:

• Auto PR — open PRs automatically when a story finishes
• Auto-merge — merge PRs automatically when checks pass
• Squash merge — squash commits on merge
• Delete branch after merge — clean up story branches after merging
• Skip asset check — bypass the missing_assets gate
• Skip business details check — bypass the missing_business_details gate
• Auto-release to base — auto-merge release branches to the production branch on approval
• Delete release branch after merge — clean up release branches
• Auto-approve quality checkpoints — run the full checkpoint pipeline but skip the human gate (release-level release_approval is always manual regardless)

Performance

Max concurrent tasks — the ceiling on how many AI tasks can run on this machine at the same time. Default is 50 (allowed range 1–200). The cap is the only throttle and is shared across every project — tasks within a single project run in parallel too. Each task spawns its own agent process, so this is effectively the cap on parallel agent runs. Story execution is fully separate and uses its own per-release worker pool. Raise it toward 200 if you regularly run many tasks in parallel and your machine + provider rate limits can keep up; lower it if you notice CPU/memory pressure or hit rate-limit errors.

This setting is per-machine and lives alongside the other appearance/timezone preferences — it is not a project-level toggle.

Storage Default

Pick where Trinity uploads project assets by default — Trinity Cloud (managed R2-backed storage with per-seat quota) or BYO S3 (your own AWS S3 / Cloudflare R2 / DigitalOcean Spaces / any S3-compatible bucket). Per-project storage choice in Project Settings overrides this default. BYO S3 credentials saved here are encrypted and follow you across teams.

When Trinity Cloud is selected, the card also shows your current usage: 5 GB included with your seat (shared across your personal scope and teams you own), plus any 10 GB add-on packs you've purchased.

Auto-Update

Trinity checks for updates every 4 hours:

• Available update → pill in the title bar with an Update Trinity button
• Auto-Update (on by default) → install automatically once Trinity is idle (no jobs running or claimed); turn it off to install updates only when you click Update Trinity
• Trinity never interrupts an active run — if jobs are in-flight it waits for them to finish
• Manual install respects the same rule: if execution is active you'll see a "waiting for execution" warning

Profile Tab

The Profile tab is where you manage your account identity. It's split into sub-tabs: Details, Avatar, Handle, Password, and Devices.

Details

Edit the display name shown across Trinity and the website (the user menu, activity, comments, and your avatar's initials fallback). Your email is shown read-only — it can't be changed.

Avatar

Upload a picture (you crop it to a square before it's saved) or Remove it to fall back to the picture from your sign-in provider — and if you have neither, your initials. Your avatar shows everywhere your name appears, across Trinity and the website (activity, comments, the people in a shared conversation). It belongs to your account, not a single project.

Handle

Pick a unique @handle for invites and identification. As you type, Trinity checks availability and only enables Update Handle for a well-formed, free handle (3–30 lowercase letters, numbers, and hyphens; no leading, trailing, or consecutive hyphens). Changing it updates everywhere your handle appears, so teammates see it right away.

Password

Set a new password (at least 8 characters). You enter your current password to confirm it's you; a wrong current password is rejected with an error.

Devices

Secrets in Trinity are end-to-end encrypted: encryption keys are generated and held on your devices, and the server only ever stores ciphertext. The Devices sub-tab lists every machine enrolled on your account and is where you approve, revoke, and recover them.

Each row shows the device's name, platform, last-seen time, and a status badge — Active, Pending approval, Revoked, or No keys.

Approving a new device. Signing in on a new machine enrolls it as pending: it can't read encrypted secrets until an existing device approves it. Open this tab on a device you already use and click Approve. Approval is your call alone — a team owner or admin can never approve a device on your behalf.

Recovery code. Your first device generates a one-time 12-word recovery code, displayed here until you confirm you've saved it. Store it somewhere safe (a password manager works well). If you ever lose every approved device, sign in on a new machine and use Restore with your recovery code on the pending device to get your keys back without an approver.

Revoking a device. Click Revoke on a lost or retired device to permanently bar it from receiving keys. A lost device's keys stay sealed in its OS keychain, so revocation alone is normally enough. If you believe the device may be compromised, check also rotate my keys in the confirmation dialog — every encryption key you hold is reissued, and anything written from that point on is unreadable with the old keys.

Device-change alerts. If new entries appear on your account's device list, Trinity shows an alert prompting you to review the list and revoke anything you don't recognize.

Git & Branching Tab

Split into sub-tabs: Accounts, Destination, Branching, Releases, Merge.

• Accounts — the git accounts connected on this device (GitHub, GitLab, self-hosted Gitea/Forgejo), with a per-host default radio choosing which account Trinity acts as on each host. Connect another account with a token or a guided CLI sign-in, import the accounts your CLIs already hold, and use Set up here for accounts connected on another machine whose credential isn't on this device yet.
• Destination — your default destination for new repositories: the host, the owner/organization, and HTTPS or SSH. New projects start here unless they pick their own destination during onboarding.
• Branching / Releases / Merge — project branching defaults (applied when a new project is created — per-project overrides live in Project Settings → Git). See Project Settings for the full shape of branching configuration.

AI Models Tab

Default models per tier — the global baseline that team / project / story overrides can replace.

You can't assign a model with a lower intelligence level than the tier requires — e.g., you can pick a Sonnet model for the Fast tier but not a micro model for Reasoning.

Providers

Trinity supports models from Anthropic, DeepSeek, Moonshot, Z.ai, Qwen, and a local Ollama runtime. Configure each provider's API key in the same tab.

See AI Model Configuration for the deeper tier explanation.

Membership Tab

Your subscription, sponsorship, and privacy:

• Subscription status (active / trialing / comp / etc.) and trial countdown
• Sponsored-seat management (owners can sponsor other users; recipients accept/decline from the Requests inbox)
• Privacy controls

(Your storage quota and usage live in the General tab under Storage Default — see above.)

How Settings Sync

Global settings live server-side and sync across every device signed into your account. The desktop reads and writes them over HTTP — there's no local override or cached copy of your preferences.

Exception: a small local cache holds non-user-facing values like schema doc hashes and per-machine timeout overrides — none of your preferences.

Data & Disk Layout

Trinity's desktop stores only machine-local state. Project data (PRDs, stories, knowledge, tags, stack, activity, recaps, releases, assets, secrets, user + team settings, etc.) lives in trinityailabs.com's Turso DBs and is reached over HTTP. There is no sync DB on the desktop.

What lives in ~/.trinity/ on disk:

~/.trinity/
├── trinity-{slot}.db          Machine-local SQLite — worktrees, workers, coordinator,
│                              chat sessions, tasks, device_config, local_project_bindings,
│                              local_job_state. Never syncs.
├── accounts-{slot}/           Per-account auth + manifest cache ({slot} = dev | prod)
│   └── {accountId}/
│       ├── auth.json          Durable session token
│       └── manifest.json      Workspace manifest cache
├── active-account-{slot}.json Pointer to the active account
└── projects/                  Trinity-owned clones + git worktrees for parallel execution

The {slot} suffix (dev | prod) keeps development and production state isolated. Signing into localhost or dev.trinityailabs.com uses -dev; signing into www.trinityailabs.com uses -prod.

Reset

If you need to start fresh:

1. Stop all execution
2. Delete ~/.trinity/trinity-{slot}.db (and/or the accounts-{slot}/ folder to sign out)
3. Restart Trinity — the local DB runs its migrations and regenerates empty; auth re-mints on next sign-in; project data is untouched because it lives on the server

Refresh Intervals

Most data updates in real time via a WebSocket push channel as events fire on the server:

• Run page — live updates as stories progress
• Metrics dashboard — push-driven via the WebSocket channel; 5-minute background poll when the channel is unavailable
• Move requests / team members — push-driven; 5-minute poll fallback
• Presence — push-driven (no polling)
• Knowledge base — loaded on navigation; refreshed when an entry is written
• Release selector — refreshed on release transitions

The push channel is on by default in production. You can toggle it via the browser console:

localStorage.setItem('trinity_flags', JSON.stringify({ use_ws_doorbells: false }));

Then refresh — Trinity falls back to the 5-minute polling cadence everywhere.

Keyboard Shortcuts

Trinity uses standard web-app navigation. No custom keybindings are user-configurable today — navigation is through the sidebar and in-page controls.

Resource Usage

Trinity runs a small bundled server alongside the desktop app, plus a local SQLite for machine-only state. Resource usage scales with:

• Number of parallel workers (each worker spawns an agent harness process)
• Active project size (worktree files on disk)
• Agent operations in flight

For most projects, Trinity runs comfortably on a standard development machine.