All plugins

hermes-parallel

Run three isolated, verified file futures inside Hermes, compare, then choose one to apply. Disclosure — /parallel apply replaces the chosen workspace folder under your configured root with the selected future (the original is kept as a hidden backup sibling for /parallel rollback); snapshots of that folder are stored in the profile's parallel-data directory; when you set ai_enabled, parallel_explore makes three model calls with your filenames, and with context_enabled also the contents of the files you name.

kOs-tileToolsv1.0.4Updated 7 days ago

About

Run three isolated, verified file futures inside Hermes, compare, then choose one to apply. Disclosure — /parallel apply replaces the chosen workspace folder under your configured root with the selected future (the original is kept as a hidden backup sibling for /parallel rollback); snapshots of that folder are stored in the profile's parallel-data directory; when you set ai_enabled, parallel_explore makes three model calls with your filenames, and with context_enabled also the contents of the files you name.

HERMES / PARALLEL

Three futures. One human decision.

A native Hermes Agent plugin that turns one requested workspace change into three real, inspectable outcomes, each on its own isolated file snapshot. Compare file diffs and (for HTML) live visual previews; explicitly choose one to apply. Roll back to the original if the selected result has not been edited.

Release candidate 1.0.4-rc.1. Verified on Hermes Agent v0.23.0 in an isolated official Docker container: native doctor and validate, clean-profile install/enable and 81/81 regression tests PASS. Worktree Arena imports three already-produced workspaces for bounded, read-only comparison. Founder VPS installation, automatic subagent spawning and provider-backed planning remain unverified. Filesystem clones are not an OS security boundary. See SECURITY.md.

The magic moment

You: "Redesign this small homepage. Give me three dramatically different futures."

Hermes: Creates three distinct, bounded file plans. Each plan changes its own real copy of the project. The plugin verifies all three and generates a self-contained gallery where you can inspect the actual versions side by side.

You: /parallel apply <RUN_ID> B

Only the chosen future is installed, with the original preserved for recovery. Clicking a visual selection alone does not mutate any file.

Tool or commandWhat it doesCost / authority
parallel_beginSnapshot approved project into A/B/CLocal only; source unchanged
parallel_stageExecute one declarative move/write_text plan on one branchLocal only; no shell
parallel_compareVerify snapshots and return exact paths/diffsRead-only
parallel_galleryRender read-only HTML gallery with sandboxed previewsLocal only, no network
parallel_previewNo-LLM file organization teaching modeLocal only
parallel_exploreAsk Hermes's active model for 3 different structured plansDisabled unless operator opts in; 3 potentially billable model calls; optional selected-file context requires separate opt-in
/parallel view RUN_IDReveal visual comparison locationRead-only
/parallel apply RUN_ID A/B/CInstall exactly one checked branchHuman slash command only
/parallel rollback RUN_IDRestore checked original (rejects newer edits)Human slash command only
/parallel recover RUN_IDReconcile specified interrupted rename states or fail closedHuman slash command

No plugin tool exists for model-initiated apply or rollback. There is no terminal execution, browser automation, delete operation, external API write, background daemon or proprietary inference SDK.

Installation

Prerequisites: Hermes Agent with its native plugin API; Python 3.11+. Requires no third-party Python packages.

# Choose a dedicated scratch directory that you explicitly authorize Parallel
# to inspect. Give Parallel a disposable folder of its own; never use $HOME
# itself, /, a credential directory or a production site root as the root.
mkdir -p "$HOME/ParallelLab/example"

# Copy this repository into the native Hermes plugin directory, or install it
# from its future standalone public GitHub repo with: hermes plugins install OWNER/hermes-parallel
mkdir -p "$HOME/.hermes/plugins/hermes-parallel"
cp -R ./plugin.yaml ./__init__.py ./core.py ./gallery.py "$HOME/.hermes/plugins/hermes-parallel/"

hermes plugins doctor "$HOME/.hermes/plugins/hermes-parallel"
hermes plugins validate "$HOME/.hermes/plugins/hermes-parallel" --install-deps
hermes plugins enable hermes-parallel

Configuration

Hermes Parallel reads its behaviour settings from config.yaml, under its own plugin entry. It does not use environment variables for behaviour settings.

plugins:
  entries:
    hermes-parallel:
      settings:
        root: ~/ParallelLab
        # data_dir: /path/to/private/run-store   # optional, see below
        ai_enabled: false
        context_enabled: false

root is required: the only parent directory the plugin may inspect. Point it at a dedicated scratch folder (for example ~/ParallelLab) and create your disposable projects inside it. If root is missing, the plugin still registers but refuses to access any workspace.

Settings are read when the plugin registers. After changing config.yaml, restart or reload the gateway so the plugin re-registers with the new values.

Optional: the data_dir setting chooses the private local run store. By default the store is parallel-data inside the active profile's Hermes home, so each profile keeps its own snapshots. The store must not overlap your allowed workspace. Never point a public web server at it; the snapshots can contain sensitive source files.

Zero-cost proof

python -m unittest discover -s tests -v
python examples/showcase.py

The second command produces a self-contained gallery.html inside a temporary run directory. Open the reported file:// path in a browser. It uses three curated deterministic demo plans, not live model generations, to prove the actual branch isolation and viewer. No API requests or third-party packages.

Hermes end-to-end walkthrough

  1. Create a disposable project under your configured root with an index.html and notes.md.
  2. Ask Hermes to call parallel_begin with its absolute path and a one-sentence goal. Keep the returned run id.
  3. Have Hermes prepare three different parallel_stage operations, one for A, B and C. Supported operations:
{"action": "write_text", "path": "index.html", "text": "<h1>Future A</h1>"}
{"action": "move", "from": "notes.md", "to": "docs/notes.md"}
  1. Use parallel_compare then parallel_gallery (or /parallel view <RUN_ID>) to see actual results. Open the local HTML file for the gallery.
  2. Select a future visually and type /parallel apply <RUN_ID> A in the Hermes conversation.
  3. Optional: /parallel rollback <RUN_ID> to restore the baseline if the selected workspace has not changed.

The entire source directory is copied into a private run store. Changes to the original after snapshot (including unrelated file edits) prevent apply. Re-running parallel_stage on an already-ready branch is refused; begin a fresh run to revise a proposal.

Opt-in AI proposals (potential provider charges)

By default parallel_explore refuses execution. To allow it, set ai_enabled: true in the plugin settings in config.yaml (see Configuration) and let the plugin re-register. It makes three sequential ctx.llm.complete_structured calls using Hermes's existing model and credentials, each with a different creative lens. The default sends file names only, not source contents. Path names may themselves be sensitive.

To produce richer redesigns, operators may separately set context_enabled: true in the same settings and pass context_files explicitly when invoking parallel_explore, for example {"path":"/allowed/site","goal":"Redesign the home page in three striking directions","context_files":["index.html","styles.css"]}. The plugin reads only these chosen text files from its verified private baseline and includes their contents in all three Hermes provider requests. Maximum five files, 16 KiB per file, 40 KiB total. Files with hidden/sensitive-looking names are excluded, but there is no reliable automated secret detector: inspect selected content first. Neither setting is enabled automatically. No extra API key is read by this plugin. A provider response can fail validation or produce a poor proposal; parallel_stage and manual Hermes reasoning remain available as fallback.

Important: This is three independent planning calls + three isolated file executions, not three unrestricted subagents or arbitrary program simulations. It does not use your previous Agent OS or KCC code and does not claim to simulate email sends, money transfers or the real world.

Engineering boundaries

  • 2000 regular files / 250 MiB per source, 40 operations per branch, 64 KiB per text write. write_text only supports a text extension allowlist.
  • File paths must be POSIX relative and cannot traverse to parent, target symlinks, hidden configuration files, or paths with sensitive credential-like names by write plan. Source symlinks, special files and symlink directories are refused.
  • Baseline and future SHA-256 fingerprints are rechecked for stage, preview, apply, recovery and rollback. Changes in permissions, ownership and timestamps are not modeled as separate changes.
  • A private run-store copy is not a hardened adversarial sandbox. Anyone with OS-level write privileges to the run store or original source can interfere. Concurrent transactions from instances sharing the same run store (data_dir) are serialized by an advisory per-source OS file lock for stage/apply/rollback/recover. Independent editors and processes that ignore that lock are not coordinated; use disposable test workspaces.
  • Rename-based application is intended for filesystems where sibling directory renames are atomic. Crash recovery handles tested checkpoints, but there is no claim of durable power-loss safety under all environments.
  • Gallery HTML is local-only, network-disconnected by CSP, and renders HTML futures in sandbox="" iframes; active JavaScript in preview content is disabled.

Release candidate validation (v1.0.4-rc.1, awaiting exact-head CI)

  • Local Python 3.13 regression: 81 tests passed, including selected-context privacy, same-workspace lock serialization, source drift, transactional recovery including corrupted-backup and forged-recovery-path refusal, and gallery sandbox tests.
  • GitHub Actions config is bundled for a future standalone repository; storing it under a directory within a shared repo does not activate it as a root workflow.
  • Official Hermes Docker CI: native doctor --ci PASS, validate --install-deps PASS, plugin install + enable + list PASS. Live VPS gateway conversations and provider-backed AI calls remain UNVERIFIED. No model credits were used.

Release / verification

See HERMES_HANDOFF.md for a copy-paste handoff to a real Hermes operator. Official Docker CLI compatibility and plugin enablement are verified. Founder VPS installation, real provider calls, standalone public distribution and catalog submission remain pending. These are separate gates; do not conflate them.

Licensed MIT. This is an independently authored Hermes extension, not affiliated with Nous Research.

Experimental Proof Mode (1.0.4-rc.1, private review branch)

When you open a gallery, Hermes Parallel builds a read-only evidence report for each A/B/C candidate:

  • Static local img src, script source and linked asset paths are checked against the candidate tree, with path escapes/symlinks rejected.
  • Outputs report explicit PASS, FAIL and NOT_RUN; no invented quality score.
  • An offline proof.json is written next to the private gallery.html. The gallery shows each candidate's evidence, including broken local assets, before the human chooses one.
  • Nonlocal resources, CSS/JS dynamically loaded assets, browser rendering, accessibility, security and model correctness remain NOT TESTED. A PASS is not a deployment approval.
  • Proof Mode does not perform shell commands, network requests, model calls or automatic source apply; private run data can contain project paths and must not be served publicly.

Example: Candidate B contains <img src=\"missing.png\">; its Proof Card reports FAIL rather than hiding a broken asset behind a good-looking screenshot.

This is a bounded experimental enhancement, not yet validated by the official Hermes Docker CI or deployed on the founder's VPS.

Proof Gate — fail-closed promotion (v1.0.4-rc.1)

When applying a planned future, the plugin rechecks the selected candidate's static local HTML evidence at the moment of promotion. A FAIL refuses the ordinary /parallel apply RUN_ID B command. The operator may explicitly opt in to the known risk by typing /parallel apply RUN_ID B --accept-failed-proof; this is a manual human slash-command only, never an agent tool. No gallery click writes files, and FAIL or PARTIAL candidates do not offer one-click copy of an ordinary apply command.

The gate is intentionally limited: a PASS only asserts the supported static local asset checks. PARTIAL or false negatives remain possible; it does not guarantee the website works, nor is it a test runner or substitute for code review. Original baseline and candidate integrity hashes are verified again before every actual filesystem mutation.

Worktree Arena (v1.0.4 RC, new experimental tool)

Hermes already supports genuine subagent delegation and optional Git worktree isolation. Parallel does not reimplement or launch these agents. It adds the missing read-only comparison step after the work is done.

Natural language: "Hermes, have your native subagents independently improve this page; then use parallel_review_worktrees to compare the three completed worktree paths and the source."

Tool: parallel_review_worktrees with source_path, a_path, b_path, c_path (all absolute under the explicitly configured root setting). The tool returns an offline gallery.html, bounded source-aware diffs and static HTML asset PASS/FAIL/PARTIAL evidence. No extra LLM calls are made by the review.

Manual slash shortcut (when paths contain no whitespace):

/parallel arena /absolute/source /absolute/agent-a /absolute/agent-b /absolute/agent-c

Critical distinctions:

  • This is read-only: the imported review ID is NOT a normal run ID and /parallel apply cannot act on it. Inspect and merge a candidate using Hermes's existing Git worktree workflow.
  • No new subagents are spawned by this tool. Agent execution/cost is separate and controlled by Hermes delegation.
  • No arbitrary shell, tests, browser navigation, live JS, network or Git commands are executed; proofs cover only bounded local HTML assets. Don't claim an automated build or deployment test.
  • Intentionally ignores .git, .worktrees, .env, credentials and common build/cache directories, caps files at 250 and total preview data at 12 MiB. Skipped files are counted, so displayed diffs are not complete Git diffs. Always inspect the native Git diff before merging.
  • Imported files are copied only into the private 0700 run store, which can contain sensitive app source despite filename-based exclusions. Don't expose gallery.html or proof.json on a public server.
  • Worktree Arena is experimental and does not imply real-host VPS or user adoption verification.

README from the reviewed commit 9f66c1c; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section