I Found a Hidden Feature in Claude Code Called Speculation

A fully built speculative execution system is sitting in the binary, waiting behind a server flag

I was poking around the Claude Code binary trying to figure out why prompt suggestions disappeared. I found something else entirely — a fully built speculative execution system that pre-runs predicted commands in the background before you hit Enter. As far as I can tell, nobody has written about this publicly.

---

How I Got Here

Prompt suggestions, the autocomplete feature where Claude predicts what you’ll type next, showed up in Claude Code for a few weeks, then vanished. I wanted to know why, so I went to the source: the binary itself.

For me, Claude Code lives at ~/.local/share/claude/versions/2.1.83. It’s a 199MB Mach-O arm64 executable — a Bun-based Single Executable Application with the JS bundle embedded. Variable names are minified but strings are fully intact and extractable.

I found the init function that gates prompt suggestions:

javascript

function vmT() {
  let _ = process.env.CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION;
  if (_ === "false") return !1;   // OFF
  if (_ === "1") return !0;       // ON — bypasses server gate
  if (!IT("tengu_chomp_inflection", !1)) return !1;  // server flag check
  // ...
}

There’s an env var escape hatch. Set `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=1` in `~/.claude/settings.json` and suggestions come back. Tab to accept and edit, Enter to accept and run.

So, I got the answer I was initially looking for, but I kept pulling the thread. Prompt suggestions feed into something bigger.

---

## Speculative Execution

Buried in the binary is a system called Speculation. Here’s every reference I extracted:

[Speculation] Starting speculation
[Speculation] Complete:
[Speculation] Accept
[Speculation] Aborting
[Speculation] Denied
[Speculation] Stopping at bash:
[Speculation] Stopping at file edit:
[Speculation] Stopping at denied tool:
[Speculation] Failed to create overlay directory
[Speculation] Failed to copy
[Speculation] Pipelined suggestion:
[Speculation] Promoting pipelined suggestion:
Speculation paused: bash boundary
Speculation paused: file edit requires permission
Write outside cwd not allowed during speculation
speculationSessionTimeSavedMs
totalSpeculationTimeSavedMs
tengu_speculation
querySource:"speculation"

The mechanism is straightforward. Claude finishes responding to your prompt. A suggestion is generated: suggestion text like “run the tests.” Then, without waiting for you to accept, Claude forks a background API call and starts executing that predicted prompt speculatively.

// After suggestion is generated and prompt suggestion is displayed:
if (Hnq() && K.suggestion)
  jnq(K.suggestion, _, _.toolUseContext.setAppState, !1, q)
//  ^ starts speculative execution of the predicted prompt

The speculation runs with querySource: "speculation" and forkLabel: "speculation", executing tools and collecting results while you’re still reading the suggestion.

The Overlay Filesystem

All file writes during speculation are redirected to an isolated sandbox:

// ~/.claude/speculation/<pid>/<speculation_id>/
let z = LmT(O);  // path.join(Hy(), "speculation", String(process.pid), _)
await nn.mkdir(z, { recursive: true });

On first write to any file, the original is copied to the overlay. All subsequent reads and writes for that path use the overlay copy. Your actual codebase is never modified during speculation.

If you accept the suggestion (hit Enter), overlay files copy back to the real filesystem and the speculated messages inject into your conversation:

if (q > 0) await eb$(f, O.current, pE());  // copy overlay → real FS
oo_(f);  // delete overlay directory

If you type something different, the overlay is deleted. Nothing happened.

N(`[Speculation] Aborting ${q}`);
K();  // abort the API call
oo_(LmT(q));  // rm -rf the overlay
return { ...T, speculation: Q8_ };  // reset to idle

---

Permission Tiers

Speculation doesn’t get carte blanche. Tools are divided into tiers:

// Freely allowed (read-only):
tb$ = new Set(["Read", "Glob", "Grep", "ToolSearch", "LSP", "TaskGet", "TaskList"]);

// Redirected to overlay:
sb$ = new Set(["Edit", "Write", "NotebookEdit"]);

During Speculation Read, Glob, Grep, ToolSearch, LSP, TaskGet, TaskListRuns freelyEdit, Write, NotebookEditRedirected to overlay; stops if not in acceptEdits modeBashRuns only if the command would already be auto-approved. Everything else, denied immediately, speculation halts.

When speculation hits a bash command that needs user approval, it creates a boundary and stops:

if (P.name === "Bash") {
  let W = "command" in D && typeof D.command === "string" ? D.command : "";
  if (!W || NmT({command: W}, IQ_(W)).behavior !== "allow")
    return N(`[Speculation] Stopping at bash: ${W.slice(0, 50)}`),
      cv_(q, () => ({boundary: {type: "bash", command: W, completedAt: Date.now()}})),
      R.abort(),
      VmT("Speculation paused: bash boundary", "speculation_bash_boundary");
}

Hard limits prevent runaway speculation:

ab$ = 20;   // max 20 tool-use turns
ob$ = 100;  // max 100 messages before forced abort

Writes outside the working directory are unconditionally blocked:

if (fG.isAbsolute(Z) || Z.startsWith("..")) {
  N(`[Speculation] Denied ${P.name}: path outside cwd: ${h}`);
  VmT("Write outside cwd not allowed during speculation", "speculation_write_outside_root");
}

Recursive Pipelining

When a speculation completes, it doesn’t stop. It immediately generates the next suggestion and starts speculatively executing that too:

if (w && _.pipelinedSuggestion) {
  let { text: k, promptId: X, generationRequestId: W } = _.pipelinedSuggestion;
  N(`[Speculation] Promoting pipelined suggestion: "${k.slice(0, 50)}..."`);
  jnq(k, h, q, true);  // isPipelined = true — recursive
}

Predict, execute, predict, execute. It tries to stay multiple steps ahead.

---

I Patched the Binary and Tested It

The gate function is hardcoded off:

Code omitted. Figure this one out yourself :)

This is controlled server-side by tengu_speculation, “Tengu” being Claude Code’s internal codename, with feature flags managed via Statsig/GrowthBook. There’s no env var override. No user-facing setting. The function just returns false.

So I patched it.

Omitting this code, too. Sorry :( 

For now, it’s not suggesting creative work. It’s suggesting the operational stuff: testing, committing, documenting, pushing. The things developers have to do but don’t want to do. The things that interrupt flow.

With auto-permissions and speculation working together, the picture is: you finish building a feature. The suggestion says “run the tests.” You hit Enter and the results are already there. It suggests “commit this.” Enter. Done. “Open a PR.” Enter. Done.

You stay in the creative work. Claude handles the pipeline in the background.

---

Telemetry Confirms This Is Being Measured

Every speculation emits structured telemetry:

F("tengu_speculation", {
  speculation_id: _,
  outcome: T,               // "accepted", "aborted", "error"
  duration_ms: Date.now() - q,
  suggestion_length: K,
  tools_executed: Ynq($),
  completed: O !== null,
  boundary_type: O?.type,    // "bash", "edit", "denied_tool", "complete"
  time_saved_ms: P,
  message_count: z.length,
  is_pipelined: j            // chained speculation?
});

Time saved is tracked cumulatively:

speculationSessionTimeSavedMs   // per-session
totalSpeculationTimeSavedMs     // lifetime

Acceptance rates. Boundary hit rates. Completion rates. Time saved per accepted speculation. This is all being instrumented. They’re measuring whether this delivers meaningful speedups before wider rollout.

This feature is likely still in testing. I’m excited for when they release it to the public!

---

I did most of this work at 3am over a couple of nights. If I got something wrong or missed something, let me know in the comments.