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 try to 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.

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.

GitHub CLI (gh)

The GitHub CLI is used to create repositories, manage pull requests, and handle branch operations during execution.

If gh is missing or unauthenticated when you try to create or import a project, Trinity walks you through the install in-place — a step-by-step checklist appears with rows like Install Homebrew → Install GitHub CLI → Sign in, completed steps stay on screen as ✓, and the next pending step mounts an inline panel that runs the right command for your OS (Homebrew for macOS, the matching package manager for your Linux distro). You can still install manually with the commands below if you prefer.

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

gh auth setup-git

This step is required, not optional. 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 the Trinity dev server can't answer (it has no terminal) and will hang waiting forever. Trinity's preflight check verifies both steps, surfacing Run: gh auth setup-git whenever the credential helper isn't routed.

Delete Permissions

If you want to use the Delete Project feature (in Project Settings > Danger Zone), the GitHub CLI needs the delete_repo scope. This is not granted by default.

gh auth refresh -s delete_repo

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.

You don't need Claude Code during project setup or planning. Trinity only checks for it when you're ready to start executing stories.

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 — Re-authenticate:

claude login

Or verify your API key is set:

echo $ANTHROPIC_API_KEY

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 projects use Docker Compose for local development services (databases, caches, etc.). Docker is only needed if your project's tech stack includes containerized services.

Install: docker.com/products/docker-desktop

Trinity detects Docker usage during the onboarding wizard 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 and PDF knowledge-base exports — 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.

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

Or refresh your existing token with additional scopes:

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]"