ptbk coder drives Claude Code, OpenAI Codex, Gemini CLI and other coding agents through a queue of plain-markdown prompts. It runs your checks 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 checks, 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 ptbkptbk init (also ptbk coder init) initializes Git automatically when needed and reuses an existing repository, worktree, submodule, or enclosing monorepo. Your project keeps its own Books and prompts. It creates no commit or remote by default. Then it creates the prompts/ queue, prompts/done/ archive, the default agents/developer.book and agents/planner.book roles, their Lawyer and Copywriter teammates, and shared Adam instructions, AGENTS.md project context, and the agent git identity entries in .env. It also adds local files created by every supported harness to .gitignore. Nothing you already own is ever overwritten: existing package.json scripts and .vscode/settings.json settings are kept as they are, and missing role Books are restored even when scripts already exist. Init adds missing helper TEAM references to Developer and Planner while preserving your rules and existing teammates. The new coder:run script uses the current Codex flagship without pinning a model version. The scripts use Developer, the current directory and AGENTS.md without repeating their flags. Missing Books and AGENTS.md are initialized independently of those script arguments. Run init again any time. The generated prompts/README.md explains PRDs, task statuses, templates, traces, and the review workflow, with a sample task and a complete manual path. Share the Markdown with another assistant or implement it yourself using ordinary repository tools; the guide works offline without a Promptbook account or installation. Your customized README is preserved and stays outside the runnable queue. Other workspace actions require Git even with --no-commit. In a terminal, accept the Git initialization question once to continue. With --no-questions or in CI, run ptbk init --no-questions, ptbk coder init --no-questions, or git init first. Listing and --dry-run previews only warn when a repository is missing and create no setup files.
$ ptbk initDeveloper reads your repository, asks about unresolved requirements, and helps split features into PRDs. Discuss several topics and revise earlier decisions in one terminal conversation. Review proposed paths and changes, then use /save for pending tasks or /draft for unresolved [-] drafts. Only PRD Markdown files can change. /exit ends without starting implementation. Customize agents/developer.book or explicitly select Planner with --agent ./agents/planner.book. The planning command keeps its restricted tools and PRD-only writes with either Book.
$ ptbk coder plan --harness openai-codexUse the lightweight description-to-prompt command, or put a task directly in prompts/. ptbk coder add creates one for you. A status checkbox is optional: a prompt without one is ready at priority 0 and receives its live status when processing begins. 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 it selects the current flagship model automatically. The local Developer Book at agents/developer.book supplies the instructions; --agent selects another Book. It implements one prompt, verifies it, commits it, then starts the next one. Run ptbk coder list first if you only want to see the ready queue for all agents grouped by priority.
$ 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 --check "npm run check"Coding and planning use agents written in the Book language, Promptbook's human-readable language for defining AI agents. Each agent's persona, rules and knowledge live in .book files. ptbk coder resolves the selected book's inheritance and imports into the system message of every coding prompt.
Override the default role with your own Book using --agent:
$ ptbk coder run --harness claude-code --model fable --agent agents/my-developer.bookptbk coder init creates this default developer agent at agents/developer.book and its shared ancestor at agents/.core/adam.book, alongside agents/planner.book. Developer implements changes; Planner discusses requirements and authors PRDs. Both inherit Adam directly through the same default inheritance. Edit the local role Books to customize their behavior.
Both roles include Lawyer and Copywriter in their TEAM. Lawyer helps identify legal and compliance questions; Copywriter helps with labels, errors, onboarding, and other application text. Their editable Books live at agents/lawyer.book and agents/copywriter.book, sharing Adam's core instructions. During coding or planning, the primary agent can ask a relevant adviser a question and use its answer in the same task. Each adviser runs its own Book; unused advisers make no model calls. Local consultations work without an Agents Server.
TEAM works with custom Books and inherited declarations across all seven coding harnesses. Planning currently uses OpenAI Codex, and every adviser follows the same planning restrictions: only the primary agent proposes PRDs for your review. Consultation results, failures and available usage appear in the task's existing trace.
run, server and plan select Developer automatically. Select Planner with --agent ./agents/planner.book. Local Book edits apply on the next invocation. --agent changes the persona, instructions and identity; --harness selects the coding tool and --model selects its model. Planning permits only PRD changes with any selected Book.
The project defaults to your current directory. Use --path to select another project. Its AGENTS.md is loaded as additional context; a missing file produces a diagnostic and continues. --context replaces it with inline instructions or a file relative to the selected project. An empty value disables this context. Books and PRDs stay in the selected project even when Git belongs to a parent directory.
Use FROM @Pavol or FROM {Pavol} to inherit from another book by its first-line name. Books are discovered recursively beneath the selected agent's folder. IMPORT and TEAM use the same reference rules.
Paths starting with ./ or ../ are relative to the book declaring them; other paths are relative to the selected project. HTTP and HTTPS book URLs work too. Adam is inherited by default. Planning requires the Books to be prepared with ptbk coder init and never creates them during a conversation. Use FROM @null or FROM @void to inherit from nothing; braces work too.
Route a ready task to that agent with a status line such as [ ] use agent `developer`. Its path, filename, filename without .book, or title from the first line of the Book all work.
coder list shows tasks for all agents unless you supply --agent. If a default Book is missing, run ptbk coder init. An invalid explicit Book selection reports an error. Repeated initialization creates missing Books and adds missing helper TEAM references, preserving your personas, rules, teammates, and scripts. Conflicting or unreadable Books are reported for you to resolve.
A finished task is signed by the agent, not only by the harness that carried it: [x] by Developer on OpenAI Codex `gpt-5.6-luna`.
readonly preview of agents/developer.book
ptbk coder does not replace your coding agent. It drives it. Pick a harness with --harness and it automatically selects the current flagship model. Override it with --model or PTBK_MODEL, and for the harnesses that support it set --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.
Default: fable
Models: fable, opus, sonnet, haiku
$ ptbk coder run --harness claude-code --thinking-level maxby OpenAI
The OpenAI Codex CLI. Automatically uses the current flagship. Use --model default to keep your Codex configuration, and --allow-credits to opt into spending beyond your rate limits.
Default: gpt-6-astra
Models: gpt-6-astra, default
$ ptbk coder run --harness openai-codexby GitHub
GitHub Copilot in your terminal. Works out of the box with your Copilot subscription and supports thinking levels.
Default: gpt-6-astra
Models: gpt-6-astra, default
$ ptbk coder run --harness github-copilot --thinking-level xhighby Google
The Google Gemini CLI. Automatically selects the latest Gemini model for coding and agent tasks.
Default: gemini-3.8-flash
Models: gemini-3.8-flash, default
$ ptbk coder run --harness geminiby Alibaba
The Qwen Code CLI. Defaults to the current Qwen Max model and signs in with a Qwen account or an OpenAI-compatible API key.
Default: qwen3.8-max
Models: qwen3.8-max, default
$ ptbk coder run --harness qwen-codeby opencode
The open-source terminal coding agent. Defaults to the OpenAI flagship through your configured OpenAI provider. Use --model default to keep your own provider and model.
Default: openai/gpt-6-astra
Models: openai/gpt-6-astra, default
$ ptbk coder run --harness opencodeby Cline Bot Inc.
The Cline CLI agent. The Google provider integration defaults to the latest Gemini coding model.
Default: gemini-3.8-flash
Models: gemini-3.8-flash, default
$ ptbk coder run --harness clineThe agent writes the code. ptbk coder does the rest: it runs your checks, 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 project check command after each prompt. When it fails, ptbk coder hands the output back to the agent, which retries until the checks pass.
$ ptbk coder run --harness claude-code --check "npm run check"Run the checks 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 --check "npm run check" --check-before yes-and-fixRun npm run check, repair failures with one verified PRD, commit eligible changes and exit. A healthy project launches no harness. Ordinary queued tasks stay untouched; verify remains the human review and archive helper.
$ ptbk coder fix --harness openai-codexEvery 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 init (also ptbk coder init), add, plan, generate-boilerplates and verify all take the same --commit, --auto-push and --auto-pull switches. Init creates missing local Git before synchronization. Commit scope includes only the operation’s eligible artifacts; unrelated user changes stay untouched. Pull and push require your configured remote. 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-6-astra`. Other runners skip it.
$ ptbk coder run --harness github-copilot --model gpt-6-astraRoute a prompt to the selected Book with its path, filename, stem or title from the first line, such as [ ] use agent `developer`. Other agents skip it.
$ ptbk coder run --harness github-copilot --model gpt-6-astra --agent agents/my-developer.bookWait 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, re-read every 5 seconds so the numbers keep moving while a prompt runs instead of standing still until it ends. 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 10mSee every ready, fully authored prompt grouped by priority before starting a harness. Narrow the list by harness, model, agent, or priority range; no files change and no tokens are spent.
$ ptbk coder listptbk 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. If that harness has missing local ignore rules, it asks before adding them to .gitignore.
$ ptbk coder ping --harness openai-codex --model gpt-6-astra --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 5hThe dashboard starts in Normal output, with agent messages, commands, file changes and verification shown separately. Press O to switch to Raw output and back while the same task keeps running. Use the arrow keys to scroll output and End to follow it live. Press P to pause the queue, X to end after the current prompt, or use --no-auto to confirm each prompt. Use --no-ui for plain logs.
$ ptbk coder run --harness claude-code --no-autoThe opposite end: --no-questions never asks anything at all. Installing a missing harness, updating an outdated one or adding ignore rules is skipped and printed as the command which does it manually, so a queue started from a script or a CI job never stops at a prompt nobody is there to answer. All workspace actions take it. Mutating commands require an existing Git working tree even with --no-commit; initialize first with ptbk init --no-questions, ptbk coder init --no-questions, or git init. Explicit init creates missing Git automatically. Read-only and --dry-run commands only warn.
$ ptbk coder run --harness claude-code --no-questionsA [ ] prompt — or plain markdown with no status checkbox — turns into [^] the moment the agent picks it up, and the line names the step that is running. A run started with --agent names that agent in front of its harness, so a finished prompt says which agent implemented it. A prompt without a checkbox starts at priority 0. Use [-] or [.] to keep a task out of the queue, or add <!--ptbk-coder-ignore--> anywhere in a Markdown file to ignore it entirely. 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 Developer on 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 round leaves a trace in prompts/traces/, named after the prompt file it belongs to. It holds the agent, harness, model, thinking level and login method that ran the prompt, what each step cost and how long it took, and the whole raw output of the harness. The trace is committed together with the prompt, so the run can still be analyzed long after its temporary logs are gone.
$ prompts/traces/2026-09-0180-add-dark-mode.mdEvery successful round writes the agent, 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 checks gate every taskChecks run before the queue starts and after every task, and failures go back to the agent until it is green. | Built in--check --check-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.