liftaris/herm

Herm

Chat stays on the left. The sidebar and tabs expose model/profile state, sessions, context, agents, analytics, skills, cron, toolsets, config, env, memory, and kanban without leaving the terminal.

herm /hɜːm/ noun : a sculptured head of Hermes on a square stone pillar, used in ancient Greece as a boundary marker at crossroads.

Why Herm

Herm gives Hermes Agent an operator-focused TUI instead of scattering work across shell commands, config files, and browser windows.

• Stay in the terminal while chatting with Hermes Agent, resuming sessions, and inspecting context.
• Operate your Hermes home through dashboard tabs for profiles, skills, cron jobs, toolsets, config, env, and memory.
• Run agentic work through kanban with boards, task detail views, diagnostics, and dispatch controls.
• Make the shell yours with rebindable keys, a command palette, slash commands, theme picker, and profile switching.

Herm is built with OpenTUI and Bun. It is a client for the Hermes Agent gateway, not a separate agent runtime.

Quickstart

Herm requires:

• a working Hermes Agent install
• Bun or a Node package runner
• a Hermes home at ~/.hermes, or HERMES_HOME pointing somewhere else

Try Herm without installing:

bunx herm-tui

Install it globally:

bun add -g herm-tui        # stable
npm i -g herm-tui          # also fine
bun add -g herm-tui@next   # bleeding edge, every dev push

Run it:

herm       # fresh session
herm -c    # resume last session

Or run from source:

git clone https://github.com/liftaris/herm.git
cd herm
bun install
bun run src/index.tsx

See .env.example for rarely-needed overrides.

What you can do

Chat with Hermes Agent

• Stream responses with markdown rendering, LaTeX-to-unicode conversion, inline images through chafa, diff chips, and expandable tool calls.
• Add file and diff context with @ references.
• Use slash commands for session control, model switching, skins, keybindings, and app actions.
• Resume, title, and manage sessions without dropping back to another command.

Operate your Hermes home

• Switch Hermes profiles from inside the TUI.
• Inspect and manage operational surfaces: sessions, context, agents, analytics, skills, cron, toolsets, config, env, and memory.

Run kanban work

• Use the kanban tab as an agent work surface rather than a detached project board.
• Open board and task detail views, inspect diagnostics, and dispatch work from the same shell you use for chat.

Share and install eikons

Eikons are 48×24 terminal avatars. The shipped lifecycle is deterministic: discover, inspect, install, use, update, and remove.

In Herm:

• Open Eikon → Marketplace, or run /marketplace, to browse shared catalog entries.
• Preview rows before installing. Trust is shown as Verified, Unverified, or Mismatch beside source and compatibility state.
• Install adds the eikon to your local library without activating it.
• Use selects an installed eikon as the active avatar.
• Update or remove an active eikon only after confirming that the active avatar's backing package will change or be cleared.

From the shell:

herm eikon search [query]
herm eikon inspect <name|github.com/user/repo/eikon-name|dir>
herm eikon install <name|github.com/user/repo/eikon-name|dir>
herm eikon use <name>
herm eikon info <name>
herm eikon update <name> --active-ok
herm eikon remove <name> --active-ok

install never activates. use is the activation action. JSON output is available for automation with --json.

Default Marketplace installs fetch built package artifacts referenced by the catalog, not creator repositories. Direct GitHub installs are for sharing outside the default catalog and support both single-package repos and multi-eikon catalog repos addressed as github.com/user/repo/eikon-name. Private GitHub repos use normal git authentication.

Creators can share Eikons through normal GitHub repositories. For official registry listing, use Eikon → Studio/Gallery → submit after baking. Herm previews the exact public bundle, asks for title/author/description/glyph, and either creates a GitHub PR through local gh auth or gives a browser/manual PR fallback with copyable bundle and PR text. Direct-install repos can still be prepared with upstream eikon pack, eikon index, and eikon manifest. eikon publish remains the lower-level GitHub PR contribution helper for the configured/default catalog repo; it is not a hosted marketplace account, upload, dashboard, or moderation flow.

Use eikon.liftaris.dev as a discovery gallery only; it previews catalog entries and gives copyable Herm install instructions.

Herm owns native Marketplace behavior. The eikon repo owns the registry, browser mirror, shared catalog/player exports, install resolver, and publish preflight. Herm imports public eikon package exports rather than browser mirror internals or unexported source paths.

Customize the shell

• Press Ctrl+K for the command palette.
• Type / for the slash popover.
• Type /theme to browse built-in themes.
• Type /keys to view and rebind keybindings, including OpenCode-compatible bindings.
• Use Tab / Shift+Tab to move between top-level tabs. Arrow keys navigate within a tab.

If text is hard to read in tmux or a dark terminal, try a light theme such as daylight, mercury, or github. If tmux is the issue, set -g default-terminal "tmux-256color" in ~/.tmux.conf often fixes color handling.

Status and compatibility

Herm does not guarantee backward compatibility with older versions of Hermes. Hermes is constantly updating, and things are bound to break. Regular Hermes parity sweeps and updates are done to keep Herm current.

Herm is the dashboard TUI for Hermes Agent. It does not replace Hermes Agent, implement model providers itself, or own Hermes runtime behavior.

Development

bun run dev
bun run typecheck
bun test

Acknowledgments

• Hermes Agent - the agent runtime Herm operates
• OpenTUI - the TUI framework
• OpenCode - interface inspiration

License

MIT - see LICENSE.