---
slug: "clawpatch"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/openclaw/clawpatch@main/README.md"
repo: "https://github.com/openclaw/clawpatch"
source_file: "README.md"
branch: "main"
---
# 🩹 clawpatch

![clawpatch banner](https://github.com/openclaw/clawpatch/raw/HEAD/docs/assets/readme-banner.jpg)

Automated code review that lands fixes.

`clawpatch` maps a repo into semantic feature slices, reviews each slice with a
provider, persists findings, and can run an explicit fix loop for one finding at
a time.

Current status: early CLI. Review/report/state are implemented; patching exists
behind `clawpatch fix --finding <id>` and still requires manual review of the
resulting worktree changes.

## Install

```bash
pnpm add -g clawpatch
```

From source:

```bash
pnpm install
pnpm build
pnpm link --global
```

## Workflow

```bash
clawpatch init
clawpatch map
clawpatch review --limit 3 --jobs 3
clawpatch review --mode deslopify --limit 3
clawpatch ci --since origin/main --output clawpatch-report.md
clawpatch report
clawpatch next
clawpatch show --finding <id>
clawpatch triage --finding <id> --status false-positive --note "covered by tests"
clawpatch fix --finding <id>
clawpatch open-pr --patch <patchAttemptId> --draft
clawpatch revalidate --finding <id>
clawpatch revalidate --all --status open
```

`fix` does not commit, push, open PRs, or land changes. It runs configured
validation commands and records a patch attempt under `.clawpatch/`.

## What It Maps Today

- npm package bins
- selected root and workspace package scripts: `start`, `build`, `test`,
  `lint`, `typecheck`, `format`
- Node/TypeScript workspace packages under `apps/*`, `packages/*`, and package
  workspace patterns
- package-less Node/TypeScript app roots under monorepo folders such as
  `apps/*` and `packages/*` when source or positive framework signals are
  present
- generic extension/plugin packages under workspace roots such as `extensions/*`
  and `plugins/*`, including package metadata, source, docs, and nearby tests
- semantic Node source groups for large packages, including runtime, commands,
  auth, storage, monitor, webhook, setup, server, client, and repeated filename
  family slices
- Nx project metadata from `project.json`, including project-scoped validation
  targets
- Turborepo task metadata for workspace-aware validation commands and feature
  context
- Next.js `app/` and `pages/` routes, including routes inside monorepo apps
- React Router routes and React components
- Go package slices from `go list ./...`, including command packages
- Go package tests and same-repo imports as review context
- Java/Kotlin Gradle source groups, Maven source groups, and root Gradle/Maven
  build/test commands
- JVM semantic roles from Java and Kotlin code evidence such as annotations,
  imports, interfaces, inheritance, supertypes, and method signatures
- Kotlin Android semantic roles for UI entrypoints, ViewModels, data
  boundaries, external clients, and dependency injection, including Metro
- C#/.NET projects from `.sln`, `.slnx`, `.csproj`, `.fsproj`, and `.vbproj`
  files, with conservative `dotnet build` / `dotnet test` defaults
- ASP.NET Core controllers, minimal API endpoints, C#/F#/Visual Basic source
  groups, and .NET test projects
- Ruby project metadata, executables, source groups, RSpec/Minitest suites
- Elixir Mix/Phoenix projects, contexts, Phoenix web slices, runtime config,
  Ecto migrations, project scripts, and ExUnit suites
- Rust `src/main.rs`, `src/bin/*.rs`, `src/lib.rs`, `crates/*`, and
  `tests/*.rs`
- C/C++/CUDA standalone `main()` files, CMake `add_executable` / `add_library`
  targets, autotools `bin_PROGRAMS` / `lib_LTLIBRARIES` targets, and source
  groups for files outside any build target, including CUDA `.cu` / `.cuh`
  sources
- Python project metadata, console scripts, bounded source groups, pytest suites,
  and Flask/FastAPI/Django routes
- SwiftPM `Sources/*` targets and `Tests/*` suites
- Laravel/PHP projects from `composer.json` and `artisan`, including routes,
  controllers, form requests, Artisan commands, jobs, services, models,
  migrations, seeders, Composer scripts, and PHP test suites
- common project config files

Deeper framework mappers and agent-assisted enrichment are next steps.

## Provider

The default provider is the local Codex CLI.

```bash
codex --version
clawpatch doctor
```

Provider calls use `codex exec` with strict JSON schemas. Review and revalidate
run read-only; fix planning runs with workspace-write because Codex may edit the
working tree during the explicit fix command.

Set `CLAWPATCH_CODEX_SANDBOX` to override the Codex sandbox passed by
Clawpatch. Use any Codex sandbox mode, or `bypass`/`none` to pass
`--dangerously-bypass-approvals-and-sandbox` when the host environment already
provides isolation.

Trusted config loaded with `--config` or `CLAWPATCH_CONFIG` can pass primitive
Codex CLI config through `provider.codexConfig`. Repository-discovered config
files cannot set this field because Codex config can affect provider routing
and credential lookup.

Supported provider names today:

- `codex`: local Codex CLI
- `acpx`: any ACP-compatible coding agent (Codex / Claude / Pi / Gemini / ...) via openclaw/acpx
- `claude`: local Claude Code CLI in print mode
- `cursor`: local Cursor Agent CLI (experimental; `doctor` is enabled by default)
- `grok`: local Grok Build CLI
- `opencode`: local OpenCode CLI
- `pi`: local Pi coding agent in print mode
- `mock`: deterministic test provider
- `mock-fail`: failure test provider

## Commands

- `clawpatch init`: create `.clawpatch/`, detect project basics, write config
- `clawpatch map`: write feature records
- `clawpatch status`: show project, dirty state, feature/finding counts
- `clawpatch review`: review pending or selected features
- `clawpatch review --mode deslopify`: review only for locally provable slop cleanup
- `clawpatch ci`: initialize if needed, map, review, write a report, and append a GitHub step summary
- `clawpatch report`: print or write a Markdown findings report
- `clawpatch next`: print the next actionable finding
- `clawpatch show --finding <id>`: inspect one finding with evidence and suggested validation
- `clawpatch triage --finding <id> --status <status>`: mark a finding with optional history note
- `clawpatch fix --finding <id>`: run the explicit patch loop for one finding
- `clawpatch open-pr --patch <id>`: commit an applied patch attempt and open a GitHub PR
- `clawpatch revalidate --finding <id>`: re-check one finding
- `clawpatch revalidate --all`: re-check open findings with report-style filters
- `clawpatch doctor`: check provider availability
- `clawpatch clean-locks`: clear feature locks

Useful flags:

- `--root <path>`
- `--state-dir <path>`
- `--config <path>`
- `--json`
- `--plain`
- `--limit <n>`
- `--jobs <n>` (default: half of CPU cores, max 10)
- `--rate-limit-per-minute <n>`
- `--source <heuristic|auto|agent>`
- `--feature <id>`
- `--project <name-or-root>`
- `--finding <id>`
- `--status <status>`
- `--severity <severity>`
- `--provider <name>`
- `--model <name>`
- `--reasoning-effort <none|minimal|low|medium|high|xhigh>`
- `--skip-git-repo-check`
- `--output <path>` / `-o <path>`
- `--dry-run`
- `--force`

Unknown flags fail fast.

### `report --json` shape

`clawpatch report --json` returns:

```json
{
  "total": 12,
  "items": [/* finding summaries */],
  "results": [/* alias for items */],
  "findings": 12,
  "output": "/path/or/null"
}
```

- `total` and `items` are the canonical keys.
- `results` is an alias for `items` with the same array for parity with `{count, results}` consumers.
- `findings: <number>` is kept for backwards compatibility but is **deprecated**. Note that in `--json` output `findings` is a _count_, not the array — use `items` (or `results`) for the array. The next breaking release (v0.4) will drop `findings: <number>` and `results`, landing on `{ total, items, output }`.

## State

State is project-local by default:

```text
.clawpatch/
  config.json
  project.json
  features/*.json
  findings/*.json
  patches/*.json
  reports/*.md
  runs/*.json
```

Feature records are the durable work units. Findings and patch attempts link back
to features so runs can resume and be audited.

## Safety

- Review does not edit files.
- Fix is explicit and selected by finding ID.
- Fix refuses a dirty source worktree by default.
- Clawpatch commits, pushes, and opens PRs only from explicit patch commands such as `open-pr`.
- Clawpatch does not land changes today.
- Provider output is parsed through strict schemas.
- Symlinked directories and generated build output are skipped during mapping.

See [`VISION.md`](https://github.com/openclaw/clawpatch/blob/HEAD/VISION.md) for project scope and `docs/spec.md` for the
longer product and implementation spec. Provider integrations are limited to
coding harnesses and agent CLIs; direct model API providers are out of scope.