Seongwoo Choi / Journal

Claude Code request size: what our local recorder measured

At a glanceRecorded request sizes for CLAUDE.md, skills and MCP tools in Claude Code. What the byte counts show, and why they do not measure your bill.

Partly testedRequest sizes were reported from Claude Code 2.1.322 on Linux. This correction reviews their interpretation; billing, latency and network isolation were not tested.

You need
Claude Code and Python. No API key and no model: the requests go to a recorder on your own machine.
You end up with
The size of your own setup, part by part, and a short list of what to trim.
In this article 8 sections
  1. The results
  2. What is in the baseline
  3. CLAUDE.md increased the initial request size
  4. MCP servers: 1 KB or 56 KB, depending on one setting
  5. Going the other way: small requests for scripts and small models
  6. Measure your own setup
  7. What to do with this
  8. What this measurement does not show

The original experiment sent a short question from Claude Code to a local recorder and compared request sizes after changing the project setup. The recorded payload included instructions, loaded tool definitions and project context. Deferred tools and skills need not send their complete contents upfront.

In these runs, a long CLAUDE.md and disabling tool search increased the request size substantially. This measures serialized data, not API tokens, charges or response time.

Correction, November 14, 2026: The earlier wording overstated what byte counts establish about bills, latency and privacy. The reported measurements below are unchanged; no new benchmark was run.

The results

Each row is the size of the request Claude Code sent for the same two-word question, "Say hello", with one thing changed.

Minimal mode--bare · 4,318

 

Three tools only--tools "Read,Edit,Bash" · 14,840

 

An empty projectthe baseline · 46,254

 

+ a 40-tool MCP serverdefault settings · 47,598

 

+ ten skillsabout 2.7 KB each on disk · 48,098

 

+ a 40-line CLAUDE.md2.5 KB on disk · 49,254

 

+ a 400-line CLAUDE.md25 KB on disk · 72,188

 

+ the same 40-tool servertool search switched off · 101,938

 
Bytes sent per request, for the same two-word question. Bars are drawn to scale.
SetupRequest sizeChange
An empty project (baseline)46,254 bytes
+ an MCP server with 3 tools46,333+79
+ one skill46,438+184
+ three subagents46,800+546
+ an MCP server with 40 tools47,598+1,344
+ ten skills48,098+1,844
+ a 40-line CLAUDE.md49,254+3,000
+ a 400-line CLAUDE.md72,188+25,934
Tool search off, nothing else added73,687+27,433
Tool search off + the 40-tool server101,938+55,684
--tools "Read,Edit,Bash"14,840−31,414
--bare4,318−41,936

These are recorded wire byte counts. JSON bytes are not character counts or model tokens; dividing them by four does not establish a token count. Use the model tokenizer or actual API usage fields to measure tokens.

What is in the baseline

One request from an empty project46,254 bytes

 tool definitionsmessages

Instructions: 6,119Tool definitions: 30,136Messages: 10,081

Relative sizes of separately reserialized fields. Their sum, 46,336 bytes, differs from the 46,254-byte wire request, so this is not an exact partition of the payload.

Three things stand out.

  • The tools are the bulk of it. Twelve tool definitions take 30,136 bytes, about 2,500 each. A tool definition is a small manual: what the tool does, when to use it, what each argument means.
  • "Say hello" was 9 bytes of a 10,081-byte message. The rest of the messages part is context Claude Code attaches for you: the date, the folder, what is available. This is also where your own additions land.
  • Two runs had the same byte count. Both reported 46,254 bytes. Equal lengths do not prove identical content, a reusable prefix or a cache hit. Cache behavior needs separate usage evidence.

CLAUDE.md increased the initial request size

A 2,480-byte CLAUDE.md made the recorded request 3,000 bytes larger. A 25,054-byte one made it 25,934 bytes larger. Those deltas describe these initial requests; they do not establish identical behavior or billing for every later turn.

Compare that with a skill. Each of our test skills was 2,688 bytes on disk, and ten of them added 1,844 bytes in total, about 184 each. Only a skill's name and description are sent; the body is read when the skill is used.

The rule this suggestsKeep in CLAUDE.md only what Claude needs on every task: the commands, the rules with no exceptions, where things are. Move anything that matters only sometimes, such as a release procedure or a style guide for one kind of file, into a skill. In the reported skill fixture, discovery added about 184 bytes per skill. That does not include loading the skill body when it is used, and it is not a matched measurement of moving the same document.

How to write the short version is in setting up a project for Claude Code.

MCP servers: 1 KB or 56 KB, depending on one setting

We wrote a made-up server offering 40 tools, with realistic descriptions: 29 KB of definitions in all. Added to the project with default settings, it made each request +1,344 bytes larger. That is about 33 bytes per tool, because only the tool names are sent. This is the feature the documentation calls tool search: definitions are deferred, and Claude looks one up when it needs it.

Then we set ENABLE_TOOL_SEARCH=false, which the documentation describes as "all MCP tools loaded upfront, no deferral".

Tools in the requestRequest size
Default, with the 40-tool server1247,598
Tool search off, no MCP server2173,687
Tool search off, with the 40-tool server61101,938

Two sources of additional payload appeared.

  • The 40 tools added their definitions: 28,251 bytes, about 700 each.
  • Additional built-in tools came along too. With tool search off and no MCP server at all, the request grew by 27,433 bytes, because built-in tools that are normally looked up on demand, among them web fetch, web search and the notebook editor, were all loaded at the start.

One more result surprised us. ENABLE_TOOL_SEARCH=auto sounds like the safe choice. It is a threshold mode: by the documentation, tools load upfront while their definitions total under 10 percent of the context window. Our 40 tools were under that line, so auto gave the largest request of the whole test, 103,647 bytes.

If you set this variable once and forgot whyCheck your shell profile and the env section of ~/.claude/settings.json for ENABLE_TOOL_SEARCH. Unset, every MCP tool is deferred. There are good reasons to load a few tools upfront, and the documentation shows how to do it per server or per tool, which is cheaper than switching deferral off for everything.

If you are writing a server yourself, the MCP server guide shows where the names and descriptions measured here come from.

Going the other way: small requests for scripts and small models

Two flags shrink the request sharply.

FlagRequest sizeWhat you give up
--tools "Read,Edit,Bash"14,840 bytesEvery built-in tool except the ones you name
--bare4,318 bytesAlmost everything automatic. The help text calls it a minimal mode that skips hooks, plugin sync, auto-memory and the automatic discovery of CLAUDE.md, among other things. You pass in what you want explicitly

Smaller payloads may be useful for repeated scripts and for Claude Code with a local model. The size ratio is not a cost or latency ratio: tokenization, prompt caching, model pricing and serving behavior all matter. Measure token usage and task success before removing tools your workflow needs.

Measure your own setup

The recorder is a small web server that pretends to be the model. It prints one line per request with the sizes of the three parts, then answers with a fixed sentence. Save it as recorder.py:

"""recorder.py: stand in for a model server and measure what each request from Claude Code is made of.

For every request it prints one line of JSON: the size in bytes of the whole request and of its three
parts (system instructions, tool definitions, messages), and the names of the tools. It then streams
back one fixed sentence. It is not a model.
"""
import json
from http.server import BaseHTTPRequestHandler, HTTPServer

REPLY = "Hello from the recorder."
size = lambda value: len(json.dumps(value, ensure_ascii=False).encode())


class Recorder(BaseHTTPRequestHandler):
    def do_POST(self):
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        body = json.loads(raw or b"{}")
        tools = body.get("tools", [])
        print(json.dumps({"path": self.path.split("?")[0], "bytes": len(raw), "system": size(body.get("system", "")),
                          "tools": size(tools), "messages": size(body.get("messages", [])), "tool_count": len(tools),
                          "deferred": sum(1 for tool in tools if tool.get("defer_loading")),
                          "names": [tool.get("name") or tool.get("type") for tool in tools],
                          "beta": self.headers.get("anthropic-beta", "")}), flush=True)
        if not body.get("stream"):
            payload = json.dumps({"id": "msg_1", "type": "message", "role": "assistant", "model": body.get("model"),
                                  "content": [{"type": "text", "text": REPLY}], "stop_reason": "end_turn", "stop_sequence": None,
                                  "usage": {"input_tokens": 10, "output_tokens": 6}, "input_tokens": 10}).encode()
            self.send_response(200)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(payload)))
            self.end_headers()
            self.wfile.write(payload)
            return
        self.send_response(200)
        self.send_header("Content-Type", "text/event-stream")
        self.end_headers()
        events = [
            ("message_start", {"type": "message_start", "message": {"id": "msg_1", "type": "message", "role": "assistant", "model": body.get("model"), "content": [], "stop_reason": None, "stop_sequence": None, "usage": {"input_tokens": 10, "output_tokens": 0}}}),
            ("content_block_start", {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}),
            ("content_block_delta", {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": REPLY}}),
            ("content_block_stop", {"type": "content_block_stop", "index": 0}),
            ("message_delta", {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": None}, "usage": {"output_tokens": 6}}),
            ("message_stop", {"type": "message_stop"}),
        ]
        for name, data in events:
            self.wfile.write(f"event: {name}\ndata: {json.dumps(data)}\n\n".encode())
        self.wfile.flush()

    def log_message(self, *args):
        pass


HTTPServer(("127.0.0.1", 8000), Recorder).serve_forever()

Run it in one terminal with python3 recorder.py. In another, go to the project you want to measure and send one question through it:

ANTHROPIC_BASE_URL=http://127.0.0.1:8000 ANTHROPIC_API_KEY=dummy ANTHROPIC_AUTH_TOKEN=dummy \
ANTHROPIC_DEFAULT_OPUS_MODEL=my-model ANTHROPIC_DEFAULT_SONNET_MODEL=my-model ANTHROPIC_DEFAULT_HAIKU_MODEL=my-model \
claude -p "Say hello"
$ python3 recorder.py
{"path": "/v1/messages", "bytes": 46254, "system": 6119, "tools": 30136, "messages": 10081, "tool_count": 12, "deferred": 1, "names": ["Agent", "Bash", "Edit", "ListAgents", "Read", "ReportFindings", "ScheduleWakeup", "Skill", "ToolSearch", "Workflow", "DeferredToolPlaceholder", "Write"], "beta": "…"}
The baseline, as recorded. Your own project will show a larger messages figure; the difference is what your setup adds.

The example redirects the model request to a local recorder and supplies dummy credentials. It does not isolate Claude Code from the network: telemetry, updates, plugins, MCP servers or other enabled features can still contact external services. Use a disposable project without sensitive material and consult the network configuration documentation before testing confidential data.

In a POSIX shell, the inline variable assignments shown above apply only to that command; they do not persist afterwards. PowerShell $env:NAME = "value" assignments persist in that process and should be restored or removed afterwards. The recorder returns made-up usage values to satisfy the client protocol; those values cannot measure tokens or billing.

What to do with this

If you haveDo thisWhy
A CLAUDE.md over about 100 linesMove the occasional material into skillsThe long fixture increased the initial wire payload by about 26 KB
Many MCP serversLeave them, and leave tool search onThe deferred 40-tool fixture added 1,344 wire bytes
ENABLE_TOOL_SEARCH set to false or autoFind out why, and unset it if the reason is goneIt was the difference between 48 KB and 102 KB
Scripts that call claude -pName the tools they need with --toolsThe request fell from 46 KB to 15 KB
A small-context model behind Claude CodeStart from --tools and add back what you missThe opening message alone can fill a small window

What this measurement does not show

  • Tokens. We counted bytes. The real token count depends on the model's tokenizer.
  • Money and latency. No paid model request or timing comparison was measured. Cache creation, cache reads and uncached input have different prices. A repeated prefix is not proof of a cache hit; inspect actual usage fields and current pricing. Cached tokens still count toward context limits.
  • An interactive session. We used print mode. A normal session carries more, and grows with every turn.
  • Your version. These are Claude Code 2.1.322's numbers. The tool list changes between releases, which is one more reason to run the recorder yourself.

Sources

This article reflects public information available when it was written. Versions, defaults and prices can change; check the linked official documentation.

The original November 12, 2026 experiment reported one short question in print mode (claude -p) sent to a local recorder with Claude Code 2.1.322 on Linux. The wire sizes are bytes, not tokens or billing measurements. The system, tools and messages fields are separately reserialized estimates and do not sum to the wire size. A custom endpoint and unrecognised model name may change tool loading relative to a supported Claude session. The instruction files, skills, agents and 40-tool server were synthetic test fixtures. The recorder and an example invocation are included, but the complete fixture suite and runner are not; independent reproduction remains outstanding. The November 14 correction retains the original reported byte counts and removes unsupported cost, token, latency and privacy conclusions. No new benchmark was run. Written for this site with AI assistance, from the sources above. For errors or additional information, please request a correction. Editorial policy