Skip to content
installcurl -fsSL https://get.farhelm.io/install.sh | sh

Your first session

The first time you open Farhelm, a welcome card points at this guide and at sending private feedback. Close it with Got it to start; Welcome in the ? menu brings it back whenever you want. Your Mac’s mark sits on the navigation rail, the column of icons down the left edge of the sidebar.

The navigation rail with the Mac you are on marked as a host that is ready.

Before you start a session, make sure the agent you want is installed on your Mac and starts when you type its command in a terminal (claude or codex, for example). Farhelm starts it the way your login shell would, with the same PATH. Supported agents lists the agents Farhelm knows.

Select + (New session) at the top of the session list, choose the agent, and launch. Start a session walks through the session launcher and its choices.

The new session in the session list, with its agent's terminal beside it.

You do not have to watch the terminal to know when an agent needs you. The session list shows every session’s status, and it updates as the agents work. A waiting agent does nothing until you answer it.

The session list with a waiting session, an idle unread session and an idle read session, each explained.

Read the session list explains every status.

Quit Farhelm while the agent is working, then open it again: the session is still there, still running, and its terminal shows everything that happened while Farhelm was closed. Farhelm also keeps track of what the agent tells it about its conversation while it is closed, so restarting the session later resumes the conversation the agent was really in. Sessions keep running until you stop them or your Mac reboots. After a reboot they show as interrupted, ready to start again; What survives what has the details, and Stop, restart, and resume covers starting them again.

Quitting Farhelm closes its window, but the supervisor, the part of Farhelm that keeps your Mac’s sessions running, keeps running in the background. One thing still does not work while Farhelm is closed: an agent asking Farhelm for something. Its farhelm spawn and farhelm agent commands fail until you open Farhelm again, because they need the helm, the part of Farhelm that shows you your sessions, and on your Mac the helm runs inside the app.

Next: Add a remote host.