Inferoa: an agent harness that treats every loop turn as an inference workload
Inference-native Tokenmaxxing Agent Harness for Loop Engineering
At a glance
- What is it?
- Inferoa is a TypeScript CLI and TUI that runs recursive agent loops while keeping prefix caches, context size and model routing in view. It is aimed at teams already running vLLM or willing to, and its npm dev tag means you adopt a moving target.
- Who is it for?
- Adopt Inferoa if you already operate vLLM or vLLM Omni and want the agent loop to reason about cache reuse, context pressure and routing rather than treat the model as a black box. Do not adopt it if you need a frozen dependency in a regulated build, since the documented install path is the @dev dist-tag, or if you have no intent to run any self-hosted inference path.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 89 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The workload Inferoa is built around
Most agent tooling treats a long session as a sequence of prompts. Inferoa treats it as an inference workload with a cost curve. The README's framing is explicit: as turns accumulate, prompt prefixes drift, cache reuse collapses, stale evidence fills context, model routing gets harder, and serving choices start to matter. Each of those is a serving-side failure, not a prompting failure, and the project positions itself as the layer that keeps them visible while a loop runs.
The target user is therefore narrower than "anyone building agents". It is someone who runs or plans to run vLLM, who cares about prefix-cache hit rates, and who has a loop that runs long enough for drift to matter. If your agent makes three model calls and stops, the machinery described here has nothing to bite on.
Loop engineering, as the project defines it
The README draws a line between prompting and what it calls Loop Engineering: give the model an objective, feedback, verification, memory, and tools, then let it self-correct until the work is proven. Inferoa's `/loop` command is the concrete form of that. According to the README, `/loop` carries an objective across loop tasks, verification, decisions, recovery, and completion evidence instead of stopping after the next answer.
That vocabulary (loop tasks, attempts, verification evidence, decisions) implies a persistent state machine rather than a chat transcript. The README also lists independent feedback surfaces: plans, tests, tool results, research metrics, and completion evidence. The claim is that the loop has something concrete to improve against, rather than grading its own prose. Whether the verification is enforced or advisory is not stated in the material available, and that distinction matters more than any of the surrounding description.
How tokenmaxxing and prefix-cache discipline fit together
The tokenmaxxing stack table is the clearest architectural statement in the README. It maps four surfaces to substrates: Loop Engineering on Loop Mode, the Agent Harness on Inferoa itself, Context Optimization on CodeGraph and RTK, and Intelligent routing on vLLM Semantic Router, with Model Serving on vLLM Engine and vLLM Omni. Inferoa is the harness in the middle, and the two things it claims to do there are give the loop a durable runtime and preserve reusable prompt prefixes.
The mechanism named for the second claim is prefix-cache discipline: prompt epochs, deterministic tool schemas, and bounded system sections. Read together, those are three constraints on what the harness is allowed to change between turns. Tool schemas stay byte-identical so the serialized prefix does not shift. System sections have a size ceiling. Prompt epochs mark points where the prefix legitimately changes. Context control is the other half: compression, summaries, graph-shaped repo context, bounded history, and bounded tool output. The stated goal is to keep useful evidence in the window without letting stale state take over, which is a bounded-context argument rather than a summarization-quality argument.
The routing layer sits above this. The README says model paths can respond to cost, safety, privacy, capability, session pressure, multimodal needs, and whether a self-hosted vLLM path is enough. Note the last clause: the default question is not which frontier model to call, but whether you need to call one at all.
Getting it running
Installation is a single global npm install, and the README is direct about which tag to use:
npm install -g inferoa@dev
The `@dev` dist-tag tracks the latest build published from `main`, and the README states that the npm `latest` tag is reserved for stable releases. That is a deliberate choice to ship from the mainline, and it has consequences for anyone pinning dependencies. If you need a frozen artifact, `@dev` is not it.
Setup is two commands:
inferoa setup inferoa
The README says `inferoa setup` walks through endpoint, model, vault-backed API key, and Omni configuration. `inferoa` opens the TUI. A prompt passed as an argument starts a session and submits it as the first user turn, for example:
inferoa "Inspect this repository and list the test entrypoints."
For scripted use there is a non-interactive mode:
inferoa --print "Summarize the README in one paragraph."
Inside the TUI, `/loop` starts the recursive loop, `/plan` turns ambiguous scope into an inspectable plan before execution, and `/tokenmaxxing` shows token and cost pressure across prefix-cache reuse, context savings, recent turn usage, and model-selection pressure. The README points to separate reference pages for the CLI, slash commands, and configuration; the config keys themselves are not reproduced in the README, so the docs site is the place to look for exact names.
Where the design puts pressure on you
The dependency on vLLM is the largest constraint and the README does not soften it. The tokenmaxxing stack is built on the vLLM ecosystem, and the serving row names vLLM Engine and vLLM Omni specifically. Prefix-cache discipline only pays off when the serving layer actually reuses prefixes. If you point Inferoa at a hosted API that does not expose or honour that behaviour, the harness is still doing bookkeeping, but the savings it is organised around do not materialise.
There is a second, subtler cost. Deterministic tool schemas and bounded system sections are restrictions on the agent's own prompt, and restrictions on a prompt are restrictions on what the model can be told. A harness that refuses to let the system section grow is trading expressiveness for cache stability. That is a defensible trade for a long loop and a poor one for a one-shot task with heavy instructions.
Finally, the release cadence is aggressive. Three releases are listed between 2026-06-16 and 2026-06-18, and the install path tracks `main`. Fast iteration on an agent harness means the slash-command surface and config keys can move under you between upgrades. Nothing in the supplied material documents a compatibility policy or a deprecation window, so treat the docs site as version-specific and re-read it after upgrading.
Alternatives and the actual difference
The most direct comparison in the README's own stack is CodeGraph, published as @colbymchenry/codegraph, and RTK, which Inferoa lists under Context Optimization. Those projects attack the same token problem from the context side: select and shrink what goes into the window. Inferoa sits above them and adds two things they do not claim: a durable loop runtime with verification and recovery, and a serving-awareness layer that reasons about prefix reuse and routing. If your problem is purely "the repo context is too large", a context-selection tool addresses it without the harness. If your problem is "the loop drifts and the bill climbs across forty turns", context selection alone does not answer it, because the cost is in the repeated prefix, not only in the retrieved content.
On the routing side, vLLM Semantic Router is named as the substrate for choosing model paths by cost, safety, privacy, capability, and session pressure. Inferoa consumes it rather than replacing it. The distinction is worth holding onto: Semantic Router decides where a request goes, Inferoa decides what the request looks like and whether the loop should continue at all. A team that only wants routing can adopt the router and skip the harness. A team that wants routing to respond to loop state needs something holding that state, which is the gap Inferoa claims to fill.
Licence and maintenance expectations
The repository is Apache-2.0. That permits commercial use and modification and includes an explicit patent grant, which is the usual reason teams prefer it over MIT for infrastructure dependencies. It also carries notice and attribution obligations for redistributed modified copies, and the licence text is the authority, not this summary; if you are vendoring or forking, have counsel read it rather than a review.
The maintenance picture from the supplied material is activity without a stability promise. Releases land frequently, the last push is recent, and the repository is not archived. What is absent is any stated support window, LTS branch, or migration guide. The practical upgrade cost is therefore re-reading the CLI, slash-command, and configuration reference pages after each bump, and testing `/loop` behaviour against your own tasks, since loop semantics are exactly the surface most likely to shift between minor versions. Budget for that as recurring work, not a one-time integration.
Editorial conclusion
Adopt Inferoa if you already operate vLLM or vLLM Omni and want the agent loop to reason about cache reuse, context pressure and routing rather than treat the model as a black box. Do not adopt it if you need a frozen dependency in a regulated build, since the documented install path is the @dev dist-tag, or if you have no intent to run any self-hosted inference path. Before committing, verify three things against the docs site: what inferoa setup actually persists for your endpoint and vault-backed key, whether your serving stack supports the prefix-cache behaviour /tokenmaxxing reports on, and whether the loop and slash-command surface in your installed version matches the reference pages. The repository is the only source of truth for behaviour here; nothing in this review was executed.
Community notes