# Token Economy

> Rubric for keeping Claude Code sessions cheap without losing quality — model tiering, cache hygiene, Read discipline, MCP pruning, subagent isolation. Use when cost feels wrong, before setting a budget, or when onboarding a teammate.

- **Type:** Skill
- **Install:** `agentstack add skill-atuljha23-holocron-token-economy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [atuljha23](https://agentstack.voostack.com/s/atuljha23)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [atuljha23](https://github.com/atuljha23)
- **Source:** https://github.com/atuljha23/holocron/tree/main/skills/token-economy
- **Website:** https://atuljha23.github.io/holocron/

## Install

```sh
agentstack add skill-atuljha23-holocron-token-economy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Token economy

Three things drive cost in Claude Code: **context size**, **cache hit rate**, and **model choice**. Most waste comes from one of these being misconfigured and left alone.

## Model tiering — match the model to the task

| Task shape | Right model |
|---|---|
| Format fix, rename, small refactor, comment tweak | **Haiku** — ~15× cheaper than Opus, fast enough to feel instant |
| Routine feature work, bug fix, test writing, reviewing a small diff | **Sonnet** — the default; 5× cheaper than Opus |
| Architectural decision, cross-file refactor, debugging a subtle bug, reviewing a large diff | **Opus** — use when you need the reasoning, not by default |

Claude Code's `/fast` or model selection lets you pick. Don't use Opus by reflex for a typo fix.

## Cache hygiene — the 80% lever nobody talks about

Anthropic caches your prompt prefix for 5 minutes. A stable prefix = the next turn reads from cache at ~10% of input cost. A prefix that changes each turn = full price every time.

**What busts cache:**
- Timestamps in CLAUDE.md, in skill content, or in hook output
- Session IDs / UUIDs interpolated into system prompt
- Rotating "quotes of the day", random greetings
- MCP servers that return time-varying schema metadata

**What preserves cache:**
- CLAUDE.md that doesn't change day-to-day
- Skill/rule content that's additive, not mutating
- Hook `additionalContext` that's deterministic for a given input
- Turning off MCP servers you don't need (every schema change invalidates cache)

**How to check:** `/holocron:cost` — the cache hit rate line. Below 50% is a signal; above 70% is healthy.

## Read discipline — the most common leak

Claude's `Read` tool pulls whole files by default. A 2000-line file is ~8k tokens. Do that 5 times in a session and you've spent ~40k tokens reading the same file repeatedly.

**Pattern:**
1. `Grep` to find the relevant range (cheap — returns only matching lines)
2. `Read` with `offset` + `limit` for the range you identified

Holocron's `read-budget.js` hook nudges this on files > 500 lines, but the discipline has to be yours.

## MCP pruning — one-time setup, ongoing savings

Every MCP server's tool schemas ship to the model on every turn. An unused MCP server costs you tokens forever.

Audit with `/holocron:mcp-audit`. Disable servers you don't actively use. Two or three MCP servers is usually plenty; ten is a tax.

## Subagent isolation — don't pollute the main context

Research / exploration / "find me all the callers" work bloats the main transcript with files and noise you won't need after. Run it in a subagent:

```
Use the Explore agent to find how `authenticateUser` is called across the repo.
```

The subagent's findings come back as a summary; its exploration stays in its own context. Main session stays lean.

## Transcript discipline

Claude Code auto-compacts near the context limit, but compaction is lossy — it summarizes, and summaries forget things. Better:

- `/holocron:handoff` at logical boundaries — write state to a file, start fresh on the next task
- For long-lived work: `/holocron:plan` → plan file → execute → handoff. The plan file acts as durable memory.

## Subtle things

- **Large tool outputs stay in the transcript.** A single 20k-token tool result inflates every subsequent turn's input cost until compaction.
- **`Write` of a large file re-reads context.** Edit prefers over Write for big files.
- **Don't paste log output.** Summarize, grep, or point to a file.
- **Emojis are multi-token.** Harmless unless you're generating content heavy in them.

## Anti-patterns

- Running Opus on every turn "to be safe"
- Full-file Reads on generated/vendored files (`dist/`, `node_modules/`, generated protobufs)
- Keeping MCP servers installed that you tested once and never used again
- Timestamp-injecting SessionStart hooks (looking at you, naive `console.log(new Date())` in a hook that emits `additionalContext`)

## How to know it's working

Run `/holocron:cost` weekly. Healthy numbers:

- Cache hit rate > 60% (70%+ if you're disciplined)
- Median session cost under your per-session budget
- Per-model split skews Sonnet-heavy, with Haiku for small things, Opus for reasoning

If those aren't true, `@cost-analyst` can tell you why.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [atuljha23](https://github.com/atuljha23)
- **Source:** [atuljha23/holocron](https://github.com/atuljha23/holocron)
- **License:** MIT
- **Homepage:** https://atuljha23.github.io/holocron/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-atuljha23-holocron-token-economy
- Seller: https://agentstack.voostack.com/s/atuljha23
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.