Patchdock

Turns a prompt into a reviewed patch. Describe a task, and agents work through it inside an isolated Docker container; the result lands as a commit on a patchdock/… branch in your repository, ready to review and merge.

Getting started

Running Patchdock requires a Docker Engine. Install the dock binary with Homebrew:

brew install HJyup/tap/patchdock

Then initialise the repository you want agents to work on:

cd your-repo
dock init

This creates a .patchdock/ directory with the configuration and agent definitions Patchdock uses during execution:

.patchdock/
├── config.yml
├── Dockerfile
├── package.json
├── .gitignore
├── planner.ts
├── executor.ts
└── reviewer.ts

Install the agent SDK. The Dockerfile copies this node_modules tree into the agent image, so it has to exist before the first run:

cd .patchdock
npm install

Adapt the Dockerfile to your repository's toolchain, then open Patchdock and submit your first task:

cd ..
dock

CLI reference

Command	Description
dock init	Create the repository's .patchdock/ directory. Add --force to regenerate it, overwriting the existing configuration and agent files.
dock	Open the interactive terminal interface on the task input. Submit tasks there and switch to the live dashboard to follow runs across repositories.
dock watch	Open the terminal interface directly on the live dashboard.
dock "<prompt>"	Queue the task, print its run ID, and exit without opening the terminal interface. Starts the daemon on demand.

Command	Description
dock cancel <run-id>	Cancel a queued or running run from any terminal. The run stops at its current stage and its container is removed.
dock daemon status	Show daemon health, uptime, process ID, socket, and log path.
dock daemon run	Run the daemon in the foreground for debugging.
dock daemon stop	Signal the running daemon to stop and wait for it to exit.

The daemon owns the run queue, Docker execution, and live state. Clients start it automatically when needed; the dock daemon commands let you inspect or control it directly.

Configuration

Dockerfile

Each repository owns a .patchdock/Dockerfile. It defines the isolated environment in which the planner, executor, and reviewer operate.

Add everything the agents need to build, test, and inspect the repository: language runtimes, package managers, compilers, system libraries, project tools, and prewarmed dependencies. These additions become part of the agent image and are available during every stage.

config.yml

The repository's .patchdock/config.yml defines the execution guardrails for its agents. For example:

container:
  timeout: 10m
  token_budget: 100000

retries:
  max: 3

The container timeout is a hard wall-clock limit for each stage. The token budget is passed to the agent as an advisory budget, while the retry limit controls how many executor and reviewer rounds may run. The configuration also selects stage files, declares read-only credential mounts, names the reusable agent image, and controls the Git branch prefix.

Patchdock Agent SDK

The TypeScript files in .patchdock/ use @patchdock/sdk to define typed planner, executor, and reviewer contracts. Each stage file decides how its agent is driven inside the container.

Supported agents

The table below lists the coding agents that can run inside the container:

Agent	Status
Codex	Supported
Claude	Coming soon

For agent contracts, custom implementations, runtime context, and configuration details, read the Patchdock Agent SDK documentation.

How it works

The dock CLI talks to a local daemon over a unix socket. The daemon queues runs, drives Docker execution, and streams live state back to the clients.

Every task moves through three agents: the planner produces a plan, the executor applies it to the repository, and the reviewer judges the changes. A rejected review sends the task back to the executor until the configured retry limit is reached; an accepted review is published as a branch and commit.

stateDiagram-v2
    [*] --> Planning

    state "Planner agent" as Planning
    state "Executor agent" as Executing
    state "Reviewer agent" as Reviewing
    state "Publish branch" as Publishing
    state "Run succeeded" as Succeeded
    state "Run rejected" as Rejected
    state "Run failed" as Failed

    Planning --> Executing: Valid plan produced
    Planning --> Failed: Error

    Executing --> Reviewing: Changes and execution result produced
    Executing --> Failed: Error

    Reviewing --> Publishing: Review accepted
    Reviewing --> Executing: Changes requested and attempts remain
    Reviewing --> Rejected: Retry limit reached
    Reviewing --> Failed: Error

    Publishing --> Succeeded: Branch and commit created
    Publishing --> Failed: Error

    Succeeded --> [*]
    Rejected --> [*]
    Failed --> [*]

Loading

References

• Architecture
• Patchdock Agent SDK