Patchwork: an agentic CLI that turns code chores into named patchflows

Three abstractions, and only three

Patchwork describes itself as an agentic AI framework for enterprise workflow automation, and its architecture is unusually small in concept. Everything in the project is one of three things.

Steps are reusable atomic actions. Create a pull request, commit changes, call an LLM. A step is the smallest unit that does one thing and can be composed into something larger. The value of the abstraction is that the side effects are separated from the reasoning, so a flow that calls a model five times and writes to Git twice still has a legible sequence.

Prompt templates are the second layer. They are customizable prompts, tuned for a specific chore such as a library update, code generation, issue analysis or vulnerability remediation. Templates carry placeholder variables enclosed in `{{}}`, and those get substituted before the prompt reaches a model.

Patchflows are the third layer and the one you actually invoke. They are the LLM-assisted automations, built by combining steps and prompts. A patchflow is what turns two abstractions into PR review or dependency remediation, and each one lives in its own directory under `patchwork/patchflows/`.

That three-layer structure is the design decision worth understanding. Most agentic tooling in this space is a single prompt template wrapped in a script, so the parts cannot be reused across tasks. Because Patchflow keeps steps and prompts separate, a new automation is a directory containing a defaults file and a sequence, and the README points at exactly that when it says you can always create your own.

Optional dependency groups are the real configuration surface

Installation is a single pip command, and the interesting design work is in what comes after it:

pip install 'patchwork-cli[all]' --upgrade

That installs everything. What follows is a set of documented extras, and reading them tells you more about the project's shape than any architecture diagram would.

The `security` extra installs `semgrep` and `depscan`, and the README is explicit that it is required for the AutoFix and DependencyUpgrade patchflows. That is a deliberate coupling: the flow that patches vulnerabilities is built on a specific scanner, not on a language model guessing at what is wrong.

The `rag` extra installs `chromadb` and is required for ResolveIssue. This is the flow that identifies which files in a repository need changing to fix a bug, which is the one place a plain prompt is not enough, because the answer depends on code the prompt never sees.

A `notifications` extra installs the pieces steps use to send messages, for example to Slack. And installing nothing beyond the core is enough for GenerateDocstring, PRReview and GenerateREADME, which are the three flows with the lightest dependency footprint.

For a source build the README points at `INSTALL.md`, and the repository tree carries `poetry.toml` and `poetry.lock` next to `pyproject.toml`, so Poetry is the development path. One release note from v0.0.123 is worth flagging for anyone building today: it upgraded poethepoet specifically to avoid Poetry version issues, which is the kind of detail you only learn from someone who hit it.

How a patchflow is invoked and configured

The CLI surface is one line, and everything else is arguments:

patchwork <PatchFlow> <?Arguments>

Arguments override default and optional attributes of the patchflow in `key=value` form. The one rule that catches people out: a key with no value at all is treated as a boolean `True` flag. So `dry_run` enables the option, and `dry_run=false` disables it, with no separate flag syntax.

The canonical example runs the vulnerability-fixing flow against the current directory:

patchwork AutoFix openai_api_key=<YOUR_OPENAI_API_KEY> github_api_key=<YOUR_GITHUB_TOKEN>

Per-flow configuration lives in a defaults file, and the README links it directly at `patchwork/patchflows/AutoFix/defaults.yml`, which means the parameters a flow understands are documented in the repository rather than in a separate site. That is the pattern to follow when you write your own flow: a defaults YAML that enumerates what can be overridden.

There is a second path to credentials. The OpenAI key can be replaced with a `patched_api_key` from the vendor's hosted service, generated from an integrations tab after signing in at `app.patched.codes`. The flow becomes `patchwork AutoFix patched_api_key=<YOUR_PATCHED_API_KEY> github_api_key=<YOUR_GITHUB_TOKEN>`. Note what this is: the hosted tier is an alternative credential source, not a required component.

A `--config` flag points the CLI at an external file of prompts and defaults, and the README points at the `patched-codes/patchwork-configs` repository as holding the default configuration and prompts for all the flows. The command shown is `patchwork AutoFix --config /path/to/patchwork-configs/patchflows`. Decoupling the prompts from the code is what lets an enterprise tune behavior without forking the package.

Any OpenAI-compatible endpoint, including your own hardware

The model layer is deliberately unopinionated. Patchwork works with any OpenAI-compatible endpoint, and the README names Groq, Together AI and Hugging Face as examples. The mechanism is two arguments, `client_base_url` and `model`:

patchwork AutoFix client_base_url=https://api.groq.com/openai/v1 openai_api_key=your_groq_key model=llama-3.1-405b-reasoning

The same two settings work through a YAML config file, which is the better route once you are past one command:

openai_api_key: your_hf_token
client_base_url: https://api-inference.huggingface.co/models/meta-llama/Meta-Llama-3.1-405B-Instruct-FP8/v1
model: Meta-Llama-3.1-405B-Instruct-FP8

Run it with `patchwork AutoFix --config=/path/to/config.yml`.

The part that matters most for regulated environments is the next sentence: this also allows local models through `llama.cpp`, `ollama`, `vllm` or `tgi`. A local server starts the same way any of these start:

python -m llama_cpp.server --hf_model_repo_id bullerwins/Meta-Llama-3.1-8B-Instruct-GGUF --model 'Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf' --chat_format chatml

And the patchflow then points at localhost with a placeholder key:

patchwork AutoFix client_base_url=http://localhost:8080/v1 openai_api_key=no_key_local_model

That `no_key_local_model` detail is small and revealing. The framework does not require a real credential when the endpoint is local, which confirms there is no vendor proxy in the request path. For Google models the README says you can set `google_api_key` and `model`, and points at the `gemini-pro-1.5` model as the example for a one million token input context. That model name is superseded, which dates the README even though the code around it has kept moving.

The six flows that ship, and what each one assumes

Patchwork comes with predefined patchflows, described in the README as samples with more added over time.

GenerateDocstring generates docstrings for methods in your code. It is the smallest of the six, and the one the core install covers.

AutoFix generates and applies fixes to code vulnerabilities in a repository. It scans first, then patches, which is why it needs the `security` extra.

PRReview runs on pull request creation: extract the code diff, summarize the changes, comment on the pull request. It needs a Git provider token and nothing else, which is why it is in the core set.

GenerateREADME creates a README markdown file for a given folder, to add documentation to your repository. Folder-scoped rather than repository-scoped, which is a useful detail for monorepos.

DependencyUpgrade updates dependencies from vulnerable versions to fixed versions. Like AutoFix it depends on `owasp-depscan`, and unlike a general dependency updater its target is defined by a vulnerability, not by a version constraint.

ResolveIssue identifies the files in a repository that need to be updated to resolve an issue or bug, and creates a pull request to fix it. This is the flow that needs `chromadb`, and the reason is instructive: locating the right files requires indexing the repository rather than prompting a model with the issue text.

The spread across the six is the argument the framework makes. Three of them need nothing beyond the core install, two need a security scanner, and one needs retrieval. A single pipeline that did all six would need all of those dependencies and could not be installed lightly, so the extras exist to keep the common cases cheap.

Dependencies, packaging, and a release history with a gap

The package manifest is worth reading closely, because it explains what the project actually does rather than what it says it does. The distribution is `patchwork-cli` at version 0.0.124, licensed AGPL, requiring Python `^3.9`, and classified as `Development Status :: 3 - Alpha`. The alpha classification is the project's own assessment of itself.

The dependency list is long, and several entries point directly at the flows. `openai` and `anthropic` cover hosted models, `google-genai` covers Gemini, and `pydantic` plus `pydantic-ai` handle structured output and agent loops. Code manipulation is done properly rather than with regex: `libcst` for concrete syntax tree edits that preserve formatting, `tree-sitter-languages` for parsing across languages, and `gitpython` for repository operations. Provider SDKs are broad, with `pygithub`, `python-gitlab` and `azure-devops`, so PR and issue automation is not GitHub-only.

Supporting libraries are pinned tightly, including transitive ones: `numpy` 1.26.4, `pandas` 2.2.3, `scipy` 1.13.1 and `boto3` 1.37.11. A dozen libraries are installed at all, from `scikit-learn` for ranking to `json-repair` for parsing models' malformed output and `python-magic` for file type detection.

The release history is the part that needs a caveat. The latest release is v0.0.124, published 2025-04-16, and its two changes were removing a TypeScript information step and adding a git tool. The releases before it sit in the same two weeks: v0.0.123 on 2025-04-14 upgraded the task runner and switched the internal agent to gemini-2.0-flash, and v0.0.122 on 2025-04-11 fixed the GitHub agent. Every release the project has published is from April 2025, yet the repository was pushed on 2026-08-24 and carries 198 open issues.

So there are two different timelines here and it is worth being clear about which one you are reading. Development has continued well past the last tag. The published wheel is a snapshot from April 2025, and anyone installing from PyPI gets that snapshot rather than the current `main` branch. The AGPL-3.0 license is the other line to read before adopting: for internal use it is unremarkable, and for anything that runs Patchwork as a service for other people, network use is distribution and the license obligations attach.

Editorial conclusion

Patchwork's bet is that the interesting part of an AI code tool is not the model call but the surrounding machinery: dependency resolution per workflow, a YAML layer that separates prompts from orchestration, and arguments you can pass on the command line without an account. Read it that way and the awkward release history stops being a scandal and becomes a decision to make. Every published release sits in April 2025, all of them at 0.0.1xx versions, while the repository has been pushed to as recently as 2026-08-24 with 198 open issues. Install the wheel from PyPI and you get v0.0.124, which is a snapshot, not a moving target. What you evaluate is really the `patchwork/` package directory and the step and prompt abstractions around it, and there is a reasonable case that those are still worth studying. Two cautions. The AGPL-3.0 license matters a great deal if you intend to embed any of it in a service you sell, because network use counts as distribution under that license. And the README still recommends `gemini-pro-1.5` for its one million token context window, a model name from a generation that has been superseded, which is the clearest single signal that the documentation is maintained less often than the code.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. patched-codes/patchwork on GitHub
3. Project website
4. README
5. Releases