Pull mirror of https://github.com/NousResearch/hermes-agent (vendor pin source, see vendor/hermes.lock in NoeticAI2.0). Auto-syncs every 8h. https://hermes-agent.nousresearch.com
  • Python 71.8%
  • TypeScript 24.7%
  • JavaScript 1.8%
  • Shell 0.4%
  • PowerShell 0.3%
  • Other 0.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
teknium1 ae2a81ccc0 fix(cloud): answer 'not signed in to Nous Portal' with 409, not 401
GET /api/cloud/agents answered 401 portal_signin_required when the install
has no Nous Portal sign-in. Every dashboard client reads a 401 as its own
session being refused: the Webapp transport turns any 401 on a no-auth
dashboard into 'sign in to the Webapp', and the dashboard auth contract e2e
(test_scraped_token_opens_every_get_route) flags the route as refusing the
dashboard's own token. Use 409 (state conflict on this install) and keep
detail.code/message, which is what the Settings consumers display.
2026-11-16 11:28:45 -08:00
.github fix(code-health): the packaged-imports scan is a guard, and it sees submodule imports 2026-11-16 11:52:44 +05:30
acp_adapter fix(fast): report Bedrock Sol fast-capable only on its Mantle route 2026-11-13 17:25:23 -08:00
agent refactor(delegation): siblings read config from its owner, not back through the facade 2026-11-16 21:58:16 +05:30
apps fix(desktop): held cold-start keys reach only the chat the handoff names 2026-11-16 11:27:04 -08:00
assets
contributors chore: map contributor email for hyeonsang010716 2026-11-15 23:38:31 -08:00
cron refactor(gateway): outbound send files move from tools/ to gateway/outbound/ 2026-11-16 18:09:07 +05:30
docker fix(docker): seed auth.json owner-only from the first instant (#155396) 2026-11-14 12:46:58 +01:00
evals refactor(environments-terminal): resolve the process checkpoint path per call 2026-11-16 21:56:33 +05:30
fixture fix(telegram): shared DM threads keep per-thread batches and the routed profile's topic state 2026-11-14 06:08:13 -08:00
gateway fix(gateway): the stream gate tolerates a partial test runner 2026-11-16 10:25:20 -08:00
hermes_agent fix(guards): judge a module moved twice against its first path, not the one between 2026-11-13 20:47:05 +00:00
hermes_cli fix(cloud): answer 'not signed in to Nous Portal' with 409, not 401 2026-11-16 11:28:45 -08:00
hermes_platform feat(gateway): report the Windows start context in gateway attach 2026-11-14 10:40:53 -05:00
locales chore(i18n): regenerate desktop key list for the gateway-down message 2026-11-16 10:29:52 -08:00
nix
optional-mcps chore(optional-mcps): drop MeetStream MCP entry from this PR 2026-11-14 13:33:11 -08:00
optional-skills test(comfyui): pin explicit-token precedence and dot-less lookalike host; note comfy-cli 1.5.0+ 2026-11-14 21:03:17 +01:00
owned fix(telegram): shared DM threads keep per-thread batches and the routed profile's topic state 2026-11-14 06:08:13 -08:00
plugin-catalog plugin-catalog: bump loredocs to 0.1.34 2026-11-16 09:48:34 -08:00
plugins refactor(gateway): outbound send files move from tools/ to gateway/outbound/ 2026-11-16 18:09:07 +05:30
pm Merge pull request #155534 from NousResearch/sec3/148835-git-for-windows-bump 2026-11-15 01:31:13 +01:00
providers fix(cache): profile ceiling is keyword-only; tolerate agent stubs without base_url 2026-11-15 12:04:54 -08:00
scripts refactor(gateway): outbound send files move from tools/ to gateway/outbound/ 2026-11-16 18:09:07 +05:30
skills fix(p5js): serve local .wasm as application/wasm 2026-11-15 01:47:59 +01:00
tests fix(cloud): answer 'not signed in to Nous Portal' with 409, not 401 2026-11-16 11:28:45 -08:00
tests-js fix(install-e2e): let the post-update desktop smoke reopen the profile the update kept 2026-11-13 15:36:40 -06:00
tools refactor(delegation): siblings read config from its owner, not back through the facade 2026-11-16 21:58:16 +05:30
tui_gateway refactor(cron): three cron helper files move from tools/ to cron/ 2026-11-16 17:43:16 +05:30
ui-tui refactor(environments-terminal): delete unreached vercel helpers, CredentialRef, failed_start and exit-137 hint 2026-11-16 15:23:37 +05:30
utils refactor: split utils.py into the utils package 2026-11-16 17:16:20 +05:30
web test(profiles): restore scrollIntoView after the dashboard warning tests 2026-11-14 16:43:19 +05:30
website fix(transfer): name the Messaging page, not "Settings → Messaging" 2026-11-16 10:29:52 -08:00
.coderabbit.yaml
.dockerignore
.env.example fix(terminal): log a one-time note when a sudo password goes to a non-local backend 2026-11-13 13:18:51 -05:00
.envrc
.gitattributes feat(compat): generate shims at old module paths for releases that update across a move 2026-11-13 18:45:32 +00:00
.gitignore
.hadolint.yaml
.mailmap
.npmrc
.nvmrc
.prettierignore
.prettierrc
.python-version
activate
activate.fish
activate.ps1
AGENTS.md docs: lazy facades may name an import hazard; tool registration is the import side effect 2026-11-16 14:55:12 +05:30
batch_runner.py refactor(core): drop the registry's stale toolset-check map and TOOL_TO_TOOLSET_MAP 2026-11-16 21:57:49 +05:30
cli-config.yaml.example feat(tts): add configurable global reply scope 2026-11-14 03:45:21 -08:00
cli.py refactor(code-files): delete unreached sandbox gate, checkpoint helpers, py shell linter 2026-11-16 15:22:48 +05:30
CONTRIBUTING.es.md
CONTRIBUTING.md docs(agents): root AGENTS.md says what a good package looks like 2026-11-16 11:52:44 +05:30
docker-compose.windows.yml
docker-compose.yml
Dockerfile fix(docker): clear the world bit on uv cache entries instead of deleting .lock 2026-11-14 12:05:16 +01:00
eslint.config.shared.mjs
flake.lock
flake.nix
hermes
hermes_bootstrap.py fix(compat): install the finder after the interrupted-update repair in hermes_bootstrap 2026-11-13 18:45:32 +00:00
hermes_constants.py fix: make path-keyed guards follow MOVES so a chunk need not edit them 2026-11-13 20:47:04 +00:00
hermes_constants_scratch.py
hermes_constants_scratch_detach.py
hermes_constants_scratch_stuck.py
hermes_dir_acl.py
hermes_logging.py fix(redact): mask credential-bearing URL query params and userinfo on the log path 2026-11-14 17:07:09 +01:00
hermes_scope.py
hermes_startup_watchdog.py
hermes_state.py feat(cache): one prompt-cache clock per session; Nous 5m ceiling as data 2026-11-15 12:04:54 -08:00
hermes_state_api_content.py
hermes_state_common.py feat(cache): one prompt-cache clock per session; Nous 5m ceiling as data 2026-11-15 12:04:54 -08:00
hermes_state_compaction_display.py
hermes_state_compression.py
hermes_state_coverage.py
hermes_state_dbfile.py refactor(state): move _chmod_pinned_inode into hermes_state_dbfile 2026-11-14 04:52:32 +01:00
hermes_state_delegate_children.py
hermes_state_detached_results.py
hermes_state_errors.py
hermes_state_fts.py
hermes_state_gateway.py
hermes_state_guard.py
hermes_state_health.py
hermes_state_holders.py
hermes_state_identity.py
hermes_state_ids.py
hermes_state_keys.py
hermes_state_legacy_refusal.py
hermes_state_local.py
hermes_state_local_lineage.py
hermes_state_local_migration.py
hermes_state_lockguard.py
hermes_state_lockowners.py
hermes_state_loop_guard.py fix(gateway): the SessionDB loop guard is a config.yaml key, not an env var 2026-11-13 17:02:18 -08:00
hermes_state_maintenance.py
hermes_state_media.py
hermes_state_messages.py
hermes_state_mutation_binding.py
hermes_state_mutation_branch.py
hermes_state_mutation_chat_pick.py
hermes_state_mutation_compress.py
hermes_state_mutation_guards.py
hermes_state_mutation_prepared.py
hermes_state_mutation_reset.py
hermes_state_mutation_retirement.py
hermes_state_mutation_transcript.py
hermes_state_mutations.py
hermes_state_pidns.py
hermes_state_portability.py
hermes_state_profile_repair.py
hermes_state_prompt_refresh.py
hermes_state_prune_rewrite.py
hermes_state_readpool.py fix(state): a read that falls back to the locked writer logs a rate-limited WARNING 2026-11-13 15:18:38 -08:00
hermes_state_reconcile.py
hermes_state_registry.py fix(state): judge state.db links before the registry resolves them 2026-11-14 04:52:31 +01:00
hermes_state_repair.py
hermes_state_rewind.py
hermes_state_runtime.py fix(cache): owner stamps the worker clock generation in the usage receipt 2026-11-15 12:04:54 -08:00
hermes_state_runtime_workers.py
hermes_state_schema.py
hermes_state_search.py
hermes_state_session_list.py
hermes_state_sessions.py
hermes_state_sessions_model_config.py
hermes_state_stored_reads.py
hermes_state_telegram.py
hermes_state_terminal.py
hermes_state_timeline.py
hermes_state_titles.py
hermes_state_todo.py
hermes_state_usage.py fix(cache): coverage deadlines, guaranteed vs estimated ends, durable generation 2026-11-15 12:04:54 -08:00
hermes_state_user_copy.py
hermes_state_wal.py chore: scripts/check fixes (narrow except, waivers on never-raise diagnostic paths, no wall-clock sleep in a test) 2026-11-13 15:18:38 -08:00
hermes_state_worker_compression.py
hermes_state_worker_context.py fix(cache): owner stamps the worker clock generation in the usage receipt 2026-11-15 12:04:54 -08:00
hermes_state_worker_lifecycle.py
hermes_state_write.py chore: scripts/check fixes (narrow except, waivers on never-raise diagnostic paths, no wall-clock sleep in a test) 2026-11-13 15:18:38 -08:00
hermes_time.py
hermes_yaml.py
justfile chore(lint): keep ruff.toml as the only ruff config 2026-11-15 14:02:40 +05:30
lefthook.yml feat(compat): generate shims at old module paths for releases that update across a move 2026-11-13 18:45:32 +00:00
LICENSE
model_tools.py refactor(core): drop the registry's stale toolset-check map and TOOL_TO_TOOLSET_MAP 2026-11-16 21:57:49 +05:30
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
pyproject.toml refactor: split utils.py into the utils package 2026-11-16 17:16:20 +05:30
README.es.md
README.md
README.ur-pk.md
README.zh-CN.md
registration_lifecycle.py
ruff.toml chore(lint): keep ruff.toml as the only ruff config 2026-11-15 14:02:40 +05:30
run_agent.py fix: import the model rule inside the two functions that call it 2026-11-16 14:23:53 +05:30
SECURITY.es.md
SECURITY.md
setup-hermes.ps1
setup-hermes.sh
setup.py
SOUL.md
toolset_distributions.py
toolsets.py fix(core): keep create_custom_toolset for embedding hosts 2026-11-16 15:40:08 +05:30
trajectory_compressor.py refactor: callers find the install folder through project_root_str() 2026-11-13 18:45:31 +00:00
uv.lock

Hermes Agent

Hermes Agent ☤

Hermes Agent | Hermes Desktop

Documentation Discord License: MIT Built by Nous Research 中文 اردو Español

The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.

Use any model you want — Nous Portal, OpenRouter, OpenAI, your own endpoint, and many others. Switch with hermes model — no code changes, no lock-in.

A real terminal interfaceFull TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.
Lives where you doTelegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.
A closed learning loopAgent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. Honcho dialectic user modeling. Compatible with the agentskills.io open standard.
Scheduled automationsBuilt-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.
Delegates and parallelizesSpawn isolated subagents for parallel workstreams. In Desktop, choose their provider, model, and limits under Settings → Model → Subagents, then Apply the complete route. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.
Runs anywhere, not just your laptopSix built-in terminal backends — local, Docker, SSH, Modal, Daytona, and Vercel Sandbox — plus plugin backends such as Singularity/Apptainer. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.
Research-readyBatch trajectory generation, trajectory compression for training the next generation of tool-calling models.

Quick Install

Linux, macOS, WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows (native, PowerShell)

Heads up: Native Windows runs Hermes without WSL — CLI, gateway, TUI, and tools all work natively. If you'd rather use WSL2, the Linux/macOS one-liner above works there too. Found a bug? Please file issues.

Run this in PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

The source installer delegates Python 3.14, Node.js, npm, pnpm, ripgrep, FFmpeg, and Python dependencies to PM. If Git is absent, it stages the verified Git for Windows archive in Hermes' tool store. It does not replace your system Git. See installation methods for the separate MSIX/App Installer package and its update ownership.

Android / Termux: A signed APT repository is available for aarch64 devices, with a stable channel (tagged releases) and a prerelease canary channel. The package includes Python, Node.js, and the TUI. Use the Termux guide, not the desktop/server installer script.

Windows: Native Windows is fully supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under %LOCALAPPDATA%\hermes; WSL2 installs under ~/.hermes as on Linux.

After installation:

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
hermes              # start chatting!

Troubleshooting

Windows Defender or antivirus flags uv.exe as malware

If your antivirus (Bitdefender, Windows Defender, etc.) quarantines uv.exe from the Hermes bin folder (%LOCALAPPDATA%\hermes\bin\uv.exe), this is a false positive. The file is Astral's uv — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.

To verify your copy is authentic:

# Install GitHub CLI if needed
winget install --id GitHub.cli

# Login to GitHub
gh auth login

# Run verification
$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
$ver = (& $uv --version).Split(' ')[1]
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$zip = "$env:TEMP\uv.zip"
Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
gh attestation verify $zip --repo astral-sh/uv
Expand-Archive $zip "$env:TEMP\uv_x" -Force
(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash

If attestation says "Verification succeeded" and the last line prints True, you're good.

To whitelist Hermes:

  • Windows Defender: Run PowerShell as Admin → Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"
  • Bitdefender: Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
  • Whitelist the folder, not the file hash — Hermes updates uv and the hash changes every version

For more context, see the upstream Astral reports: astral-sh/uv#13553, astral-sh/uv#15011, astral-sh/uv#10079.


Getting Started

hermes              # Interactive CLI — start a conversation
hermes model        # Choose your LLM provider and model
hermes tools        # Configure which tools are enabled
hermes config set   # Set individual config values
hermes config get   # Print individual config values
hermes gateway      # Start the messaging gateway (Telegram, Discord, etc.)
hermes setup        # Run the full setup wizard (configures everything at once)
hermes update       # Update to the latest version
hermes doctor       # Diagnose any issues

📖 Full documentation →


Skip the API-key collection — Nous Portal

Hermes works with whatever provider you want — that's not changing. But if you'd rather not collect five separate API keys for the model, web search, image generation, TTS, and a cloud browser, Nous Portal covers all of them under one subscription:

  • 300+ models — pick any of them with /model <name>
  • Tool Gateway — web search, image generation (FAL), text-to-speech (OpenAI), cloud browser (Browser Use), all routed through your sub. No extra accounts.

One command from a fresh install:

hermes setup --portal

That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with hermes portal info. Full details on the Tool Gateway docs page.

You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.


CLI vs Messaging Quick Reference

Hermes has two entry points: start the terminal UI with hermes, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.

Action CLI Messaging platforms
Start chatting hermes Run hermes gateway setup + hermes gateway start, then send the bot a message
Start fresh conversation /new or /reset /new or /reset
Change model /model [provider:model] /model [provider:model]
Set a personality /personality [name] /personality [name]
Retry or undo the last turn /retry, /undo /retry, /undo
Compress context / check usage /compress, /usage, /insights [--days N] /compress, /usage, /insights [days]
Browse skills /skills or /<skill-name> /<skill-name>
Interrupt current work Ctrl+C or send a new message /stop or send a new message
Platform-specific status /platforms /status, /sethome

For the full command lists, see the CLI guide and the Messaging Gateway guide.


Documentation

All documentation lives at hermes-agent.nousresearch.com/docs:

Section What's Covered
Quickstart Install → setup → first conversation in 2 minutes
CLI Usage Commands, keybindings, personalities, sessions
Configuration Config file, providers, models, all options
Messaging Gateway Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant
Security Command approval, DM pairing, container isolation
Tools & Toolsets 40+ tools, toolset system, terminal backends
Skills System Procedural memory, Skills Hub, creating skills
Memory Persistent memory, user profiles, best practices
MCP Integration Connect any MCP server for extended capabilities
Cron Scheduling Scheduled tasks with platform delivery
Context Files Project context that shapes every conversation
Architecture Project structure, agent loop, key classes
Contributing Development setup, PR process, code style
CLI Reference All commands and flags
Environment Variables Complete env var reference

Migrating from OpenClaw or another agent

If you're coming from OpenClaw, Claude Code, Codex CLI or Cursor, Hermes can import your settings, memories and skills (and, for OpenClaw, API keys when you ask for them).

During setup: hermes setup asks whether to import from another agent, pre-selects the ones it finds (~/.openclaw, ~/.claude, ~/.codex, ~/.cursor), installs the official agent-importers plugin and runs the import with a preview first.

Anytime after install:

hermes plugins install agent-importers          # once per profile
hermes import-agent openclaw                    # interactive migration (full preset)
hermes import-agent openclaw --dry-run          # preview what would be migrated
hermes import-agent openclaw --migrate-secrets  # also bring allowlisted API keys
hermes import-agent claude-code                 # or codex / cursor

What gets imported from OpenClaw:

  • SOUL.md — persona file
  • Memories — MEMORY.md and USER.md entries
  • Skills — user-created skills → ~/.hermes/skills/openclaw-imports/
  • Command allowlist — approval patterns
  • Messaging settings — platform configs, allowed users, working directory
  • API keys — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs), only with --migrate-secrets
  • TTS assets — workspace audio files
  • Workspace instructions — AGENTS.md (with --workspace-target)

hermes claw migrate still works as the older spelling. See the OpenClaw migration guide and Import from Other Agents.


Contributing

We welcome contributions! See the Contributing Guide for development setup, code style, and PR process.

Start with the PM developer workflow for activation, daily use, dependency changes, and leaving the environment. Development Setup covers the separate test environment and verification commands.


Community

  • 💬 Discord
  • 📚 Skills Hub
  • 🐛 Issues
  • 🔌 computer-use-linux — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
  • 🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.

License

MIT — see LICENSE.

Built by Nous Research.