[ClaudeCode] Optimizing Token Consumption Based on Cost-Inducing Factors [Tokens]

This article is a machine translation of the contents of the following URL, which I wrote in Japanese:

【ClaudeCode】コスト発生要因から考えるトークン消費最適化術【トークン】 #AWS - Qiita

はじめに Claude Codeをはじめとする AI コーディングエージェントを使っていると、「トークン消費を減らすには？」というTipsは世の中にたくさん転がっています。「CLAUDE.mdを短くしよう」「/clearしよう」「サブエージェントを使おう」。どれも間違いで...

qiita.com

Introduction

When using AI coding agents such as Claude Code, there are many tips available on "how to reduce token consumption." These include "shorten CLAUDE.md," "use /clear," and "use subagents." While none of these are wrong, simply collecting tips haphazardly can lead to problems such as:

• Implementing them without understanding why they work

• Failing to recognize counterproductive cases (e.g., overuse of subagents)

• Inability to prioritize which tips are relevant to your workload

These are common problems.

Therefore, this article takes an approach that starts with the cause (factors) of token costs and then builds countermeasures. We have investigated the implementations in the official Anthropic documentation and AWS official repositories, organizing the information while verifying the rationale. The content is labeled according to its degree of accuracy.

• Anthropic Official Verified — Content directly documented and quoted in the official Anthropic documentation (code.claude.com/docs).
• AWS Examples — Specific operational standards from the official AWS repository (awslabs/agent-plugins(https://github.com/awslabs/agent-plugins)). Not an official Anthropic specification.

Five Structures that Generate Token Costs

First, an overview. The factors that generate token costs can be broadly classified into five categories based on "when and why they occur."

Category	Timing of Occurrence	Avoidability
A. Structural Cost	Always (Every Turn)	Mitigable through Design (Cannot be Reduced to Zero)
B. Inefficient Behavior	Result of Specific Actions/Instructions	Avoidable (Depending on Prompts and Design Optimization)
C. State Transition Cost	Timing of Specific Operations	Mitigable by Being Mindful of Operations
D. Scaling/Parallelization Cost	When Multiple Instances are Running	Mitigable through Scale Management
E. Background Cost	Always (Including Idle Times)	Almost Unavoidable (Small Impact)

Each category has multiple specific cost factors attached to it. Before going into detailed explanations, let's first summarize all items in a table.

List of Cost Factors

ID	Name	Category	Probability	Summary
A1	Context-Residual Cost	A. Structural Cost	Anthropic	CLAUDE.md, MCP Tool List, and Skill Description are always included in the context, regardless of whether they are used or not.
A2	Cumulative Conversation Retransmission Cost	A. Structural Cost	Anthropic	Because it is stateless, the entire conversation is resent with each message.
B1	Search Cost	B. Inefficient Behavior	Anthropic	If the procedure and structure are not explicitly stated, the system searches through files and rediscovers the information each time.
B2	Cost of Redundant Output Inclusion	B. Inefficient Behavior	Anthropic	Large logs, raw JSON, and other unnecessary output are included in the context.
B3	Rework Cost Due to Ambiguous Instructions	B. Inefficient Behavior	Anthropic	Ambiguous requests trigger wide-ranging scans
B4	Cost of rework in the wrong direction	B. Inefficient behavior	Anthropic	Incorrect implementation direction will result in redoing previous work
B5	Inference (Extended Thinking) token cost	B. Inefficient behavior	Anthropic	Thinking tokens are charged as output tokens, and the default budget is tens of thousands of tokens
B6	Tool round-trip cost	B. Inefficient behavior	AWS	Multiple sequential tool calls are less efficient than processing them together (details in Part 2)
C1	Cache miss cost	C. State transition cost	Anthropic	Exceeding the cache TTL (1 hour subscription, 5 minutes API key) will result in full charge for the prefix
C2	Cost of summarization (/compact) itself	C. State transition cost	Anthropic	/compact reads the entire conversation, so summarizing a large context itself becomes a large request
D1	Agent Teams' Duplicate Costs	D. Scaling and Parallelization Costs	Anthropic	Each teammate has an independent full context window, consuming approximately 7 times the normal tokens.
E1	Background Processing During Idle Times	E. Background Costs	Anthropic	Conversation summarization jobs, /usage checks, and scheduled tasks occur even during idle times (the impact is small).

Below, we will look at each of these in detail.

Part 1: Cost Structure Based on the Anthropic Official Documentation

From here, we will focus on content directly described or quoted in the Anthropic official documentation (code.claude.com/docs).

A. Always Occurring Structural Costs

A1. Context Resident Costs (Anthropic)

CLAUDE.md, the MCP tool list, and Skill descriptions are loaded into the context every time, regardless of whether they are used in that turn or not. This is clearly stated in the Anthropic official documentation.

"If it contains detailed instructions for specific workflows (like PR reviews or database migrations), those tokens are present even when you're doing unrelated work."
—— code.claude.com/docs/en/costs.md

[Measures]

• Aim for CLAUDE.md to be under 200 lines, focusing only on essential content.
• Do not include procedural content that is not always necessary (e.g., PR review procedures, migration procedures) in CLAUDE.md; instead, extract it into Skills (see Skills Structure for details).
• Disable unused servers with /mcp for MCP tools. Tool definitions are lazily loaded by default, so the schema for unused tools will not be loaded until they are actually called.

(Note) CLAUDE.md is read only once at the start of a session and retained in memory. Editing during a session does not invalidate the cache, but it is important to note that "the edited content will not be reflected in that session."

"Editing them mid-session does not invalidate the cache, but the edit also doesn't apply. Claude keeps working with the version that was loaded at session start."
—— code.claude.com/docs/en/prompt-caching.md

New content is loaded only during the next /clear, /compact, or reboot. This specification is worth understanding to avoid unnecessary back-and-forth about "I edited CLAUDE.md, but it's not reflected."

A2. Cumulative Conversation Retransmission Cost (Anthropic)

Claude Code is stateless, and the entire conversation is resent with each message. Even a single-line question incurs the cost of the entire conversation up to that point.

"Claude Code sends your full conversation with every message, so a one-line question in a session that has been open all day uses tokens for the whole conversation, not just the one line."
—— code.claude.com/docs/en/costs.md

【Solutions】

• Before entering unrelated tasks, completely reset with /clear. If continuity is not needed, /clear has zero execution cost (it simply discards without reading anything).
• In fact, Anthropic explicitly lists "long-running sessions that are not cleared" as a typical cause of high charges.

"Unexpectedly high spend on an API or cloud-provider plan: usually traces back to long sessions that were never cleared or to Opus left as the default model."

• If you don't want to lose the conversation by clearing, you can rename it first and then clear it, and then revert to it later with resume.

B. Waste due to inefficient behavior

This section deals with cases where "tokens that were not originally necessary" are generated by specific actions or instructions.

B1. Search Cost (Anthropic)

If known procedures or structures are not explicitly stated anywhere, Claude will have to read through files and rediscover them every time.

"A skill can give Claude domain knowledge so it doesn't have to explore. For example, a 'codebase-overview' skill could describe your project's architecture, key directories, and naming conventions. When Claude invokes the skill, it gets this context immediately instead of spending tokens reading multiple files to understand the structure."
—— code.claude.com/docs/en/costs.md

[Solution]
Explicitly provide knowledge of standard procedures and project structure as a Skill (see Skills Structure for details).

B2. Cost of Redundant Output (Anthropic)

This is a case where output beyond the necessary information is included in the context, such as in huge log files or raw JSON responses.

"Instead of Claude reading a 10,000-line log file to find errors, a hook can grep for ERROR and return only matching lines, reducing context from tens of thousands of tokens to hundreds."
—— code.claude.com/docs/en/costs.md

[Solution]

Use the PreToolUse hook to rewrite the command string itself before the Bash command is executed, replacing it with a command that includes filtering. Since PreToolUse fires before execution, tool_output (execution result) cannot be received, but tool_input (the command to be executed) can be rewritten (hookSpecificOutput.updatedInput). By utilizing this, for example, replacing npm test with a piped command like npm test 2>&1 | grep -E 'FAIL|ERROR' | head -100 before execution, the output (results after execution) that is passed to Claude can already be filtered (costs.md).

json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }
]
}
]
}
}
plaintext
A typical example is a hook that filters the output of a test command to show only the failed lines. In fact, the sample script in the official documentation also implements the following: it determines whether it's a test command, adds| grep -A 5 -E '(FAIL|ERROR|error:)' | head -100to the command string, and then replaces it withupdatedInput.command`.

B3. Rework Costs Due to Ambiguous Instructions (Anthropic)

"Vague requests like 'improve this codebase' trigger broad scanning. Specific requests like 'add input validation to the login function in auth.ts' let Claude work efficiently with minimal file reads."
—— code.claude.com/docs/en/costs.md

[Solution]
Write prompts that reduce ambiguity, such as specifying the target file and function name specifically. While this may seem obvious, it's worth noting that the official documentation explicitly mentions this as a "token cost factor." #### B4. The Cost of Rework Due to Wrong Direction (Anthropic)

If the implementation direction is wrong, all the work done up to that point will have to be redone.

"Claude explores the codebase and proposes an approach for your approval, preventing expensive rework when the initial direction is wrong."
—— code.claude.com/docs/en/costs.md

[Solutions]

• Obtain approval first in Plan mode (switch with Shift+Tab) before starting implementation.
• If the direction is off, immediately stop with Escape and roll back with /rewind.
• Provide test cases and expected output in advance so that Claude can verify them itself.
• Proceed in stages: write one file, test it, then write another file and test it again.

(Note) /rewind is more cache-efficient than /compact. /compact requires a new prefix to be created because it replaces the conversation history with a new summary, while /rewind simply truncates the conversation to a past point in time that is already cached, so the prefix can reuse the existing cache.

"Rewinding truncates back to a prefix that is already cached, rather than building a new one as compaction does."
—— code.claude.com/docs/en/prompt-caching.md

"Using /rewind instead of /compact when going in the wrong direction" makes sense both in terms of preventing rework and billing.

B5. Inference (Extended Thinking) Token Cost (Anthropic)

Extended thinking is enabled by default, and thinking tokens are billed as output tokens. The default budget can reach tens of thousands of tokens depending on the model. > "Extended thinking is enabled by default because it significantly improves performance on complex planning and reasoning tasks. Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model."

—— code.claude.com/docs/en/costs.md

[Solutions]
For simple tasks that don't require deep reasoning, you can lower the effort level with /effort, disable thinking with /config, or, for models with a fixed thinking budget, limit the budget using the environment variable MAX_THINKING_TOKENS (e.g., MAX_THINKING_TOKENS=8000).

(Note) Regardless of whether it's Extended thinking or not, output tokens are billed at a higher unit price than input tokens. For example, Claude Sonnet 5 has an input of $2 and an output of $10 (introductory price until August 31, 2026; planned to transition to an input of $3 and an output of $15 thereafter), and Opus 5 has an input of $5 and an output of $25 (both per 1M tokens). In both price ranges, the output is five times the input (Official Pricing Page). This means that regardless of whether thinking is involved, the redundancy of Claude's own responses directly impacts costs. Furthermore, in multi-turn conversations, a redundant response from one turn is continuously resent as input tokens in subsequent turns, so the length of a response affects both the "current output cost" and the "inflation of subsequent input costs." Providing instructions to encourage concise responses in CLAUDE.md or /output-style is a reasonable measure considering this asymmetry in unit price.

(Regarding B6. Tool round-trip costs, since this is based on examples from the official AWS repository, it will be explained in detail in Part 2, "Specific Numerical Criteria.")

C. Costs Incurred During State Transitions

C1. Cache Miss Cost (Anthropic)

Claude Code automatically manages prompt cache by default. Model switching, configuration changes, and session restarts exceeding the cache TTL (1 hour for subscriptions, 5 minutes for API keys) will change the prefix, resulting in full billing from that point onward.

"Cache misses: Your first message after a break longer than the cache lifetime misses the cache and reprocesses your full context."
—— code.claude.com/docs/en/costs.md

[Solution]
When using API keys, Bedrock, Google Cloud, Microsoft Foundry, or Claude Platform on AWS (default TTL is 5 minutes), setting the environment variable ENABLE_PROMPT_CACHING_1H=1 extends the TTL to 1 hour (this increases the cost per cache write, but prevents cache misses over long intervals). The official documentation also clearly recommends this:

"Pick your model and effort level at the top of a session, then save /compact for natural breaks between tasks. The fewer changes you make mid-task, the higher your cache hit rate."
—— code.claude.com/docs/en/prompt-caching.md

In other words, consciously avoiding "cache invalidation operations" mid-task—such as deciding on the model and effort level at the start of a session and not changing it mid-session, and executing /compact at the end of a task (not relying on automatic compaction)—is an officially supported measure (other invalidation triggers: switching fast mode, changing MCP server connections, adding denial rules for the entire tool, upgrading Claude Code, etc.).

C2. The Cost of Summarizing (/compact) Itself (Anthropic)

This is often overlooked, but /compact is not free.

"/compact reads the conversation it summarizes, so compacting a large context is itself a large request. When you want a fresh start instead of continuity, /clear costs nothing."
—— code.claude.com/docs/en/costs.md

There is actually no specific threshold in the official documentation for when to use /compact, such as "when context usage reaches X%." Instead, Claude Code has a mechanism (automatic compaction) that automatically summarizes when approaching the maximum input size.

[Solutions]

• If continuity is not required, the official criterion is that /clear (free) is more rational than /compact (cost).
• Manual /compact presents a choice between "letting automatic compaction handle it" or "actively controlling the summarization content with /compact [focus]."

D. Multiplier Costs Due to Scaling and Parallelization

D1. Duplicate Costs of Agent Teams (Anthropic)

The Agent teams feature (experimental feature, disabled by default), which launches multiple Claude Code instances, gives each teammate an independent full-context window.

"Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance."
—— code.claude.com/docs/en/costs.md

The figure of approximately 7x is impactful. costs.md has a dedicated section for mitigating this duplicate cost.

"To keep agent team costs manageable: Use Sonnet for teammates... Keep teams small... Keep spawn prompts focused... Shut down teammates when their work is done."
—— code.claude.com/docs/en/costs.md

[Solutions]

• Use Sonnet for teammates (good cost-benefit balance for coordination tasks)
• Keep teams small (token consumption is roughly proportional to team size)
• Lighten spawn prompts (CLAUDE.md/MCP/skills is automatically loaded, so what you write in the spawn prompt is added directly to the context)
• Shut down teammates promptly after work is done (active teammates continue to consume tokens until they are terminated or the session ends)

E. Background Costs

E1. Background Processing During Idle Times (Anthropic)

Even when a session is idle, processes such as conversation summarization jobs for --resume, status checks for /usage, and periodic firing of scheduled tasks occur. While the impact is small, usually less than $0.04 per session, it's good to be aware of its existence.

[Countermeasures]
Since the impact is small, proactive countermeasures are unnecessary. Simply being aware that these background costs exist is sufficient.

Skills and Subagents Don't Always Make Things Cheaper

This is the most important point to emphasize in this article. While you often see advice like "Use Skills" or "Let Subagents Do It," a more accurate understanding is that, looking at single calls alone, it often actually increases tokens.

Subagent Structure

Subagents do not inherit the parent's cache (cold start). Therefore, the following costs occur:

• Consumes tokens from zero for system prompts.
• Adds the steps of "reading the original output" + "writing a summary" + "the parent reads that summary."
• Startup overhead is only incurred for the entire conversation of the sub-agent itself.

The reduction effect is seen not for single calls, but from the perspective of the entire session and long term. If redundant output is left in the main conversation, that will continue to be carried over as an accumulated cost in all subsequent turns (A2). By isolating it in a sub-agent, the main thread only needs to handle the summary, and it becomes easier to maintain the cache hit rate. The essential value is not "making the search work itself cheaper," but "preventing compound bloat when subsequent conversations are prolonged."

Suitable for: Large-scale codebase searches, large-volume log processing, and other one-time tasks where the raw output is huge and you don't want to leave it in the main. Independent tasks that can be parallelized.

Not suitable for: Quick checks, tasks that require close interaction with the main conversation (the overhead of cold start + round-trip summarization would be higher).

Note that regular subagents always use a 5-minute TTL cache, even with a subscription (the automatic 1-hour TTL extension applied to the main conversation does not apply).

"Subagents use the five-minute TTL even on a subscription, since the automatic one-hour TTL applies to the main conversation."
—— code.claude.com/docs/en/prompt-caching.md

(Supplement) As an exception for cases where you want to avoid cold starts but also want isolation, there is a "fork" function called /subtask (formerly /fork). A fork is a subagent that inherits the conversation history, system prompts, tools, and model directly from the main session, and the initial request can reuse the prompt cache from the main conversation (i.e., it does not result in a cold start). Only the result is returned to the main, and the fork's own tool calls do not remain in the main conversation, thus achieving both "requests without background explanation" and "not cluttering the main conversation." However, unlike regular subagents, a trade-off is that forks cannot have their own system prompts or tool restrictions.

"Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's prompt cache. This makes forking cheaper than spawning a fresh subagent for tasks that need the same context."
—— code.claude.com/docs/en/sub-agents.md

Skills Structure

Unlike CLAUDE.md, Skills utilize a progressive disclosure mechanism where the body text is not loaded until it's used.

"Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it."
—— code.claude.com/docs/en/skills.md

In other words, the cost at the moment a Skill is activated is not significantly different from if its content were directly written in CLAUDE.md. The advantage lies in the fact that it incurs zero cost in sessions where the Skill is not used. Therefore, it is rational to use them in the following way:

• Procedures that occur infrequently or are only used in specific tasks (e.g., PR reviews, migration procedures) are effectively turned into Skills.
• For content used almost every turn, the benefits of lazy loading diminish, so it may be more rational to keep it permanently in CLAUDE.md.

Anthropic officially also clearly recommends Skills as a destination for extracting routine workflows.

"Move instructions from CLAUDE.md to skills... Aim to keep CLAUDE.md under 200 lines by including only essentials."
—— code.claude.com/docs/en/costs.md

There are three reasons why routine tasks are a good fit for Skills.

1. Compatibility with lazy loading (suits usage patterns that are frequent but not always)
2. Reduced search costs (as mentioned in B1, having a Skill eliminates the need to read through files every time)
3. Reduced rework through consistency (clearly defined procedures reduce the likelihood of waste such as Claude trying different approaches each time and requiring corrections)

Part 2: Token Saving Know-how Learned from AWS Examples

From here on, the insights are derived from the AWS Agent Skills repository awslabs/agent-plugins. Please note again that these are operational standards and design guidelines uniquely defined by AWS for this repository, not the official Anthropic specification (AWS label).

Specific Numerical Criteria

The official Anthropic documentation also contains specific numerical criteria for the size of SKILL.md.

Anthropic Official
"Keep SKILL.md under 500 lines. Move detailed reference material to separate files."
—— code.claude.com/docs/en/skills.md

Regarding this single criterion of 500 lines, the AWS Agent Skills repository awslabs/agent-plugins has a more operational-level standard (the following are AWS's own operational standards and not part of the official Anthropic specification).

The design philosophy of this repository is summarized in the following sentence:

AWS Example
"Files should be SHORT and FOCUSED. Every token counts in an agent's context window."
—— docs/DESIGN_GUIDELINES.md

The size criteria enforced by CI (tools/markdownlint-skill-length.cjs, custom lint rule SKILL001) are as follows:

Criteria	Lines	Words	Behavior
Hard Error	Over 500 lines	Over 8,000 words	Blocks CI
Warning	Over 300 lines	Over 5,000 words	Warning only

It's interesting that the hard error threshold (500 lines) perfectly matches Anthropic's official criterion of "less than 500 lines." Anthropic's single numerical target of "500 lines" can be further refined by AWS in three stages, down to the operational level: ① an early warning signal at 300 lines, ② a word count (8,000 words/5,000 words) independent of lines, and ③ automatic enforcement via CI.

The tool's comments succinctly express the essence of Skills:

"SKILL.md is loaded into the agent's context window on every invocation. Keep it lean — big ideas and routing only. Push detailed instructions, examples, and reference material into sub-files under references/ so the agent loads them on demand."

Further detailed guidelines are provided, such as SKILL.md itself being 200-300 lines, reference files (under references/) being 50-100 lines per file, aiming for less than 5,000 tokens for the initial load, and splitting code blocks if they exceed 30 lines. The repository also suggests using claude --plugin-dir ./plugin --verbose to check actual token consumption as a measurement method.

In addition, several guidelines can be obtained from the same repository. The "Write for Agents, Not Humans" policy requires avoiding conversational language, small talk, emojis, and preambles, and instead using explicit and unambiguous instructions. The concept of Minimize Roundtrips suggests that a design that processes data in a single call is more efficient than multiple sequential tool calls that scan data separately in 10 separate steps, thus reducing context consumption incurred with each round trip. Furthermore, there is a method of explicitly specifying Caching Guidance within Skill instructions, such as "Cache the AWS service list during the session (low change frequency)" and "Retrieve pricing data every time (high change frequency)," explicitly controlling the agent's decision to re-fetch data within the instructions.

List of Countermeasures

This table is a counterpart to the "[List of Cost Factors]" (#List of Cost Factors) at the beginning. It lists the specific countermeasures introduced in this article for each cost factor. The IDs correspond to those in the table at the beginning.

ID	Name	Countermeasure	Probability
A1	Context Resident Cost	Limit CLAUDE.md to under 200 lines / Extract procedural content to Skills / Disable unused MCP servers with /mcp	Anthropic
A2	Cumulative Retransmission Cost of Conversations	Use /clear before unrelated tasks (zero execution cost) / Rename conversations you want to keep before clearing and resume with /resume	Anthropic
B1	Exploration Cost	Explicitly provide knowledge of standard procedures and project structures as Skills	Anthropic
B2	Cost of Redundant Output Inclusion	Rewrite the command string itself with the PreToolUse hook and replace it with a command that includes filtering (updatedInput)	Anthropic
B3	Rework Cost Due to Ambiguous Instructions	Specify target file and function names specifically and write prompts that reduce ambiguity	Anthropic
B4	Cost of rework due to wrong direction	Implement after obtaining approval in Plan mode / Stop with Escape and /rewind if the direction deviates / Present verification goals in advance / Proceed step by step, one file at a time	Anthropic
B5	Inference (Extended Thinking) token cost	Lower the effort level with /effort / Disable thinking with /config / Limit the budget with MAX_THINKING_TOKENS	Anthropic
B6	Tool round-trip cost	Design to process in one go rather than multiple sequential tool calls (Minimize Roundtrips)	AWS
C1	Cache miss cost	Extend TTL to 1 hour with ENABLE_PROMPT_CACHING_1H=1 when using API keys, etc. / Fix the model effort level at the start of the session and do not change it midway / Execute /compact at the end of a task	Anthropic
C2	Cost of the summary (/compact) itself	Use the free /clear if continuity is not needed / If continuity is needed, let automatic compaction take over or actively control it with /compact [focus]	Anthropic
D1	Duplicate cost of agent teams	Use Sonnet for teammates / Keep teams small / Lighten spawn prompts / Terminate promptly after work is completed	Anthropic
E1	Background processing during idle	The impact is small (less than $0.04/session), so no proactive measures are needed. Simply be aware of its existence.	Anthropic

Please note that the "certainty" in this table refers to the evidence for the countermeasure itself, and is a separate axis from the certainty in the cost factor list (evidence of the fact that a cost is incurred).

How to actually verify in your environment

If you want to verify the contents of this article with your own workload, you can use the following method.

Easy Method (Built into Claude Code)

Method	Purpose
/usage	Total number of tokens for the session, input/output/cache read/write tokens per model. Pro/Max/Team/Enterprise plans also display a warning if cache misses etc. account for more than 10% of recent usage.
/context [all]	Visualize context usage by item.
statusline settings	Always display token usage in the terminal. By examining the cache_creation_input_tokens (new cache writes) and cache_read_input_tokens (cache reads) of the current_usage object, you can immediately check the C1 cache hit rate.
claude --plugin-dir ./plugin --verbose	Check the actual token consumption of a specific Skill/plugin.

Precise Method (Token Counting API)

The official Anthropic Token Counting API (POST /v1/messages/count_tokens) is available for free. By comparing input_tokens before and after changing the way CLAUDE.md, SKILL.md, and prompts are written, you can verify with concrete numbers whether the changes actually reduce the number of tokens.

bash
curl https://api.anthropic.com/v1/messages/count_tokens \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5",
"messages": [{"role": "user", "content": "This function validates user input and then saves it to the database."}]
}'

If you have the ant CLI, you can call it more concisely.

bash
ant messages count-tokens --model claude-opus-5 \
--message '{role: user, content: "text to be measured"}' \
--transform input_tokens -r


(Note) If you use a tokenizer other than Claude, such as tiktoken (for OpenAI), there will be a discrepancy with the actual number of tokens in Claude (the specific error rate is not listed in the official API/product documentation, and since it is an unofficial figure, it will be omitted in this article). Always use the official Claude Token Counting API. Also, note that simple estimations such as "number of characters ÷ 4" are empirical rules based on English text and are unlikely to apply to Japanese.

In conclusion

Starting from the cause of the cost, as in this case, the scope and priority of countermeasures naturally become clear. Implementing countermeasures haphazardly without considering the underlying causes can lead to wasted time on ineffective solutions or failure to recognize unintended side effects, such as the misuse of sub-agents. My biggest takeaway from writing this article is that understanding "what a countermeasure is effective for" is essential for determining what to try next.

Specific implementation details, often missed by simply following general theories, are found in the official documentation, making direct access to primary sources crucial. Whether it's token consumption or any other aspect of this research, starting by questioning your assumptions might ultimately be the most efficient approach.

The specifications of Claude Code are likely to change in the future, so the content of this article will eventually become outdated. Please share any questions or results from your own testing in the comments.

References

• Manage effectively — Claude Code Docs
• How Claude Code uses prompt caching — Claude Code Docs
• Create custom subagents — Claude Code Docs
• Explore the context window — Claude Code Docs
• Slash commands — Claude Code Docs
• Agent Skills — Claude Code Docs
• Token counting — Claude Docs
• awslabs/agent-plugins — GitHub
• docs/DESIGN_GUIDELINES.md
• tools/markdownlint-skill-length.cjs
• tools/validate-size.py