Skip to content

docs: rewrite README to house standard #180

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
steipete merged 1 commit into from
Aug 3, 2026
+76 −201
Merged

docs: rewrite README to house standard #180

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

## 0.7.3 - Unreleased

- Reworked the README around a verified install and quickstart path, with deeper command, mapper, provider, and safety details linked to the existing docs.

## 0.7.2 - 2026-08-01

- Reclaimed dead same-host review locks automatically and added `clean-locks --stale-only` for safe scripted cleanup while preserving live and remote locks, thanks @goutamadwant.
Expand Down
275 changes: 74 additions & 201 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,230 +1,103 @@
# 🩹 clawpatch
# clawpatch 🩹 — Review by feature, fix by finding.

![clawpatch banner](docs/assets/readme-banner.jpg)

Automated code review that lands fixes.
[![CI](https://img.shields.io/github/actions/workflow/status/openclaw/clawpatch/ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/openclaw/clawpatch/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/clawpatch?style=flat-square)](https://www.npmjs.com/package/clawpatch)
[![Node.js](https://img.shields.io/node/v/clawpatch?style=flat-square)](https://nodejs.org/)
[![License](https://img.shields.io/github/license/openclaw/clawpatch?style=flat-square)](LICENSE)

`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.
Clawpatch maps a repository into semantic feature slices, asks an installed coding agent to review each slice, and stores evidence-backed findings for later repair. It is for maintainers who want review, patching, and revalidation to stay explicit and resumable.

## Install

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

From source:
Or with npm:

```bash
pnpm install
pnpm build
pnpm link --global
```sh
npm install -g clawpatch
```

## Workflow
Clawpatch requires Node.js 22 or newer.

```bash
## Quick start

Start in a Git repository:

```sh
cd /path/to/repository
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
clawpatch status
```

`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
Initialization creates project-local state under `.clawpatch/`. The default mapper inspects repository structure without calling a model.

With a [supported coding agent](docs/providers.md) installed and authenticated, run the first review:

```sh
clawpatch doctor
clawpatch review --limit 3
clawpatch report
```

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; add `--stale-only` to reclaim only dead local 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"
}
```
Review progress goes to stderr. Findings and run records remain under `.clawpatch/`, so interrupted work can resume without starting over.

- `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 }`.
## Workflow

## State
| Stage | Command | Result |
| ---------- | ------------------------------------- | ------------------------------------------------------------------------ |
| Initialize | `clawpatch init` | Detect the project and write configuration. |
| Map | `clawpatch map` | Create durable semantic feature records. |
| Review | `clawpatch review` | Run bounded, parallel reviews and persist findings. |
| Inspect | `clawpatch next`, `show`, `report` | Prioritize and examine evidence. |
| Repair | `clawpatch fix --finding <id>` | Apply one explicit patch attempt and run configured validation. |
| Confirm | `clawpatch revalidate --finding <id>` | Re-check the finding against the current code. |
| Publish | `clawpatch open-pr --patch <id>` | Commit the recorded patch files, push a branch, and open a pull request. |

State is project-local by default:
Use `clawpatch ci --since origin/main --output clawpatch-report.md` for the source-read-only init, map, review, and report loop in CI. The [quickstart](docs/quickstart.md) walks through the full workflow, and the [code-review guide](docs/code-review.md) covers selection, concurrency, rate limits, and diff-scoped review.

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

Clawpatch detects reviewable boundaries across Node.js and TypeScript, Python, Ruby, PHP, Go, Rust, C and C++, Java and Kotlin, .NET, and Swift projects. Mappers use manifests, framework conventions, routes, packages, targets, tests, and nearby context; generated directories and symlinked directories are skipped.

Mapping is deterministic by default. `--source auto` and `--source agent` can add provider-assisted slices when the repository needs deeper interpretation. See [Feature Mapping](docs/feature-mapping.md) for supported project shapes and known gaps.

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

The default provider is the local Codex CLI. Clawpatch also integrates ACP-compatible agents through ACPX and has adapters for Claude Code, Grok Build, OpenCode, Pi, and an experimental Cursor Agent path.

Providers are installed coding harnesses or agent CLIs; Clawpatch does not call model APIs directly. Authentication, model transport, and agent execution remain with the selected harness. See [Providers](docs/providers.md) for setup, model selection, permissions, and isolation details, and [VISION.md](VISION.md) for the project boundary.

## State and configuration

Clawpatch stores configuration, feature records, findings, patch attempts, reports, and run history under `.clawpatch/`. Commands that support `--json` keep machine-readable results on stdout and send human progress to stderr.

Configuration can set include and exclude paths, provider defaults, context limits, and validation commands. Start with [Configuration](docs/configuration.md), then use the focused guides for [findings](docs/findings.md), [patching](docs/patching.md), [reporting](docs/reporting.md), and [validation](docs/validation.md).

## 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`](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.
Clawpatch requests read-only provider execution for review and revalidation. `fix` requires a finding ID, refuses a dirty source worktree by default, records changed files and validation results, and does not commit or push. Creating a commit and pull request requires the separate `open-pr` command; Clawpatch does not merge changes.

Provider sandboxes and tool restrictions differ. Read [Safety](docs/safety.md) before using write-capable providers on untrusted code.

## Development

```sh
pnpm install
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build
pnpm pack:smoke
```

Use Node.js 22 or newer and the pnpm version declared in `package.json`.

## License

[MIT](LICENSE)