Prerequisites & Tool Setup

Trinity relies on a few command-line tools to create projects, manage repositories, and run AI agents. This page covers what you need and how to set it up.

Trinity checks for these tools contextually — when you enter a workspace, open a project, create a project, start a run, or delete a project, you'll see a clear message if something is missing, along with the exact command to fix it. You never have to install anything up front and guess at what's needed: Trinity tells you which tool, and offers to install it in place.

Installing Trinity

Pick your platform from the downloads page — Trinity ships three artifacts: macOS Apple Silicon, Linux x86_64, and Linux arm64.

macOS (Apple Silicon)

Download the .dmg, open it, drag Trinity to your Applications folder, and double-click to launch. Trinity is code-signed with our Developer ID and notarized through Apple, so there's no quarantine workaround needed.

Linux

Download the .deb package matching your architecture (amd64 for x86_64, arm64 for ARM) and install it:

sudo dpkg -i Trinity_*.deb

Required Tools

Git

Git is required for all project operations — creating repos, managing branches, and running worktrees for parallel execution.

macOS:

xcode-select --install

A system dialog will appear — click Install and wait for it to complete. This installs Git along with other developer tools Trinity uses.

Linux (Debian/Ubuntu):

sudo apt install git

Linux (Fedora):

sudo dnf install git

Configure your identity (required for commits, both platforms):

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Trinity checks this when you create or import a project. If name or email aren't set, you'll be prompted to configure them.

Connecting a GitHub account

Repository creation, pull requests, and every other GitHub operation Trinity performs run through Trinity's own REST client, authenticated with whichever account you connect — the gh binary itself is never spawned to do this work. The primary way to connect an account is Sign in with GitHub: an OAuth device flow where Trinity shows a short code, you enter it on github.com, and Trinity finishes connecting the account — no CLI and no token to create. Other hosts (GitLab, Bitbucket, self-hosted GitLab/Forgejo) use an access token instead. See Signing In for the full setup screen and Creating Your First Project for where this fits in project setup.

The GitHub CLI (gh) is optional, and useful in two situations:

• As a way to obtain a credential. If you don't have gh yet, Trinity's setup screen offers Install & sign into the GitHub CLI as one path to a connected account, walking you through the install and gh auth login in-place.
• To reuse an already-authenticated CLI session. If gh is already signed in on your machine, Trinity offers Use @you or Auto-import from your CLIs to lift that session's token straight into Trinity's own keyring, so you don't have to sign in again inside the app.

Either way, once an account is connected, Trinity authenticates git operations itself via its own GIT_ASKPASS helper — gh's own credential state is no longer consulted.

If you'd rather install gh manually first:

macOS (Homebrew):

brew install gh

Linux (Debian/Ubuntu):

(type -p wget >/dev/null || sudo apt install wget) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh

Or see cli.github.com for other distributions.

Authenticate (both platforms):

gh auth login

Follow the prompts to authenticate with your GitHub account.

Route git through gh (ambient identity only)

gh auth setup-git

An account connected through Trinity — by OAuth device flow, by PAT, or by auto-importing an already-authenticated gh/glab/tea session — authenticates git operations through Trinity's own GIT_ASKPASS helper and never touches git's own credential helper, so this step isn't part of that path.

It matters only for the ambient git identity — git operations that run under your machine's own, unbound identity rather than a Trinity-connected account. There, gh auth login only authenticates the gh CLI itself; git's own credential helper still needs to be told to ask gh for a token. Without setup-git, push and fetch over HTTPS will silently prompt for a username on stdin, which has no terminal to answer it and will hang waiting forever. If you rely on the ambient identity, run this once so the credential helper is routed.

Delete Permissions

If you want to use the Delete Project feature (in Project Settings > Danger), the GitHub repo deletion it performs needs the delete_repo scope on your connected GitHub token — not on the gh CLI itself. This scope isn't granted by default.

If you connected your account via the GitHub CLI (Install & sign into the GitHub CLI, or lifting an already-authenticated session with Use @you / Auto-import), add the scope to that CLI session and then re-import the account so Trinity picks up the refreshed token:

gh auth refresh -s delete_repo

Then reconnect the account in Trinity — raising gh's own scope doesn't reach Trinity until the account is re-imported, because the token Trinity stored is a one-time snapshot. If you connected another way (OAuth device flow, a manual token, or a non-GitHub host), reconnect the account with a token that carries delete_repo instead.

Trinity will prompt you for this if needed when you try to delete a project.

Claude Code CLI

Claude Code is the AI agent that powers Trinity's story execution. It's the engine behind the Analyst, Implementer, Auditor, and Documenter phases — the thing that actually writes, reviews, and tests your code.

Trinity checks for it as soon as your model tiers resolve to it — on the way into a workspace, and again when you open a project whose own tiers name it. That check blocks the work surfaces until it clears, and it offers both fixes on the spot: install Claude Code inline, or move those tiers onto the Codex CLI if that's the one you already have. The same binary is what the in-app help assistant runs on, which is why the workspace-level check comes before you've opened any project at all.

Step 1: Install Claude Code

macOS (Homebrew):

brew install --cask claude-code

Any platform (curl):

curl -fsSL https://claude.ai/install.sh | bash

Or via npm:

npm install -g @anthropic-ai/claude-code

Verify the installation:

claude --version

If you see a version number, you're good.

Step 2: Authenticate Claude Code

Claude Code needs access to an AI provider. Run:

claude login

This opens your browser to authenticate with Anthropic. Once approved, Claude Code stores the credentials locally.

Alternatively, if you have an Anthropic API key, you can set it as an environment variable:

export ANTHROPIC_API_KEY="sk-ant-..."

Add this to your shell profile (~/.zshrc on macOS, ~/.bashrc on Linux) so it persists across terminal sessions:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

Step 3: Verify it works

Run a quick test to make sure Claude Code can communicate with the API:

echo "Say hello" | claude --print

You should see a response from Claude. If you get an authentication error, double-check your API key or re-run claude login.

Updating Claude Code

Claude Code auto-updates in the background — no action needed.

Troubleshooting Claude Code

"claude: command not found" — Claude Code isn't installed or isn't in your PATH. Install it:

curl -fsSL https://claude.ai/install.sh | bash

Or via Homebrew on macOS: brew install --cask claude-code

Authentication issues — Trinity runs Claude Code under the same sign-in your own terminal uses, and that sign-in refreshes itself in the background. A run that happens to land while it's refreshing gets turned away once and then works, so a chat turn re-runs itself a few times before it reports anything — you'll usually never see it. If a turn does come back saying the sign-in was refused every time, it's not a refresh in progress, so sign in again:

claude login

Or, if you're using an Anthropic API key instead of a Claude subscription, verify it's set:

echo $ANTHROPIC_API_KEY

Codex CLI

Codex is Trinity's second engine. You only need it if you point a tier at a model it serves — OpenAI's GPT-6 and GPT-5.6 models or xAI's Grok — under Settings → AI Models. If every tier you use runs on Claude Code, skip this.

Like Claude Code, Trinity checks for Codex the moment your tiers resolve to it — entering a workspace whose tiers name it, or opening a project that points its own tiers at it — and again when a run reaches for it, where a missing binary pauses the story at a Tool Not Installed gate rather than failing it. The entry check offers the install inline, or a one-click switch of those tiers back to Claude Code.

Step 1: Install Codex

macOS (Homebrew):

brew install codex

Any platform (npm):

npm install -g @openai/codex

Step 2: Authenticate

Two paths, and either works:

• Sign in with your OpenAI account — run codex login and follow the browser prompt.
• Let Trinity supply the key — add an OpenAI API key under Settings → Secrets and Trinity hands it to Codex on every run. Use this when you'd rather key the engine per-project than sign the machine in.

Step 3: Verify it works

codex --version

If that prints a version, Trinity will find it.

Sandbox dependencies (Linux only)

Every agent Trinity runs is fenced into a sandbox. On macOS that's Seatbelt, which is built into the OS — nothing to install. On Linux the fence is built on bubblewrap, and it needs three packages on your machine:

• bubblewrap — the sandbox itself
• ripgrep — the file-scanning helper it uses
• socat — the sandbox's network relay

Trinity checks for all three once, when it starts, and offers to install them for you: a panel with your password prompt inline, running the right command for your distribution. If you'd rather do it yourself:

# Debian / Ubuntu
sudo apt install bubblewrap ripgrep socat
 
# Fedora / RHEL
sudo dnf install bubblewrap ripgrep socat
 
# Arch
sudo pacman -S bubblewrap ripgrep socat
 
# openSUSE
sudo zypper install bubblewrap ripgrep socat
 
# Alpine
sudo apk add bubblewrap ripgrep socat

On RHEL, bubblewrap and socat come from the base repositories but ripgrep needs EPEL enabled — if the install stops on that one package, that's why.

Optional Tools

Node.js

You only need Node.js if you want to install Claude Code via npm install -g @anthropic-ai/claude-code. The brew and curl install paths above are self-contained and don't require Node.

If you do install Node, 18+ works (22 recommended):

# macOS
brew install node
 
# Linux (Debian/Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Docker Desktop

Some codebases use Docker Compose for local development services (databases, caches, etc.). Docker is only needed if one of your project's codebases includes containerized services.

Install: docker.com/products/docker-desktop

Trinity detects Docker usage per codebase during greenfield setup and shows a reminder if Docker Desktop isn't running when needed.

Chromium-based browser (for PDF exports)

Trinity uses any installed Chromium-based browser to render PDF reports — Chrome, Edge, Brave, and Chromium all work interchangeably. Most users already have one. If none is installed, Trinity offers to install it for you in-place — the PDF export dialogs show an install panel that runs brew install --cask google-chrome on macOS or the right chromium package for your Linux distro (Debian/Ubuntu/Fedora/RHEL/Arch/openSUSE/Alpine all supported). You stay in Trinity the whole time. Other formats (JSON, HTML zip) don't need a browser.

When Checks Happen

If a check fails, you'll see an inline alert with the exact command to run. After running the command, click Check Again to verify.

The git-host connection itself isn't part of these per-project checks — it's verified once per workspace scope, at the First-Time Workspace Setup gate you clear when you first enter a workspace (see Signing In → First-Time Workspace Setup). Every project you create or import in an already-set-up workspace reuses that connected account.

Troubleshooting

"git: command not found"

• macOS: Run xcode-select --install to install Xcode Command Line Tools
• Linux: Run sudo apt install git (Debian/Ubuntu) or sudo dnf install git (Fedora)

"gh: command not found"

The GitHub CLI isn't in your PATH. Restart your terminal after installation, or install it:

• macOS: brew install gh
• Linux: See install instructions above, or visit cli.github.com

"claude: command not found"

Claude Code isn't installed. Run:

curl -fsSL https://claude.ai/install.sh | bash

Or via Homebrew on macOS: brew install --cask claude-code

Token expired / authentication errors

GitHub CLI tokens can expire. Re-authenticate:

gh auth login

Deleting a project's GitHub repos needs the delete_repo scope on your connected account's token, not on gh itself. If you connected via the GitHub CLI, refresh the CLI session's scopes, then reconnect the account in Trinity so it picks up the refreshed token:

gh auth refresh -s delete_repo

Git identity not configured

Git requires a name and email for commits. Set them globally:

git config --global user.name "Your Name"
git config --global user.email "[email protected]"