Agent wrappers
To run a known agent through a wrapper, choose the agent in the session launcher’s Agent tab and enter a Wrapper
prefix, such as with-endpoint --profile work --. Farhelm puts those words before the command it would otherwise run,
including on resume. It still chooses the agent’s arguments, reads its status, and follows its conversation where that
agent supports it. The wrapper must run that agent and pass its arguments and environment through. Farhelm takes your
word for that; it cannot check what the wrapper actually does.
The prefix runs through Bash, on the host or inside the session’s container. ~, variables, globs and shell operators
have their usual Bash meaning; with-endpoint --profile "$PROFILE" --, for example, reads PROFILE when the session
starts. Farhelm keeps your quotes and escapes as typed and quotes the agent’s own arguments separately, so a model or
initial prompt cannot become shell code. Previously saved prefixes acquire the same Bash meaning. Farhelm refuses
placeholders such as {cwd} in a prefix; use a custom command when your wrapper needs one. Leave it empty for no
wrapper. Farhelm remembers the last prefix you launched each agent with; switching agents picks up that agent’s value. A
launch template can set a prefix or explicitly clear one, including for
quick launch. Clone, Replace with, and Restart with open with the
session’s prefix so you can keep or change it. Plain Restart reuses the stored launch.
NOTE: Do not put secrets in a prefix. It becomes part of the launch command, which other processes may see, and an agent on any host can read prefixes saved in the templates listing.
Some wrappers need more than a prefix: wrapper run <dir> <agent...> needs a directory argument, and another wrapper
may need a different resume command. Use the command tab for those. Write {cwd} where
the wrapper wants the session’s directory and {farhelm_args} where the agent’s arguments go. Declare the agent the
wrapper ends up running, and write a resume command when it can resume. The rest of this page covers that route and the
rules both routes share. On stop the wrapper is killed along with the agent; being the agent’s parent exempts it from
nothing.
A custom wrapper command, field by field
Section titled “A custom wrapper command, field by field”On the session launcher’s Command tab, four fields matter:
- Agent command:
my-wrapper run {cwd} claude {farhelm_args} - Runs in YOLO mode: your answer, Yes (YOLO) or No. Farhelm believes it and never reads the command to check it, and it covers the resume command too.
- Agent type: Claude — the agent the wrapper ends up running, never the wrapper itself
- Resume command, which appears once you tick Resume:
my-wrapper run {cwd} claude --resume {conversation} {farhelm_args}
Placeholders must be separate, unquoted words. Farhelm refuses --dir={cwd}, '{cwd}', or a {cwd} inside a sh -c
script string when you save the command, and also refuses older saved commands with those forms when they next start.
{conversation} and {farhelm_args} follow the same rule, and both must appear exactly once where they are required.
Beyond that: every occurrence of {cwd} is filled, not just the first; it may not be the first word, because
substituting there would make the working directory the program this session runs, and the launcher refuses that
outright; and a directory whose name contains spaces arrives as a single argument, because the value goes into the
argument’s own slot, safely quoted by Farhelm. The rest of the command and resume text runs through Bash with full shell
meaning, as Custom commands describes.
The value is the directory the session’s terminal starts in, spelled the way you gave it after ~ expansion, symlinks
intact. On a restart — and on the retry of an interrupted create — Farhelm checks that the spelling still resolves to
the canonical identity it recorded when the session was created and hands over that resolved path instead. Either way
the wrapper is handed exactly the string the session’s terminal is started in — one string, which is not quite one
directory: on a fresh create each side resolves that spelling for itself, so a symlink retargeted in between puts them
in different places. That race is yours rather than Farhelm’s, and the recorded directory closes it from the first
restart onwards. Resume depends on the agent reporting its conversation; Farhelm does not use the working directory to
guess which one it is.
A worked example with sh
Section titled “A worked example with sh”sh is a real wrapper of the minimal kind, and worth running once before you point a command at the actual thing:
sh -c 'cd "$1" && shift && "$@"; exit $?' w {cwd} claude {farhelm_args}w becomes $0 for the inner shell, {cwd} lands in $1 as a positional argument (not inside the script text, where
it would stay literal), and "$@" is the agent command line with Farhelm’s arguments where {farhelm_args} stood. The
trailing ; exit $? is load-bearing: when /bin/sh is bash, the last command of a script is tail-execed as an
optimization, so ... && "$@" on its own replaces the shell with the agent and leaves no resident wrapper at all. With
a command after it, bash and dash both stay put as the agent’s parent, which is what a real wrapper does.
Why the agent must be declared
Section titled “Why the agent must be declared”Farhelm never reads a command line to decide which agent it runs: a command whose first word happens to be claude runs
no Claude integration unless you declare Claude as its agent. That is deliberate, because the shapes it would have to be
clever about — wrappers, env, a command buried in a bash -c script string — cannot be recognized reliably, and
declaring the agent means nothing has to try.
A wrapper command with no declared agent launches and runs fine — no error, no warning. What it does not get is conversation tracking, Farhelm’s arguments, per-agent status, and the restart that follows from them: such a session cannot be restarted at all, only replaced.
What the wrapper must pass through
Section titled “What the wrapper must pass through”With a prefix on the Agent tab, Farhelm composes the agent’s arguments and places them after your prefix. With a
custom command, it puts its arguments exactly where {farhelm_args} stands, and only there; for an agent that takes
none it stands for nothing. Those arguments turn the agent’s conversation reporting on, as
Agent hook injection describes. A resume is no exception: the resume command
is a complete command line in its own right — Farhelm fills in its {conversation} and {farhelm_args} and runs THAT
instead of the start command, which is why the wrapper has to appear in it too.
Farhelm’s arguments are what a wrapper must forward, and one that treats everything after its own arguments as the
command to run, verbatim, does. A wrapper that parses trailing options as its own eats them first, and the symptom is
indirect: the agent never reports its conversation, and the session cannot be restarted. NOTE: that is the one thing
Farhelm cannot check for you. Its own tests stand in sh -c for the real wrapper, so whether YOUR wrapper stops at the
agent command and forwards the rest is something only you can verify — ps -o args= -p <agent pid> against a live
session shows what actually reached the agent.
Claude works through multiple wrappers that stay running, including a wrapper that starts another script which then
starts Claude without exec. Farhelm follows the first Claude process whose conversation it accepts. Another Claude
started inside the session cannot replace a conversation already reported by its parent. If that nested Claude reports
first, Farhelm may briefly follow its conversation. When the Claude that started it next reports at the end of a turn,
or at start, resume, /clear, or compact, Farhelm switches to that conversation and tells you in the session’s
notifications what a Restart before the switch would have resumed. If the followed Claude exits and you start a
fresh one in the same terminal, Farhelm can follow the new one. Sessions already running before end-of-turn reporting
was added gain it on relaunch; until then, correction waits for another start, resume, /clear, or compact.
Muse also works through multiple wrappers that stay running. Farhelm follows the first Muse process whose conversation it accepts; a nested Muse cannot replace a conversation already reported by its parent. If the nested process reports first, the parent’s next report switches Farhelm back and a session notification explains what Restart would have resumed before that switch. If the followed Muse exits, a fresh Muse in the same terminal can report its own conversation. See Muse for when it reports after a new conversation or resume.
Codex also works through a wrapper that stays running, including one named codex itself. Farhelm follows the first
Codex process whose conversation it accepts; wrappers above that process do not need to replace themselves. If another
Codex process started inside the session reports first, Farhelm may briefly follow its conversation. When the Codex
process that started it reports, Farhelm switches to that conversation and tells you in the session’s notifications what
a Restart before the switch would have resumed. If the followed Codex exits and you start a fresh one in the same
terminal, Farhelm can follow the new one. The native Codex executable must still be named codex; a renamed one cannot
supply the conversation Restart needs.
Grok accepts a wrapper that execs Grok or stays resident as Grok’s one parent process, unless that resident wrapper is
itself named grok or its program is named grok- followed by anything. A deeper resident chain prevents Farhelm from
following the conversation, leaving Restart unavailable. Its hooks still have to be
installed, and the wrapper must pass through its environment.
OMP accepts a prefix wrapper only when the wrapper execs OMP, leaving no extra process between the session and OMP’s
own launcher. A resident wrapper can run OMP, but Farhelm will not follow its conversation, so Restart stays
unavailable. The same process rule applies when you write a custom command.
A compound command or prefix can keep Bash running above the wrapper. That extra process can prevent Farhelm from following Grok’s or OMP’s conversation when the wrapper also stays running, leaving Restart unavailable. Claude, Muse and Codex tolerate that extra process.
Four variables travel in the environment rather than on the command line: FARHELM_SESSION_ID (which session this is —
no sweep will claim a process that does not carry it), FARHELM_AGENT_ID (the same session id again, under a name that
says this process belongs to the session’s AGENT rather than to one of its terminal tabs; that is the marker a stop
selects on), FARHELM_SESSION_TOKEN (the bearer credential proving that a farhelm agent or farhelm spawn request
came from this session), and FARHELM_SUPERVISOR_SOCK (the supervisor socket, whose directory is also where
conversation reports are saved). Goose, Pi, and OMP launches also carry variables their conversation reporters need. A
wrapper inherits all of them and passes them to its child by default, so this needs no thought unless your wrapper
deliberately scrubs the environment, in which case farhelm commands and conversation tracking stop working for that
session.
What happens on stop
Section titled “What happens on stop”There are fewer processes involved than the launch chain suggests. Farhelm starts a login shell in the session’s
terminal, the shell execs Farhelm’s launch shim, and the shim execs your command. For a custom command or wrapper
prefix, Bash interprets the text and can replace itself with a simple command; compound commands can keep Bash running
above the wrapper and agent. A wrapper that execs the agent replaces itself in that chain. Where farhelm’s own probe
finds a WORKING systemd user manager — it creates a throwaway scope, looks it up, kills it, and confirms it went away,
rather than trusting a systemd-run on PATH — the launch also runs inside a per-launch cgroup scope, which is
containment rather than a level of the tree (systemd-run --scope execs in place too). Each launch records what it
selected, so a session can outlive the manager that scoped it.
Stopping or restarting a session reaps the agent’s tree. Stop also closes its terminal tabs; Restart leaves them
running. What the agent reap claims is the descendants of that login shell plus every process carrying the session’s
FARHELM_AGENT_ID — the value is the session’s own id, set on every agent launch, so the marker says “an agent of this
session” rather than “this generation of it” — and, for sessions launched by builds predating that marker, anything
wearing the session marker with no other claim on it. All of those additionally require the session’s
FARHELM_SESSION_ID: one session’s stop can never reach another’s processes however their other markers read. A tab’s
shell wears its own tab marker, which keeps it out of the agent reap — and, when a tab is closed, including by Stop or
Delete, earns it a SIGHUP alongside the SIGTERM: an interactive shell ignores SIGTERM and exits on the hangup its
terminal closing would have sent, so a tab close ends inside the grace instead of waiting for the SIGKILL. Agents never
carry a tab marker and are never hung up.
Where this launch recorded a cgroup scope, the manager is still there, and that unit still exists, the scope is killed first: SIGTERM to everything in it, up to five seconds for the unit to retire on its own (the wait ends the moment it does), then SIGKILL if it has not, then a bounded wait for the unit to be collected. When every scope is confirmed gone and nothing Farhelm started directly is still alive, that is the whole cleanup: a process that moved itself out of the scope, or only carries the session’s markers, is left running. Otherwise, and on a host with no user manager, the process-table sweep runs afterwards. It SIGTERMs everything the first enumeration found, waits up to the same five seconds for every one of those pids to be confirmed gone (again ending as soon as they are), then RE-ENUMERATES and SIGSTOPs the refreshed set: the refresh comes first so that a process forked inside a TERM handler is frozen along with everything else rather than escaping with the parent. Stopped processes cannot fork, so what is left only shrinks — up to five further passes re-enumerate and SIGSTOP whatever is newly there, then everything found gets SIGKILL and is polled until each pid is confirmed gone: exited, replaced by an unrelated process on the same number, or a zombie nobody has reaped yet, all three of which mean it can no longer run anything. Both bounds fail loudly rather than quietly: a fifth pass that still finds something new, or a pid still alive when the poll gives up, makes the stop report a failure. A supervisor restart does not kill sessions, and a host reboot takes everything down with the machine.
There is no ordering between parent and child: the wrapper and the agent are signalled in one pass over an unordered set, and nothing waits for either before signalling the other. What is offered is up to five seconds between SIGTERM and SIGKILL, and only to what the first enumeration found — something that first appears AFTER the grace period is picked up by a later pass and gets SIGSTOP and SIGKILL without ever seeing a SIGTERM at all. The wait is not a fixed delay: it ends as soon as everything signalled is gone, so exiting promptly is what makes a stop feel prompt.
For a wrapper author that means three things. A TERM handler has a budget of about five seconds of wall clock, and a
budget is not a guarantee: the timer starts when the signal goes out, not when your handler is scheduled, and a loaded
host or a slow disk spends it for you. Plan for less than you measure. Unlinking a marker or writing a small state file
fits; waiting on the child, syncing a large tree, or a network round trip does not. A handler still running when the
grace expires is killed mid-work — SIGSTOPped first on the sweep-only path, straight to SIGKILL under a scope — so
anything it writes must be crash-safe: write a temporary file and rename it, never update one in place. And an flock
is released by the kernel when its holder dies, whichever signal did it, so holding a lock on the directory for the
agent’s lifetime needs no handler at all.
Related shapes
Section titled “Related shapes”env FOO=1 can be a prefix for an agent launch; it execs the agent, so it adds no resident process. A custom command
such as env FOO=1 claude {farhelm_args} works too, but then you must write its resume command. Neither form needs
{cwd} — the session’s terminal already starts in its directory and the command inherits it. env is for variables you
do not mind being public: the value is stored verbatim with the session and sits in the launch’s argv, where ps shows
it to anyone who can read the process table for as long as the process runs. A secret belongs in a file the agent reads,
not on a command line. For the custom-command form, declare the agent and write the resume command out as for any
wrapper: env FOO=1 claude --resume {conversation} {farhelm_args}.
bash -c needs one more step. {farhelm_args} written inside the script string is not a whole argument, so it does not
count, and a command whose only {farhelm_args} is there is refused. Pass it after the script as positional parameters
instead and forward them, with a dummy $0 ahead of them exactly as the sh example does:
bash -c 'claude "$@"' sh {farhelm_args}. A script that names the agent and its arguments itself and does not forward
"$@" drops Farhelm’s arguments, and the only sign is that the agent never reports its conversation.