Trellis

Product Introduction

1. Definition: Trellis is a free, open-source, native macOS terminal emulator and integrated development workspace application, built with Swift. It falls into the technical categories of terminal multiplexers, developer productivity tools, and local automation platforms.
2. Core Value Proposition: Trellis exists to replace the fragmented macOS terminal experience by providing a unified, project-centric workspace. Its core value is consolidating terminal windows, SSH sessions, project-specific tasks, and automation APIs into a single, persistent, and code-configurable native application, eliminating context switching and manual session management for developers and DevOps engineers.

Main Features

1. Sidebar Window Management: Trellis organizes terminal sessions into a persistent sidebar. Each project or context gets a dedicated window listed in the sidebar, containing its own set of color-labeled tabs. This provides a visual, spatial map of all active work, replacing dozens of floating terminal windows. It works by managing native macOS windows under a single application instance, with state persistence across restarts.
2. Workspace as Code (project.json & launch.json): This feature allows developers to define terminal workspace layouts and common tasks as version-controlled JSON files within a project's .trellis directory. project.json declaratively specifies window tabs, split-pane layouts, starting directories, and pane-specific startup commands. launch.json defines reusable tasks (like build, test, run) with environment variables. Trellis parses these files to reconstruct an identical workspace for any team member, ensuring environment consistency.
3. Local Automation API & MCP Server: Trellis exposes a comprehensive JSON-RPC API over a local Unix socket for programmatic control. This allows scripts to create windows, send commands, read output, and manage sessions. Critically, it also implements a Model Context Protocol (MCP) server, enabling AI coding assistants (like Claude Code) and other MCP clients to interact directly with the terminal. Access is controlled via scoped, expiring OAuth2-style grants created in the app settings.
4. Shell-Aware Terminal Engine: Based on a patched SwiftTerm engine, it offers modern terminal features without dotfile modifications. It automatically integrates with zsh, bash, and fish to track working directories, command exit statuses, and prompt locations. This enables features like visual failure indicators for commands and keyboard shortcuts (Cmd+↑/↓) to jump between previous prompts, enhancing command-line navigation.
5. Integrated SSH Host Management: Beyond basic terminal emulation, Trellis includes a dedicated host manager (File → Hosts…) that reads ~/.ssh/config and allows for saving additional connections. It uses the system's /usr/bin/ssh, respecting SSH config rules and host key verification. Passwords can be stored securely in the macOS Keychain, protected by Touch ID.

Problems Solved

1. Pain Point: Disorganized Terminal Sprawl and Lost Context. Developers often have numerous terminal windows and tabs open for different projects, leading to a cluttered desktop and difficulty re-establishing complex layouts after a restart or machine reboot.
2. Target Audience: The primary user personas are macOS-based software engineers, full-stack developers, SRE/DevOps professionals, and technical leads who work across multiple repositories, microservices, or remote servers and require a structured, reproducible terminal environment.
3. Use Cases:
   • Onboarding New Team Members: A developer clones a repository, runs one command to load the .trellis project, and instantly has the correct terminal layout and predefined tasks for that project.
   • Context Switching Between Microservices: A developer working on a service-oriented architecture can have a dedicated Trellis window for each service (API, frontend, database), with all relevant tabs and splits pre-configured and one click away in the sidebar.
   • AI-Powered Development Workflow: A developer using an AI agent can grant it controlled access via the MCP server to execute commands, run tests, or monitor logs within the Trellis environment, creating a seamless human-AI collaboration loop.
   • Standardizing DevOps Procedures: Teams can check in launch.json task definitions for deployment, backup, or monitoring scripts, ensuring every engineer uses the same exact commands and environment variables.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):
   • Pros:
     • Native macOS Integration: Built with Swift/SwiftUI, it feels like a first-class macOS citizen with smooth performance, native menus, and deep system integration (Keychain, notifications).
     • "Workspace as Code" Philosophy: The JSON-based project configuration is a powerful differentiator for team standardization and personal environment persistence.
     • Privacy-First & Offline: No telemetry, no accounts, no cloud dependency. All data stays local.
     • Powerful Automation Layer: The combination of a CLI, JSON-RPC API, and MCP server is unique for a terminal, opening advanced scripting and AI integration possibilities.
   • Cons:
     • Platform Lock-in: Exclusively for macOS 14+, excluding Linux, Windows, and older macOS users.
     • Learning Curve: The workspace model and configuration files introduce concepts beyond traditional terminals like iTerm2, requiring initial investment to learn.
     • Early-Stage Ecosystem: As a newer project, it lacks the vast plugin ecosystem and community scripts of established terminals like iTerm2 or Warp.
2. Key Alternatives & Differentiation:
   • iTerm2: The dominant free macOS terminal. Differentiation: iTerm2 is a powerful, feature-rich terminal emulator. Trellis is a workspace manager built around a terminal. iTerm2 has superior theming/scripting via Python API but lacks native project persistence, a sidebar workspace organizer, and the "as code" configuration paradigm.
   • Warp: A modern, GPU-accelerated terminal with AI features. Differentiation: Warp is cloud-connected (with accounts/telemetry), focuses on AI inline in the terminal, and uses a proprietary Rust engine. Trellis is fully local/open-source, focuses on window/tab management and project configuration, and uses a Swift-native engine. Their automation models (Warp's AI vs. Trellis's MCP/API) are philosophically different.
   • tmux / screen: Terminal multiplexers run inside any terminal. Differentiation: tmux is incredibly powerful and cross-platform but operates at a lower level with a steep learning curve and separate keyboard prefix commands. Trellis provides a graphical, native macOS layer on top of multiplexing, with visual management, native font rendering, and direct file/URL clicking, making it more accessible.

Frequently Asked Questions (FAQ)

1. Is Trellis a free terminal for Mac? Yes, Trellis is completely free and open-source software released under the permissive MIT license, with no paid tiers, subscriptions, or telemetry.
2. How does Trellis handle security for project files and automation? Trellis employs a strict "trust-on-first-use" model. Project JSON files are never executed automatically; you must explicitly review and trust a specific version. The local automation API uses scoped, expiring access tokens (grants) and an owner-only Unix socket; the optional MCP server is disabled by default and requires manual activation and token authorization.
3. Can I use Trellis to manage SSH connections and remote servers? Yes, Trellis includes a built-in SSH host manager that imports aliases from your ~/.ssh/config file and allows you to save additional hosts with credentials stored securely in the macOS Keychain, optionally protected by Touch ID.
4. What are the system requirements to run the Trellis terminal app? Trellis requires macOS 14 Sonoma or later. It is distributed as a Universal 2 binary, compatible with both Apple silicon (M1/M2/M3) and Intel-based Macs, with separate architecture-specific DMG downloads also available.
5. How does Trellis compare to using iTerm2 with tmux for session management? While both achieve persistent sessions, Trellis offers a graphical, native macOS management layer (sidebar, drag-and-drop splits) versus tmux's keyboard-driven, text-based interface within iTerm2. Trellis configurations are version-controlled JSON files, whereas tmux configurations are script files. Trellis provides deeper native integration (notifications, Keychain) and a different automation approach via its local API/MCP server.