Reading the Claude Code /usage breakdown

Published 2026-05-25 by Owner

Claude Code 2.1.149 itemizes /usage by skills, subagents, plugins, and per-MCP-server cost. The breakdown is useful only if you can map each line back to its source — and once you can, you have a tool for cutting cost that did not exist a week ago.

Reading the breakdown

Run /usage inside any session on 2.1.149 or later. The new output reports a percentage against your limit and then names each of the four categories with its share. The category list is the exact wording from Claude Code’s changelog; nothing else is added at the user layer.

/usage

Limit: 67% used
  skills            24%
  subagents         12%
  plugins            5%
  mcp:filesystem    18%
  mcp:fetch          8%

That example is illustrative — your output names your configured servers by their MCP identifiers, not by filesystem and fetch literally. Look for the line that dominates, then move to the mapping below.

Mapping a hot category back to its source

The project-local conventions below match the typical Claude Code installation; confirm the exact directory layout against your own project before relying on these paths.

A skill line points to one of your installed skills. Skills live as Markdown files under .claude/skills/; list them by recency to find which were edited or invoked recently:

ls -t .claude/skills/*.md | head -10

A subagent line points to one of your Agent-tool dispatches. Subagents are configured per-project in .claude/agents/; the same listing pattern applies:

ls -t .claude/agents/*.json | head -10

A plugin line points to one of your Claude Code plugins; the plugin identifier in /usage matches the directory name under .claude/plugins/. An MCP server line names the server as it appears in your MCP configuration file. The exact file name varies by installation; the typical project-local path is .claude/mcp_servers.json and the keys live under mcpServers:

jq '.mcpServers | keys' .claude/mcp_servers.json

The identifier in the /usage output is one of those keys. If a server is the offender, the next step is to isolate it.

Isolate the offender for a session

Claude Code 2.1.149 does not ship a native per-category cap, so the workable pattern is to swap in an empty configuration, restart the session, and compare /usage. For MCP servers, move the config file aside and replace it with an empty one:

mv .claude/mcp_servers.json .claude/mcp_servers.json.bak
echo '{"mcpServers": {}}' > .claude/mcp_servers.json

Start a fresh Claude Code session, do the same kind of work, and read /usage. The MCP line should be zero; whatever the other categories report is your floor without that surface. Restore when you are done:

mv .claude/mcp_servers.json.bak .claude/mcp_servers.json

For a skill, the analogous isolation is to temporarily move the skill file out of .claude/skills/:

mkdir -p .claude/skills.disabled
mv .claude/skills/<skill-name>.md .claude/skills.disabled/

Run the same work, read /usage, and reverse the move to restore. The pattern is the same one Claude Code’s loader exposes: a skill or server that does not exist on disk does not contribute to the breakdown.

Throttle without removing

Once you know which sub-component is the offender, the durable fix is to tighten its configuration. The exact field names depend on the MCP server’s own configuration schema; consult that server’s documentation rather than copying field names from a guide. The general shape of the change is: lower the per-call work the server does, raise the threshold for invocation, or reduce the data scope it has access to. For a skill, edit its Markdown file to require an explicit invocation rather than auto-firing on every turn — a skill that fires on every turn shows up roughly four times the size of a skill that fires only when asked.

Watching the trend

The single-session breakdown is a snapshot. To see whether a category is creeping up over time, save what you read after each significant session to a log:

date -u +%Y-%m-%dT%H:%M:%SZ >> ~/.claude/usage-log.txt
echo "skills=24 subagents=12 plugins=5 mcp:filesystem=18 mcp:fetch=8" >> ~/.claude/usage-log.txt

A week of entries is enough to see whether a category is trending up — and a category whose share is climbing across sessions is usually the next one to throttle.

The argument for why all of this surface exists at all is the bill finally itemized; the existing cost-control baseline is Claude Code cost control; the broader token-budgeting context is AI coding token budget management; the release that triggered this guide is Claude Code’s /usage adds a per-category breakdown.