toolrush README

The project's README from github.com/OnlyTerp/toolrush. As one markdown file: README.md.

ToolRush — kill the tool-call tax

shipped and live v2.0 206 tests passed Windows / MSYS

Modern agent models stream tokens faster than their harness can read a file. The bottleneck stopped being tokens/sec — it became the tool-call tax: every read_file, search_files, and terminal call paying process spawns, shell round-trips, wrapper layers, and full re-dispatch for work that costs microseconds.

ToolRush kills the tax. It is a low-overhead execution layer for Hermes Agent: same tools, same output envelopes, same safety gates — radically cheaper transport, plus real batched parallelism and survival across harness updates.

Benchmark bars: stock shell path vs ToolRush v2 on the real installed harness

Results (measured on the real installed harness — no mocks, no fixtures)

Lane Before After Win
Native file reads 255.23 ms 4.44 ms 57.5x
Warm terminal (persistent shell) 285 ms 12.1 ms 23.6x
Search transport (direct rg) 183–455 ms 27–97 ms 4.7–6.8x
Batched parallel RPC 108 ms seq 53 ms batched 2.1x (3.3x controlled overlap)

These are tool-operation wall times, not model-inclusive turn speed — the honest framing: tool-heavy turns get dramatically faster, chat-heavy turns barely move. Full samples, p95s, methodology, and one disclosed regression (trivial native reads don't benefit from threading) in v2/README.md.

Architecture

Five lanes: native read, direct rg transport, warm terminal, batched parallel RPC, update survival

  1. One search engine, accelerated transport. No second, less-correct reimplementation. Direct rg.exe execution preserves real ignore files, regex grammar, context flags, and configuration; native Windows reads reuse the upstream bounded reader, access guards, binary/document routing, and output assembler.
  2. Correctness before speed. Fixed JSON-breaking trailing text in search results; pagination now has stable content order and a more-results sentinel; regex backslashes and leading hyphens stay literal; CRLF and unterminated final lines handled consistently.
  3. Real programmatic parallelism. from hermes_tools import parallel — a batch of 1–16 read operations runs on up to 4 workers through one RPC, returns input order, and keeps authentication, tool allowlists, call budgets, and cell retirement fully enforced. Whole invalid batches are rejected before dispatch. No writes, no terminal.
  4. Correct warm-shell transport. One persistent bash, streaming through an OS pipe with bounded parser memory, a filtered atomic snapshot commit, preserved exit status/cwd/exports, and command-tree kill on cancellation. Never retries a submitted command.
  5. Hardened scheduler admission. Fail-closed classifier refuses hidden writes (wget, curl -o, sed w, branch creation, env-wrapped scripts, shared cwd mutations). Admission is not approval: anything refused still runs — just sequentially, the regular way.
  6. Update survival. Hash-verified helper sources and 25 function-scoped compatibility patches live outside the upstream checkout; after a harness update the plugin restores them in memory, preserving imported references. Unknown upstream drift degrades loudly instead of overwriting new code.
  7. Diagnostics and rollback. doctor.py --smoke, per-lane kill-switches (TOOLRUSH_*=0), a master toolrush.enabled: false, source preimages, payload hashes, and a documented runbook.

Verification

206 passed 5 negative controls live activation verified

Repo layout

Path What
v2/ The shipped implementation — full report, intent recovery, design, MANIFEST (sha256), plugin, installed-source snapshot, evidence
toolrush.py v1 lab runtime (fast_read / batch_read, persistent pool, session cache)
toolrush_search.py · toolrush_exec.py wave-3 in-process search · wave-2 persistent-shell executor
bench_*.py, dissect_*.py the profiling and benchmarking that named the tax
validation-contract*.md VAL- contracts, one per wave (contract-first)
results.md, *.json measured evidence — no invented numbers anywhere

The origin story: lab waves

Before v2 shipped into the live tree, the tax was found and killed one wave at a time in this repo. Kept for the receipts:

Wave Target Result
1 read_file dispatch 1460 ms → 1.18 ms (1237x) — root cause: up to 5 shell commands per read (stat + head|base64 + sed|cut + wc -l + tail); the bytes cost 0.25 ms, the wrapping cost 1460 ms
2 terminal spawn tax echo 285 ms → 12.1 ms (23.6x) via one persistent bash; win decomposed by negative control into ~8x wrap-trim + ~3x shell persistence
3 content search 900 ms → 42 ms (21.3x) in-process walk + memoized real-guard verdicts; match sets identical 40/40
4 dispatch pipeline measured, then STOP — registry 0.005 ms, full path 4.44 ms; the remaining "tax" is load-bearing safety rails. No theater.

Wave 4's verdict is the project's favorite line: know when to stop. v2 then rebuilt the lab wins as production code — one engine, correct semantics, hardened admission, update survival — because a 21x search that drops .gitignore semantics is a bug with a speedup.

Laws


Built for Hermes Agent by Nous Research · shipped and running live since 2026-09-05.

toolrush (OnlyTerp/toolrush)

Searching Database…

Что это?ToolRush — плагин слоя исполнения с минимальными накладными расходами для Hermes Agent (агентной оболочки от Nous Research): он убирает задержки вызовов инструментов вроде чтения файлов, поиска и терминальных команд, сохраняя те же инструменты, результаты и защитные проверки.
Это самостоятельный инструмент или плагин к чему-то другому?Это плагин, который устанавливается в уже развёрнутую оболочку Hermes Agent и ускоряет её транспортный слой; он нарочно не переизобретает поисковый движок или читалку файлов, а ускоряет настоящие.
Как после установки проверить, что всё работает?После установки плагина в оболочку запустите doctor.py --smoke для диагностики; любое ускоренное направление можно отключить по отдельности аварийным переключателем TOOLRUSH=0 или общим флагом toolrush.enabled.
Сначала нужно установить Hermes Agent?Да: ToolRush — плагин и работает только внутри установленной оболочки Hermes Agent; его быстрый поисковый канал напрямую запускает rg.exe (ripgrep на Windows), а чтение файлов выполняет штатным ридером оболочки для Windows.
Он ускоряет любой ход агента?Нет — ускоряется реальное время операций с инструментами, а не весь ход модели: ходы, где много вызовов инструментов, становятся заметно быстрее, а чисто диалоговые ходы почти не меняются; тривиальные одиночные чтения также не выигрывают от многопоточности, которая используется для пакетных чтений.
Для кого это сделано?Он создан специально для пользователей и операторов Hermes Agent — оболочки от Nous Research, — а не как универсальный ускоритель вызовов инструментов.
Насколько ToolRush ускоряет нативное чтение файлов?Нативное чтение файлов сокращается с 255.23 мс до 4.44 мс — измеренное ускорение в 57.5 раза; замер делался на реально установленной оболочке, без заглушек и подставных данных.
Что будет, если команду пометят как небезопасную для ускорения?Классификатор допуска в ToolRush устроен так, что при сомнениях запрещает ускорение: он отказывается ускорять операции со скрытой записью вроде wget, curl -o или создания веток, но такие вызовы всё равно выполняются — обычным, более медленным последовательным путём, а не блокируются.
Как ToolRush продолжает работать после обновлений Hermes Agent?Он хранит сверенные по хэшам исходники хелперов и 25 точечных патчей совместимости вне апстрим-чекинта, после обновления восстанавливает их в памяти, а если апстрим-код неожиданно разошёлся — громко сообщает об этом, а не ломается молча.
Что делает функция параллельного пакетного чтения?Через hermestools.parallel от 1 до 16 операций чтения выполняются максимум на 4 воркерах в одном RPC-вызове; результаты возвращаются в порядке входных данных, при этом действуют аутентификация, белые списки и лимиты вызовов; невалидные пакеты целиком отклоняются ещё до отправки.
Creator
OnlyTerp
Size
0.6 MB
Stars
157
Updated
CommitSep 05
Age
1mo
Commits · 90 Days