If your LLM agent is hallucinating because it never saw half your codebase, stop blaming the model. The culprit is likely your token counting logic. A new open-source tool called Roomy, released on November 3, 2026, argues that the ubiquitous '4 characters per token' rule of thumb undercounts real code by 27% on average. This isn't a minor rounding error; it's a silent failure mode where agents drop critical context without warning.

The Silent Truncation Problem

Most developer tools handle over-budget prompts by either truncating the tail of the input or stopping file inclusion abruptly. Both methods leave you with an agent that answered from a prompt you never actually saw. Roomy takes a different approach: it packs files under an explicit budget and returns a transparent log for every candidate file, stating either the reason it was included or the specific reason it was excluded. This transparency forces developers to acknowledge what is missing from the context window.

Why Code Breaks the 4-Char Rule

The 4-chars-per-token heuristic is an average derived from English prose. Code is structurally different, with identifiers splitting into multiple tokens and punctuation consuming its own space. In a measurement of a real repository containing 206,658 characters, the standard rule estimated 51,664 tokens, while Roomy's more aggressive estimate hit 65,859 tokens. That 27% gap means relying on the old rule causes overflow errors that manifest as truncated replies rather than clean exceptions. Roomy deliberately biases its estimate toward over-counting to prevent these silent overflows.

Budgets, Reserves, and Hard Limits

Roomy enforces two critical constraints that many libraries ignore: the output reserve and the required-item exception. The tool requires a --reserve flag to ensure space is left for the model's response, preventing a scenario where a 'fitting' prompt leaves no room for the answer. Furthermore, if a file marked as required does not fit within the remaining budget, Roomy raises a WontFit exception instead of silently dropping it. This ensures that a confident, wrong answer from a truncated prompt is replaced by a crash that developers can actually debug.

Heuristics Over Perfection

Optimal packing is a knapsack problem, but Roomy uses a greedy heuristic sorting by priority, then size, then name. The author acknowledges this isn't optimal, measuring a 90.7% efficiency rate against an exhaustive search at a 3,000-token budget. However, the trade-off is intentional: a reproducible, explainable packing strategy is more valuable for human-in-the-loop debugging than squeezing out the last few percent of context. The tool ships without a vendored tokenizer to avoid tying the logic to a single model family, and it includes a JavaScript port verified against the Python implementation to ensure cross-language consistency.

Key Takeaways

  • The 4-char-per-token rule undercounts code tokens by ~27%, leading to silent truncation.
  • Roomy provides explicit inclusion/exclusion logs for every file in the prompt budget.
  • Silent truncation is replaced by hard exceptions for required items that don't fit.
  • A reserve flag is mandatory to ensure space for model output, not just input.

The Bottom Line

Roomy is a necessary corrective for agent developers who are tired of debugging hallucinations caused by invisible context loss. By prioritizing transparency and hard failures over silent optimization, it treats token budgeting as a serious engineering constraint rather than a background calculation.