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

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.

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.

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.

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.

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.

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.

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.