hermes-mend

A lightweight terminal agent for Kali Linux (or any Linux) that talks to a Hermes model through an API. No local model, no GPU, no third-party Python packages. Only python3 (3.10+) and an API key.

It has two modes:

Command	What it does
hermes-mend run "task"	Hermes proposes one shell command per turn; guardrails and you decide what runs.
hermes-mend heal	Hermes fixes Hermes. Runs the test suite, sends failures plus source to Hermes, applies a minimal patch, re-tests, and rolls back automatically if it did not help.

Prerequisites

• Linux with bash and python3 >= 3.10 (Kali ships both).
• An API key for any OpenAI-compatible endpoint that serves a Hermes model (default: OpenRouter, model nousresearch/hermes-3-llama-3.1-70b). Check that the model name is still available on your provider.

Setup

unzip hermes-mend.zip && cd hermes-mend
./setup.sh            # safe to re-run; add --test to run the offline tests too
nano .env             # set HERMES_API_KEY
hermes-mend doctor    # verifies config and one real API call

setup.sh checks the Python version, creates .env from .env.example (mode 600, never overwritten), and writes a launcher to ~/.local/bin/hermes-mend. It installs nothing system-wide and needs no network. If ~/.local/bin is not on your PATH, the script prints the line to add. Without the launcher you can run PYTHONPATH=src python3 -m hermes_mend ... from the repo root.

Configuration

Environment variables win over .env files. Files are searched in this order: ./.env, <repo>/.env, ~/.config/hermes-mend/.env (or pass --env-file).

Variable	Default	Meaning
HERMES_API_KEY	none (required)	API key. Never printed; redacted from command output sent to the model.
HERMES_BASE_URL	https://openrouter.ai/api/v1	OpenAI-compatible base URL.
HERMES_MODEL	nousresearch/hermes-3-llama-3.1-70b	Model identifier at your provider.
HERMES_COMMAND_TIMEOUT	60	Seconds before a command is killed.
HERMES_MAX_STEPS	12	Max agent turns per task.

Usage

hermes-mend run "show disk usage and the five largest folders in /var/log"
hermes-mend run --cwd ~/lab "list open listening ports on this machine"

hermes-mend heal                          # repair this repo's own source (asks before each patch)
hermes-mend heal --yes                    # apply without asking (still tested + rolled back on failure)
hermes-mend heal --root ~/proj --tests "pytest -q" --editable app --attempts 4

How heal stays safe

1. Hermes may only return {path, old, new} edits. Each old must match exactly once.
2. Paths must be relative, inside --editable directories (default src), and end in .py. Tests are never editable.
3. A patch that would not compile is rejected before touching disk.
4. You see a unified diff and approve it (unless --yes).
5. Originals and the diff are saved to .hermes-mend/backups/<timestamp>-attemptN/.
6. If tests still fail after the patch, files are restored and the failure is fed to the next attempt.
7. Repair kernel: client.py, config.py, healer.py, replies.py, safety.py, shell.py are protected by default, because the loop needs them to work and cannot repair itself through a broken copy of them. --unprotect-kernel (experimental) lifts this, except for safety.py, which is always protected. Healable by default: agent.py, cli.py. For other projects, no files are protected by this list.

Safety model (read this)

safety.py is a policy filter, not a sandbox.

• Read-only commands such as ls, cat, uname run automatically (only when they have no pipes, redirects or expansions).
• Everything else asks you first. Destructive patterns and credential files (.env, SSH keys, /etc/shadow) are blocked even with --yes.
• A determined or confused model can still do harm with an approved command. Run as an unprivileged user, preferably in a VM or container, and read every command you approve.
• Command output is sent to the API provider. Do not run it against data you cannot share.

Tests

PYTHONPATH=src python3 -m unittest discover -s tests

All tests run offline: a scripted fake client, a local HTTP server for the API client, and a temporary project for the repair loop.

Layout

src/hermes_mend/   client, config, safety, shell, replies, agent, healer, cli
tests/             offline unit and integration tests
setup.sh           idempotent setup
.env.example       configuration template

Limitations

• The model must return strict JSON; malformed replies are retried within the step or attempt budget.
• heal edits Python files only, and quality depends on the model and on your test coverage.
• Tested here against a mock API only; the first real API call is hermes-mend doctor.