Cost Reasoning

This skill brings cost and token awareness to agentic coding sessions. Claude Code does not expose token counts or cost metrics to plugins directly, so this skill works through estimation heuristics, behavioral nudges, and reference data.

The Constraint

Claude Code does not provide:

• A token counter accessible to plugins
• Per-tool-call token breakdowns
• Session cost totals
• Model tier information for the current session

This means the plugin cannot measure actual usage. Instead, it provides the tools to reason about cost before, during, and after work.

What This Plugin Can Do

1. Estimation

Before starting a task, estimate its token cost using heuristics from references/task_cost_heuristics.md. Given a task description and an understanding of the codebase, estimate the number of file reads, tool calls, and output tokens required, then calculate a cost range for each model tier using references/pricing_table.md.

2. Model Selection

Given a task description, recommend the right model tier (Opus, Sonnet, or Haiku) based on task complexity, reasoning requirements, and cost tradeoffs. Use the decision tree and capability matrix from references/model_capabilities.md.

3. Efficiency Nudges

The PreToolUse hook on Read provides a soft reminder to use offset and limit parameters instead of reading entire files. The efficiency patterns in references/efficiency_patterns.md document 8 token-saving techniques for Claude Code tool usage.

4. Post-Session Auditing

The PreCompact hook fires before context compression and prompts a brief audit of token efficiency in the session. It writes findings to .claude/token-efficiency.md as a persistent reference. The /cost-audit command provides on-demand auditing without waiting for compression.

Reference Files

Load these from ${CLAUDE_PLUGIN_ROOT}/skills/cost-reasoning/references/:

File	Purpose
pricing_table.md	Current model pricing per million tokens
model_capabilities.md	What each model tier is good and bad at, with decision tree
task_cost_heuristics.md	Token estimates by task type with cost formulas
efficiency_patterns.md	8 token-saving patterns for Claude Code tool usage

Usage Flow

For Cost Estimation (/cost-estimate)

1. Read task_cost_heuristics.md to map task type to token ranges
2. Read pricing_table.md for current model pricing
3. Assess the task: number of files, complexity, expected tool calls
4. Calculate cost range (low/medium/high) for each model tier
5. Present comparison table and recommend a model

For Model Selection (/model-pick)

1. Read model_capabilities.md for the decision tree
2. Assess task complexity: file count, reasoning depth, architectural scope
3. Walk the decision tree to a recommendation
4. Show cost comparison using pricing_table.md

For Cost Auditing (/cost-audit)

1. Check for .claude/token-efficiency.md (written by PreCompact hook)
2. Review conversation patterns for inefficiencies
3. Identify: unnecessary full-file reads, repeated reads, massive Bash output, unproductive tool calls
4. Estimate tokens wasted and suggest improvements

Important Notes

• All cost estimates are approximations. Actual token counts depend on tokenizer behavior, system prompts, and conversation history.
• Pricing changes over time. The pricing_table.md includes a "last updated" date. Verify against Anthropic's official pricing page for critical decisions.
• The efficiency nudges are soft reminders, not blocks. They should never prevent a user from completing their work.