I Built a Terminal That Tells Me Which Agent Needs Me

Hello there!

These days I rarely run one coding agent. I run three or four, Claude Code in one tab, Codex in another, each on its own task.

Starting them is easy. The annoying part is knowing which one needs me.

I kept cycling through tabs to find the one stuck on a permission prompt. Sometimes it had been waiting for ten minutes while I was watching another one work.

So I built Farol, a macOS terminal made for this. Farol means lighthouse in Portuguese 🙂

One dot per agent

Every session lives in a sidebar, and each one has a dot.

Cyan and breathing means the agent is working. Yellow means it is waiting for you. Green means it finished while you were somewhere else.

That's the whole idea. One look at the sidebar and I know where to go.

The same state shows in the menu bar, so I can be in the browser or in Slack and still see when an agent needs me.

Every task in its own worktree

Running agents in parallel on the same folder is a mess. They edit each other's files and you lose track of who did what.

In Farol you press ⇧⌘N and describe the task, or pick a GitHub issue or a Jira ticket. Farol opens a git worktree on a new branch and starts the agent there, with the task as its first prompt.

Each agent gets its own copy of the code, so they never touch each other's files.

Review what the agent did

When an agent finishes, I want to see what it changed before anything else.

The title bar shows a small count like ± +821 −61. Click it and you get every changed file as one scrolling diff.

From the same panel you can commit, push and open the pull request. I don't leave the terminal for that anymore.

If a rebase stops on conflicts, there is a three column view to resolve them too.

Files next to the terminal

Sometimes I just want to look at a file the agent is talking about, or fix one line myself.

⇧⌘E opens the project as a tree. Click a file and it opens in a pane beside the terminal, with syntax colors from your theme. You can edit it and save with ⌘S.

When the agent changes the file you have open, it reloads by itself.

There is more, like a git graph and split panes. The docs have the full list.

How it works

I was curious about this part before I started, so maybe you are too.

I did not write a terminal emulator. That would have taken me years. Ghostty is built as a library, libghostty, and you can put your own app around it. So Farol renders like Ghostty, is as fast as Ghostty, and loads your Ghostty config and themes.

Farol does not wrap the agents. Claude Code and Codex run exactly like in any other terminal. They both have hooks, commands they run on events like "permission needed" or "turn finished".

Farol adds a hook that calls a tiny CLI:

"Notification": [{
  "matcher": "permission_prompt|elicitation_dialog",
  "hooks": [{ "type": "command", "command": "[ -z \"$FAROL_CLI\" ] || \"$FAROL_CLI\" status waiting" }]
}]

The CLI sends one line to a Unix socket the app listens on, and the dot changes color.

Outside Farol that variable is not set, so the hook does nothing. You turn it on with one click in the settings, and turning it off removes only what Farol added.

I'll write a second article about embedding libghostty in a Swift app, because there is a lot to say there.

Try it

Farol is free and open source, MIT licensed. No account and no telemetry.

It needs a Mac with Apple Silicon and macOS 14 or later.

You can download it from farol.sh, or check the code at github.com/snowztech/farol.

It is early. I use it as my daily terminal, but expect rough edges.

If you try it, tell me what's missing, in an issue or on Discord.

Hope you find it useful!

Comments

[오피셜메일]

대기·완료 상태를 점으로 구분하고 각 에이전트를 별도 worktree에 두는 조합이 좋네요. 특히 권한 요청 훅만 추가하고 Farol 밖에서는 환경변수가 없으면 동작하지 않게 한 점이 인상적입니다. 여러 세션이 같은 이슈나 브랜치를 동시에 잡으려 할 때 중복 경고까지 있으면 운영에 더 도움이 될 것 같습니다.

[Lucas Neves Pereira]

그런 경고를 하는 게 좋은 생각인 것 같네요. 감사합니다, 한번 고려해 볼게요.