anthropics / anthropics/claude-code
[BUG] Claude Code CLI (`claude -p`) burns ~15-16k tokens of fixed overhead per call when used as a stateless batch text-completion backend
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
### Preflight Checklist
- [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
### What's Wrong?
Subject: Claude Code CLI (`claude -p`) burns ~15-16k tokens of fixed overhead per call when used as a stateless batch text-completion backend
Summary
-------
I built a local Python pipeline that calls the Claude Code CLI in non-interactive
mode (`claude -p "" --output-format json`) once per work item, to run a
narrow, schema-constrained text-extraction task (extract structured JSON from a
short document excerpt) across a batch of ~2640 items, using a Claude Pro/Max/Team
subscription instead of the metered API.
Each invocation is a brand-new, independent CLI process/session (no `--resume`,
no shared session state between calls - this is intentional, since each work item
is unrelated to the others). What I did not anticipate is that every single one of
these "cold" invocations reloads Claude Code's own internal system prompt / tool
definitions from scratch, adding a large, constant token overhead that has nothing
to do with the actual task prompt.
Measured data
-------------
From `--output-format json` usage stats on real calls in this session:
- Cold-start call: `cache_creation_input_tokens` ~14,857-16,550
- A call shortly after (within the same short window): `cache_read_input_tokens`
~27,516-31,687 (i.e. it read back an even larger cached context, not the small
one we created)
- Actual task prompt size (measured from the real batch, average over 104
successfully completed calls):
- System prompt: 2,897 characters (~750-830 tokens)
- User prompt (task-specific content): 4,797 characters average (~1,200-1,370
tokens)
- Output: 3,896 characters average (~975-1,115 tokens)
- So the actual task itself needs roughly ~3,000 tokens total per call.
In other words: the task itself needs ~3k tokens per call, but each `claude -p`
invocation appears to load on the order of 15k-30k additional tokens of
Claude Code's own overhead that is unrelated to the prompt I sent it.
Impact
------
Running this batch through `claude -p` consumed the Claude Pro/Max/Team
subscription's usage limit after only 104 of the planned 2,640 calls (~4% of
the job), i.e. roughly 6-7x more usage than the task itself should have required.
For comparison, running the same 2,640 calls against the plain Anthropic Messages
API directly (no Claude Code agent overhead) would cost an estimated $55-60 total
at current Sonnet-tier pricing, for the full batch - a small fraction of what got
consumed against the subscription for less than 5% of the same job.
Environment
-----------
- Claude Code CLI version: 2.1.274
- Invocation: `claude -p --output-format json --model sonnet` with the prompt
piped via stdin (not as a CLI argument)
- OS: Windows 11
- No `--resume`/session reuse between calls (each call is a separate, unrelated
work item by design)
Ask
---
1. Is this large per-call overhead when using `claude -p` as a stateless
one-shot completion backend expected/known behavior, or is there a flag/mode
to invoke Claude Code without loading its full agent system prompt / tool
definitions for a simple text-in/JSON-out task?
2. Separately, on the account/billing side: since the usage was consumed by this
fixed per-call overhead rather than by the actual workload, is there any way
to have the subscription's usage window/limit reviewed or reset for this
period?
### What Should Happen?
Token/usage consumption per `-p` call should be roughly proportional to the
prompt actually sent (in this case ~3,000 tokens total: system + user + output).
I'd expect a one-shot, non-interactive `-p` invocation used purely as a
text-in/JSON-out completion call to have minimal fixed overhead, or at least for
that overhead to be clearly documented/surfaced so it can be budgeted for before
running a batch job like this.
### Error Messages/Logs
```shell
```
### Steps to Reproduce
1. Install Claude Code CLI: `npm install -g @anthropic-ai/claude-code`, then
`claude /login` (subscription auth, not an API key).
2. Prepare a short, fixed system prompt (a few KB) and a short, task-specific
user prompt (a few KB), together well under 10k characters (~3k tokens).
3. Run, from a script/subprocess (not the interactive REPL), piping the prompt
via stdin:
`claude -p --output-format json --model sonnet < prompt.txt`
4. Repeat step 3 many times in a loop, once per work item (each call is an
independent, cold session - no `--resume`, no shared conversation state).
5. Inspect the `usage` block of the returned JSON for each call.
### Claude Model
Sonnet (default)
### Is this a regression?
Yes, this worked in a previous version
### Last Working Version
_No response_
### Claude Code Version
2.1.274 (installed via `npm install -g @anthropic-ai/claude-code` on 2026-09-17)
### Platform
Anthropic API
### Operating System
Windows
### Terminal/Shell
Windows Terminal
### Additional Information
_No response_
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reproducing the repeated `claude -p --output-format json --model sonnet < prompt.txt` calls on Windows with subscription authentication, then inspect each returned JSON `usage` block. Compare cold and repeated invocations for fixed system-prompt and tool-definition overhead. Done means determining whether the behavior is expected, identifying an available low-overhead mode or documenting the limitation, and separating any account or billing review from the CLI issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js, python
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100