Part of Promptbook
ptbk coder drives Claude Code, OpenAI Codex, Gemini CLI and other coding agents through a queue of plain-markdown prompts. It runs your tests after every task, commits what passes and pushes it. You do not have to be at the keyboard for any of it.
$ npm install ptbkptbk coder reads the PRD markdown files in prompts/ and works through them one at a time. You choose the harness and start the run. Come back to commits that already passed your tests, instead of a chat window full of questions.
No babysitting
Put your PRD markdown files in prompts/ and start a run. ptbk coder implements each task, runs the checks you configured, feeds every failure back to the agent, and commits before it moves to the next one.
No vendor lock-in
The behavior of the agent lives in a .book file you commit next to the code, not in one vendor prompt box. Change --harness and the same queue runs on Claude Code or OpenAI Codex. With opencode you point it at whatever provider you configured, local models included.
One source of truth
When a task passes, ptbk coder writes its [x] into the PRD and puts that line in the same commit as the code it describes. Revert the commit and the checkbox goes back to [ ] together with the code.
ptbk coder ships with the ptbk package. Install it in your project (or globally with -g).
$ npm install ptbkCreates the prompts/ queue, prompts/done/ archive, the default agents/developer.book persona, AGENTS.md project context, and the agent git identity entries in .env.
$ ptbk coder initptbk coder add writes one ready-to-run markdown file into prompts/ for you. Describe the task the same way you would prompt Claude Code or Codex, in plain language and as specific as you like. Pipe in a heredoc for longer descriptions, or run it with no arguments and type one interactively.
$ ptbk coder add "Add a dark mode toggle to the settings page"Pick a harness and let it work. It implements one prompt, verifies it, commits it, then starts the next one. Add --dry-run first if you only want to see what the queue would do.
$ ptbk coder run --harness claude-codeptbk coder server never stops. It watches prompts/ for new files and serves a Trello-style kanban board at localhost:4441, where you can follow progress and edit prompts in the browser.
$ ptbk coder server --harness claude-code --model fable --thinking-level max --agent agents/developer.book --context AGENTS.md --test npm run testEvery run can carry an agent written in the Book language, Promptbook's human-readable language for defining AI agents. Its rules, its persona and what it knows live in one .book file, and ptbk coder compiles that file into the system message of every coding prompt.
Point ptbk coder at any agent file with --agent:
$ ptbk coder run --harness claude-code --model fable --agent agents/developer.book --context AGENTS.mdptbk coder init creates this default developer agent at agents/developer.book. Edit it like any other file in your repository to change how your agent codes.
readonly preview of agents/developer.book
ptbk coder does not replace your coding agent. It drives it. Pick a harness with --harness, add a --model if you want one, and for the harnesses that support it a --thinking-level (low, medium, high, xhigh, max).
by Anthropic
The agentic CLI by Anthropic. ptbk coder drives it through your whole prompt queue, with thinking levels up to max.
Models: fable, opus, sonnet, haiku
$ ptbk coder run --harness claude-code --model fable --thinking-level maxby OpenAI
The OpenAI Codex CLI. It needs an explicit model, and it only spends credits beyond your rate limits when you pass --allow-credits.
Models (required): gpt-5.2-codex, default
$ ptbk coder run --harness openai-codex --model gpt-5.6-terraby GitHub
GitHub Copilot in your terminal. Works out of the box with your Copilot subscription and supports thinking levels.
Models: gpt-5.4
$ ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhighby Google
The Google Gemini CLI. It needs an explicit model, such as one of the fast flash previews.
Models (required): gemini-3-flash-preview, default
$ ptbk coder run --harness gemini --model gemini-3-flash-previewby opencode
The open-source terminal coding agent. Bring any provider configured in your opencode installation.
Uses the models configured in the harness itself.
$ ptbk coder run --harness opencodeby Cline Bot Inc.
The Cline CLI agent. Uses the models configured in your Cline setup.
Uses the models configured in the harness itself.
$ ptbk coder run --harness clineThe agent writes the code. ptbk coder does the rest: it runs your tests, commits, pulls and pushes, paces the queue against your quota window, and gives you back control the moment you press P or X. That is what keeps a run going for hours without you.
Run any test command after each prompt. When it fails, ptbk coder hands the output back to the agent, which retries until the tests pass.
$ ptbk coder run --harness claude-code --test npm testRun the tests before the first coding prompt. Stop on failures that were already there, or let one repair prompt fix them before the backlog starts.
$ ptbk coder run --harness claude-code --test npm test --test-before yes-and-fixEvery successful round lands under a git identity that belongs to the agent, GPG-signed if you set that up. You can always tell which commits it wrote.
$ CODING_AGENT_GIT_NAME="Promptbook Coding Agent"Pull before prompts and push after commits, so a long-running queue stays in sync with your remote.
$ ptbk coder run --harness claude-code --auto-pull --auto-pushptbk coder init, add, generate-boilerplates and verify all take the same --commit, --auto-push and --auto-pull switches. Setting up a project, queueing prompts and archiving finished ones leave no uncommitted work behind. Verify pulls and pushes around every single verification.
$ ptbk coder init --auto-pull --commit --auto-pushImplement every prompt in its own temporary git worktree with its own environment. Verified work lands back on your branch as one commit. If a task will not merge, ptbk coder marks it failed and keeps its worktree so you can look at it. Deeply nested repositories work on Windows too.
$ ptbk coder run --harness claude-code --isolateptbk coder server keeps running after the queue is empty, watches for new prompt files and serves a Trello-style board where you can edit prompts in the browser.
$ ptbk coder server --port 4441 --harness claude-codeGive prompts a priority and process only the range you want in the current run.
$ ptbk coder run --harness claude-code --min-priority 1 --max-priority 5Route a prompt to a model family or harness with a backtick token on its [ ] status line, such as [ ] use model `gpt-5.5`. Other runners skip it.
$ ptbk coder run --harness github-copilot --model gpt-5.5Wait a fixed wall-clock duration between prompts. The clock keeps running through a pause and through sleep, and errors retry after a cool-down. The terminal also shows every subscription window a harness reports, with its remaining allowance and reset time. Whenever S is offered it skips whatever the coder waits for right now, down to the harness session limit that would otherwise hold the run for hours.
$ ptbk coder run --harness claude-code --wait-between-prompts 30m --wait-after-error 10mPreview which prompts would run. No files touched, no tokens spent.
$ ptbk coder run --dry-runptbk coder ping sends one tiny dummy prompt to a harness and model and reports the answer, the response time and the usage. Use it to check that a harness, model and login work before you queue anything. It also opens the hourly or weekly quota window early, so the quota is already refreshing by the time you need it. It touches nothing in your project.
$ ptbk coder ping --harness openai-codex --model gpt-5.6-sol --thinking-level xhighAdd --period and the ping repeats until you stop it with CTRL+C. One ping every 5h holds the Claude Code 5-hour limit window open, so a queue you start at any hour already has a refreshing window waiting for it. That costs a handful of tokens per ping instead of a run you have to babysit.
$ ptbk coder ping --harness claude-code --model claude-sonnet-5 --thinking-level low --period 5hConfirm each prompt yourself with --no-auto. Press P to pause a running queue, or X to end it after the current prompt. Every press is answered in the Controls panel on the next frame, so you can tell that the key landed even when it changed nothing.
$ ptbk coder run --harness claude-code --no-autoA prompt turns from [ ] into [^] the moment the agent picks it up, and the line names the step that is running. It only becomes [x] after the work is implemented, verified and committed. ptbk coder never reverts a [^], so if the queue is killed or crashes you can see which task was left half-done.
$ [^] by OpenAI Codex `gpt-5.6-luna` - Implementation in progressA dirty working tree stops ptbk coder by default. --git-changes ignore starts anyway, and --git-changes continue resumes the one prompt left in [^] with its half-finished changes still in place. Any harness can take the work over, and the status line then names both the one that started and the one that finished it.
$ ptbk coder run --harness claude-code --git-changes continueEvery successful round writes the harness, model and thinking level into the prompt status line. Walk through completed prompts one by one, archive the finished ones to prompts/done/, and get a repair prompt appended for anything left incomplete. Pick the order with --order from-earliest, from-latest or random.
$ ptbk coder verify --order from-latestptbk coder generate-boilerplates writes one prompt per file by default (--count 5*1). Use --count N*M to pack a whole backlog into fewer files: N files with M prompts each. A --- line separates the sections, every file carries one fresh emoji tag, and each section still runs as its own task.
$ ptbk coder generate-boilerplates --count 10*7Claude Code, OpenAI Codex and opencode are agents that ptbk coder drives, so you keep the one you already use. The table is not about who writes better code. It compares what happens around a task: whether the queue runs unattended, whether the agent definition moves to another vendor, and whether git history keeps the code and its done state together. Where all three behave the same, the table says so once instead of three times.
| Capability | ptbk coderby Promptbook | Claude Codeby Anthropic | OpenAI Codexby OpenAI | opencodeby opencode |
|---|---|---|---|---|
| One task, side by sideSit in the terminal with the agent and steer a single task while it happens. | Not availableIt drives them instead | Built inWhat they are built for | ||
| The whole backlog, unattendedTask files go through the agent one after another: implement, verify, commit, next one. | Built inptbk coder run | Do it yourselfScript one session per task | ||
| Several agents on one backlogRun more harnesses and models at once, each taking its own slice of the queue. | Built in--min-priority --max-priority | Not availableNo shared queue | ||
| The same agent on another vendorThe queue and the .book behavior move to a different harness or model without a rewrite. | Built in--harness | Not availableOne of the harnesses | Do it yourselfAny provider, your config | |
| Your tests gate every taskTests run before the queue starts and after every task, and failures go back to the agent until it is green. | Built in--test --test-before | Do it yourselfAsk for it, or wire a hook | ||
| Done state committed with the codeThe finished [x] lands in the same commit as the work it describes, so reverting takes both back. | Built inIn every commit | Do it yourselfTrack it by hand | ||
| Git kept in order around each taskCommits under the agent git identity, a pull before and a push after, and one throwaway worktree per task. | Built in--auto-pull --auto-push --isolate | Do it yourselfIt commits as you, when asked | ||
| Long runs that outlast a quota windowPacing between tasks, a cool-down retry after an error, and a ping that keeps the quota window refreshing. | Built in--wait-between-prompts | Not availableNo queue to pace | ||
| A backlog you can watch and refillA kanban board over the prompt files while the queue runs, with commands that write new ones and archive the finished. | Built inptbk coder server | Not availableNo backlog to show | ||
Inside a single task nothing changes. ptbk coder runs your harness as it is, with its own tools, its own sandbox and its own MCP servers. The features above explain every capability in this table in detail.