Farol

Product Introduction

1. Definition: Farol is a native macOS terminal application specifically engineered for agentic coding workflows. It is a specialized terminal emulator built on libghostty, designed to manage and supervise multiple AI-powered coding agents like Claude Code and Codex simultaneously.
2. Core Value Proposition: Farol exists to solve the operational complexity of running parallel AI coding sessions. Its primary value is providing a unified, visual interface for macOS developers to orchestrate multiple AI agents, each isolated in its own git worktree, with integrated tools for code review, version control, and deployment, thereby streamlining the transition from AI-generated code to production-ready pull requests.

Main Features

1. Parallel Agent Sessions with Visual Status: Farol allows users to run Claude Code, Codex, and other terminal-based AI agents concurrently. Each session is visually represented in a sidebar with color-coded status indicators (e.g., working, waiting, done). This is powered by Farol's internal session management and status reporting via a custom CLI or terminal bell integration.
2. Git Worktree Isolation for Each Task: When initiating a new task via a prompt, GitHub issue, or Jira ticket, Farol automatically creates a new git worktree on a fresh branch. This core technical feature ensures complete filesystem and version control isolation between agents, preventing conflicts and allowing truly parallel development streams.
3. Integrated Code Review & Deployment Workflow: Farol includes a built-in diff viewer for all changed files. From within the same window, users can stage changes, write commit messages, push to remote repositories, and directly open a pull request on GitHub or GitLab, creating a seamless CI/CD pipeline for AI-generated code.
4. System-Wide Agent Status Monitoring: Beyond the main app window, Farol provides persistent status updates via a macOS menu bar item (a "lighthouse" icon) and a panel at the Dynamic Island (notch) on supported MacBooks. This delivers non-intrusive, system-wide notifications when an agent requires human input.
5. libghostty Foundation with Native macOS Integration: Unlike a fork, Farol is a standalone native Cocoa application that embeds the libghostty rendering engine. This provides exceptional terminal performance, full support for Ghostty configuration files and themes, and deep integration with macOS native APIs for notifications and UI.

Problems Solved

1. Pain Point: Managing multiple, stateful AI coding agent sessions in standard terminal emulators (iTerm2, Terminal, Warp) is chaotic. Developers struggle to track which agent is active, which is stuck, and manually managing separate git branches for each task is error-prone and time-consuming.
2. Target Audience: The primary user personas are software engineers, senior developers, and tech leads working on macOS who actively incorporate AI coding agents like Claude Code into their daily workflow. Secondary users include open-source maintainers and development managers reviewing AI-assisted contributions.
3. Use Cases:
   • Parallel Feature Development: A developer describes two independent features, spawning a Claude Code session for one and a Codex session for the other, reviewing and merging both sets of changes independently.
   • Bug Triage & Fixes: Linking a GitHub issue to a new Farol task automatically creates a branch and starts an agent to diagnose and fix the bug, with the diff ready for review.
   • Supervised Code Generation & Refactoring: A lead engineer oversees several agents performing different refactoring tasks across a large codebase, using the integrated git graph and diff tool to audit changes before committing.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):

   • Pros:
     • Unparalleled Workflow for AI Agents: It is arguably the most purpose-built, integrated environment for running multiple AI coding agents on macOS.
     • Git-Centric Safety: Automatic git worktree creation is a killer feature that enforces best practices and eliminates cross-session contamination.
     • Native Performance & Integration: Leverages libghostty for speed and offers true macOS-native UI elements and notifications.
     • Transparent & Extensible: MIT-licensed, open-source, no telemetry, and supports custom agents via CLI status reporting.
   • Cons:
     • Platform Lock-in: Exclusively for macOS 14+ on Apple Silicon, excluding Intel Macs, Windows, and Linux users.
     • Agent Protocol Limitation: Advanced status reporting is currently optimized for Claude Code and Codex; integrating other agents may require manual CLI scripting.
     • New & Evolving: As a relatively new open-source project, it may lack the extensive customization and plugin ecosystem of established terminals like iTerm2.

2. Key Alternatives & Differentiation:

   • iTerm2 / Warp / Kitty: These are general-purpose, high-performance terminal emulators. Differentiation: Farol is not a general-purpose terminal competitor; it is a specialized supervisory environment built on top of terminal tech. It adds the orchestration layer, git automation, and review workflow that these terminals lack.
   • Cursor / Zed with AI Features: These are modern AI-powered IDEs with integrated agents. Differentiation: Farol is agent-agnostic and terminal-based, fitting into existing editor-agnostic or Vim/Emacs-centric workflows. It focuses on managing external agent processes and the git/PR lifecycle, rather than embedding an editor's own AI.
   • Manual Scripting & Multiple Terminal Windows: The traditional method. Differentiation: Farol replaces a fragmented, manual process involving several terminal windows, manual git commands, and context switching with a unified, automated, and visual interface.

Frequently Asked Questions (FAQ)

1. Can I use Farol with AI agents other than Claude Code and Codex? Yes, Farol works with any AI coding agent that runs in a terminal. For full status reporting (working/waiting/done), agents need to integrate with Farol's CLI tool or use the standard terminal bell sequence for notification.
2. How does Farol handle different projects or repositories? Farol operates within the context of an opened project directory. Each new task creates a git worktree and branch within that repository. To work on a different project, you open a new Farol window pointed at that project's root directory.
3. Is my Ghostty configuration fully compatible with Farol? Farol reads and utilizes your existing Ghostty configuration file (e.g., ~/.config/ghostty/config), including key bindings, color schemes, and font settings, as it uses the same libghostty engine. Some Ghostty-specific features not related to the core terminal may not be applicable.
4. Does Farol require a subscription or an account to use? No. Farol is completely free, open-source (MIT license), and does not require any user account, subscription, or internet connection for core functionality. There is no telemetry data collection.
5. What are the system requirements for running Farol? Farol requires a Mac with Apple Silicon (M1, M2, M3, or later) running macOS Sonoma (14.0) or a newer version. It is not compatible with Intel-based Macs or older macOS versions.