Metadata-Version: 2.4
Name: hermes-gpt
Version: 0.6.0
Summary: Local-dev MCP sidecar for exposing selected Hermes Agent capabilities.
Author: hermes-gpt contributors
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.0
Requires-Dist: packaging>=23
Requires-Dist: uvicorn
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pyyaml; extra == "dev"
Dynamic: license-file

# hermes-gpt

[![PyPI version](https://img.shields.io/pypi/v/hermes-gpt.svg)](https://pypi.org/project/hermes-gpt/)
[![PyPI downloads](https://img.shields.io/pypi/dm/hermes-gpt.svg)](https://pypi.org/project/hermes-gpt/)

![Hermes GPT v0.5.0 — Two-Way Codex Bridge](assets/hermes-gpt-v0.5.0-two-way-codex-bridge.png)

`hermes-gpt` is a standalone MCP sidecar for Hermes Agent. It imports selected local Hermes Agent internals at runtime and exposes them to MCP clients without modifying Hermes Agent source files.

```bash
pip install hermes-gpt
```

Or clone from [GitHub](https://github.com/asimons81/hermes-gpt).

This is a **local-dev release**.

## v0.5.0 Two-Way Codex Bridge

v0.5.0 adds a two-way bridge: Codex can opt into Hermes Operator tools, and trusted Hermes GPT clients can delegate asynchronous tasks and reviews to Codex. Updates remain check-first and mutations remain gated and dry-run-first. See [Codex setup](docs/codex.md), [Operator Mode](docs/operator-mode.md), [updating](docs/updating.md), and the [v0.5.0 release notes](docs/release-notes-v0.5.0.md).

## v0.6.0 Mission Control, Work Contracts, and Swarms

v0.6.0 adds **Mission Control**, a read-only operational view of the whole
Hermes fleet exposed as the `hermes_mission_*` tool family; **Work Contracts**
(`hermes_contract_*`) that validate completion from observed state rather than a
worker's self-report; and bounded **Swarm Orchestration** (`hermes_swarm_*`) on
top of those contracts. See the [release notes](docs/release-notes-v0.6.0.md)
and [retention policy](docs/retention-policy.md).

Mission Control is structurally read-only — all SQLite is opened `mode=ro`, no
write/dry-run/apply arguments exist, and no mutating shell calls are made. It
never returns raw message, memory, transcript, request-dump, or profile-secret
bodies; prompts surface as `{prompt_len, prompt_sha256}` only, and every call is
audited. Per-client authorization uses the `HERMES_GPT_MISSION_ALLOWED_SURFACES`
allowlist (deny-by-default). See [Operator Mode](docs/operator-mode.md) for the
full surface, allowlist, and redaction contract.

### Updating Hermes GPT

```powershell
hermes-gpt update
hermes-gpt update --apply
```

The first command only checks. `--apply` fast-forwards a clean checkout on its default branch, or upgrades an installed PyPI package. It never creates merge commits, rebases, downgrades packages, or overwrites tracked local changes.

## Codex App / Codex CLI Support

The v0.5.0 core connector is a curated tool surface for planning, local vision analysis, web search/extraction, cron planning, skill drafts, and gateway diagnostics; it does not modify Codex itself or bypass its permissions.

```powershell
$env:HERMES_GPT_ENABLE_CODEX="1"
$env:HERMES_GPT_ENABLE_MCP="1"
hermes-gpt codex install --toolset core
hermes-gpt codex doctor
```

Use `hermes-gpt codex install --toolset operator --refresh` for the opt-in Operator control plane. The installer creates a backup before refreshing only the Hermes GPT entry. Use `--project` for `<repo>/.codex/config.toml`, and `uninstall` to remove only that entry. Full setup, runner gates, and troubleshooting live in [docs/codex.md](docs/codex.md). For a Windows deployment where ChatGPT dispatches approved jobs to the standalone Codex CLI, see [docs/windows-chatgpt-codex.md](docs/windows-chatgpt-codex.md).

## What's New in v0.4.0

v0.4.0 is the Tool Surface Expansion release. It adds env-gated Hermes tool wrappers, a cron creation operator tool, and ships the first external contribution.

- **New env-gated MCP tools:**
  - `hermes_vision_analyze` — analyze images through Hermes Agent (`HERMES_GPT_ENABLE_VISION=1`)
  - `hermes_web_search` — search the web (`HERMES_GPT_ENABLE_WEB=1`)
  - `hermes_web_extract` — extract page content (same env gate)
- **New operator tool:**
  - `hermes_cron_create` — create cron jobs from scratch with full field support: schedule, prompt, script, skills, deliver, repeat, workdir, no_agent, model, context_from, enabled_toolsets
- **First external contribution:** Gateway PID fallback from `gateway_state.json` when `gateway.pid` is missing (fixes macOS detection)
- **Expanded gateway diagnostics:** New fields — `gateway_state`, `gateway_kind`, `gateway_pid_source`, `gateway_updated_at`, `gateway_exit_reason`, `gateway_active_agents`
- **Infrastructure:** Vercel static site deploys correctly, HTTP smoke test no longer fails CI
- **Published on PyPI:** `pip install hermes-gpt`

## What’s New in v0.3.0

v0.3.0 is the Operator Reliability Release. It makes Hermes GPT self-diagnosing, safely recoverable, and release-checkable.

- New operator diagnostics tools:
  - `hermes_operator_doctor` — read-only deep health check across operator, gateway, config, env, cron, skills, policy, audit, and connector surfaces.
  - `hermes_operator_snapshot` — single current-state summary.
  - `hermes_release_doctor` — release readiness checks with PASS / WARN / BLOCKED classification.
  - `hermes_operator_recover` — conservative dry-run-first recovery sequence.
- All operator-facing failures now return a structured error envelope:
  `{success, ok, error, layer, code, safe_message, suggested_action, trace_id}`.
- Diagnostic and recovery statuses use PASS / WARN / FAIL / UNSUPPORTED.
- Connector re-registration is explicitly reported as unsupported unless a real supported command/API exists.
- `hermes_operator_recover` is dry-run by default and requires `apply=true` for mutations.

## What’s New in v0.2.0

v0.2.0 adds tiered Operator / Owner Mode so trusted MCP clients can see the full Hermes GPT surface while the default posture stays safe.

- Default mode remains read-only.
- Recommended always-on connector/tunnel mode is `dry_run`.
- Direct mutation requires both:
  - `HERMES_GPT_OPERATOR_APPLY_MODE=direct`
  - the mutating tool call sets `dry_run=false`
- Owner Mode requires the exact break-glass acknowledgement:
  - `HERMES_GPT_OWNER_ACK=I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE`
- Operator Mode is not a sandbox.
- Do not expose publicly without real auth, VPN, Tailscale, or an equivalent private boundary.

What v0.2.0 adds:

- operator policy, status, and audit tools
- cron tools
- skill tools
- config and env tools
- gateway tools
- workspace tools
- owner tools behind explicit acknowledgement
- audit logging with hashes and lengths instead of raw prompt/content
- Hermes data-root normalization for operator profile operations
- packaging fixes so operator modules ship in the release

| Mode | Env posture | What happens |
| --- | --- | --- |
| Read-only | no operator env vars | read/list/status tools only; mutations refuse |
| Dry-run Operator | operator enabled + apply_mode=dry_run | mutation tools return plans/previews only |
| Direct Operator | operator enabled + apply_mode=direct | writes allowed only when tool call also sets `dry_run=false` |
| Owner Mode | level=owner + exact owner ack | break-glass local owner tools; still denies secret paths |

For the full Operator Mode guide, new-user quickstart, and tunnel safety model, see `docs/operator-mode.md`.

## Fleet routing through one connector

When the local Hermes install already has authenticated named peers in its A2A
registry, one Hermes GPT connector can route bounded tasks to those peers:

- `hermes_fleet_list()` lists registered peers without exposing bearer tokens.
- `hermes_fleet_status(agent)` runs a metadata-only A2A compatibility check.
- `hermes_fleet_dispatch(agent, message, confirm, dry_run)` submits a task only
  to a registered peer. A real dispatch requires workspace-level Operator Mode,
  direct apply mode, `dry_run=false`, and `confirm=true`.
- `hermes_fleet_task(agent, task_id)` returns a safe status summary without
  returning task prompts or histories.
- `hermes_fleet_dispatch_work_order(...)` validates and submits a canonical,
  profile-aware work order.
- `hermes_fleet_result(agent, task_id)` returns only a safe completion bundle.
- `hermes_fleet_authority_drift()` reports registry, manifest, profile, role,
  and Agent Card drift.

This is deliberately not a generic remote shell: callers cannot provide a peer
URL or token, and dispatch is constrained to the local authenticated A2A
registry. Use `hermes_fleet_list` before selecting a target. Keep the connector
behind an authenticated private boundary; A2A peer authentication does not make
an unauthenticated public MCP endpoint safe.

Structured dispatch reads `HERMES_GPT_FLEET_AUTHORITY_MANIFEST`, defaulting to
`<Hermes data root>/config/fleet-authority.json`. The server-controlled path is
absolute, non-symlinked, size-bounded, and checked by the secret-path policy.
Copy `examples/fleet-authority.example.json`, set expected roles and identities,
install it with service-account-only permissions, and run the drift tool before
enabling direct mode. Confirmed structured dispatch rechecks the live peer
identity and host role against that manifest immediately before sending. Never
place URLs, credentials, or tokens in the manifest.

## Security posture

By default, `hermes-gpt` is designed for a trusted local machine:

- HTTP binds to `127.0.0.1` by default.
- Tools advertise `noauth` only for local-dev MCP clients.
- Write, patch, terminal execution, memory writes, and session search are disabled or hidden by default.
- Remote/public release is not supported until real OAuth or another ChatGPT-compatible authentication layer is added.

Do not expose this server publicly without authentication. A temporary tunnel is acceptable only for short local testing when you understand that any enabled tool is reachable through that URL.

## Prerequisites

- Python 3.10+
- A local Hermes Agent install
- MCP Python SDK and Uvicorn

Install dependencies:

```bash
cd ~/hermes-gpt
python -m pip install -r requirements.txt
```

## Local MCP clients

Stdio mode is for local MCP clients that support subprocess MCP servers:

```bash
cd ~/hermes-gpt
python server.py
```

Example client command:

```json
{
  "command": "python",
  "args": ["C:\\Users\\<YOU>\\hermes-gpt\\server.py"]
}
```

## Local HTTP

HTTP mode uses FastMCP streamable HTTP:

```bash
cd ~/hermes-gpt
python server.py --http --host 127.0.0.1 --port 7677
```

Local endpoint:

```text
http://127.0.0.1:7677/mcp
```

If you bind to anything other than loopback in the default `local-dev` profile, the server prints a warning. This warning means the configuration is not release-safe.

## ChatGPT local testing

ChatGPT developer mode expects a remote MCP endpoint. Do not enter a localhost URL such as `http://127.0.0.1:4750`; ChatGPT fetches the MCP configuration through its connector path, where `127.0.0.1` is not your machine.

For short local testing only:

```powershell
cd C:\Users\<YOU>\hermes-gpt
python server.py --http --host 127.0.0.1 --port 4750
```

In another terminal:

```powershell
& "C:\Program Files (x86)\cloudflared\cloudflared.exe" tunnel --url http://127.0.0.1:4750 --http-host-header 127.0.0.1:4750
```

In ChatGPT, configure:

- Protocol: Streaming HTTP
- MCP server URL: `https://<your-trycloudflare-host>/mcp`
- Authentication: No Authentication

If ChatGPT only shows the old 5-tool surface, reconnect or recreate the connector and follow the workflow in `docs/operator-mode.md`.

Example scripts for local setup live under `examples/`.

## Tool gates

Default visible tools:

- `hermes_read_file(path, offset=1, limit=500)`
- `hermes_search_files(pattern, target="content", path=".", file_glob=None, limit=50)`
- `hermes_memory(action="search", target="memory", content=None, old_text=None)`
- `hermes_skill_list()`
- `hermes_skill_view(name)`

Opt-in tools and actions:

| Capability | Env var | Default |
| --- | --- | --- |
| Write file and patch tools | `HERMES_GPT_ENABLE_WRITE=1` | Hidden |
| Memory `add`, `replace`, `remove` | `HERMES_GPT_ENABLE_MEMORY_WRITE=1` | Disabled |
| Session search | `HERMES_GPT_ENABLE_SESSION_SEARCH=1` | Hidden |
| Terminal command execution | `HERMES_GPT_ENABLE_TERMINAL=1` | Hidden |

Terminal timeout is capped at 120 seconds even when enabled.

The broad `HERMES_GPT_ENABLE_*` flags still work for backward compatibility,
but for tiered, safe operation prefer the **Operator / Owner Mode** tools
documented below.

## Hermes GPT Operator Mode

Operator / Owner Mode is a tiered control plane that lets trusted MCP
clients (like ChatGPT) operate Hermes safely: cron jobs, skills, profile
config wiring, safe non-secret env keys, gateway/runtime status and restart,
scoped workspace edits, and (with explicit acknowledgement) owner-level
command and file access.

### Safety model

- **Default behavior is read-only.** Mutating operator tools refuse unless
  operator mode is explicitly enabled.
- **Dry-run is the default.** Even when operator mode is enabled, every
  mutating tool defaults to `dry_run=True` and returns a plan instead of
  mutating. To actually mutate, you must set
  `HERMES_GPT_OPERATOR_APPLY_MODE=direct` AND pass `dry_run=False` to the
  tool call.
- **Direct mutation requires explicit opt-in.** `HERMES_GPT_OPERATOR_APPLY_MODE=direct`
  is required for any write to happen.
- **Owner Mode requires an explicit break-glass activation and acknowledgement.**
  Setting `HERMES_GPT_OPERATOR_LEVEL=owner` alone is clamped to effective
  `workspace` operation. Owner tools require both `HERMES_GPT_OWNER_ACTIVE=1`
  and `HERMES_GPT_OWNER_ACK=I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE`.
- **No secrets exposed.** Config `get` redacts secret-looking keys; `env`
  tools never return values; skill/cron prompts are logged and surfaced
  only as `prompt_len` + `prompt_sha256`.
- **No `.env` raw read/write.** The denied-path policy refuses `.env`,
  `auth.json`, `mcp-tokens/`, `.ssh/`, `.aws/`, `vault/`, and any
  secret-looking filename.
- **No `shell=True` anywhere.** Every subprocess invocation uses
  `shell=False` with a fixed argv.
- **No `git add -A`, no `git push`, no destructive filesystem operations.**
  Workspace `run_test` only allows a conservative allowlist (pytest, ruff,
  mypy, npm test/lint, git status/diff). Owner `run_command` blocks
  catastrophic patterns (`rm -rf /`, `del /s`, `format`, `curl | bash`,
  `git push --force`, `git add -A`, `git add .`, anything touching
  `.env`/`vault`/`token`/`.ssh`).
- **Operator Mode is not a sandbox.** Use OS-level isolation (container,
  VM, or a tool like OpenShell) for untrusted input. The operator gates
  are defense-in-depth, not a security boundary — same stance as Hermes
  Agent's own SECURITY.md.
- **Do not expose remote without real auth.** Operator Mode does not add
  any authentication. Bind to loopback only, or put a real auth layer
  (VPN, Tailscale, OAuth) in front before exposing on a network.

### Operator levels

Levels are ordered; each level includes all capabilities of the levels
above it in this list.

| Level | Capabilities |
| --- | --- |
| `read_only` | status, policy, audit tail, cron list/status, skill diff/list/view, config get, env status, gateway status, git status/diff |
| `cron` | + cron run, cron pause, cron copy, cron move |
| `skills` | + skill create, edit, patch, write_file, copy, sync_to_default, delete |
| `skills_config` | + config set/patch, env set/copy (non-secret keys only) |
| `workspace` | + scoped workspace patch/write, test/lint allowlist, gateway restart |
| `owner` | + raw command, raw file patch/write — still gated by explicit owner ack and still denies secret paths |

### Env flags

| Env var | Default | Purpose |
| --- | --- | --- |
| `HERMES_GPT_OPERATOR_ENABLED` | unset (false) | Enable operator mode |
| `HERMES_GPT_OPERATOR_LEVEL` | `read_only` | Operator level (see table above) |
| `HERMES_GPT_OPERATOR_APPLY_MODE` | `dry_run` | `dry_run` returns plans; `direct` allows mutation |
| `HERMES_GPT_OPERATOR_ALLOWED_PROFILES` | `default` | Comma-separated profile names, or `*` for all existing |
| `HERMES_GPT_OPERATOR_ALLOWED_PATHS` | empty | Comma-separated workspace root paths; empty disables workspace writes |
| `HERMES_GPT_OPERATOR_DENIED_PATHS` | built-in defaults | Extra denied paths (additions only; cannot weaken defaults) |
| `HERMES_GPT_OWNER_ACTIVE` | unset | Must be truthy to activate break-glass Owner Mode; otherwise configured `owner` is clamped to `workspace` |
| `HERMES_GPT_OWNER_ACK` | unset | Must equal `I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE` for owner tools |

### Examples

Read-only default (no env vars needed):

```powershell
hermes-gpt
```

Cron dry-run:

```powershell
$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="cron"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="dry_run"
$env:HERMES_GPT_OPERATOR_ALLOWED_PROFILES="default,hermes-researcher"
hermes-gpt
```

Skills/config dry-run:

```powershell
$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="skills_config"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="dry_run"
$env:HERMES_GPT_OPERATOR_ALLOWED_PROFILES="default,hermes-researcher,hermes-trt-manager,hermes-nexus-wiki"
hermes-gpt
```

Workspace direct with allowed path:

```powershell
$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="workspace"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="direct"
$env:HERMES_GPT_OPERATOR_ALLOWED_PATHS="C:\Users\<YOU>\hermes-gpt,C:\Users\<YOU>\AppData\Local\hermes\hermes-agent"
hermes-gpt
```

Owner Mode (WARNING: can mutate your machine):

```powershell
$env:HERMES_GPT_OPERATOR_ENABLED="1"
$env:HERMES_GPT_OPERATOR_LEVEL="owner"
$env:HERMES_GPT_OPERATOR_APPLY_MODE="direct"
$env:HERMES_GPT_OWNER_ACTIVE="1"
$env:HERMES_GPT_OWNER_ACK="I_UNDERSTAND_THIS_CAN_MUTATE_MY_MACHINE"
hermes-gpt
```

### Audit log

Every mutating tool call appends a JSONL record to:

- `%USERPROFILE%\AppData\Local\hermes\logs\hermes_gpt_operator_audit.jsonl` (preferred), or
- `<hermes-gpt>\logs\hermes_gpt_operator_audit.jsonl` (fallback)

Each record contains: `timestamp`, `tool`, `level`, `apply_mode`, `dry_run`,
`success`, `changed`, `summary`, `error`, profile(s), path summary, job_id /
skill_name / key (when relevant), and `prompt_len` + `prompt_sha256` /
`content_len` + `content_sha256` for skill/cron content. The audit log
**never** records full prompts, full config values, raw `.env` contents,
vault contents, or command output likely to contain secrets. Read it with
the `hermes_operator_audit_tail` tool.

### Owner Mode warning

Owner Mode can mutate your machine. Use it only on a trusted local
machine. It is **not a sandbox** — it is the explicit break-glass path
for the local owner. Even in Owner Mode, secret paths (`.env`, `auth.json`,
`.ssh/`, `mcp-tokens/`, etc.) remain denied; no secret override is
shipped in this release.

## Remote profile

`--profile remote` is intentionally blocked because authentication is not implemented:

```bash
python server.py --http --profile remote
```

For temporary experiments only, you can bypass this block with both:

```bash
HERMES_GPT_UNSAFE_REMOTE_NOAUTH=1
python server.py --http --profile remote --i-understand-this-is-unsafe
```

Do not use this bypass for release.

## Release checklist

Before publishing:

- No `*.pem` files.
- No `*.log` or `*.err.log` files.
- No `__pycache__/` or `*.pyc`.
- `python -m py_compile server.py` passes.
- `pytest` passes.
- Server binds to loopback by default.
- Terminal, write tools, memory writes, and session search are disabled by default.

## Current capability notes

The feasibility probe passed in this environment:

- Hermes source root: `C:\Users\<YOU>\AppData\Local\hermes\hermes-agent`
- File tools: available
- Terminal tool: available, gated by `HERMES_GPT_ENABLE_TERMINAL=1`
- Memory tool: available
- Skill discovery: available through local and bundled skill directories
- Session search: available through `SessionDB.search_messages`
- FastMCP stdio: available
- FastMCP streamable HTTP: available

See `FEASIBILITY.md` for probe details and exact signatures.

## License

MIT. See `LICENSE`.
