# Pitfall Log

Project: NousResearch/hermes-agent

Summary: Found 25 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_ebdf0d00876046d89748da04ed227c7e | https://github.com/NousResearch/hermes-agent/issues/3002

## 2. Configuration risk - Configuration risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_0b1cf269e8544779854a23690e9187be | https://github.com/NousResearch/hermes-agent/issues/38240

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_533af3ccff3243efbc8a4a049fb486f8 | https://github.com/NousResearch/hermes-agent/issues/38412

## 4. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.12.0 (2026.4.30)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.12.0 (2026.4.30)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.12.0 (2026.4.30). Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_1ab5e40250fb7bb7500a78bfac6921ce | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.30

## 5. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.13.0 (2026.5.7) — The Tenacity Release. Context: Observed when using windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_abceb1a94a2e1f07743c8878577f695b | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.7

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.14.0 (2026.5.16)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.14.0 (2026.5.16)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.14.0 (2026.5.16). Context: Observed when using python, windows
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_94f238ed56ebeb1d4c3cc44c330f6166 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.16

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.1 (2026.5.29) — The Patch Release. Context: Observed when using node, docker
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_42c8eb734be226f0ea2754c6ec441b49 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.16.0 (2026.6.5) — The Surface Release. Context: Observed when using windows, macos, linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_cd46b9a84f20e3a44f6b2422437a74b8 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.6.5

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Hermes Agent v0.9.0 (v2026.4.13)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.9.0 (v2026.4.13)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.9.0 (v2026.4.13). Context: Observed during installation or first-run setup.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_ebc5e39694eba4ae912d57e33b801fbc | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.13

## 10. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: [Bug]: Fails to install NeuTTS during setup
- User impact: Developers may fail before the first successful local run: [Bug]: Fails to install NeuTTS during setup
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Fails to install NeuTTS during setup. Context: Observed when using python, docker, linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_aa0532f69fee3ba2c93ab682a2a9d932 | https://github.com/NousResearch/hermes-agent/issues/3002

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.10.0 (2026.4.16)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.10.0 (2026.4.16)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.10.0 (2026.4.16). Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_b7814ac23ad116ffc89c5c84de52d640 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.16

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.11.0 (2026.4.23)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.11.0 (2026.4.23)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.11.0 (2026.4.23). Context: Observed when using python
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_682469568c053ba9d4541275da2f3a7a | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.4.23

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.0 (2026.5.28) — The Velocity Release. Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_b143f7fe51c8e3b04b46ced013277c58 | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.28

## 15. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client
- User impact: Developers may misconfigure credentials, environment, or host setup: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: Desktop "Remote gateway" can't connect over WebSocket — /api/ws always rejected (4403) for packaged Electron client. Context: Observed when using python, macos, linux
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_4474a22161ce67918a103e3a46b3eb5d | https://github.com/NousResearch/hermes-agent/issues/38412

## 16. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 17. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_3a4ba2c2a31141689dcea24451693682 | https://github.com/NousResearch/hermes-agent/issues/41050

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 20. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 21. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: community_evidence:github | cevd_480a48c0230941ad98930d4a5261ec5e | https://github.com/NousResearch/hermes-agent/issues/41053

## 22. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this conceptual risk before relying on the project: [skills-index-watchdog] Skills index is stale or degraded (degraded)
- User impact: Developers may hit a documented source-backed failure mode: [skills-index-watchdog] Skills index is stale or degraded (degraded)
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_issue | fmev_67c9459bf558bd4c6d02e9d7b9f434a2 | https://github.com/NousResearch/hermes-agent/issues/38240

## 23. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 24. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Suggested check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | github_repo:1024554267 | https://github.com/NousResearch/hermes-agent

## 25. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: Hermes Agent v0.15.2 (2026.5.29.2)
- User impact: Upgrade or migration may change expected behavior: Hermes Agent v0.15.2 (2026.5.29.2)
- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Hermes Agent v0.15.2 (2026.5.29.2). Context: Source discussion did not expose a precise runtime context.
- Guardrail: State this as source-backed community evidence, not as Doramagic reproduction.
- Evidence: failure_mode_cluster:github_release | fmev_d6b7af62a9cd2afad3287b2ede57124e | https://github.com/NousResearch/hermes-agent/releases/tag/v2026.5.29.2