Skip to content
Back to search

prewalk

MarketplaceWorks with Claude CodeGitHub

Dual-host prewalk plugin for Codex and Claude Code: one engine, trajectory-inheritance handoff (fork_turns=all), durable v4 checkpoints

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tardisbooo--prewalk/badge.svg)](/listings/tardisbooo--prewalk)

HTML

<a href="/listings/tardisbooo--prewalk"><img src="/api/listings/tardisbooo--prewalk/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requirements

- Python 3.10+ - Codex CLI 0.146.0+ **or** Claude Code 2.1.145+

Install

This repository is the plugin marketplace. Add the catalog, then install the plugin — the same two-step flow as other Claude Code / Codex marketplace plugins. There is no project-scaffold `/setup` step. After a restart, arm a planner session with `prewalk`. From a local clone, pass the checkout path instead of `TardisBooo/prewalk`.

**Claude Code** — in a session:

/plugin marketplace add TardisBooo/prewalk
/plugin install prewalk@prewalk

Same steps from a shell:

claude plugin marketplace add TardisBooo/prewalk
claude plugin install prewalk@prewalk

**Codex** — from a shell (`plugin add`, not `plugin install`):

codex plugin marketplace add TardisBooo/prewalk
codex plugin add prewalk@prewalk-marketplace

The name after `@` is the marketplace id: `prewalk` on Claude Code, `prewalk-marketplace` on Codex. Restart the CLI. Copy `hosts/claude/presets.example.json` to `~/.claude/prewalk-presets.json` (or `hosts/codex/presets.example.toml` to `~/.codex/prewalk-presets.toml`) only if you need custom executor routes. Confirm with `pw-doctor`, then in the session you want as planner:

$prewalk:prewalk Add a settings page with tests    (Codex)
/prewalk:prewalk Add a settings page with tests    (Claude Code)

Three steps to a run

1. **Arm** with the `prewalk` command above and let the planner work: explore, plan, complete and verify task 1, then stop. 2. **Review** the persisted checkpoint — or arm with `--fast` to release it automatically (checkpoint validation is identical either way). 3. **Hand off** with `pw-go`. The executor finishes the remaining tasks and ends with exactly one marker; `pw-status` always shows the phase and the one recommended next command.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "prewalk",
  4. "owner": {
  5. "name": "TardisBooo"
  6. },
  7. "metadata": {
  8. "description": "Prewalk for Claude Code — frontier explores + plans + lands the first edit, then hands off to a cheaper executor subagent"
  9. },
  10. "plugins": [
  11. {
  12. "name": "prewalk",
  13. "description": "Frontier model explores, plans, and lands the first verified edit, then hands a token-bound handoff to a configured executor agent.",
  14. "version": "1.0.9",
  15. "author": {
  16. "name": "TardisBooo"
  17. },
  18. "source": "./hosts/claude",
  19. "category": "workflow",
  20. "tags": ["prewalk", "model-routing", "cost", "planner", "executor"]
  21. }
  22. ]
  23. }
README.md · README · 369 lines
  1. <div align="center">
  2. # prewalk
  3. **Let the frontier model make the one edit that matters — then hand the verified start to a cheaper executor.**
  4. _One engine · Two native hosts · Durable checkpoints · Verified executor routing_
  5. [![CI](https://github.com/TardisBooo/prewalk/actions/workflows/check.yml/badge.svg)](https://github.com/TardisBooo/prewalk/actions/workflows/check.yml)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-32CD32.svg)](LICENSE)
  7. ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
  8. ![Codex CLI](https://img.shields.io/badge/Codex%20CLI-0.146%2B-8A2BE2)
  9. ![Claude Code](https://img.shields.io/badge/Claude%20Code-2.1.145%2B-D97757)
  10. **English** | [简体中文](README.zh-CN.md)
  11. </div>
  12. ---
  13. ## 📋 Quick Navigation
  14. [What is prewalk?](#-what-is-prewalk) ·
  15. [Where it comes from](#-where-it-comes-from) ·
  16. [What we built](#-what-we-built) ·
  17. [Benchmark](#-benchmark) ·
  18. [Quick Start](#-quick-start) ·
  19. [Commands](#-commands) ·
  20. [Presets](#-presets) ·
  21. [Development](#-development)
  22. ---
  23. ## 🚶 What is prewalk?
  24. Prewalk is a two-phase cost structure for coding agents. A frontier **planner** (your active
  25. session) does the most expensive part of a change — understanding the repository, writing a
  26. bounded plan, and completing **and verifying** task 1. A cheaper **executor** then finishes the
  27. remaining tasks from that verified start:
  28. ```text
  29. planner: explore -> bounded plan -> complete & verify task 1 -> root Stop checkpoint
  30. |
  31. review with pw-go, or auto-release with --fast
  32. |
  33. executor: inherit the trajectory (or a structured packet) -> finish the rest -> verify -> PREWALK_COMPLETE / PREWALK_INCOMPLETE
  34. ```
  35. Reach for prewalk when *understanding the repository is a real part of the work* — new features
  36. that must follow existing patterns, cross-cutting refactors, changes gated on tests you have to
  37. discover first. A one- or two-file fix does not need it.
  38. ## 🧭 Where it comes from
  39. The technique was proposed by **Can Bölük** (Stencil Labs) in
  40. ["You only need the frontier model for one single edit"](https://stencil.so/blog/prewalk),
  41. based on a token-distribution analysis of ~2 million agent tool calls: the frontier model earns
  42. its price during planning and the first edit, and the remaining edits do not need it. The post
  43. ships the idea as `/prewalk` and `/plan` modes for a pi-lineage harness, and it is implemented
  44. natively in [oh-my-pi](https://github.com/can1357/oh-my-pi); the community has since ported it
  45. to other coding agents, including
  46. [Codex CLI](https://github.com/TerenceLiu98/prewalk),
  47. [OpenCode](https://github.com/Daniel-97/opencode-prewalk),
  48. [Hermes](https://github.com/ildunari/hermes-prewalk), and Claude Code hooks.
  49. This repository is an independent, dual-host implementation of the technique for
  50. **Codex CLI** and **Claude Code**.
  51. The rest of this page describes how to use it and what we adapted for these two hosts.
  52. ## ⚙️ How a run works
  53. 1. **Arm** — in your planner session, run the `prewalk` command with the task. The plugin
  54. persists a run record and returns the planning protocol (real todos only).
  55. 2. **Plan and verify** — the planner explores, plans, and completes task 1 with real
  56. verification. When it stops, the Stop hook validates the checkpoint (todo quality, packet
  57. structure, verification evidence) and persists it atomically.
  58. 3. **Review** — inspect the checkpoint, or pass `--fast` to skip human review (validation is
  59. identical). `pw-revise` sends it back for changes.
  60. 4. **Hand off** — `pw-go` probes the host's real capabilities, mints exactly one route token,
  61. and spawns the executor. A pinned Codex executor starts with the persisted packet.
  62. Claude Code starts a scoped subagent with the same packet.
  63. 5. **Finish** — only the bound executor's stop event with a `PREWALK_COMPLETE` /
  64. `PREWALK_INCOMPLETE: <reason>` marker ends the run. Anything else leaves a recoverable,
  65. explicitly reported state with exactly one recommended next command.
  66. ## 🛠️ What we built
  67. ### 1. Handoff context
  68. Codex exposes `fork_turns` or the equivalent boolean `fork_context` depending on its version.
  69. When the live schema accepts an explicit model, Prewalk starts a fresh executor with the
  70. verified packet so it can select the configured model. When a preset allows routing without
  71. model selection, the context setting applies:
  72. - **`fork_turns: "all"`** — the executor inherits the planner's full turn history.
  73. The exploration, the todo list, and the already-verified first edit are in its context, and
  74. the handoff message is a short phase-2 note. The executor does not re-read files.
  75. - **`fork_turns: "none"`** — fresh-context handoff seeded with the
  76. full structured packet, for when you want a minimal executor context.
  77. The packet is always captured and persisted for recovery and audit; with fork handoff it is no
  78. longer the executor's primary context. On our benchmark (below) fork handoff is the only arm
  79. that beat a frontier one-shot on both cost and duration at equal pass rate.
  80. ### 2. One engine, two native adapters
  81. ```text
  82. prewalk_engine/ host-independent engine (stdlib only)
  83. protocol frozen names, limits, todo rules (imports nothing local)
  84. store cross-process lock + atomic JSON persistence
  85. records v4 record types + transition kernel (event-idempotent)
  86. checkpoint / routing / operations the three v4 workflows
  87. presets / capabilities configuration + host capability probing (fail-closed)
  88. prompts / legacy model-facing copy (leaves) + frozen 0.3 event machine
  89. hosts/codex/ native spawn_agent route validation, CODEX_THREAD_ID identity, shell wrappers
  90. hosts/claude/ token-bound Agent PreToolUse rewrite, subagent lifecycle binding
  91. ```
  92. The engine never imports a host; adapters only normalize payloads and render hook output. Each
  93. adapter vendors a byte-identical engine copy (`scripts/sync_engine.py --check` enforces this in
  94. CI), so the plugin installed from either marketplace is self-contained, and both hosts share
  95. one tested state machine.
  96. ### 3. Checkpoint reject-retry loop
  97. When root Stop validation fails (unqualified todos, missing packet sections, no verification
  98. evidence), the plugin records the reason and attempt count (limit 3) and **blocks the stop**
  99. with the exact defect. The planner repairs its todo list or packet in place and stops again —
  100. no manual re-prompting, and both hosts behave identically.
  101. ### 4. Planner mutation budget
  102. Every successful planning-phase file mutation is counted. From the sixth mutation the model
  103. receives an explicit nudge to finish planning; past the limit (twelve) the nudge instructs it
  104. to stop coding and hand off. The budget never edits files or blocks a tool call — it is model
  105. guidance backed by durable counters, so the planner keeps control of its own edits while
  106. prewalk keeps its cost structure intact.
  107. ### 5. Durable v4 state machine
  108. Six phases — `planning / checkpoint_ready / handoff_requested / executor_running /
  109. incomplete / stale` — with `idle` meaning "no record". Every transition has exactly one owner;
  110. repeated and out-of-order events are idempotent no-ops. Records are written atomically under a
  111. cross-process lock; corrupt records are quarantined; unknown schema versions fail closed and
  112. are left untouched. Each handoff mints a one-time random route token that may bind at most one
  113. tool-use ID and one agent ID — foreign, nested, or parallel subagent events are ignored. A
  114. timeout enters `stale` but never kills or clears an unknown agent; `pw-reconcile` requires
  115. proof that the bound agent is no longer live.
  116. <details>
  117. <summary><b>Phase reference</b></summary>
  118. | Phase | Meaning | Valid user action |
  119. | --- | --- | --- |
  120. | `planning` | Root session is exploring, planning, completing task 1. | Continue, or `pw-off`. |
  121. | `checkpoint_ready` | Valid checkpoint persisted; review pending. | `pw-go`, `pw-revise`, `pw-off`. |
  122. | `handoff_requested` | Route token minted; spawn not yet bound. | Complete the spawn, `pw-retry`, `pw-off`. |
  123. | `executor_running` | Native agent ID bound. | Wait, inspect with `pw-status`, reconcile after interruption. |
  124. | `incomplete` | Route ended without a complete result; retryable from the checkpoint. | `pw-retry`, `pw-revise`, `pw-off`. |
  125. | `stale` | Timeout/restart left an ambiguous route. | `pw-reconcile`, then as reported. |
  126. </details>
  127. ### 6. Fail-closed capability probing
  128. `pw-go` probes the host's live capability before minting a route: on Codex it checks the live
  129. `spawn_agent` schema for `model`, its live fork control, and `reasoning_effort` (a missing
  130. required field keeps the checkpoint and refuses the route); on Claude Code a PreToolUse rewrite guarantees
  131. the scoped executor type and model, and a conflicting `CLAUDE_CODE_SUBAGENT_MODEL` refuses the
  132. arm (`override-conflict`). With `require_model_routing = true`, prewalk never spawns on a
  133. route it could not prove.
  134. ## 📊 Benchmark
  135. 13 SWE-bench Verified instances (sympy×7, django×4, sphinx×2; each task base-verified to fail
  136. and gold-verified to pass in its own py3.9 venv), 5 arms, 65 real runs (~14 h).
  137. Planner = gpt-5.6-sol (medium), executor = gpt-5.6-luna (low); Windows 11, Codex CLI 0.152.1.
  138. | Arm | Description | Pass | Cost / task | Time / task |
  139. | --- | --- | --- | --- | --- |
  140. | `oneshot_luna` | cheap model one-shot (lower bound) | 12/13 (92.3%) | $0.023 | 437s |
  141. | `oneshot_sol` | frontier one-shot (upper bound) | 13/13 (100%) | $0.182 | 522s |
  142. | `packet` | document handoff, fresh executor context | 13/13 | $0.177 | 925s |
  143. | **`fork`** | **trajectory inheritance + short note** | **13/13** | **$0.152** | **743s** |
  144. | `plan` | plan-document handoff | 13/13 | $0.176 | 763s |
  145. Paired comparisons over the 13 shared instances:
  146. - **fork vs packet: −14.3% cost ($1.98 vs $2.31), −19.6% wall time (9665s vs 12030s)**
  147. - **fork vs oneshot_sol: −16.4% cost** at equal pass rate
  148. - plan vs oneshot_sol: −3.0%
  149. The saving is concentrated in the executor phase: executor output tokens drop from 24487 to
  150. **9046 (−63%)** and executor time from 3456s to **2119s (−39%)** — the executor finishes the
  151. work instead of re-reading the repository. Behavioral evidence (sympy-24213, fork executor's
  152. first message): *"There are no remaining planned tasks—the single source fix was completed and
  153. verified. I'm rerunning the relevant unit tests once more."*
  154. **Honest boundaries.** When a task is easy enough for the cheap model alone (92.3% of this
  155. subset), a cheap one-shot is still the best unit economics ($0.023/task). Prewalk pays off in
  156. the mid-to-hard band where you need the frontier's pass rate but want to cut its bill. This
  157. subset's pass-rate ceiling was reached by the frontier one-shot, so the pass dimension does
  158. not discriminate; timings include network noise; costs are computed from list prices.
  159. ## ❓ Quick Q&A
  160. **Q: Does prewalk switch my session's model?**
  161. A: **No.** The active root session is always the planner; prewalk never changes, replaces, or
  162. "restores" its model. Presets configure the *executor* only.
  163. **Q: What if the executor fails or is interrupted?**
  164. A: The run enters `incomplete` (or `stale` when liveness is unknown) with exactly one
  165. recommended command — `pw-retry` respawns from the same checkpoint, and task 1 is never
  166. repeated. Unknown agents are never killed automatically.
  167. **Q: Does the handoff survive compaction, restart, or resume?**
  168. A: Yes. The checkpoint packet, todos, and evidence are persisted at Stop, not kept in
  169. conversation memory; any later command reads the durable record.
  170. **Q: What does the planner do to my todo list?**
  171. A: Real work items only, each with a stable ID and a verification criterion — no control
  172. pseudo-todos. Planning mutations beyond the budget trigger explicit nudges to hand off.
  173. ## 🚀 Quick Start
  174. ### Requirements
  175. - Python 3.10+
  176. - Codex CLI 0.146.0+ **or** Claude Code 2.1.145+
  177. ### Install
  178. This repository is the plugin marketplace. Add the catalog, then install the
  179. plugin — the same two-step flow as other Claude Code / Codex marketplace
  180. plugins. There is no project-scaffold `/setup` step. After a restart, arm a
  181. planner session with `prewalk`. From a local clone, pass the checkout path
  182. instead of `TardisBooo/prewalk`.
  183. **Claude Code** — in a session:
  184. ```text
  185. /plugin marketplace add TardisBooo/prewalk
  186. /plugin install prewalk@prewalk
  187. ```
  188. Same steps from a shell:
  189. ```sh
  190. claude plugin marketplace add TardisBooo/prewalk
  191. claude plugin install prewalk@prewalk
  192. ```
  193. **Codex** — from a shell (`plugin add`, not `plugin install`):
  194. ```sh
  195. codex plugin marketplace add TardisBooo/prewalk
  196. codex plugin add prewalk@prewalk-marketplace
  197. ```
  198. The name after `@` is the marketplace id: `prewalk` on Claude Code,
  199. `prewalk-marketplace` on Codex. Restart the CLI. Copy
  200. `hosts/claude/presets.example.json` to `~/.claude/prewalk-presets.json` (or
  201. `hosts/codex/presets.example.toml` to `~/.codex/prewalk-presets.toml`) only if
  202. you need custom executor routes. Confirm with `pw-doctor`, then in the session
  203. you want as planner:
  204. ```text
  205. $prewalk:prewalk Add a settings page with tests (Codex)
  206. /prewalk:prewalk Add a settings page with tests (Claude Code)
  207. ```
  208. ### Three steps to a run
  209. 1. **Arm** with the `prewalk` command above and let the planner work: explore, plan, complete
  210. and verify task 1, then stop.
  211. 2. **Review** the persisted checkpoint — or arm with `--fast` to release it automatically
  212. (checkpoint validation is identical either way).
  213. 3. **Hand off** with `pw-go`. The executor finishes the remaining tasks and ends with exactly
  214. one marker; `pw-status` always shows the phase and the one recommended next command.
  215. ## 🧭 Commands
  216. | Action | Codex | Claude Code |
  217. | --- | --- | --- |
  218. | Arm | `$prewalk:prewalk <task>` | `/prewalk:prewalk <task>` |
  219. | Review & hand off | `$prewalk:pw-go` | `/prewalk:pw-go` |
  220. | Revise the plan | `$prewalk:pw-revise <changes>` | `/prewalk:pw-revise <changes>` |
  221. | Inspect state | `$prewalk:pw-status` | `/prewalk:pw-status` |
  222. | Diagnose host & config | `$prewalk:pw-doctor` | `/prewalk:pw-doctor` |
  223. | Retry a failed attempt | `$prewalk:pw-retry` | `/prewalk:pw-retry` |
  224. | Resolve an ambiguous route | `$prewalk:pw-reconcile` | `/prewalk:pw-reconcile` |
  225. | Disarm | `$prewalk:pw-off` | `/prewalk:pw-off` |
  226. | Manual model-compat route | `$prewalk:pw-resume` | `/prewalk:pw-resume` |
  227. `--preset <name>` selects a preset; `--fast` (formerly `--no-pause`) skips human review only —
  228. checkpoint validation and route confirmation are never skipped.
  229. ## 🔧 Presets
  230. | Host | Preset file | Format |
  231. | --- | --- | --- |
  232. | Codex | `~/.codex/prewalk-presets.toml` | TOML |
  233. | Claude Code | `~/.claude/prewalk-presets.json` | JSON |
  234. `CODEX_HOME` / `CLAUDE_CONFIG_DIR` relocate presets and state files wholesale.
  235. `PREWALK_STATE_FILE` overrides only the state file and must be an absolute writable path;
  236. this is useful when the project sandbox cannot write to the host config directory. Arm only
  237. succeeds after it prints `PREWALK ARMED`; otherwise fix the reported permission or preset error
  238. before continuing. Templates:
  239. [hosts/codex/presets.example.toml](hosts/codex/presets.example.toml),
  240. [hosts/claude/presets.example.json](hosts/claude/presets.example.json).
  241. | Field | Meaning |
  242. | --- | --- |
  243. | `executor` | Host-resolvable executor model |
  244. | `max_todos` | Cap on real work items in the plan |
  245. | `executor_effort` | Effort requested when the host exposes per-spawn control |
  246. | `handoff_mode` | `auto` / `spawn` / `manual-model` |
  247. | `require_model_routing` | `true` refuses spawns that cannot pin the model |
  248. | `fork_turns` | Codex without model selection: `"all"` inherits context and `"none"` uses the packet |
  249. ```toml
  250. default_preset = "code-value"
  251. [presets.code-value]
  252. executor = "gpt-5.6-terra"
  253. max_todos = 12
  254. executor_effort = "medium"
  255. handoff_mode = "auto"
  256. require_model_routing = true
  257. ```
  258. Quote Codex TOML table names that contain periods, for example
  259. `[presets."grok-4.6"]`. On Codex surfaces without a native plan/todo tool, put
  260. the complete todo snapshot in the Handoff Packet as a strict Markdown checkbox
  261. list; the Stop hook validates and persists that fallback.
  262. Presets configure the executor only. Legacy `planner` / `planner_thinking` fields are ignored
  263. with a deprecation warning; `executor_thinking` is accepted as a deprecated alias of
  264. `executor_effort`.
  265. ## 💻 Development
  266. Python 3.10+ standard library only.
  267. ```sh
  268. ./scripts/check.sh
  269. ```
  270. covers: unit and end-to-end tests (99 passing — state machine, routing, host adapters,
  271. subprocess-driven lifecycles), static contracts, vendored-engine byte identity, JSON manifest
  272. validation, shell entry checks, and install smoke tests. CI runs on Linux/macOS × Python
  273. 3.11–3.14 plus a native-contract matrix against minimum and latest Claude Code and Codex CLIs.
  274. - Engine layering and invariants: [docs/adr/0001-v4-native-workflow.md](docs/adr/0001-v4-native-workflow.md)
  275. - Host specifics: [Codex](hosts/codex/README.md) · [Claude Code](hosts/claude/README.md)
  276. - Local benchmark recorder: `python3 scripts/benchmark.py record|report`
  277. - History: [CHANGELOG.md](CHANGELOG.md) · Upgrades: [MIGRATION.md](MIGRATION.md)
  278. ## 📄 License and credits
  279. MIT — see [LICENSE](LICENSE).
  280. The prewalk technique comes from Can Bölük's post
  281. ["You only need the frontier model for one single edit"](https://stencil.so/blog/prewalk)
  282. (Stencil Labs). This repository is a dual-host refactor of the
  283. [TerenceLiu98/prewalk](https://github.com/TerenceLiu98/prewalk) v4 prototype: one engine with
  284. two host adapters, trajectory inheritance where the host allows it, and the reject-retry
  285. loop and planner mutation budget on both hosts.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.