Custom commands
The session launcher’s Command tab runs any command line as a session. Use it for an agent Farhelm does not know, or for one it does know when you want to start it your own way: through a wrapper that needs a directory argument or a different resume command, with flags the Agent tab does not offer, or from a different install. For a wrapper that only needs to run Farhelm’s agent command, use the agent tab’s wrapper prefix instead. What Farhelm can then do for a custom-command session depends on what you tell it, and the Command column of the support matrix sums that up.
The command and resume command run through Bash, with the environment your login shell provides. You can use
~/bin/tool, $VARIABLE, globs, pipes, redirection and compound commands as you would in a Bash script. Bash runs
without rereading ordinary login or interactive startup files. Ordinary aliases and unexported functions from your login
shell are not inherited. If your setup exports BASH_ENV, Bash reads that file; exported Bash functions are available
too. A missing command prints Bash’s error in the session’s terminal and leaves the session Exited, with code 127.
The fields
Section titled “The fields”- Agent command: the command line to run. Write
{cwd}as a whole unquoted argument where the command wants the session’s directory, and Farhelm fills it in at every launch and restart. - Runs in YOLO mode: Yes (YOLO) or No, and you have to pick one. Guarded can approve actions automatically through a classifier, AI reviewer or sandbox, so no prompt by itself does not mean YOLO (Permission modes). Farhelm never reads the command to work out which; it takes your answer, and asks you to confirm a YOLO launch on hosts that ask. An agent cannot give this answer for you, so an agent cannot start a command at all on a host that asks before YOLO launches (Approve what agents do).
- Agent type, optional: the agent the command ends up running. Leave it at None for anything that is not one of the agents Farhelm knows.
- Resume, which appears once you declare an agent type, and the Resume command it reveals: how to start the command again on the same conversation, so the session can be restarted.
Declaring the agent
Section titled “Declaring the agent”Declaring the agent type gives the session what Farhelm does for that agent, as far as the agent allows: Claude’s, Codex’s and Muse’s reading of the screen, including showing when the agent waits for you (for Muse, only at its directory-trust question), and conversation tracking for Claude, Codex, Muse, Goose, OMP, Pi, and Grok (with its hooks installed). Declaring Cursor or OpenCode gives no tracking, since Farhelm has none for them.
A declared agent needs {farhelm_args} in the command, once, as a whole argument, where that agent’s own arguments go.
Farhelm puts there whatever it needs to follow the conversation; for an agent that takes nothing, it becomes nothing.
Your command has to pass those arguments on to the agent: a wrapper that drops them loses tracking.
Agent wrappers shows how to write one that keeps them.
Leave the placeholders unquoted and separate from other text: {cwd}, rather than "{cwd}" or --dir={cwd}. Farhelm
quotes the value for you, so a directory or conversation containing spaces stays one argument and cannot turn into
another shell command.
Making it restartable
Section titled “Making it restartable”A command can be restarted only when it declares an agent Farhelm can track, ticks Resume, and has a resume command
with {conversation} and {farhelm_args} in it, each once, as a whole argument. Farhelm puts the tracked conversation
where {conversation} stands. Without all of that, Restart stays greyed out and replace is how you start over.
The resume command is usually the start command plus the agent’s own way of picking a conversation:
| Agent | Resume command, after your start command’s options |
|---|---|
| Claude | --resume {conversation} {farhelm_args} |
| Codex, Muse | resume {conversation} {farhelm_args} |
| Goose | --resume --session-id {conversation} {farhelm_args}, on goose session |
| OMP, Grok | --resume {conversation} {farhelm_args} |
| Pi | --session {conversation} {farhelm_args} |
So claude --model sonnet {farhelm_args} resumes as claude --model sonnet --resume {conversation} {farhelm_args}.
Your answer to Runs in YOLO mode covers the resume command too.
Each agent’s own page notes anything its custom commands need beyond this, such as Grok’s --no-leader and Goose’s
session.
Opening links
Section titled “Opening links”Commands in remote sessions can open links in your browser when they open them through the BROWSER environment
variable, as most programs do. A BROWSER you set yourself wins; see
Open links from a remote session for approvals
and the limitations of remote login callbacks. A command can ask explicitly with farhelm agent open-url -- <url>.
Reusing a command
Section titled “Reusing a command”Save a command and its fields as a launch template to start it again without typing it, or choose Clone on a session started from it.