Merge branch 'main' into bb/gui

2026-05-15 22:18:15 -04:00
parent 40ad610968 c7db6a5800
commit 62905e0a6e
109 changed files with 6979 additions and 539 deletions
@@ -19,13 +19,16 @@ Prefer a native installer? Use the desktop release channel that matches your ris

 Stable desktop builds ship signed/notarized macOS artifacts and Windows installers with checksum files.

-### Linux / macOS / WSL2
+### One-Line CLI Installer (Linux / macOS / WSL2)
+
+For a git-based install that tracks `main` and gives you the latest changes immediately:
+>>>>>>> main

 ```bash
 curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
 ```

-### Windows (native, PowerShell) — Early Beta
+### Windows CLI (native, PowerShell) — Early Beta

 :::warning Early BETA
 Native Windows support is **early beta**. It installs and works for the common paths, but hasn't been road-tested as broadly as our POSIX installers. Please [file issues](https://github.com/NousResearch/hermes-agent/issues) when you hit rough edges. For the most battle-tested setup on Windows today, use the Linux/macOS one-liner above inside **WSL2** instead.
@@ -76,7 +79,8 @@ Where the installer puts things depends on whether you're installing as a normal

 | Installer | Code lives at | `hermes` binary | Data directory |
 |---|---|---|---|
-| Per-user (normal) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` |
+| pip install | Python site-packages | `~/.local/bin/hermes` (console_scripts) | `~/.hermes/` |
+| Per-user (git installer) | `~/.hermes/hermes-agent/` | `~/.local/bin/hermes` (symlink) | `~/.hermes/` |
 | Root-mode (`sudo curl … \| sudo bash`) | `/usr/local/lib/hermes-agent/` | `/usr/local/bin/hermes` | `/root/.hermes/` (or `$HERMES_HOME`) |

 The root-mode **FHS layout** (`/usr/local/lib/…`, `/usr/local/bin/hermes`) matches where other system-wide developer tools land on Linux. It's useful for shared-machine deployments where one system install should serve every user. Per-user config (auth, skills, sessions) still lives under each user's `~/.hermes/` or explicit `HERMES_HOME`.
@@ -104,7 +108,9 @@ hermes setup          # Or run the full setup wizard to configure everything at

 ## Prerequisites

-The only prerequisite is **Git**. The installer automatically handles everything else:
+**pip install:** No prerequisites beyond Python 3.11+. Everything else is handled automatically.
+
+**Git installer:** The only prerequisite is **Git**. The installer automatically handles everything else:

 - **uv** (fast Python package manager)
 - **Python 3.11** (via uv, no sudo needed)
@@ -48,7 +48,16 @@ Pick the row that matches your goal:

 ## 1. Install Hermes Agent

-Run the one-line installer:
+**Option A — pip (simplest):**
+
+```bash
+pip install hermes-agent
+hermes postinstall     # optional: installs Node.js, browser, ripgrep, ffmpeg + runs setup
+```
+
+PyPI releases track tagged versions (major/minor releases), not every commit on `main`. For bleeding-edge, use Option B.
+
+**Option B — git installer (tracks main branch):**

 ```bash
 # Linux / macOS / WSL2 / Android (Termux)
@@ -8,19 +8,36 @@ description: "How to update Hermes Agent to the latest version or uninstall it"

 ## Updating

+### Git installs
+
 Update to the latest version with a single command:

 ```bash
 hermes update
 ```

-This pulls the latest code, updates dependencies, and prompts you to configure any new options that were added since your last update.
+This pulls the latest code from `main`, updates dependencies, and prompts you to configure any new options that were added since your last update.
+
+### pip installs
+
+PyPI releases track **tagged versions** (major and minor releases), not every commit on `main`. Check for updates and upgrade with:
+
+```bash
+hermes update --check    # see if a newer release is on PyPI
+hermes update            # runs pip install --upgrade hermes-agent
+```
+
+Or manually:
+
+```bash
+pip install --upgrade hermes-agent    # or: uv pip install --upgrade hermes-agent
+```

 :::tip
 `hermes update` automatically detects new configuration options and prompts you to add them. If you skipped that prompt, you can manually run `hermes config check` to see missing options, then `hermes config migrate` to interactively add them.
 :::

-### What happens during an update
+### What happens during an update (git installs)

 When you run `hermes update`, the following steps occur:

@@ -32,7 +49,7 @@ When you run `hermes update`, the following steps occur:

 ### Preview-only: `hermes update --check`

-Want to know if you're behind `origin/main` before actually pulling? Run `hermes update --check` — it fetches, prints your local commit and the latest remote commit side-by-side, and exits `0` if in sync or `1` if behind. No files are modified, no gateway is restarted. Useful in scripts and cron jobs that gate on "is there an update".
+Want to know if an update is available before pulling? Run `hermes update --check` — for git installs it fetches and compares commits against `origin/main`; for pip installs it queries PyPI for the latest release. No files are modified, no gateway is restarted. Useful in scripts and cron jobs that gate on "is there an update".

 ### Full pre-update backup: `--backup`

@@ -189,12 +206,21 @@ See [Nix Setup](./nix-setup.md) for more details.

 ## Uninstalling

+### Git installs
+
 ```bash
 hermes uninstall
 ```

 The uninstaller gives you the option to keep your configuration files (`~/.hermes/`) for a future reinstall.

+### pip installs
+
+```bash
+pip uninstall hermes-agent
+rm -rf ~/.hermes            # Optional — keep if you plan to reinstall
+```
+
 ### Manual Uninstall

 ```bash