Issue Station
Sign In
Tools hereToolbox

hermes - 💡(How to fix) Fix Consider splitting gateway/run.py and run_agent.py into smaller modules

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…

Root Cause

  • Merge conflicts for forks: Anyone maintaining a fork (even with minimal patches) hits conflicts constantly because every upstream feature lands in the same two files. A 9-line patch can break on a 1,500-commit sync because the surrounding context shifted.
  • Code review friction: PRs that touch these files are hard to review because the diff context is ambiguous — the same variable names and patterns repeat across unrelated sections.
  • Onboarding: New contributors have to understand a 17K-line file to make a small change.

Fix Action

Fix / Workaround

  • Merge conflicts for forks: Anyone maintaining a fork (even with minimal patches) hits conflicts constantly because every upstream feature lands in the same two files. A 9-line patch can break on a 1,500-commit sync because the surrounding context shifted.
  • Code review friction: PRs that touch these files are hard to review because the diff context is ambiguous — the same variable names and patterns repeat across unrelated sections.
  • Onboarding: New contributors have to understand a 17K-line file to make a small change.
RAW_BUFFERClick to expand / collapse

The situation

gateway/run.py is 17,128 lines and run_agent.py is 16,452 lines. Together they account for 33,600 lines across two files, with 833 and 934 commits touching them respectively.

Why this matters

  • Merge conflicts for forks: Anyone maintaining a fork (even with minimal patches) hits conflicts constantly because every upstream feature lands in the same two files. A 9-line patch can break on a 1,500-commit sync because the surrounding context shifted.
  • Code review friction: PRs that touch these files are hard to review because the diff context is ambiguous — the same variable names and patterns repeat across unrelated sections.
  • Onboarding: New contributors have to understand a 17K-line file to make a small change.

What's already good

The project has started extracting structure — gateway/hooks.py, plugins/, app/services/ modules, memory provider abstraction. These are great. The core orchestration files just haven't gotten the same treatment yet.

Suggestion

Even a coarse split would help. For example, run_agent.py has distinct sections (init, tool handling, conversation loop, memory sync, provider management) that could become separate modules with the orchestrator importing them. Same for gateway/run.py (adapter management, session handling, message routing, agent lifecycle).

No specific design prescription — just flagging that the current file sizes create real friction for anyone working with the codebase.

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…
#autograd error#model save/load#optimization#mixed precision#training loop

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

hermes - 💡(How to fix) Fix Consider splitting gateway/run.py and run_agent.py into smaller modules