Skip to content

perf(termux): fast-path cli version startup#30521

Closed
adybag14-cyber wants to merge 2 commits into
NousResearch:mainfrom
adybag14-cyber:perf/termux-cold-start
Closed

perf(termux): fast-path cli version startup#30521
adybag14-cyber wants to merge 2 commits into
NousResearch:mainfrom
adybag14-cyber:perf/termux-cold-start

Conversation

@adybag14-cyber

@adybag14-cyber adybag14-cyber commented May 22, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

This PR speeds up Termux non-TUI CLI startup in two places:

  • hermes --version, hermes -V, and hermes version now use a pre-import
    Termux fast path.
  • Bare interactive hermes now reaches the classic non-TUI prompt first, then
    defers agent-only discovery until the first submitted turn.

The bare hermes path is the real end-to-end prompt startup path, not a
version-check proxy. It still launches the Python console entry point, imports
the CLI, renders the compact startup UI, initializes prompt-toolkit, and waits
for the input prompt marker.

Why this approach:

  • Version output does not need config, logging, argparse, or package metadata.
  • Bare interactive startup should not discover plugins/MCP tools, build full
    tool counts, scan skill commands, initialize tool callbacks, or check terminal
    command security before the user has typed anything.
  • The heavy agent/tool imports are still loaded before the first agent turn, so
    the first submitted message keeps the same agent behavior.
  • The fast paths are Termux-gated and can still be disabled with
    HERMES_TERMUX_DISABLE_FAST_CLI=1.

Related Issue

Issue filed on discord by @likiuslnik https://discord.com/channels/1053877538025386074/1507281286073417798

Related PRs found during duplicate check:

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Security fix
  • Documentation update
  • Tests (adding or improving test coverage)
  • Refactor (no behavior change)
  • New skill (bundled or hub)

Changes Made

  • hermes_cli/main.py
    • Adds the pre-import Termux version fast path.
    • Makes bare Termux hermes use compact startup UI.
    • Defers agent startup discovery for bare interactive prompt startup.
    • Preserves eager startup discovery for one-shot and chat -q paths.
  • cli.py
    • Defers plugin/MCP/shell-hook startup until the first agent initialization
      when HERMES_DEFER_AGENT_STARTUP=1.
    • Avoids full tool discovery for the compact Termux startup status line.
    • Avoids git banner state lookup on the fast bare startup path.
    • Lazily imports heavy agent/tool/skill/cron/pricing/table modules.
    • Defers tool callbacks and tirith availability checks until tools can run.
  • tests/hermes_cli/test_tui_resume_flow.py
    • Adds coverage for the ultra-fast version path.
    • Adds coverage that bare Termux hermes defers agent startup and enables
      compact fast startup.

How to Test

  1. Run syntax, lint, whitespace, and compatibility checks:

    /data/data/com.termux/files/home/.hermes/hermes-agent/.venv/bin/python -m py_compile hermes_cli/main.py cli.py tests/hermes_cli/test_tui_resume_flow.py
    /data/data/com.termux/files/home/.hermes/hermes-agent/.venv/bin/ruff check hermes_cli/main.py cli.py tests/hermes_cli/test_tui_resume_flow.py
    git diff --check
    /data/data/com.termux/files/home/.hermes/hermes-agent/.venv/bin/python scripts/check-windows-footguns.py hermes_cli/main.py cli.py tests/hermes_cli/test_tui_resume_flow.py
  2. Run focused tests:

    env -i PATH="$PATH" HOME="$HOME" TZ=UTC LANG=C.UTF-8 LC_ALL=C.UTF-8 PYTHONHASHSEED=0 \
      /data/data/com.termux/files/home/.hermes/hermes-agent/.venv/bin/python \
      scripts/run_tests_parallel.py \
      tests/hermes_cli/test_tui_resume_flow.py \
      tests/hermes_cli/test_startup_plugin_gating.py \
      tests/hermes_cli/test_codex_models.py \
      -- -o addopts=''
  3. Measure full bare hermes prompt readiness with a PTY and CPU pinning:

    • Launch /data/data/com.termux/files/home/.hermes/hermes-agent/.venv/bin/hermes
      with PYTHONPATH pointing at this branch.
    • Pin with taskset -c <cpu>.
    • Stop the timer when both Welcome to Hermes Agent and the prompt marker
      � have appeared.

Results

Test platform:

  • RedMagic 10 Pro / NX789J
  • Android / Termux
  • Linux 6.6.92-android15-8-g3637f4904cf5-ab13944661-4k
  • Python 3.11.10
  • Hermes Agent 0.14.0
  • Ruff 0.15.10

Validation:

  • py_compile passed for changed Python files.
  • ruff check hermes_cli/main.py cli.py tests/hermes_cli/test_tui_resume_flow.py
    passed.
  • git diff --check passed.
  • python scripts/check-windows-footguns.py hermes_cli/main.py cli.py tests/hermes_cli/test_tui_resume_flow.py
    passed.
  • Focused tests passed: 97 passed, 0 failed.

Performance:

  • Initial full bare hermes PTY startup-to-prompt measurement was about
    5.079s on cpu4.
  • Warm full bare hermes baseline before this second pass was about 2.90s
    on cpu4.
  • After this change, full bare hermes prompt readiness on the slowest measured
    core in this run:
    • cpu0 final avg 0.814466s
    • min 0.805957s
    • max 0.827856s
    • 10 runs: 0.809 0.816 0.819 0.806 0.815 0.814 0.809 0.828 0.814 0.813
  • All-core bare prompt sweep after validation:
    • cpu0: avg 0.825642s, max 0.878412s
    • cpu1: avg 0.808882s, max 0.812983s
    • cpu2: avg 0.811985s, max 0.818701s
    • cpu3: avg 0.813983s, max 0.818755s
    • cpu4: avg 0.806089s, max 0.818785s
    • cpu5: avg 0.809485s, max 0.817154s
    • cpu6: avg 0.584450s, max 0.590861s
    • cpu7: avg 0.580315s, max 0.580855s
  • Existing version fast path remains under the 0.05s target on efficiency
    cores from the earlier validation: worst-core cpu4 avg 0.037920s, max
    0.041s.

Checklist

Code

  • I've read the Contributing Guide.
  • My commit messages follow Conventional Commits.
  • I searched for existing PRs to make sure this is not a duplicate.
  • My PR contains only changes related to this fix.
  • I've run pytest tests/ -q and all tests pass.
  • I've added tests for my changes.
  • I've tested on my platform: Android / Termux on RedMagic 10 Pro.

Documentation & Housekeeping

  • Documentation update: N/A, startup behavior is implementation-only.
  • cli-config.yaml.example update: N/A, no config keys added.
  • CONTRIBUTING.md / AGENTS.md update: N/A, no workflow policy changed.
  • Cross-platform impact considered: new prompt fast path is Termux-gated;
    regular desktop startup remains unchanged.
  • Tool descriptions/schemas update: N/A, no tool behavior changed.

For New Skills

N/A.

Screenshots / Logs

Focused test output:

=== Summary: 3 files, 97 tests passed, 0 failed (100% complete) in 1.1s (16 workers) ===

Worst-core bare prompt timing:

cpu0 final avg=0.814466 min=0.805957 max=0.827856 times=0.809 0.816 0.819 0.806 0.815 0.814 0.809 0.828 0.814 0.813

@alt-glitch alt-glitch added type/perf Performance improvement or optimization P3 Low — cosmetic, nice to have comp/cli CLI entry point, hermes_cli/, setup wizard labels May 22, 2026
@teknium1

Copy link
Copy Markdown
Contributor

Salvaged onto current main via #30609 (rebase-merge → a3beee4 + 6c3fd97 — your authorship preserved on both commits). Termux non-TUI cold start now under 1s for bare hermes and ultrafast --version lands pre-import. Thanks for the careful PR description and the per-core timing data.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/cli CLI entry point, hermes_cli/, setup wizard P3 Low — cosmetic, nice to have type/perf Performance improvement or optimization

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants