This page documents the repository organization, dependency management, and installation ecosystem of Hermes Agent. It covers the directory layout, key source files, the uv-based dependency and Python management system, and native multi-platform installation including Nix flake support for declarative deployments.
Hermes Agent follows a modular codebase design with well-defined directory boundaries for CLI, core agent logic, tools, messaging gateways, and frontends.
The diagram below associates conceptual system components to their corresponding code entities and main source files:
Sources: hermes_cli/__init__.py1-12 pyproject.toml3-23 tools/lazy_deps.py1-50
Hermes uses a platform-aware directory structure for state and configuration.
hermes_cli/__init__.py hermes_cli/__init__.py17-18 and pyproject.toml pyproject.toml5scripts/release.py utility automates version bumping (CalVer) across the codebase scripts/release.py1-21 It handles contributor attribution via an email-to-username mapping, merging legacy frozen mappings with a modern one-file-per-email directory structure scripts/release.py33-46Sources: hermes_cli/__init__.py17-18 pyproject.toml5 scripts/release.py33-46
uv Package Manager EcosystemHermes Agent leverages the uv package manager for fast, reproducible Python environment management.
uv from selecting Python 3.14 where Rust-backed transitives (like pydantic-core) may lack pre-built wheels pyproject.toml8-14openai==2.24.0) to ensure that new package versions only reach users via intentional updates pyproject.toml19-32uv.lock file captures the full resolution of the dependency tree for reproducibility uv.lock1-9anthropic, faster-whisper) are lazy-installed via tools/lazy_deps.py when the user selects that specific backend, reducing the base install footprint pyproject.toml34-39The pinned set of dependencies in pyproject.toml ensures stability:
| Category | Key Dependencies | Role |
|---|---|---|
| LLM / Data | openai, pydantic, python-dotenv | Model communication, validation, and env config pyproject.toml40-55 |
| CLI / UI | prompt_toolkit, rich, fire | Interactive REPL, terminal formatting, and CLI parsing pyproject.toml43-57 |
| Networking | httpx[socks], requests, tenacity | HTTP clients and retry logic pyproject.toml44-49 |
| Process | psutil | Cross-platform PID and process-tree management pyproject.toml99 |
| Scheduling | croniter | Core engine for scheduled/interval jobs pyproject.toml59 |
| Web Server | fastapi, uvicorn[standard] | Backend for the Web UI Dashboard pyproject.toml105-106 |
| Terminal | ptyprocess (Unix), pywinpty (Windows) | Cross-platform pseudo-terminal management pyproject.toml112-113 |
| Image Processing | Pillow | Image resize recovery for vision tools pyproject.toml125 |
Hermes supports modular installation via tools/lazy_deps.py. Only specs that appear in the LAZY_DEPS allowlist can be installed at runtime tools/lazy_deps.py48-50
| Feature Namespace | Package Specs | Notable Dependencies |
|---|---|---|
provider.anthropic | anthropic==0.87.0 | Native Anthropic SDK tools/lazy_deps.py101 |
provider.bedrock | boto3==1.42.89 | AWS Bedrock provider tools/lazy_deps.py103 |
provider.vertex | google-auth==2.55.1 | Google Vertex AI provider tools/lazy_deps.py107 |
provider.azure_identity | azure-identity==1.25.3 | Microsoft Foundry Entra ID auth tools/lazy_deps.py112 |
search.exa | exa-py==2.10.2 | Exa web search backend tools/lazy_deps.py115 |
tts.mistral | mistralai==2.4.8 | Mistral TTS provider tools/lazy_deps.py128 |
stt.faster_whisper | faster-whisper==1.2.1 | Faster Whisper STT provider tools/lazy_deps.py134-138 |
memory.honcho | honcho-ai==2.2.0 | Honcho AI-native memory tools/lazy_deps.py144 |
Sources: pyproject.toml15-135 uv.lock1-30 tools/lazy_deps.py1-160
Hermes Agent provides a native NixOS module and flake outputs for declarative deployments. The system uses a centralized package-lock.json at the root for all npm workspaces nix/lib.nix3-5
The module supports two modes nix/nixosModules.nix3-5:
apt/pip/npm installs.The container entrypoint script ensures a writable toolchain is available even when the core agent is read-only in the Nix store nix/nixosModules.nix95-152:
hermes user and group with specified UID/GID nix/nixosModules.nix98-129npm installs nix/nixosModules.nix143-151The TUI and Web dashboard are built using Node-based toolchains and integrated into the Python package. Nix uses mkNpmPassthru and importNpmLock to manage JS dependencies reproducibly nix/lib.nix168-176
Sources: nix/tui.nix1-33 nix/lib.nix1-176 nix/nixosModules.nix1-157 ui-tui/package.json9 web/package.json8 apps/desktop/package.json27
Key command-line entry points registered in pyproject.toml and managed by the CLI wrapper:
| Command | Entry Point | Purpose |
|---|---|---|
hermes chat | hermes_cli.main:main | Interactive chat REPL |
hermes gateway | hermes_cli.main:main | Multi-platform messaging gateway |
hermes setup | hermes_cli.main:main | Interactive configuration wizard |
hermes status | hermes_cli.main:main | System diagnostic and component status |
hermes web | hermes_cli.main:main | Starts the web UI dashboard |
The hermes_cli/__init__.py file also performs an early UTF-8 stream enforcement to prevent UnicodeEncodeError crashes on minimal environments like Raspberry Pi hermes_cli/__init__.py21-51
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.