From 723e25ce7c173b6a28e9c3bb2dfc4e3629cfba4b Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 2 Aug 2026 18:14:17 -0700 Subject: [PATCH] docs: rewrite README to house standard --- CHANGELOG.md | 2 + README.md | 275 ++++++++++++++------------------------------------- 2 files changed, 76 insertions(+), 201 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a3868fc..b7d6385 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index 673133e..ab1b290 100644 --- a/README.md +++ b/README.md @@ -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 ` 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 -clawpatch triage --finding --status false-positive --note "covered by tests" -clawpatch fix --finding -clawpatch open-pr --patch --draft -clawpatch revalidate --finding -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 `: inspect one finding with evidence and suggested validation -- `clawpatch triage --finding --status `: mark a finding with optional history note -- `clawpatch fix --finding `: run the explicit patch loop for one finding -- `clawpatch open-pr --patch `: commit an applied patch attempt and open a GitHub PR -- `clawpatch revalidate --finding `: 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 ` -- `--state-dir ` -- `--config ` -- `--json` -- `--plain` -- `--limit ` -- `--jobs ` (default: half of CPU cores, max 10) -- `--rate-limit-per-minute ` -- `--source ` -- `--feature ` -- `--project ` -- `--finding ` -- `--status ` -- `--severity ` -- `--provider ` -- `--model ` -- `--reasoning-effort ` -- `--skip-git-repo-check` -- `--output ` / `-o ` -- `--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: ` 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: ` 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 ` | Apply one explicit patch attempt and run configured validation. | +| Confirm | `clawpatch revalidate --finding ` | Re-check the finding against the current code. | +| Publish | `clawpatch open-pr --patch ` | 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)