Dr. Done

An opinionated CLI tool that processes a queue of task prompts using the Claude Agent SDK. Add tasks as markdown files, and Dr. Done works through them autonomously -- reviewing its own work, committing progress, and recovering from failures.

This is an alternative to the Ralph Wiggum plugin for long-running autonomous loops ("Ralph Loops") in Claude Code.

Quick Start

# Initialize dr-done in your project
npx dr-done init

# Add a task
npx dr-done add "Refactor the authentication module"

# Process the queue
npx dr-done start

Why Dr. Done?

Dr. Done has a few opinions baked into it over just using the Claude Code CLI:

• It's just a CLI. Pipe the output to your own logging tools. Compose with bash scripts. No terminal UI flickering and re-rendering to worry about.
• Permissions requests are automatically denied. I highly recommend using something like the Claude Code sandbox with bash auto-approve. Despite this, Claude will sometimes reach out of the sandbox or switch to the unsandboxed bash and trigger a permission request. This tool automatically denies them and forces Claude to figure out an alternative, so you don't have to babysit the tool.
• Each task gets a new context window. If you stack multiple prompts together, you don't have to worry about context from one polluting the other.
• Regular commits and updates. By default, the tool commits after each subtask and appends status to a file for ease of human review.
• Automated reviews. By default, the tool spins up a separate agent session for each prompt to review.

How It Works

Dr. Done manages a queue of tasks stored as markdown files in a .dr-done/tasks/ directory. Each task progresses through a state machine:

pending  -->  review  -->  done
                |
                v
              stuck

State is encoded directly in filenames:

| State | Extension | Meaning | |---------|---------------|----------------------------------| | Pending | .md | Waiting to be processed | | Review | .review.md | Being reviewed by the reviewer | | Done | .done.md | Completed successfully | | Stuck | .stuck.md | Needs human intervention |

Tasks are numbered (e.g., 001-build-feature.md) and processed in order. Each task can decompose into subtasks that the agent works through iteratively, committing progress along the way.

Dr. Done uses your existing Claude Code settings and auth.

Commands

dr-done init

Initialize the .dr-done/ directory in the current repository. Creates the task directory structure and default configuration.

dr-done add [message...]

Add a task to the queue. If no message is provided, opens $EDITOR for composing a longer task description.

dr-done add "Fix the login bug on the settings page"
dr-done add    # opens editor

dr-done start (alias: run)

Process the task queue. Picks up the next pending task and works through it.

dr-done start         # process all tasks
dr-done start --once  # process one task then exit

dr-done do [message...]

Add a task and immediately start processing it first (skips ahead in the queue). Opens $EDITOR if no message is given.

dr-done do "Add input validation to the signup form"

dr-done continue [message]

After interrupting (ctrl+c) Dr. Done, resume the processing loop from where it left off. Optionally provide feedback that gets appended to the current task.

dr-done continue                         # resume without feedback
dr-done continue "Try a different approach"  # resume with feedback
dr-done continue -e                      # open editor for feedback

dr-done status

Show the current state of the task queue.

dr-done unstick [prefix]

Rename stuck tasks back to pending so they can be retried. Optionally specify a task prefix to unstick a specific task.

dr-done unstick      # unstick all stuck tasks
dr-done unstick 003  # unstick only task 003

dr-done cleanup

Remove completed tasks from the queue (moves to OS trash when available).

dr-done cleanup       # remove completed tasks
dr-done cleanup --all # remove all tasks

Configuration

Configuration lives in .dr-done/config.json:

{
  "review": "subtask",
  "gitCommit": "subtask",
  "maxRetries": 3,
  "maxIterations": 50
}

Options

| Option | Values | Default | Description | |-----------------|-----------------------------|---------|------------------------------------------------------| | review | "off", "subtask", "task" | "task" | When to run the automated reviewer | | gitCommit | "off", "subtask", "task" | "subtask" | When to auto-commit progress | | maxRetries | number | 3 | Max retry attempts when the agent gets stuck | | maxIterations | number | 50 | Max subtask iterations per task | | model | string | — | Model to use for the worker agent | | reviewModel | string | — | Model to use for the reviewer |

Review Modes

• off -- No automated review. Tasks go directly to done.
• subtask -- The reviewer runs after every subtask iteration, catching issues early.
• task -- The reviewer runs only when the agent reports the entire task is done.

Git Commit Modes

• off -- No automatic commits.
• subtask -- Commit after each subtask iteration. When the reviewer makes fixes, those are amended into the existing commit.
• task -- Commit once when the entire task is complete.

Project-Level Customization

.dr-done/TASK.md

Instructions that are injected into every task prompt. Use this to provide project-specific context, coding standards, or constraints that apply to all tasks.

.dr-done/REVIEW.md

Instructions for the automated reviewer. Define what checks should pass, what standards to enforce, etc.

Example:

The following checks must pass:
- [ ] `pnpm run lint:fix`
- [ ] `pnpm run typecheck`
- [ ] `pnpm run test`

Development

./dev.sh    # Run the command (this is just `npx run -s dev`)

Or PNPM commands

pnpm install          # install dependencies
pnpm build            # compile TypeScript
pnpm dev              # run via tsx (no build needed)
pnpm test             # run tests (vitest)
pnpm test:watch       # run tests in watch mode
pnpm typecheck        # check types
pnpm lint             # lint
pnpm lint:fix         # lint with auto-fix
pnpm format           # format with prettier

Related

• Bueller Wheel - An earlier take on this in which tasks are sorted via folders and subtasks get their own markdown files. Dr. Done uses file extensions to denote state and Claude's own TaskList tools for subtasks.
• Dr. Done Claude Plugin - Conceptually similar but triggered via Claude skills. I personally find I get better results with the CLI because the Agent SDK allows more control over sessions and permission requests than plugins do.