Overview

Trellis, in Plain Terms

Trellis is an AI-native development environment. It runs as a local web app that brings together AI sessions (Claude Code and Codex), terminals, tmux sessions, git worktrees, and logs—both local and remote—into one keyboard-driven interface. The AI sessions get the same access to your services, logs, traces, and crash reports that you have, so debugging starts from real data instead of copy-pasted context.

On Your Machine (Development Environment)

Worktrees as First-Class Environments

Each git worktree represents a separate copy of your code. Trellis treats each worktree as its own environment, with its own terminals, running processes, and logs. Switching branches means switching environments, not re-wiring anything by hand.

Terminal and tmux Management

Trellis creates and manages tmux sessions for you. It defines terminal windows and panes for shells, builds, tests, and diagnostics, so you don’t have to manually manage tmux layouts.

Running Your Application’s Components Locally

Trellis runs and supervises the local instances of the services that make up your application—APIs, workers, daemons, etc.—as part of your development environment. When you rebuild a binary, Trellis detects the change and restarts the affected process automatically.

Local Log Access

You can tail and search the logs produced by those locally running components directly from the Trellis UI.

Reverse Proxy

Trellis can run reverse proxy listeners that mirror your production routing (e.g., Caddy or nginx) locally. Route requests to different backend services by path, with optional Tailscale TLS or custom certificates.

AI Sessions (Claude Code & Codex)

Each worktree can have multiple AI chat sessions — Claude Code, OpenAI Codex, or both side by side. You interact with the agent directly in the Trellis web UI, save transcripts to cases for later reference, and continue previous conversations.

Session Inbox

A small chromeless popup, openable from the inbox icon in any Trellis header, lists every live Claude and Codex session across worktrees. Each row shows a real-time status — running, awaiting your input, stalled on an approval, or errored — alongside a live description of what the agent is doing and how long it’s been there. Click a row and the foreground Trellis window jumps to that session — no scrolling through worktree lists to find the agent that’s waiting on you.

Pair Review & Checklist Runs

Any two live sessions — Claude or Codex, in any worktrees — can be wired into a paired review loop: one session implements, the other reviews, and Trellis relays messages between them until the reviewer approves (a configurable stop signal like LGTM) or a round cap is hit. You watch and steer from a banner on the session pages; typing into either session pauses the loop.

A checklist run builds on pairing to work through a multi-phase plan: the implementer completes one phase, a review pair critiques it until it converges, and the run advances to the next phase — repeating until the implementer signals the checklist is done. Phases that fail to converge pause the run for you to retry, skip, or stop. See Pair Review & Checklist Runs.

Usage & Cost Tracking

Trellis reads the transcript files Claude Code and Codex write locally and turns them into a usage report: cost and tokens per day, per worktree, and per session, priced at API list rates. A badge in every page header shows today’s spend, the Claude chat footer shows the running cost of the current session, and the Usage page has the full breakdown.

Cases

A case is the durable record of a worktree’s effort — one unit of work (bug, feature, investigation, task) that accumulates notes, links, transcripts, evidence, traces, and a commit timeline over its lifetime. Cases are created lazily on the first commit, and at most one is open per worktree.

When the work is done, Wrap Up archives the case directory and bundles it into the final commit, alongside a structured summary that the system generates to make the case searchable later. Intermediate commits along the way are recorded on the case as a per-commit timeline, each with a short Claude-generated description.

Remote Systems (Over SSH)

Remote Terminals

Open terminals on remote machines (staging or production) over SSH directly inside the same web interface you use for local work.

Tailing Remote Logs

Stream logs from remote hosts in real time, without maintaining separate SSH sessions.

Grepping Remote Logs

Search through remote logs—including rotated and compressed logs—using standard Unix tools, but driven from a single UI.

Multi-Host Log Correlation

Search for an ID across multiple remote machines at once, making it practical to follow a request as it moves through several services.

Web UI, Keyboard-First

Trellis runs as a web app (typically on localhost) but is designed to be operated primarily from the keyboard.

Pickers for Everything

A global picker lets you quickly jump between worktrees, terminals, running processes, logs, and workflows.

Keyboard Shortcuts

Common actions—switching context, opening terminals, running commands—are bound to shortcuts so you rarely need to touch the mouse.

Glossary

Term Description
Service A long-running process that Trellis manages (starts, stops, restarts). Services are your app’s components—APIs, workers, daemons. In the picker, services appear as #name.
Service Log The stdout/stderr output from a managed service. Stored in an in-memory ring buffer and displayed in the web UI.
Log Viewer A configured source for streaming logs—SSH connections, local files, Docker containers, or custom commands. Unlike service logs, log viewers pull from external sources. In the picker, log viewers appear as ~name.
Worktree A git worktree—a separate checkout of your repository on a different branch. Trellis treats each worktree as an isolated environment with its own services, terminals, and logs.
Workflow A predefined command or sequence of commands you run frequently—builds, tests, deployments. Workflows can have input parameters and run from the UI or CLI.
Trace Group A named collection of log viewers that are searched together during distributed tracing. Allows correlating events across multiple systems by trace ID.
Remote Window An SSH terminal to a remote server, displayed in the same UI as local terminals. In the picker, remote windows appear as !name.
AI Session A Claude Code or Codex chat session, scoped to a worktree. Accessible via the navigation picker with @ prefix and a robot icon.
Case The durable record of a worktree’s effort — one unit of work (bug, feature, investigation, task) accumulating notes, links, transcripts, evidence, traces, a commit timeline, and a generated summary. At most one open per worktree.
Picker The fuzzy-search popup (Cmd+P) for quickly navigating to any terminal, service, log viewer, or page.