Issue Station
Sign In
Tools hereToolbox

hermes - ✅(Solved) Fix restructure PR 1: create hermes_agent/ package — move all files, rewrite imports [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#14183•Fetched 2026-04-23 07:46:23
View on GitHub
Comments
0
Participants
1
Timeline
11
Reactions
0
Author
alt-glitchalt-glitch
Participants
alt-glitchalt-glitch
Timeline (top)
labeled ×8cross-referenced ×3

Fix Action

Fix / Workaround

CurrentNewNotes
run_agent.pyhermes_agent/agent/loop.py12k-line god file, move as-is
cli.pyhermes_agent/cli/repl.py11k-line REPL, move as-is
model_tools.pyhermes_agent/tools/dispatch.pyTool discovery + dispatch
toolsets.pyhermes_agent/tools/toolsets.pyNamed tool bundles
toolset_distributions.pyhermes_agent/tools/distributions.pyDatagen distributions
mcp_serve.pyhermes_agent/tools/mcp/serve.pyMCP server
utils.pyhermes_agent/utils.pyPackage root
hermes_constants.pyhermes_agent/constants.pyDrop prefix
hermes_state.pyhermes_agent/state.pyDrop prefix
hermes_logging.pyhermes_agent/logging.pyDrop prefix
hermes_time.pyhermes_agent/time.pyDrop prefix

PR fix notes

PR #14498: refactor: move all source into hermes_agent/ package (PR 1/3)

Description (problem / solution / changelog)

Summary

Consolidates the entire codebase into a single hermes_agent/ Python package. This is PR 1 of 3 in the restructure tracked by #14182 (sub-issue: #14183).

Before: 8 independent packages (agent/, tools/, hermes_cli/, gateway/, acp_adapter/, cron/, plugins/) + 11 top-level modules (run_agent.py, cli.py, model_tools.py, etc.) with unprefixed imports (from agent.prompt_builder import ...).

After: One hermes_agent/ package with organized subpackages. All imports are from hermes_agent.X import ....

Diff breakdown

The diff looks large (+13,057 / -12,287) but ~95% is mechanical one-line import path changes. Here's the breakdown:

CategoryFiles+lines-linesWhat it is
Pure renames7200git mv only — invisible in diff
Renames + import rewrites2192,1092,104Moved files that also had imports rewritten
Tests (not renamed)6499,8149,895Import rewrites + test fixture fixes
Scripts1191436Move map + import rewriter (new files)
Infra + other42226245tui_gateway/, environments/, Dockerfile, AGENTS.md, etc.

Tests dominate because every test file imports from the packages we moved, so every from agent., from tools., from hermes_cli. line was rewritten — plus all patch() and monkeypatch.setattr() target strings. There are more test files (649) than source files (291) because each test imports and mocks multiple modules.

The actual semantic changes (infra, new scripts, .git-blame-ignore-revs) account for ~1,100 lines.

What changed

  • 268 source files moved into hermes_agent/ via git mv (100% similarity preserved for blame)
  • All imports rewritten across 898 files — covers import X, from X import, patch() strings, monkeypatch.setattr(), sys.modules[] keys, importlib.import_module() strings
  • Infrastructure updated — pyproject.toml entry points, Dockerfile, docker/entrypoint.sh, scripts/install.sh, setup-hermes.sh, scripts/install.ps1, web/vite.config.ts, MANIFEST.in, AGENTS.md, nix/checks.nix
  • New subpackage organization:
    • agent/transports/ + provider adapters → hermes_agent/providers/
    • tools/environments/ → hermes_agent/backends/
    • tools/browser_*.py → hermes_agent/tools/browser/
    • tools/mcp_*.py → hermes_agent/tools/mcp/
    • tools/skills_*.py → hermes_agent/tools/skills/
    • tools/file_*.py → hermes_agent/tools/files/
    • tools/*_tool.py (media) → hermes_agent/tools/media/
    • hermes_cli/auth*.py → hermes_agent/cli/auth/
    • hermes_cli/model*.py → hermes_agent/cli/models/
    • hermes_cli/banner.py, colors.py, etc. → hermes_agent/cli/ui/
  • New console script: hermes-skills-sync — decouples shell scripts from internal module layout
  • Zero logic changes — this is purely mechanical file moves + import rewrites

Commit strategy

#CommitPurpose
18bff8bf2Add move map data structure (268 file mappings)
265ca3ba9Pure git mv — all files into hermes_agent/ (100% similarity)
34b163419Rewrite all imports + string references (898 files)
4a1e667b9Fix test regressions from import rewrite (113 test files)
576aebd73Update infrastructure (pyproject, Docker, shell scripts, vite, AGENTS.md)
6ff99611eUpdate Nix files
725072fe6Fix stale references missed by import rewrite
8987962f4Add .git-blame-ignore-revs for restructure commits

Commits 1-2 are separated so git log --follow and git blame work correctly. The git mv commit has 100% similarity on all 268 files. .git-blame-ignore-revs tells git blame (and GitHub) to skip commits 2-3.

Key decisions

DecisionChoiceRationale
plugins/ locationMoved into hermes_agent/plugins/Single package boundary
Layer inversions (agent→cli)Moved as-isPR 1 is mechanical only; fix in follow-up #14278
sys.path hacks in prod codeStrippedAll install paths use editable installs; hacks are redundant
tests/conftest.py sys.pathStripped, added ImportError guardForces proper uv pip install -e '.[all,dev]'
Logger COMPONENT_PREFIXESUpdated to new pathsPreserves hermes logs --component filtering
Process-name matching (gateway)New patterns added alongside oldRunning gateways from pre-upgrade installs still have old cmdline
skills_syncAdded hermes-skills-sync console_scriptDecouples setup-hermes.sh, install.sh, entrypoint.sh from internal layout
Transport discoveryUpdated _discover_transports()Same auto-discovery pattern, new hermes_agent.providers.*_transport paths
Tool registryExtended discover_builtin_tools()Scans browser/, files/, media/, skills/ subpackage directories

Test results

MetricBaseline (pre-restructure)After restructure
Passed14,09914,220 (+121)
Failed6771
Errors7372
Skipped3830

All errors are pre-existing (Callable type annotation bug). The +121 passed is from previously-erroring tests now resolving correctly. No regressions introduced.

Entry points verified

hermes --help          ✅
hermes-agent --help    ✅
hermes-acp --help      ✅
hermes-skills-sync     ✅

Follow-up issues

  • #14278 — Fix layer inversions (agent→cli imports)
  • #14279 — Remove legacy process-name patterns after one release cycle

Directories unchanged (stay at repo root)

skills/, optional-skills/, environments/, tui_gateway/, ui-tui/, web/, website/, docker/, nix/, packaging/, scripts/, tests/, acp_registry/, assets/

Closes #14183

Part of #14182

Changed files

  • .git-blame-ignore-revs (added, +5/-0)
  • AGENTS.md (modified, +64/-73)
  • Dockerfile (modified, +2/-2)
  • MANIFEST.in (modified, +1/-0)
  • datagen-config-examples/run_browser_tasks.sh (modified, +1/-1)
  • datagen-config-examples/web_research.yaml (modified, +1/-1)
  • docker/entrypoint.sh (modified, +1/-1)
  • environments/agent_loop.py (modified, +9/-6)
  • environments/benchmarks/terminalbench_2/terminalbench2_env.py (modified, +3/-3)
  • environments/benchmarks/yc_bench/yc_bench_env.py (modified, +2/-2)
  • environments/hermes_base_env.py (modified, +4/-4)
  • environments/tool_context.py (modified, +4/-4)
  • hermes (modified, +1/-1)
  • hermes_agent/__init__.py (added, +0/-0)
  • hermes_agent/acp/__init__.py (renamed, +0/-0)
  • hermes_agent/acp/__main__.py (renamed, +0/-0)
  • hermes_agent/acp/auth.py (renamed, +1/-1)
  • hermes_agent/acp/entry.py (renamed, +2/-7)
  • hermes_agent/acp/events.py (renamed, +1/-1)
  • hermes_agent/acp/permissions.py (renamed, +0/-0)
  • hermes_agent/acp/server.py (renamed, +14/-14)
  • hermes_agent/acp/session.py (renamed, +7/-7)
  • hermes_agent/acp/tools.py (renamed, +2/-2)
  • hermes_agent/agent/__init__.py (renamed, +0/-0)
  • hermes_agent/agent/context/__init__.py (added, +0/-0)
  • hermes_agent/agent/context/compressor.py (renamed, +4/-4)
  • hermes_agent/agent/context/engine.py (renamed, +0/-0)
  • hermes_agent/agent/context/references.py (renamed, +3/-3)
  • hermes_agent/agent/copilot_acp_client.py (renamed, +2/-2)
  • hermes_agent/agent/display.py (renamed, +6/-5)
  • hermes_agent/agent/file_safety.py (renamed, +1/-1)
  • hermes_agent/agent/image_gen/__init__.py (added, +0/-0)
  • hermes_agent/agent/image_gen/provider.py (renamed, +1/-1)
  • hermes_agent/agent/image_gen/registry.py (renamed, +2/-2)
  • hermes_agent/agent/insights.py (renamed, +2/-2)
  • hermes_agent/agent/loop.py (renamed, +149/-143)
  • hermes_agent/agent/manual_compression_feedback.py (renamed, +0/-0)
  • hermes_agent/agent/memory/__init__.py (added, +0/-0)
  • hermes_agent/agent/memory/manager.py (renamed, +3/-3)
  • hermes_agent/agent/memory/provider.py (renamed, +0/-0)
  • hermes_agent/agent/prompt_builder.py (renamed, +7/-7)
  • hermes_agent/agent/redact.py (renamed, +0/-0)
  • hermes_agent/agent/shell_hooks.py (renamed, +3/-3)
  • hermes_agent/agent/skill_commands.py (renamed, +7/-7)
  • hermes_agent/agent/skill_utils.py (renamed, +4/-3)
  • hermes_agent/agent/subdirectory_hints.py (renamed, +1/-1)
  • hermes_agent/agent/title_generator.py (renamed, +1/-1)
  • hermes_agent/agent/trajectory.py (renamed, +0/-0)
  • hermes_agent/backends/__init__.py (renamed, +1/-1)
  • hermes_agent/backends/base.py (renamed, +6/-6)
  • hermes_agent/backends/daytona.py (renamed, +2/-2)
  • hermes_agent/backends/docker.py (renamed, +6/-6)
  • hermes_agent/backends/file_sync.py (renamed, +3/-3)
  • hermes_agent/backends/local.py (renamed, +8/-8)
  • hermes_agent/backends/managed_modal.py (renamed, +3/-3)
  • hermes_agent/backends/modal.py (renamed, +4/-4)
  • hermes_agent/backends/modal_utils.py (renamed, +3/-3)
  • hermes_agent/backends/singularity.py (renamed, +4/-4)
  • hermes_agent/backends/ssh.py (renamed, +2/-2)
  • hermes_agent/cli/__init__.py (renamed, +0/-0)
  • hermes_agent/cli/auth/__init__.py (added, +0/-0)
  • hermes_agent/cli/auth/auth.py (renamed, +28/-24)
  • hermes_agent/cli/auth/commands.py (renamed, +13/-13)
  • hermes_agent/cli/auth/copilot.py (renamed, +0/-0)
  • hermes_agent/cli/auth/dingtalk.py (renamed, +3/-3)
  • hermes_agent/cli/backup.py (renamed, +2/-2)
  • hermes_agent/cli/claw.py (renamed, +5/-5)
  • hermes_agent/cli/clipboard.py (renamed, +8/-5)
  • hermes_agent/cli/commands.py (renamed, +12/-12)
  • hermes_agent/cli/config.py (renamed, +374/-23)
  • hermes_agent/cli/cron.py (renamed, +9/-10)
  • hermes_agent/cli/debug.py (renamed, +4/-4)
  • hermes_agent/cli/default_soul.py (renamed, +0/-0)
  • hermes_agent/cli/doctor.py (renamed, +26/-28)
  • hermes_agent/cli/dump.py (renamed, +7/-7)
  • hermes_agent/cli/env_loader.py (renamed, +1/-1)
  • hermes_agent/cli/gateway.py (renamed, +44/-32)
  • hermes_agent/cli/hooks.py (renamed, +8/-8)
  • hermes_agent/cli/logs.py (renamed, +2/-2)
  • hermes_agent/cli/main.py (renamed, +167/-171)
  • hermes_agent/cli/mcp_config.py (renamed, +11/-11)
  • hermes_agent/cli/memory_setup.py (renamed, +7/-7)
  • hermes_agent/cli/models/__init__.py (added, +0/-0)
  • hermes_agent/cli/models/codex.py (renamed, +0/-0)
  • hermes_agent/cli/models/models.py (renamed, +23/-23)
  • hermes_agent/cli/models/normalize.py (renamed, +2/-2)
  • hermes_agent/cli/models/switch.py (renamed, +20/-20)
  • hermes_agent/cli/nous_subscription.py (renamed, +8/-8)
  • hermes_agent/cli/pairing.py (renamed, +1/-1)
  • hermes_agent/cli/platforms.py (renamed, +0/-0)
  • hermes_agent/cli/plugins.py (renamed, +13/-13)
  • hermes_agent/cli/plugins_cmd.py (renamed, +22/-22)
  • hermes_agent/cli/profiles.py (renamed, +9/-9)
  • hermes_agent/cli/providers.py (renamed, +3/-3)
  • hermes_agent/cli/repl.py (renamed, +205/-177)
  • hermes_agent/cli/runtime_provider.py (renamed, +12/-12)
  • hermes_agent/cli/setup_wizard.py (renamed, +44/-44)
  • hermes_agent/cli/skills_config.py (renamed, +6/-6)
  • hermes_agent/cli/skills_hub.py (renamed, +30/-30)
  • hermes_agent/cli/timeouts.py (renamed, +2/-2)

Code Example

python -c "import hermes_agent"
rg "^from (agent|tools|hermes_cli|gateway|cron|acp_adapter|run_agent|model_tools|toolsets|toolset_distributions|mcp_serve|hermes_constants|hermes_state|hermes_logging|hermes_time)[\. ]" hermes_agent/ tests/
pytest
hermes --help
hermes-agent --help
RAW_BUFFERClick to expand / collapse

Parent: #14182

Goal

Create the hermes_agent/ package by moving every source file into it and rewriting all imports. This is the biggest PR — every file moves, no logic changes. One .git-blame-ignore-revs entry.

Commit strategy

CommitWhatWhy
Commit 1Pure git mv — every file moves, zero content changesGit sees 100% similarity, clean blame
Commit 2Import rewrite — apply move map across all filesContent changes only in import lines
Commit 3Infrastructure — pyproject.toml, Dockerfile, nix, CIBuild system points at new locations
Commit 4Dynamic imports — string-based importlib.import_module(), __import__(), config refsManual fixes for things the AST rewriter can't catch

Move areas

Top-level modules → proper homes

CurrentNewNotes
run_agent.pyhermes_agent/agent/loop.py12k-line god file, move as-is
cli.pyhermes_agent/cli/repl.py11k-line REPL, move as-is
model_tools.pyhermes_agent/tools/dispatch.pyTool discovery + dispatch
toolsets.pyhermes_agent/tools/toolsets.pyNamed tool bundles
toolset_distributions.pyhermes_agent/tools/distributions.pyDatagen distributions
mcp_serve.pyhermes_agent/tools/mcp/serve.pyMCP server
utils.pyhermes_agent/utils.pyPackage root
hermes_constants.pyhermes_agent/constants.pyDrop prefix
hermes_state.pyhermes_agent/state.pyDrop prefix
hermes_logging.pyhermes_agent/logging.pyDrop prefix
hermes_time.pyhermes_agent/time.pyDrop prefix

agent/ → hermes_agent/agent/ + hermes_agent/providers/

  • ~48 files
  • Core agent files stay in agent/
  • Transports, adapters, credentials, pricing, rate limiting → providers/
  • Context engine, compressor, references → agent/context/
  • Memory manager, provider → agent/memory/
  • Image gen provider, registry → agent/image_gen/

tools/ → hermes_agent/tools/ + hermes_agent/backends/

  • ~77 files
  • tools/environments/ → hermes_agent/backends/ (promoted — independent axis)
  • Browser tools → tools/browser/
  • MCP tools → tools/mcp/
  • Skills tools → tools/skills/
  • Media tools → tools/media/
  • File tools → tools/files/
  • Security tools → tools/security/
  • Remaining flat tools keep tools/ prefix, drop _tool suffix

hermes_cli/ + cli.py → hermes_agent/cli/

  • ~51 files
  • Auth modules → cli/auth/
  • Model modules → cli/models/
  • UI modules (banner, colors, output, skin, curses, tips, status, completion) → cli/ui/
  • hermes_cli/setup.py → cli/setup_wizard.py (avoid setuptools confusion)

Other packages

CurrentNew
gateway/*hermes_agent/gateway/*
acp_adapter/*hermes_agent/acp/*
cron/*hermes_agent/cron/*

External consumers (import rewrites only, no moves)

  • tests/**/*.py
  • plugins/**/*.py
  • scripts/*.py
  • tui_gateway/*.py
  • environments/*.py (RL envs)

Infrastructure updates

  • pyproject.toml — entry points, packages.find, package-data
  • Dockerfile — COPY paths, CMD/ENTRYPOINT
  • docker/entrypoint.sh — Python invocations
  • flake.nix — source path
  • nix/packages.nix, nix/python.nix, nix/nixosModules.nix
  • .github/workflows/*.yml — test/lint paths
  • MANIFEST.in — include patterns
  • AGENTS.md / CLAUDE.md — path references

Things to discover along the way

This list will grow as we hit unknown unknowns:

  • Circular import issues when reorganizing
  • String-based dynamic imports (importlib.import_module("tools." + name))
  • Config files with module path strings (YAML, TOML, JSON)
  • Plugin system assumptions about import paths
  • sys.modules manipulation
  • Relative imports that need converting
  • Test fixtures or conftest files with path assumptions
  • Entry points in packaging (Homebrew, Nix) beyond pyproject.toml

Verification

python -c "import hermes_agent"
rg "^from (agent|tools|hermes_cli|gateway|cron|acp_adapter|run_agent|model_tools|toolsets|toolset_distributions|mcp_serve|hermes_constants|hermes_state|hermes_logging|hermes_time)[\. ]" hermes_agent/ tests/
pytest
hermes --help
hermes-agent --help

After this PR stabilizes

  • Extract the final move map → write scripts/migrate_imports.py
  • Land migration script as a separate PR before this one merges
  • Notify contributors with open PRs

extent analysis

TL;DR

The most likely fix involves a multi-step process of refactoring the codebase by moving files into the hermes_agent/ package, rewriting imports, and updating infrastructure configurations.

Guidance

  1. Move files: Execute git mv commands to relocate files to their new destinations as outlined in the "Move areas" section, ensuring that Git recognizes the file movements for clean blame tracking.
  2. Rewrite imports: Apply the move map across all files to update import statements, focusing on changing import lines without altering logic, and handle dynamic imports that the AST rewriter cannot catch.
  3. Update infrastructure: Modify pyproject.toml, Dockerfile, nix files, and CI configurations to point to the new file locations, ensuring the build system and dependencies are correctly updated.
  4. Verify changes: Run the provided verification commands, including python -c "import hermes_agent", rg for import checks, pytest, and hermes --help to ensure the refactored codebase works as expected.

Example

No specific code snippet is provided due to the nature of the issue focusing on structural changes rather than specific code fixes.

Notes

The process involves significant changes to the codebase structure and import mechanisms. It's crucial to methodically follow the outlined steps and verify each change to avoid introducing errors or breaking existing functionality.

Recommendation

Apply the workaround by following the detailed step-by-step guide provided in the issue description, as it outlines a comprehensive approach to refactoring the codebase and updating dependencies. This approach ensures that all necessary changes are considered and applied systematically.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#LLM response#prompt template#agent execution#callback error#memory management

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING