Overview

Restructure the hermes-agent codebase from a flat collection of top-level modules and independent packages into a single hermes_agent/ package with clear subpackages, dependency direction, and import hygiene.

No logic changes. No API changes. No behavior changes. The same code runs the same way — it just lives at better addresses.

Approach: Top-down layered. Move packages with the fewest inbound dependencies first, working inward toward the core. Each PR moves one layer, leaves the codebase fully working. No shims, no migration scripts, no deferred breakage.

Manifest: hermes_restructure_manifest_v3.md (in repo root, untracked)

Why now

Problem 1: There's no package. The pyproject.toml tells the story — 11 loose py-modules at the root, 8 independent packages discovered via packages.find, and entry points pointing at three different top-level locations. There is no hermes_agent you can import.

Problem 2: Related code is scattered. Model adapters live in agent/, transports live in agent/transports/, execution backends are nested under tools/environments/. The CLI is split between an 11k-line cli.py and a 51-file hermes_cli/ package.

Problem 3: The cost of waiting compounds. Every PR merged against the current structure deepens existing patterns. Before v1 is the natural moment.

Target structure

hermes_agent/
├── constants.py, state.py, logging.py, time.py, utils.py   # leaf modules
├── agent/          # core agent loop, prompt builder, context, memory
├── providers/      # transport + adapter per provider, credentials, pricing
├── backends/       # execution environments (local, docker, ssh, modal, ...)
├── tools/          # tool registry, dispatch, all tool implementations
│   ├── browser/, mcp/, skills/, media/, files/, security/
├── cli/            # CLI entry point, REPL, commands, auth, models, UI
│   ├── auth/, models/, ui/
├── gateway/        # gateway runner, session dispatch, platforms
├── acp/            # ACP adapter
├── cron/           # cron scheduler
└── plugins/        # bundled plugins (memory, context_engine)

Dependency DAG (post-restructure)

hermes_agent.cli
    ↓
hermes_agent.agent  ←  hermes_agent.gateway  ←  hermes_agent.acp
    ↓        ↘
hermes_agent.providers    hermes_agent.tools
                              ↓
                         hermes_agent.backends

hermes_agent.constants, .state, .logging, .time  ←  imported by everything

PR Tracker

Dependency graph

PR1 (#14586) → PR2 (#14587) → PR3 (#14588) → PR4 (#14589) → PR5 (#14590) → PR6 (#14591)
(strictly sequential — each PR rewrites imports that depend on prior moves)

Abort points

Each PR delivers standalone value. Safe stopping points:

• After PR 1 — hermes_agent/ package exists, canary PR proves the workflow
• After PR 3 — all "peripheral" packages moved (acp, cron, gateway)
• After PR 6 — single package, clean imports, full restructure complete

What each PR does NOT do

Every PR is purely mechanical. Across all PRs:

• No logic changes — code behavior is identical before and after
• No layer inversion fixes — agent/ importing from cli/ is moved as-is
• No API changes — CLI commands, entry points, config format unchanged
• No migration script — top-down approach means each PR is atomic

Commit strategy (same for all PRs)

Verification checklist (run after every PR)

python -c "import hermes_agent"
rg "^from <old_package>[\. ]" --type py     # adjust pattern per PR
rg "(import_module|__import__|importlib)\(.*['\"]" --type py
pytest
hermes --help && hermes-agent --help

Key decisions

Learnings from V1 prototype

The monolithic approach (branch sid/foundational-restructure, draft PR #14498) validated the mechanics:

1. Tests are ~75% of the diff (each test averages ~15 rewrite sites)
2. git mv in a separate commit gets 100% similarity — clean blame
3. Non-.py files (scripts/hermes-gateway, install.ps1) get missed by **/*.py globs
4. 4 test files write old-style imports as string literals into dynamically-created plugin files
5. Plugin sys.modules surgery needs dedicated verification (string-based paths)
6. _get_bundled_dir() in skills_sync breaks silently after move (wrong Path(__file__) depth)

Superseded

• Draft PR refactor: move all source into hermes_agent/ package (PR 1/3) #14498 (monolithic approach) — closed, replaced by granular PRs
• Sub-issue restructure PR 1: create hermes_agent/ package — move all files, rewrite imports #14183 (monolithic PR 1) — closed, replaced by restructure PR 1: move acp_adapter/ → hermes_agent/acp/ (canary) #14586–restructure PR 6: move agent/ + leaf modules → hermes_agent/agent/ + hermes_agent/providers/ #14591

Reference

• Manifest: hermes_restructure_manifest_v3.md (in repo root)
• V1 prototype reference: docs/restructure-v1-reference/
• Prior art: tracking: provider transport refactor (agent/transports/) #13473 (transport refactor), tracking: provider modules refactor — Cycle 2 of transport/provider infrastructure #14418 (provider modules — same workstream format)

Follow-up issues