Token Utilization and Optimization

[Trinanjan90]

Is there any guidelines/document which can help estimate how many token might get consumed per Agent.
Also is the current version optimized with respect to token usage or is there a plan to release a token Optimized version.

[eugeneboms]

I am not aware of any such documentation. I am thinking we'll need to build it. Here is the proposal: #2343

[WilliamBerryiii]

Thanks for raising this — token usage is something we're actively working on, and it's worth being candid about where things stand.

Where we are today

The honest answer is that the current version is not yet fully token-optimized. There are two distinct cost centers, and we're tackling them differently:

1. Conversation-start (input) tokens — context that loads before you even type a request.
2. In-workflow (output) tokens — what agents generate as they run, especially artifact-heavy planning flows.

Direction: the transition to Skills

The most impactful change underway is the shift from .instructions.md files toward Skills (SKILL.md).

The key difference is when content loads:

• Instruction files with an applyTo glob are eagerly pulled into context at conversation start whenever the pattern matches. The more instruction surface a workspace accumulates, the heavier every conversation gets — whether or not that guidance is relevant to what you're doing.
• Skills are lazily loaded. Only a short description sits in context; the full SKILL.md body is read on demand, and only when the task actually calls for that domain knowledge.

So moving domain content out of always-on instruction files and into on-demand skills directly shrinks the baseline conversation-start cost. This is the single biggest lever we have on input tokens.

Honest assessment of the remaining work

We're partway through this transition, not finished. Today the repo has on the order of ~75 instruction files and ~50 skills, and the two overlap. Fully realizing the savings requires:

• Migrating remaining instruction content into skills where it's domain-specific rather than universally applicable, and tightening applyTo scopes on what stays so files load only when genuinely relevant.
• Auditing shared/overlay instruction files that currently attach broadly, to confirm each one earns its place in every matching conversation.
• Reducing redundancy in artifact generation. The RPI and planner workflows produce a lot of durable tracking artifacts (research, plans, details, changes, review logs). Some of that content is regenerated or restated across artifacts, which inflates output tokens. Consolidating overlapping sections, referencing rather than re-quoting prior artifacts, and skipping artifact scaffolding for simpler tasks are all on the table.

None of this is a single flip-the-switch fix — it's incremental, and each migration needs validation so behavior doesn't regress. But the trajectory is deliberate: less eager context, more lazy loading, and leaner artifacts.

On estimating cost up front

For the specific "how many tokens will this burn before I run it?" question, @eugeneboms captured the shape of the problem well in #2343 — because many flows are interactive and open-ended, precise prediction is effectively unbounded, so any estimate will be a heuristic (target a rough order-of-magnitude / ±2x warning rather than an exact figure). That effort is complementary to the optimization work above: one predicts cost, the other reduces it.

Happy to go deeper on any of these threads if it's useful.