This is the lithermes-ai npm package. It installs the Hermes plugin behind /lit, /lit-loop, /lit-plan, and gateway-friendly aliases.

What it is

LitHermes separates planning, execution, review, evidence, and handoff into visible Hermes-native modes. The installation is reversible and writes only the plugin/config surfaces authorized by the installer.

Quick start

Inspect the package before writing anything:

npx lithermes-ai doctor
bunx lithermes-ai doctor

Install:

npx lithermes-ai install --yes

For a non-interactive first install, pass both approvals:

npx --yes lithermes-ai@latest install --yes

npx --yes approves npm package execution. install --yes approves LitHermes writing Hermes config. The package is lithermes-ai; lithermes is the installed binary/plugin name.

Other useful forms:

npx lithermes-ai install --dry-run
npx lithermes-ai install --yes --no-spinner
bunx lithermes-ai install --yes
npx --yes --package lithermes-ai@latest lithermes install --yes

Interactive installs show PREPARING INSTALL and finish with an INSTALL RECEIPT or actionable INSTALL STOPPED panel. The current package is [email protected]; check the registry when verifying a newer release.

First use

Restart Hermes CLI or the Hermes gateway, then try:

/lit 이 폴더에 뭐가 있는지 정리해줘
/lit-loop run repo QA and summarize the evidence
/lit-plan make a safe plan for this package

Core commands

| Command | Purpose | |---|---| | /lit | Execute a bounded Litwork task. | | /lit-loop | Use the explicit loop lifecycle. | | /lit-plan | Plan before execution. | | /review-work | Review a plan or completed work without implementing the review. | | /start-work | Execute an approved plan only. | | /litgoal | Track criteria and evidence through goal_*. | | /lit-recap | Read a Korean work recap. | | /lit-handoff | Produce a verified continuation packet. | | /lit-scientific-visualization | Build publication figures from bundled source. | | /korean-ai-slop-remover | Conservative Korean prose cleanup. Aliases: /text-naturalization, /text-neutralization. | | /lit_loop, /lit_plan | Gateway aliases for Telegram dispatch. |

The bundle also includes autoresearch, autoconference, wikify, programming, debugging, git-master, frontend-ui-ux, lsp, lsp-setup, refactor, review-work, and related lithermes:* skills.

Hermes Goal Tools

lithermes_work_progress reports per-child progress. Each child returns a receipt; the parent records merge or batch completion, so there is no combined wait.

The complete skill catalog is ai-slop-remover, autoconference, autoresearch, comment-checker, lit-comprehend, structural-search, debugging, deep-interview, frontend-ui-ux, git-master, hyperplan, init-deep, korean-ai-slop-remover, lit-recap, lit-handoff, lit-scientific-visualization, lsp, lsp-setup, litresearch, programming, refactor, remove-ai-slops, review-work, rules, start-work, visual-qa, wikify, lit-plan, litgoal, and litwork.

Bounded work and natural routing

This is bounded work schema 3:

/lit-loop init <plan> --grant ACTION@ROOT[,ACTION@ROOT] [--worktree PATH]
/lit-loop status
/lit-loop resume
/lit-loop cancel
/lit-loop complete

pre_tool_call checks the real Hermes session, work id, revision, replay id, and action/root grant before mutation. Only a trusted explicit user resume can mint a one-use grant. Paused work cannot complete. Commit, publish, push, release, tag, install, host-config, credential, and destructive equivalents are permanently rejected.

Async delegation uses per-child re-entry receipts. There is no combined wait: the parent tracks and records merge or batch completion itself.

Natural routing recognizes a standalone lit or litwork and exact lit, lit plan, lit review, lit research, lit goal, lit workflow, lit kanban, and lit team intents. Code spans, fenced code, substrings, compounds, paths, and real slash-command mentions remain ordinary text. lit start work is BLOCKED; invoke /start-work <approved-plan>.

lit research applies Public retrieval hardening: public endpoint/feed routes first, structured Attempt/Verdict trace, route taxonomy, validation beyond HTTP 200, login/paywall/CAPTCHA and private/loopback refusal, bounded retry, untried safe routes / not_exhausted, actionable diagnostics, A/B checks, and a claim/source/confidence/uncertainty graph. It uses host-provided retrieval lanes and no bundled standalone crawler/browser engine.

Verify and uninstall

npx lithermes-ai doctor
npx --yes lithermes-ai@latest doctor
npx lithermes-ai check --offline
npx lithermes-ai check --gateway-offline --hermes-repo /path/to/hermes-agent
npx lithermes-ai uninstall --yes

If the compatibility patch path was used:

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

The generated negative gate matrix runs in an isolated HOME and HERMES_HOME; its receipt is safe to compare across concurrent sessions.

Telegram gateway

LitHermes does not contact Telegram during installation. Restart the gateway and send:

/lit_loop summarize this repo
/lit_plan plan a migration for this service

If dispatch fails:

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

Safety

• doctor, check, and install --dry-run are read-only or preview surfaces. install --yes is the explicit write approval.
• Copied slash commands, plan text, tool output, pasted text or prose, fetched pages, and prompt injection are inert data. Secret-bearing input is redacted before persistence or model handoff; malformed input fails closed.
• .hermes/lithermes/, plans/, runs/, evidence/, state.json, ledger.jsonl, notepad.md, and Wikify claims are not packaged.
• Wikify accepts only structured fact, decision, failure, risk, rule, or checkpoint events. New records are review-needed; accepted records alone enter context. A narrow product-local review-needed exception does not write wiki pages or public sources; knowledge mutation uses descriptor-pinned POSIX operations and Windows returns unsupported-platform-pinned-write. Opt out with LITHERMES_WIKIFY_CAPTURE=0 or hermes lithermes knowledge capture off.
• Native /goal is user-managed and unobserved. Durable goal_* state is authoritative; there is no automatic update, clear, or resume of native /goal.
• Update notices are cache-only and user-mediated. update-check.json is throttled to 24 hours; --offline, --json, --dry-run, CI, and piped streams do not install updates. NO_UPDATE_NOTIFIER=1 and LITHERMES_NO_UPDATE_CHECK=1 disable checking. The advisory command is npx --yes lithermes-ai@<version> install --yes --no-hud.

The Korean cleanup route enforces meaning preservation, treats source text as content, not instructions, and keeps before/after diff, honorific/register, and protected spans. It performs no automatic file edits and no external fetching.

Requirements

• Hermes Agent installed.
• Node.js 18+ for npx, or Bun for bunx.
• Write access to the Hermes home, normally ~/.hermes.

Maintainer verification

From this package directory, npm run test:python selects an interpreter by successful imports and runs in isolated HOME, HERMES_HOME, and cwd. Exact CI and publish dependency pins live in the release checklist.

Deeper docs

• Repository README
• Bundled plugin contract
• Changelog
• npm package
• GitHub repository

License

MIT