turnpack0.1.0

Try the demo · See an example · Set it up · The three tools · What it saves · Safety · FAQ

_{Drawn from the recorded runs in bench/results. One small task, three runs per arm: what that does and does not show.}

AI coding agents work in round trips: the model asks for something, waits, reads the result, and asks again. Each trip is a full model turn, a wait for the first token and then the tokens themselves. Today's apps already run independent reads side by side, so the trips that are left are the ones that depend on each other. A search has to come back before the agent knows which files to open. An edit has to land before the tests can run. And when the tests fail at the end, your repo is left half-edited while the agent spends more turns backing out.

Turnpack is a small local MCP server that gives the agent three tools to fold those trips together:

It runs entirely on your machine: no API keys, no account, no telemetry, no network calls, and zero runtime dependencies. It works with Claude Code and Claude Desktop, Codex CLI and the ChatGPT desktop app, OMP, Grok Build, Cursor, Gemini CLI, OpenCode and anything else that speaks MCP over stdio.

_{Both columns are the tool calls of those same recorded runs, not an illustration.}

Try it in 10 seconds

npx turnpack demo

This builds a throwaway repo in your temp folder, runs all three tools against it, and deletes it. Nothing in your own projects or AI app config is touched.

The recording is generated from the real output of those two commands (scripts/render-assets.py), so it cannot drift from what the tool does. doctor is run on a temporary home directory in which init has just set up five apps, which is why it lists them.

Want to run it straight from this repository instead of npm? npx github:OnlyTerp/turnpack demo

What it looks like

A rename that misses a call site is the classic way an agent breaks a build. Here is that mistake going through ship. The agent renames a function but forgets the file that imports it:

{
  "edits": [
    {
      "path": "src/tax.js",
      "search": "export function calculateTax(amount)",
      "replace": "export function computeTax(amount)"
    }
  ],
  "verify": "npm test"
}

FAILED_AND_ROLLED_BACK: verify "npm test" failed (exit code 1).

Restored 1 file(s) to byte-exact pre-edit snapshots. The workspace is unchanged; fix the edit and ship again.

$ npm test
> test
> node test/invoice.test.js

file:///home/you/shop/src/invoice.js:1
import { calculateTax } from "./tax.js";
         ^^^^^^^^^^^^
SyntaxError: The requested module './tax.js' does not provide an export named 'calculateTax'

The repo is exactly as it was, and the agent has the error that tells it what it missed. It ships again with both files:

{
  "edits": [
    {
      "path": "src/tax.js",
      "search": "export function calculateTax(amount)",
      "replace": "export function computeTax(amount)"
    },
    {
      "path": "src/invoice.js",
      "search": "calculateTax",
      "replace": "computeTax",
      "replace_all": true
    }
  ],
  "verify": "npm test"
}

SHIPPED_AND_VERIFIED in 170ms: 2 file(s) changed (src/tax.js, src/invoice.js).

$ npm test  (passed)
> test
> node test/invoice.test.js

ok - invoice total includes tax

Two turns, and at no point was the working tree broken. Both replies are real output, with Node's internal stack frames cut from the first and the project path shortened.

{
  "query": "calculateTax",
  "files": ["src/tax.js", { "path": "src/invoice.js", "symbol": "invoiceTotal" }, ".env"],
  "git_status": true
}

## GIT STATUS
## master

## SEARCH "calculateTax" (3 hits, engine=rg)
src/invoice.js:1: import { calculateTax } from "./tax.js";
src/invoice.js:4:   return Number((subtotal + calculateTax(subtotal)).toFixed(2));
src/tax.js:3: export function calculateTax(amount) {

## FILES (3)
### FILE: src/tax.js (L1-6/6)
1 | export const TAX_RATE = 0.08;
2 |
3 | export function calculateTax(amount) {
4 |   return Number((amount * TAX_RATE).toFixed(2));
5 | }
6 |

### SYMBOL: src/invoice.js :: function invoiceTotal (L3-5/6)
3 | export function invoiceTotal(subtotal) {
4 |   return Number((subtotal + calculateTax(subtotal)).toFixed(2));
5 | }

### FILE: .env
[REDACTED SECRET FILE: .env — pass allow_secrets: true if intentional]

Set it up

You need Node.js 22 or newer. Then:

npx turnpack init

npx turnpack doctor

init finds the AI apps you have installed, shows you exactly what it would change, and asks before writing. By default that is Claude Code, Claude Desktop, Codex (the CLI and the ChatGPT desktop app share one config), OMP and Grok Build.

• The entry it writes starts a file on your machine, with an absolute path to Node. That starts in tens of milliseconds, works offline, cannot change version without you, and does not depend on the PATH a desktop app happens to be given. If you ran init through npx, the server's files are first copied to ~/.turnpack/versions/<version>, because the npx cache gets cleaned. Prefer a portable entry? init --npx writes npx -y turnpack@<version> serve instead, pinned to the version.
• It then starts the server with that exact command and tells you whether it answered. An entry in a config file and an entry that works are different things.
• It is careful with your files. Every file it edits gets a .turnpack.bak copy, anything you added to an existing entry is kept, a config it cannot parse is left untouched, and the file's own indentation and line endings are preserved. It never adds rules to your CLAUDE.md or AGENTS.md. npx turnpack uninstall removes only what init added.
• It leaves room for slow tests. Codex and Grok Build give an MCP tool 60 seconds by default, which is also ship's default verify timeout. init sets the app's limit for Turnpack to 10 minutes so a long test run is not cut off by the app.

doctor checks the fences and then every app: it reads each app's config and starts the server exactly as that app would, so a stale path shows up as a failure there instead of as tools silently missing in a session. Restart your AI apps after init so they load the server.

Claude Desktop without a terminal. Each release carries turnpack.mcpb. Open it and Claude Desktop shows an install dialog and asks, with a folder picker, which project folder Turnpack may work in. It runs on the Node that ships inside Claude Desktop.

claude mcp add --scope user turnpack -- npx -y turnpack serve

{
  "mcpServers": {
    "turnpack": { "command": "npx", "args": ["-y", "turnpack", "serve"] }
  }
}

[mcp_servers.turnpack]
command = "npx"
args = ["-y", "turnpack", "serve"]

{
  "mcpServers": {
    "turnpack": {
      "command": "npx",
      "args": ["-y", "turnpack", "serve"],
      "env": { "TURNPACK_ROOT": "/path/to/your/project" }
    }
  }
}

npx turnpack init --client omp --yes

npx turnpack init --client cursor --yes

npx turnpack init --experimental --yes

Turnpack tells the agent when to use its tools through the MCP instructions field: about 230 tokens, the same on every session in a project. In Claude Code, which hides MCP tools behind a search step by default, Turnpack asks for its three tools to be loaded with the session, so the model can call them straight away. If your agent still reaches for one-file-at-a-time tools, docs/steering.md has an optional snippet for your rules file, an optional Claude Code hook, and a one-line way to log which tools were called.

The three tools

pack: gather context in one call

ship: edit, test, and undo if it fails

Every edit is checked before anything is written: a problem in file five means files one to four are never touched. All the problems come back in one reply, each with the closest text in the file, its line numbers and the first line that differs, so the next attempt needs no re-read:

ABORTED_BEFORE_WRITE: src/invoice.js (edits[1]): search text not found. The closest text is lines 3-5 (2 of 3 line(s) identical apart from indentation):
  3 | export function invoiceTotal(subtotal) {
  4 |   return Number((subtotal + calculateTax(subtotal)).toFixed(2));
  5 | }
First difference, at line 4:
  search has: "  return subtotal + calculateTax(subtotal);"
  file has:   "  return Number((subtotal + calculateTax(subtotal)).toFixed(2));"

Nothing was written.

If the server finds your project's check command (a test or typecheck script in package.json, cargo check, go test, pytest, a make test target), it tells the model at the start of the session, so verify is not left out for want of knowing what to run.

The reply always starts with what is true on disk now:

SHIPPED_AND_VERIFIED · APPLIED_NO_VERIFY · ABORTED_BEFORE_WRITE · FAILED_AND_ROLLED_BACK · FAILED_ROLLBACK_PARTIAL · FAILED_KEPT_ON_DISK

When verify fails, the agent gets the beginning and the end of the output, because test failures are reported at the end. When it passes, it gets a few lines, because nobody needs 800 lines of green.

batch: one script instead of forty reads

// Which source files still import the old module, and how many functions does each have?
const hits = await ctx.grep("from \"./legacy", { literal: true });
const files = [...new Set(hits.map((h) => h.relPath))];
return files.map((f) => ({ file: f, functions: ctx.outline(f).length }));

The script gets ctx.files(glob), ctx.read(path, start, end), ctx.outline(path), await ctx.grep(pattern) and await ctx.gitStatus(). It cannot write files, start processes, or see your environment variables. See Safety for how that is enforced.

How much does it save?

First, what your app already does. We read the source and documentation of Claude Code, Codex, OMP and Grok Build (docs/baselines.md). All four run independent calls in parallel, so none of them makes one tool call per round trip, and pack saves less than a naive count would suggest. Codex and OMP can already edit several files in one call. What none of the four has is a step that edits, runs the check, and puts every file back when the check fails. That is ship.

Then, a measurement. One task (rename a function used in five files, then make the tests pass), run through Claude Code 2.1.280 with Claude Sonnet 5, three times per arm, with nothing in the prompt about Turnpack:

Each figure is the median of three runs; the per-run numbers are in bench/results/2026-11-13-claude-code.json, and the charts on this page are drawn from that file. With Turnpack every run was the same three round trips: one pack (a search with three lines of context), one ship that made nine edits in five files and ran npm test, one closing message. The model chose those tools unprompted in all three runs.

Read it with these in mind:

• It is one small task, one model, three runs per arm. It shows the direction and that the model reaches for the tools. It is not a benchmark of your work. Bigger tasks have more round trips of thinking that no tool removes.
• The built-in arm was already batching. Its 13 tool calls took 6 round trips, with up to 9 calls in one. Asking it to batch harder changed nothing. The saving came from the dependent steps: search then read, and edit then test.
• Other apps: less evidence. In Codex CLI 0.166, three runs out of three used pack and then one ship carrying all five edits and the test. We have no Codex comparison without Turnpack: on the test machine its shell sandbox could not start processes in the scratch directory, so that arm could not run the tests at all. OMP and Grok Build were not measured.

Run it on your own setup. It costs a few cents per run:

npm run bench:agents -- --agents claude,codex --arms native,turnpack --runs 3

bench/agent-bench.mjs builds a throwaway project for every run, hands Turnpack to the CLI through a flag, and leaves your own configs alone. If your result differs, including "no gain", please open an issue with it.

A way to estimate your own case

time saved per task = round trips avoided × (time to first token + tokens per turn ÷ tokens per second)

The chart models one scenario, a task that would take 16 round trips done in 4, across five latency profiles. That scenario is an agent that makes one tool call per round trip. None of the apps above works that way by default, so treat it as the upper end and put your own round-trip counts into the calculator:

Read it with these in mind:

• The turn counts are an assumption, not a measurement. Agents that already issue tool calls in parallel make fewer round trips for reads to begin with: 6 rather than 13 in the run above. With those, expect less from pack and most of the gain from ship, because no built-in tool edits, tests and rolls back in one turn.

• The latency numbers are examples. Yours are easy to measure, and both the CLI and the interactive calculator take them as input:

  npx turnpack estimate --ttft 2 --tok-per-turn 300 --tps 40
  

• It does not count the turns an agent spends repairing a half-applied edit, which is the cost ship exists to remove.

The formula and every default are written out in docs/time-calculator.md. The benchmark protocol (native tools, native tools plus a batching prompt, and native tools plus Turnpack, on the same model and task) and how to read its output are in bench/README.md.

What Turnpack itself costs

These are measured, by npm run bench and npx turnpack doctor --json on Linux x64 with Node 22.23:

Safety

An agent that can edit files and run commands deserves fences. These are the ones Turnpack puts up, and where each one ends.

Each fence has tests that attack it: sandbox escapes, path traversal, symlink escapes, Windows path aliases, allowlist smuggling, argument injection, runaway regexes, rollback under a kill signal, a save made while the tests run. They are in test/, and npx turnpack doctor re-checks the main ones on your machine. The full threat model is in SECURITY.md.

When you don't need it

• A one-line fix in a file the agent already has open. One edit is one edit; there is nothing to fold.
• Pasting a whole repository into a chat window. That is what Repomix is for. Turnpack is for an agent working inside a repo, a slice at a time.
• A project with no fast check. ship earns its keep when a test, type check or build takes seconds. Without a verify it is a multi-file edit with validation and nothing more.

FAQ

My agent already reads several files in parallel. What does pack add? Less than it would for an agent that does not, and all four apps in docs/baselines.md do. Parallel calls remove round trips for reads the model already knows it wants. What they cannot remove is the trip between a search and the reads it leads to, which pack folds into one call with context. It also caps the reply size, redacts secrets, and behaves the same in apps and with models that do not parallelize. If your agent batches reads well, you will mostly notice ship.

Codex and OMP can already edit several files in one call. What does ship add there? The test run in the same call, and putting every file back when it fails or when a write fails part-way. ship takes Codex's own patch format, so the model does not have to change how it writes edits to get that.

Will the model actually use these tools? In the runs we measured, yes: Claude Code with Sonnet 5 and Codex CLI each chose pack and ship in three runs out of three, with nothing in the prompt about them. That is two apps, one task and default settings, so it is evidence and not a guarantee. An install with other tools or rules that push the model elsewhere may behave differently; one heavily customised OMP setup we tried solved the task without touching Turnpack. TURNPACK_LOG tells you what your own agent does, and docs/steering.md covers the optional ways to push harder.

Why not git stash or git checkout to roll back? ship works without git, never touches your index, staging area or unrelated uncommitted changes, restores only the files it changed, and removes the files it created.

Is batch a sandbox? It is two layers. The script gets a tiny API and no host objects, and it runs in a process that Node itself refuses to let write, spawn or read outside the workspace. Node documents its permission model as a safety net against trusted code doing something unintended rather than a defence against deliberately malicious code, and we describe ours the same way. SECURITY.md says exactly what is and is not blocked.

Does it send anything anywhere? No. There is no network code in the server. ship runs the verify command you or the agent names, and that command can do whatever your shell can.

Does it work on Windows? Yes, natively. CI runs the full suite on Windows, macOS and Linux. Timed-out verify commands are stopped with taskkill /T, and paths are checked across drive letters.

Prior art

Turnpack builds on ideas from Anthropic's programmatic tool calling, Cloudflare's Code Mode, context-mode, Repomix and Serena. Its own angle is narrow: three tools, a small schema, and edits that are tested before they are allowed to stay.

More

• Recipes: multi-file rename, verify allowlist, native Windows, when not to use it
• Steering your agent toward the tools
• App compatibility matrix
• What Claude Code, Codex, OMP and Grok Build already do without Turnpack
• Time model and calculator · interactive version
• Benchmarks: engine timings and the agent comparison
• Security policy · Contributing · Changelog

License

Apache License 2.0. You may use, change and redistribute Turnpack, including in commercial products. If you redistribute it, with or without changes, keep the license and the NOTICE file with it and say which files you changed. The license grants no right to use the Turnpack name or logo, beyond saying where the software came from.