CLI workflow for AI coding agents

ptbk coder

Prompt queues into shipped commits.

If Claude Code or Codex is the agent, ptbk coder is the operating loop around it: project-owned prompt files, consistent agent behavior, verification feedback, local progress UI, and Git bookkeeping after each task.

Start with commands See the workflow

6agent harnesses

3xtest-feedback attempts

1prompt queue in Git

~/repo - ptbk coder server

$ ptbk coder server --harness claude-code --model fable

Loading prompts from ./prompts Running prompts with Claude Code Server: http://localhost:4441

Current prompt prompts/2026-07-08-0010-api-cleanup.md#1 Build retry-safe token refresh and update tests.

Attempt 1: agent edited 4 files Verification: npm test failed Attempt 2: sent test output back to agent Done: committed "Refactor token refresh flow"

Ready 3

Repair flaky checkout test[ ] !! prompts/checkout.md#2

Extract auth provider[ ] ! prompts/auth.md#1

Running 1

Token refresh retry flowattempt 2 - verifying

Draft 2

Document migration guard[-] prompts/db.md#3

Done 8

Normalize line endings[x] openai-codex gpt-5.5

Terminal walkthrough

From install to a running agent queue.

The landing page shows the actual operating shape: install, initialize, write markdown tasks, run them, keep the server open, and scale the loop.

01 install

Install the Promptbook CLI

Add ptbk to the project or run it through npx. The coder commands live under the same CLI.

npm install ptbk
npx ptbk coder --help

02 initialize

Create the prompt workspace

Initialization creates prompt folders, reusable templates, a developer agent book, AGENTS wiring, package scripts, and VS Code image paste settings.

ptbk coder init

# Created or updated:
# prompts/
# prompts/done/
# prompts/templates/common.md
# agents/developer.book
# AGENTS.md
# .vscode/settings.json

03 write tasks

Write work as prompt sections

Each markdown section becomes a queued unit of work. Use [-] for draft tasks, [ ] for runnable tasks, and extra ! markers for priority.

ptbk coder generate-boilerplates --template ./prompts/templates/common.md

# prompts/2026-07-08-0010-api-cleanup.md
[ ] !!
Refactor the token refresh flow.

- Keep backwards compatibility.
- Add tests.
---
[-]
Document the new retry behavior.

04 run locally

Run the queue through an agent

ptbk coder builds the prompt, prepends your agent behavior, appends project context, checks the working tree, runs the harness, verifies changes, and records the result.

ptbk coder run \
  --harness openai-codex \
  --model gpt-5.5 \
  --thinking-level xhigh \
  --agent agents/developer.book \
  --context AGENTS.md \
  --test "npm test"

05 operate

Keep a browser board open

Server mode keeps watching for new prompt files, exposes a local kanban board, and lets the browser pause or edit prompt sections while the runner stays alive.

ptbk coder server \
  --harness claude-code \
  --model fable \
  --thinking-level max \
  --agent agents/coding/developer.book \
  --context AGENTS.md \
  --test npm run test-for-ptbk-coder

06 scale

Automate routine engineering

Use priority filters, pacing, automatic pulls, pushes, database migrations, and refactor-candidate prompts when the queue becomes a continuous workflow.

ptbk coder find-refactor-candidates --level medium --limit 10
ptbk coder run --priority 1 --auto-pull --auto-push --auto-migrate
ptbk coder verify --ignore experimental

How it works

A coding-agent loop you can inspect.

ptbk coder keeps the important state in files and Git, while the selected harness focuses on implementation.

Prompt backlog

Store coding work in markdown files that can be reviewed, reordered, prioritized, and committed.

Agent behavior

Load a .book agent and project context so every task runs with the same engineering rules.

Verification loop

Run a test command after each attempt and feed failing output back to the agent up to three times.

Git bookkeeping

Mark prompts done or failed, normalize changed line endings, commit successful work, and optionally push.

Features

Built for developers who already live in terminals.

The feature set is intentionally practical: repeatable prompts, runner selection, verification feedback, browser visibility, and clean repository state.

Terminal-native agent runs

Use rich TTY progress when interactive, or switch to plain streaming output with --no-ui for logs.

Local kanban server

Open a browser board at localhost, watch progress, edit prompt sections, and pause or resume the runner.

Clean repository discipline

Require a clean working tree before each task, pull between rounds, and keep generated commits scoped.

Failure visibility

Failed tasks are marked in the prompt file and get an error log so the next repair prompt has context.

Fresh prompt boilerplates

Generate numbered prompt files with reusable templates and repository-wide fresh emoji tags.

Refactor discovery

Scan the codebase for oversized or complex files and generate prompt candidates for the highest-impact work.

Server mode

Keep the queue visible while agents work.

The server command runs the same prompt processor in keep-alive mode and exposes a local kanban UI for day-to-day operation.

http://localhost:4441

Ready 3

Repair flaky checkout test[ ] !! prompts/checkout.md#2

Extract auth provider[ ] ! prompts/auth.md#1

Running 1

Token refresh retry flowattempt 2 - verifying

Draft 2

Document migration guard[-] prompts/db.md#3

Done 8

Normalize line endings[x] openai-codex gpt-5.5

Operate it like a local control room.

The browser is not a separate product surface. It is a live view over prompt files, pause state, and runner progress so a developer can keep long-running work understandable.

Pause or resume from browser or terminal before key checkpoints.
Edit prompt sections from the board and commit those prompt edits.
Keep watching for new runnable prompts instead of exiting when the queue empties.

Harnesses

Bring the coding agent you already trust.

ptbk coder normalizes the project workflow around multiple runner integrations instead of forcing one model or editor.

OpenAI Codex

Use Codex models with explicit model and optional credit spending controls.

--harness openai-codex --model gpt-5.5

Claude Code

Run the same prompt queue through Claude Code when that is the developer workspace of choice.

--harness claude-code --model fable

GitHub Copilot

Drive the Copilot CLI with configurable thinking level and the same prompt lifecycle.

--harness github-copilot --thinking-level xhigh

Cline

Use Cline as the implementation harness while ptbk coder owns queueing and verification.

--harness cline

Opencode

Connect Opencode to prompt files and keep the existing ptbk coder bookkeeping around it.

--harness opencode

Gemini

Run Gemini CLI models with the same context, test feedback, and prompt status updates.

--harness gemini --model gemini-3-flash-preview

FAQ

Plain answers for developers.

The goal is to make the first run understandable before someone reads the CLI source.

Is ptbk coder another AI model?

No. It is a Promptbook CLI workflow that runs external coding harnesses such as OpenAI Codex, Claude Code, GitHub Copilot, Cline, Opencode, or Gemini.

Why use prompt files instead of one-off chat?

Prompt files make coding work durable. You can review task wording, set priority, split work into sections, archive verified prompts, and keep the backlog in Git.

What happens when tests fail?

The verification output is appended back into the next attempt. After the configured attempts are exhausted, the prompt is marked failed and an error log is written.

Does the server send code to a hosted ptbk service?

The server is a local HTTP UI over the prompt folder and runner state. The selected harness still decides which AI provider receives prompt context.