Claude Code Prompt Suggestions: One Took 9 API Requests

Claude Code prompt suggestions are the grayed-out next prompts that show up in the input box after Claude finishes a turn. Press Tab or the right arrow and the suggestion becomes your prompt. A Hacker News thread arguing that the real customer for this feature is the model reached 269 points this week, and most of its 153 comments are people guessing at how it works. I read the code instead.

The worst part first. On the Mac mini that runs this blog, a single suggestion took 9 API requests, not one. A plugin's SubagentStop hook kept sending the background request back for another round, until Claude Code hit its block cap. In 5 probe runs where I logged every request, the suggestion request repeated 9 or 12 times each, and 4 of those 5 runs showed nothing at the end. Below is how Claude Code 2.1.291 decides whether to suggest, the 12 checks that throw a suggestion away, the back-off that hides them, and the three ways to turn them off.

How Claude Code generates a prompt suggestion

The official docs say each suggestion is "a short background request to the same model your session is using" and that it reuses the prompt cache, so it's mostly cache reads. That matches the bundle. The JavaScript inside the 2.1.291 binary forks the conversation with the query source prompt_suggestion, denies every tool call ("No tools needed for suggestion"), skips the transcript and skips the cache write. Then it appends one user message. These are its opening lines and its rules, verbatim:

[SUGGESTION MODE: Suggest what the user might naturally type next into Claude Code.]
...
THE TEST: Would they think "I was just about to type that"?
...
NEVER SUGGEST:
- Evaluative ("looks good", "thanks")
- Questions ("what about...?")
- Claude-voice ("Let me...", "I'll...", "Here's...")
- New ideas they didn't ask about
- Multiple sentences

Stay silent if the next step isn't obvious from what the user said.
...
Format: 2-12 words, match the user's style. Or nothing.

So the model is asked to predict your words, not recommend a step, and it's told to say nothing when unsure. That instruction explains most of my empty results below.

When Claude Code skips a suggestion

Before any request goes out, the code runs a chain of gates. Each one that fails logs a suppressed event with a reason name and stops. I took the order and thresholds from the bundle:

Three of these gates are more specific in the code than in the docs:

• Short conversations. The code wants at least two assistant messages. A one-shot question with no tool calls gets nothing. My "What is 2+2?" probe sent no suggestion request at all.
• Cold cache. If the last reply's uncached input plus output tokens passed 10,000, the reason is uncached. If adding the tokens written to cache crosses 10,000, the reason is cache_write, unless a server-side flag allows it. In practice, a turn that just read a large file into context won't get a suggestion.
• Usage limits. Anything other than an "allowed" rate-limit status skips the suggestion. Setting CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true keeps them on during the warning band, which the changelog says only works from 2.1.238. If you want to see where you are against the limit, I covered that in how to check your Claude Code usage limit.

The 12 filters that drop a suggestion

After the model replies, the code strips wrappers like <suggestion> or "Suggestion:" and runs the text through 12 checks in order. The first hit drops it. There's no retry and you see nothing.

Reason logged	Drops the text when
empty	Nothing came back
done	It is exactly "done" (or the Japanese, Chinese or Korean equivalent)
meta_text	"nothing found", "no suggestion", "silence", "stay silent"
meta_wrapped	The whole thing is in parentheses or brackets
error_message	Starts with "api error:", "prompt is too long", "invalid api key" and similar
prefixed_label	Starts with a word, a colon and a space
too_few_words	Under 2 words, unless it starts with / or is one of 17 words such as yes, ok, commit, push, deploy, continue
too_many_words	More than 12 words
too_long	100 characters or more
multiple_sentences	Punctuation, a space, then a capital letter
has_formatting	Contains a newline or an asterisk
evaluative / claude_voice	Praise or thanks anywhere in the text; or starts like Claude talking ("let me", "I'll", "here's", "this is", "you can", "sure,")

The last row is two separate checks I merged to keep the table short, and empty runs before the list, so the code has 12 filters plus the empty test. Reading the patterns, a few will catch reasonable prompts. The evaluative check is an unanchored substring match on words like "great", "nice" and "perfect", so "add a greater-than check" contains "great" and gets dropped. The prefixed_label check drops anything shaped like a conventional commit, such as "fix: handle empty input". The claude_voice check drops "this is wrong, revert it". I didn't get the model to produce those exact strings in my probes, so these are readings of the regular expressions, not observed drops.

The back-off: 20 unused, then 1 turn in 10

If you ignore 20 suggestions in a row, Claude Code shows "Showing fewer prompt suggestions · use one to bring them back" and from then on only generates a suggestion on every 10th eligible turn. Using one suggestion, or toggling the setting in /config, resets the streak. The counter is saved as promptSuggestionUnusedStreak in ~/.claude.json, next to firstStartTime, so it survives restarts.

Two details from the code aren't in the docs. The back-off only applies if your first Claude Code start was at least 14 days ago (the constant is 1,209,600,000 ms), so a new install always gets the full rate. And CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true turns the back-off off completely. The changelog dates the back-off to 2.1.283, so if you noticed suggestions thinning out in the last few weeks, this is why.

What 8 probe runs showed on my machine

My scheduled sessions run headless with claude -p, and the bundle disables suggestions there with the reason non_interactive. That means the 10 daily runs behind this blog have never paid for one. To see them I used the documented print-mode switch:

claude -p "Create a folder demo with a README.md ..." \
  --output-format stream-json --verbose --prompt-suggestions \
  --max-turns 6 --allowedTools "Bash Write Read" --debug-file dbg_8.txt

Each run that produces a suggestion emits one extra line after the result line, for example {"type":"prompt_suggestion","suggestion":"cat demo/README.md"}. Here are all 8 runs:

Task	Suggestion requests	Suggestion shown
Write and run a Fibonacci script	not logged	commit this
Count lines in .sh files	not logged	exclude count.sh itself from the count
What is 2+2?	0	none
Run a failing Python import	12	none
Write notes, offer 2 options, ask me to pick	9	none
Write and run FizzBuzz, then stop	9	none
Summarize /etc/hosts in one sentence	12	none
Create demo/README.md, list the folder	9	cat demo/README.md

The request counts are the problem. The debug log shows why: after each suggestion request finishes, every SubagentStop hook I have runs, because the fork counts as a subagent. One of them, from an older oh-my-claudecode plugin, returns additionalContext, and Claude Code sends that back as a new turn. That's the same loop I traced in Claude Code subagents not working, where it re-ran real subagents exactly 9 times. Here it hits background requests you never asked for. Six of the 8 runs also emitted the notice "A hook blocked the turn from ending 9 consecutive times", including both runs I didn't debug-log. Each repeat sends the whole conversation again, and the first suggestion request in each logged run took 0.7 to 1.6 seconds to return its first byte.

If you have any SubagentStop hook, check what it returns before blaming suggestions for your usage. The fix is in the hook: return nothing extra, or check stop_hook_active. My notes on Claude Code hooks not working cover how to read hook output, and Claude Code debug mode shows how to get the log with source=prompt_suggestion lines in it. I only tested print mode. I didn't confirm that interactive sessions repeat the same way, though they use the same forked-request code.

How to turn off Claude Code prompt suggestions

Any one of these works. They are checked in this order:

1. Environment variable. CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false wins over everything. Per the env-vars reference it needs 2.1.238 or later.
2. Server flag. If the feature flag hasn't reached your session (third-party providers, gateways, or the first run after an update), suggestions are off and the /config toggle is hidden.
3. Setting. Turn off "Prompt suggestions" in /config, which writes this to settings:

{
  "promptSuggestionEnabled": false
}

In print mode you don't need to do anything. Suggestions only appear there if you pass --prompt-suggestions with stream-json output.

Is the model the real customer?

The code can't settle the Hacker News question, but it shows what's recorded. Every skip logs an event named tengu_prompt_suggestion with the reason. In the SDK path, a shown suggestion logs whether it was accepted or ignored, how many milliseconds that took, and a "similarity" score that is just the ratio of the two text lengths, the suggestion and what you sent. Every chunk of the bundle also starts with a comment saying that code acceptance or rejection decisions "constitute Feedback under Anthropic's Commercial Terms" that "may be used to improve Anthropic's products, including training models." That comment is general, not specific to suggestions. What you can control is covered in Claude Code telemetry.

FAQ

How do I disable prompt suggestions in Claude Code?

Turn off Prompt suggestions in /config, or set "promptSuggestionEnabled": false in your settings file. To force it from the environment, set CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false, which overrides the setting and needs Claude Code 2.1.238 or later. Print mode (claude -p) never shows suggestions unless you pass --prompt-suggestions.

Why did Claude Code stop showing prompt suggestions?

Since 2.1.283, after you leave 20 suggestions in a row unused, Claude Code shows "Showing fewer prompt suggestions" and only generates one every 10th eligible turn. Using one suggestion resets it. Suggestions are also skipped when the prompt cache is cold, in plan mode, after an API error, near your usage limit, and when the reply fails one of 12 text filters such as being over 12 words.

Do Claude Code prompt suggestions use tokens?

Yes. Each suggestion is a background request to your session's model that counts toward plan usage or API cost, mostly as cache reads plus a few output tokens. If you have a SubagentStop hook that returns additionalContext, the request can repeat. In one test it repeated 9 to 12 times per suggestion.

Method: I read the JavaScript embedded in the Claude Code 2.1.291 binary on a Mac mini M4 running macOS 26.4.1 on October 10, 2026, specifically the prompt-suggestion module, its filter function and the back-off module. The prompt text, thresholds (2 assistant messages, 10,000 tokens, 2 to 12 words, 100 characters, 20 unused, 1 in 10, 14 days) and reason names above are copied from that code. I then ran 8 claude -p --prompt-suggestions sessions with Opus 5.5 in an empty directory, 6 of them with --debug-file, and counted source=prompt_suggestion requests and hook executions in the logs. Version dates come from the public changelog. The debug log doesn't record why a suggestion was dropped, so I can't say which filter removed the 4 empty results. I didn't test interactive sessions, other Claude Code versions or other models. Raw logs are in research/claude-code-prompt-suggestions-raw.