Hermes Agent Archive / Skills

A plugin with its own chat client

From Official Docs · November 14, 2026

A plugin can add a command ( hermes <name> , through ctx.register_cli_command ) that starts its own chat frontend. The frontend attaches to the profile's shared gateway with hermes gateway attach --json (see Programmatic integration ). The command exists only when the plugin runs inside the Hermes process ( plugins.isolation: in_process , the default). With plugins.isolation: host , Hermes skips ctx.register_cli_command , and hermes <name> is not a command. Three imports do what the Hermes terminal client's launcher does around its own client: hermes_cli.gateway_chat.shell_client_env() returns the allowlisted variables of the shell that ran your command, as a dict. Call it in the launcher, before you change the environment, and send the dict as client_env on session.create . The session's commands then run with the user's PATH , virtual environment and toolchain variables. Names that look like credentials are left out, and the gateway filters the dict again by its own rules. hermes_cli.chat_launch.hermes_command(args) returns the argv that runs this Hermes install with args . It needs no PYTHONPATH ; the child serves the profile named by the inherited HERMES_HOME . Give it to your…

From the official Hermes Agent documentation.

import json
import os
import subprocess
import tempfile

def _arguments(parser):
    # The exit summary prints `hermes my-client --resume <id>` and `hermes my-client -c "<title>"`.
    parser.add_argument("--resume", "-r", metavar="ID")
    parser.add_argument("--continue", "-c", dest="title", metavar="TITLE")

def _session_to_resume(args):
    wanted = args.resume or args.title
    if not wanted:
        return None  # a new chat: a new profile has no session store to open yet
    from hermes_constants import get_hermes_home
    from hermes_state import SessionDB

    db = SessionDB(db_path=get_hermes_home() / "state.db", read_only=True)
    try:
        # The summary prints a short id: resolve_session_id takes a unique prefix.
        found = db.resolve_session_id(args.resume) if args.resume else db.resolve_session_by_title(args.title)
    finally:
        db.close()
    if not found:
        raise SystemExit(f"hermes my-client: no session matches {wanted!r}")
    return found

def _run_chat(args):
    from hermes_cli.chat_launch import hermes_command, print_exit_summary
    from hermes_cli.gateway_chat import shell_client_env

    env = dict(os.environ)
    env["MY_CLIENT_ENV"] = json.dumps(shell_client_env())
    env["MY_ATTACH_COMMAND"] = json.dumps(hermes_command(["gateway", "attach", "--json", "--start"]))
    env["MY_RESUME"] = _session_to_resume(args) or ""  # the frontend sends it with session.resume
    # One file for this launch: the frontend writes {"session_id": ...} there for the session it shows.
    fd, session_file = tempfile.mkstemp(prefix="my-client-", suffix=".json")
    os.close(fd)
    env["MY_SESSION_FILE"] = session_file
    try:
        subprocess.run(["my-client"], env=env)
        with open(session_file, encoding="utf-8") as f:
            shown = f.read()
    finally:
        os.unlink(session_file)
    if shown:  # empty when the client left before it opened a session
        print_exit_summary(json.loads(shown)["session_id"], command="hermes my-client")

def register(ctx):
    ctx.register_cli_command("my-client", "Chat in my client", _arguments, _run_chat)