-w: run the session in a fresh worktree
The same launcher can offer -w the way hermes --tui -w does. It calls three functions from hermes_cli.session_worktree : create() before the client starts. It makes a new git worktree of the repository the user is in, under <repo>/.worktrees/ , on its own hermes/ branch. It returns {"path", "branch", "repo_root", "base"} , or None when no tree could be made (it has already printed why). Send path as the cwd of session.create . restore(session_id) before the client attaches to a resumed session. Pass the full session id. When that session ran in a -w tree that an earlier quit removed, it makes the tree again at the same path and returns the path. Otherwise it returns None . Without it, the gateway refuses every turn of that session with workspace_unavailable . finish(info, session_id, ask=...) after the client exits, in a finally block, so a client that fails to start does not leave the tree behind. Pass ask=True after a clean exit: a tree with uncommitted or unpushed work then gets a keep / archive / discard question on the terminal. Call it only after your client has given the terminal back. A clean tree that nothing still uses is removed with its branch. A kept tree is handed to…
From the official Hermes Agent documentation.
import os
from hermes_cli.session_worktree import create, finish, restore
resume = _session_to_resume(args) # the full session id, from the launcher above
info = create() if args.worktree else None
if args.worktree and info is None:
raise SystemExit(1)
if resume and not args.worktree:
restore(resume)
code, session_id = None, resume
try:
code, session_id = run_my_client(cwd=info["path"] if info else os.getcwd(), resume=resume)
finally:
if info: # also when the client did not start, or Ctrl+C reached the launcher
finish(info, session_id, ask=code == 0)