Setting up agents

Farol doesn’t ship its own model. It runs the coding agents you already use, through their command-line tools. Install the CLI, sign in once, and Farol can use it in Chat and in AI pipeline steps.

Supported agents

After installing, run the CLI once in a terminal and sign in. Farol uses that login, so your existing plan or subscription pays for the runs.

Farol looks for CLIs on your shell’s PATH, plus common install folders: Homebrew, ~/.bun/bin, pnpm, and every Node version under nvm. If a CLI works in your terminal but Farol can’t find it, check that it is installed in one of these places.

Choose agents on first launch

The first time you open Farol, the Set up your agents screen scans your Mac. Claude, Codex, and OpenCode are listed as main agents. Cursor and OMP are under other agents.

• Every agent that is found shows its version and is switched on. Select an agent to switch it off.
• An agent that is not installed shows its install command. Select Copy, run it in a terminal, then select Rescan.
• Select Make default on the agent new chats should start with.
• Select Open Farol. At least one agent must be on.

Change the default agent

Open Settings with ⌘, and go to General. The Default agent starts new chats and picks up failures sent from a pipeline run. You can still switch the agent and model for any one chat from the picker below the message box.

On the same page, Send failures to Chat decides whether a failed step’s report goes straight to the agent. Turn it off to review failures first and send them with Fix in Chat.

Set default models

In Settings › Models, pick the model each agent starts new chats with. Leave one on Default to let that CLI decide. The lists refresh from the installed CLIs. Select the refresh button if a new model is missing.

Pipeline AI steps don’t follow these defaults. Each step keeps the agent and model you set on it in the pipeline editor, so a quick lint review can run on a small model while an architecture review runs on a larger one.

The Commit messages generator on the same page picks the agent and model used when Source Control drafts a commit message with Generate with AI. It is separate from your chat default.

Add fallbacks

Agents hit usage limits. In Settings › Fallbacks you can list backup models, in order. If a model fails for a reason the agent can’t fix, like a missing CLI, a crash, or a usage or quota limit, Farol retries the same turn on the next model down.

• Build mode: new Build chats start on the first model in the list. Empty means the default model only.
• Plan mode: the chain for planning. Empty keeps whichever model the chat is already on.
• Pipelines: tried when an AI step can’t run on its own model. Empty means AI steps don’t fall back.

Use models through OpenRouter

OpenRouter gives you models from many providers with one key. Farol runs them through OpenCode or pi, so install one of those first:

brew install opencode
# or
npm i -g @mariozechner/pi-coding-agent

1. In Settings › OpenRouter, paste your API key (sk-or-…). Farol encrypts it on your Mac.
2. Under Runs through, choose OpenCode or Pi.
3. Pin the models you want under Pinned models. Chat and pipeline pickers list them under OpenRouter.

Farol passes the key only to the OpenCode and pi processes it starts. It is not added to your terminal panes or to either CLI’s own settings.

Pay with API keys instead of a login

By default each CLI uses its own login. To bill API credits instead, add an Anthropic key for Claude or an OpenAI key for Codex in Settings › API keys. Switch a key off to go back to the CLI login without deleting it. The interactive Codex terminal always uses the Codex login.

Give agents standing instructions

Settings › Custom prompts holds instructions added to every Chat turn while they are switched on, such as your code style or a library to avoid. A global prompt applies in every project. A project prompt is saved in .farol/prompts.json, so you can commit it for your team.

Run an agent in a terminal

You can also start an agent interactively: press ⌘K and choose New agent terminal. It opens the CLI in a real terminal, with Farol’s MCP server available so the agent can list and run pipelines. The agent decides whether to call those tools, so checks are not enforced there the way they are in Chat.