Farol

Quick start

From download to your first checked change in about five minutes. You need an Apple Silicon Mac and a project in a Git repository.

  1. Install Farol

    Download the Mac build, open the .dmg, and drag Farol into Applications.

    The build is not notarized by Apple, so macOS blocks the first launch. Right-click Farol in Applications and choose Open. If macOS still refuses, go to System Settings › Privacy & Security and select Open Anyway. You only do this once.

    Prefer to build it yourself? Clone the repository and follow its README.

  2. Install an agent CLI

    Farol runs agents through their own command-line tools, so it needs at least one installed and signed in. If you already use Claude Code or Codex in a terminal, you are set. If not, install one and sign in:

    npm i -g @anthropic-ai/claude-code
claude   # sign in once, then quit

    Other agents, and models through OpenRouter, are covered in Setting up agents.

  3. Pick your agents

    On first launch Farol shows Set up your agents. It scans your machine and switches on every agent it finds. Switch off any you don’t want, select Make default on the one new chats should use, and select Open Farol.

    Installed an agent while this screen was open? Select Rescan. An agent that is not found shows its install command with a Copy button.

  4. Open a project

    Select Open Project…, or press ⌘O, and choose the folder of a Git checkout. The project appears in the rail on the left, with its branch in the status bar.

    If the project has no pipelines yet, Farol adds a starter set to .farol/pipelines.json, such as a Code Review pipeline. Open one to see how steps are wired. Change the commands to match your project, for example your own lint and test scripts.

  5. Give the agent a task

    Open Chat from the toolbar. Below the message box:

    • Choose Plan to get a plan first, or Build to start changing code.
    • Pick the agent and model, if you want something other than your default.

    Type the task and press Enter to send. Shift + Enter adds a new line. You can drop files onto the message box to attach them.

    In Plan mode, the agent may ask you questions. Answer them in Chat. When the plan is ready, select Execute plan to switch to Build mode and start the work.

  6. Watch the checks

    When the agent finishes a change, it picks the pipelines that apply, and Farol runs them on the branch. Each run opens in its own tab, with every step’s status and output.

    If a step fails, its report goes back to Chat and the agent fixes the problem. The pipelines run again until they pass. To review failures yourself first, turn off Send failures to Chat in Settings › General. A failed run then waits for you to select Fix in Chat.

  7. Review and ship

    Select the Git button in the project rail to open Source Control. Check the files to include, write a commit message or select Generate with AI, then commit and push. From the same page you can open a pull request and, when its checks pass, merge it.

Next steps

  • Set up more agents, set default models, and add fallbacks for when one hits a limit.
  • Learn the rest of Chat: file mentions, questions, todos, and fresh starts.
  • Build pipelines for your own lint, tests, and AI reviews, and choose which ones Chat always runs.
  • Press ⌘K to open the command palette and see everything Farol can do from the keyboard.