This is the npm package source for LitHermes. It installs the Hermes plugin that provides /lit, /lit-loop, /lit-plan, and gateway-friendly aliases.

Quick Start

Run a doctor check first:

npx lithermes-ai doctor
bunx lithermes-ai doctor

Install the plugin:

npx lithermes-ai install --yes

Restart any running Hermes CLI or Hermes gateway process. Then open Hermes and try:

/lit 이 폴더에 뭐가 있는지 정리해줘
/lit-plan lithermes를 더 안전하게 배포하는 플랜 세워줘

What You Get

• /lit: start an Litwork loop immediately.
• /lit-loop: explicit alias for the same execution loop.
• /lit-plan: create a durable implementation plan.
• /litwork-loop and /litwork-plan: longer aliases.
• /lit_loop and /lit_plan: gateway-friendly aliases for Telegram dispatch.
• Native /goal binding: Hermes has no model-facing goal tools, so /lit, /lit-loop, and /lit-plan bind the native standing /goal via the session goal manager (persists across turns; native evidence-judge decides completion). Criteria + evidence use the durable goal_* tools.
• Interactive install spinner keeps terminal installs lively while redirected or scripted installs stay plain; use npx lithermes-ai install --yes --no-spinner for quiet terminal installs.
• start-work: open or dry-run a LitHermes plan inside Hermes.
• LitHermes workflow skill set: ai-slop-remover, comment-checker, debugging, deep-interview, frontend-ui-ux, git-master, init-deep, lsp, programming, refactor, remove-ai-slops, review-work, rules, visual-qa, lsp-setup, litresearch, start-work, lit-plan, litgoal, and litwork are installed as lithermes:* skills.
• The full plugin payload — the pre_llm_call / subagent_stop hooks, every skill, and the durable goal tooling — ships in the bundle exactly as installed, so each release is reproducible and auditable. Repo-rule loading is handled by Hermes' native context-files feature, not a LitHermes hook.

Requirements

• Hermes Agent already installed on the machine.
• Node.js 18 or newer for npx.
• Bun if you want to use bunx.
• Write access to the Hermes home directory, normally ~/.hermes.

The default install target is:

~/.hermes/plugins/lithermes
~/.hermes/config.yaml

Use --hermes-home PATH if your Hermes home is somewhere else.

Install

Preview changes without writing anything:

npx lithermes-ai install --dry-run

Install with npm:

npx lithermes-ai install --yes

Install with Bun:

bunx lithermes-ai install --yes

Install into a custom Hermes home:

npx lithermes-ai install --yes --hermes-home /path/to/.hermes

LitHermes refuses to mutate Hermes config unless you pass --yes. If ~/.hermes/plugins/lithermes already exists but was not created by this installer, installation stops instead of overwriting user files.

Verify

Check the package and Hermes compatibility:

npx lithermes-ai doctor
bunx lithermes-ai doctor

Check an installed plugin:

npx lithermes-ai check --offline

Expected successful output includes:

LitHermes check PASS
commands: lit, lit-loop, lit-plan

For gateway compatibility checks:

npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent

Expected successful output includes:

gateway /lit_loop PASS
gateway /lit_plan PASS

Hermes Goal Tools

Hermes exposes no model-facing goal tools. LitHermes binds the native standing /goal for you through the session goal manager when you start an Litwork run, so it persists across turns and the native evidence-judge decides completion. Success criteria and evidence are tracked with the durable goal_* tools and hermes lithermes goal status.

That means a recent Hermes Agent can continue the same LitHermes work across turns instead of stopping after the command creates a run directory or plan file.

Telegram Gateway

LitHermes does not contact Telegram during install. It only installs the Hermes plugin and checks whether the local Hermes gateway source supports plugin command dispatch.

After installing:

1. Restart the Hermes gateway process.
2. In Telegram, send /lit_loop your task.
3. For planning-only work, send /lit_plan your task.

If Telegram does not recognize the command, run:

npx lithermes-ai doctor --hermes-repo /path/to/hermes-agent

If cli payload dispatch, tui payload dispatch, or gateway underscore dispatch is not PASS, update Hermes or use the patch fallback below.

Patch Fallback

When LitHermes can find ~/.hermes/hermes-agent, install --yes attempts known compatibility patches automatically and writes backups first. Use the explicit form when Hermes lives elsewhere, or add --no-patch-installed-hermes if you only want to copy the plugin.

npx lithermes-ai install --yes --patch-installed-hermes --hermes-repo /path/to/hermes-agent

The patch path writes .lithermes.bak backups and a rollback manifest under the Hermes home.

Rollback patches:

npx lithermes-ai uninstall --yes --rollback-patches

Uninstall

Remove only manifest-owned LitHermes files and remove the config entry:

npx lithermes-ai uninstall --yes

Uninstall intentionally preserves unrelated files in ~/.hermes/plugins.

Troubleshooting

Hermes installation not found

Pass the Hermes home explicitly:

npx lithermes-ai doctor --hermes-home /path/to/.hermes

Commands do not appear inside Hermes

Restart Hermes. Plugin discovery is loaded by the running process, so an already-open CLI or gateway may not see a newly installed plugin.

Then check:

npx lithermes-ai check --offline

Telegram /lit_loop does not respond

Run:

npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent

If the gateway check fails, update Hermes or use the explicit patch fallback.

Bun local tarball testing

Current Bun versions may not execute a local tarball directly with bunx ./file.tgz. For local release testing, install the tarball into a temp project and run the binary:

bun init -y
bun add ./lithermes-*.tgz
bunx --no-install lithermes doctor

Release Checklist

npm test
npm pack --dry-run --json
npm publish --access public
npx --yes lithermes@latest doctor

Security note: npx and bunx execute package code. Use doctor and --dry-run first when installing on a sensitive Hermes host.