Farol

Overview

Farol is a Mac app for running coding agents on a local Git checkout. You give the agent a task in Chat. When it changes code, Farol runs your pipelines on the branch. A failed check goes back to the agent, which fixes it, and the loop repeats until every check passes.

How it works

  1. You describe the task

    Open a project and write the task in Chat. Pick the agent and model, and choose Plan or Build mode.

  2. The agent works on the checkout

    The agent runs through its own CLI, like Claude Code or Codex, in the project folder. When it finishes a change, it picks the pipelines that apply to it.

  3. Farol runs the checks

    Farol runs every pipeline the agent picked, against the files on disk, uncommitted work included. Shell steps run your linter and tests. AI steps review what a script can’t.

  4. Failures go back to the agent

    A failed step sends its report to Chat. The agent fixes the problem and the pipelines run again. The task is done only when they all pass.

The workspace

The Farol window has a few parts. You will use all of them in a normal session.

ProjectsThe rail on the left. Each open folder is a project. Worktrees of the same repository sit under one group, so two agents can work on two branches at once.
ChatWhere you talk to the agent. Plan mode proposes a plan without changing files. Build mode makes the change and runs pipelines.
PipelinesLists of checks: shell commands, AI reviews, and Git steps. You build them on a canvas, and they are saved in the repository.
Source ControlA full page for Git: pick the files to commit, write or generate a message, push, and open or merge a pull request.
Code and TerminalPanels beside Chat. Terminal panes run your own shell, with your prompt, aliases, and PATH. Split them any way you like.
SettingsOpen with ⌘,. The default agent, default models, fallbacks, custom prompts, and API keys live here.

Key ideas

Plan mode and Build mode

In Plan mode the agent can read the project and ask questions, but it does not change files. When the plan is ready, select Execute plan. Chat switches to Build mode and the agent starts on it. Build mode needs at least one pipeline with steps in the project.

See Chat for everything else in the Chat panel.

Pipelines

A pipeline is a named list of steps. Each step is one of three types:

  • Shell: a command, like npm run lint or your test suite.
  • AI: a prompt run by the agent and model you pick for that step.
  • Git: a fixed Git command, such as a diff against main, whose output later steps can read.

Mark a step as a gate and a failure there skips the steps after it. Pipelines are saved in .farol/pipelines.json in the project, so you can commit them and share them with your team. A new project starts with a few starter pipelines.

See Pipelines to build your own.

Runs belong to a branch

Results are tracked per branch. A pipeline that passed on main shows as not run after you switch branches. The earlier result is still listed under other branches.

What Farol checks, and what it doesn’t

Checks apply to the agents Farol runs in Chat. If you start an agent yourself in a terminal, it can use Farol’s pipeline tools over MCP, but Farol does not enforce them.

Requirements

  • A Mac with Apple Silicon (arm64). Intel Macs, Windows, and Linux are not supported yet.
  • Git, and a project folder that is a Git checkout.
  • At least one coding agent CLI installed and signed in. See Setting up agents.