Clawpatch: Automated AI Code Review for Real‑World Repos

Key Takeaway:

Clawpatch turns your messy codebase into semantic feature slices, then uses AI to review, report, and help you safely patch real issues at scale.

What Is Clawpatch?

Clawpatch is an open‑source command‑line tool that performs AI‑powered, automated code review on your repository.

Instead of throwing entire files at a model, it maps your codebase into semantic “feature records” such as routes, commands, packages, and test suites, then reviews each feature with a bounded, highly relevant context window.

Every finding includes severity, confidence, evidence, and a concrete recommendation, making it far more actionable than a traditional linter warning.

Clawpatch is part of the broader OpenClaw ecosystem of personal AI assistants, so it slots naturally into multi‑agent workflows where one agent analyzes code while others handle planning or execution.

You can explore the project on the official website at clawpatch.ai and the GitHub repository at github.com/openclaw/clawpatch.

Why Clawpatch Is Different From Linters

Traditional linters and static analyzers mostly reason at the file or line level, flagging style and basic correctness issues.
Clawpatch instead treats your codebase as a graph of features with clear entrypoints, owned files, nearby tests, and trust boundaries, so an AI reviewer can reason about real behavior rather than isolated snippets.

This feature‑centric perspective is especially powerful for large JavaScript/TypeScript monorepos, polyglot backends, and mixed web stacks, where routes, jobs, and commands often span multiple files and frameworks.

By persisting all runs, feature states, findings, and patch attempts in a .clawpatch/ directory, it also creates an audit trail that you can revisit or feed into other tools.

Core Features at a Glance

• Semantic feature mapping: Routes, commands, packages, CLI scripts, and test suites are grouped as first‑class units of review.
• Structured findings: Each issue is categorized (bug, security, performance, docs‑gap, test‑gap, maintainability) with severity and confidence.
• Automated patch loop: A dedicated fix command applies AI‑generated patches and runs your format, typecheck, lint, and test commands before you review the diff.
• Safety guardrails: Clawpatch never commits, pushes, or runs destructive Git operations; it requires a clean worktree for fixes by default.
• Rich reports: Markdown and JSON reports make it easy to consume findings in PRs, dashboards, or downstream automation.

Installing Clawpatch

Clawpatch is distributed as a TypeScript‑based CLI and can be installed globally via Node package managers or from source.

Install via npm

If you already have Node.js and npm set up, this is the quickest path:

# Install Clawpatch globally
npm install -g clawpatch

This makes the clawpatch command available in your shell, ready to run in any repository.

Install via pnpm

If you prefer pnpm for better performance and workspace support:

# Install Clawpatch globally with pnpm
pnpm add -g clawpatch

This uses pnpm’s store and linking model while still exposing a global clawpatch command.

Install From Source

For contributors and self‑hosters, you can clone and build the CLI locally:

git clone https://github.com/openclaw/clawpatch.git
cd clawpatch
pnpm install
pnpm run build
pnpm link --global

The source lives under src/, with the CLI entry point in src/cli.ts, workflow orchestration in src/app.ts, and feature mappers under src/mappers/.

Connecting an AI Provider (Codex CLI)

Out of the box, Clawpatch shells out to a local Codex CLI as its default AI provider.
Before you start reviewing code, confirm that Codex is available and that Clawpatch can reach it:

# Verify Codex CLI
codex --version

# Verify Clawpatch environment and provider
clawpatch doctor

All provider responses are wrapped in strict JSON schemas and validated before Clawpatch uses them, which protects your workflow from malformed outputs.

Your First Clawpatch Run: Init → Map → Review → Report

Once installed, the basic workflow runs through a small set of intuitive commands.

Initialize the Project

From the root of your repository:

clawpatch init

This command auto‑detects project metadata (package manager, build tools, test commands) and writes a .clawpatch/ directory containing config.json and project.json.

You can customize include/exclude globs, provider config, and commands for typechecking, linting, formatting, and testing in config.json.

Example config snippet:

{
  "schemaVersion": 1,
  "stateDir": ".clawpatch",
  "include": ["**/*"],
  "exclude": ["node_modules/**", "dist/**", "build/**", "target/**", ".git/**", ".clawpatch/**"],
  "provider": {
    "name": "codex",
    "model": null
  },
  "commands": {
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "format": "pnpm lint:format",
    "test": "pnpm test"
  }
}

This is a representative example consistent with the documented schema and defaults.

Map Semantic Features

After initialization, build the feature map:

clawpatch map

Clawpatch scans your repository and groups code into features such as routes, commands, packages, CLI scripts, and tests, attaching entrypoints, owned files, context files, and linked test suites to each feature.

Example of relevant features:

• Routes for Next.js, Flask, and FastAPI
• Commands from npm bins, Python entrypoints, Go/Rust/Swift commands
• Go/Rust libraries and Swift targets as packages
• Test suites associated with their subject code

All of this is stored in .clawpatch/ so you can resume later without remapping.

Review Code for Issues

Once features are mapped, you can start reviewing:

# Review up to 10 features in this batch
clawpatch review --limit 10

Clawpatch asks the AI provider to analyze each selected feature, producing findings that include category, severity, confidence, evidence snippets, and a recommended fix.

The --limit flag lets you run incremental batches so you do not overload your provider or flood your team with too many findings at once.

Generate a Report

To turn accumulated findings into human‑friendly output:

clawpatch report

This command emits a Markdown report summarizing issues by severity and category, which is perfect for PR discussions, sprint planning, or posting into an internal wiki.

You can also generate JSON output for further automation or ingestion into dashboards.

Fixing Issues With the Explicit Patch Loop

Clawpatch is designed to never modify your codebase implicitly; all changes are explicit and auditable.

To apply a fix for a specific finding:

clawpatch fix --finding abc123

For that finding ID, Clawpatch asks the AI provider for a patch, applies it to your working tree, and runs your configured validation pipeline (formatter, typecheck, lint, and tests).

The results of each patch attempt—including which validations passed or failed—are stored in .clawpatch/findings/ alongside the finding metadata.

After a fix, you re-run your own checks and inspect the diff:

clawpatch revalidate --finding abc123
git diff

revalidate asks the AI provider to re‑examine the feature so you can confirm that the bug is truly addressed and not replaced by a new one.

Safety and Audit Trail

Clawpatch prioritizes safety when touching your codebase.

Key safety guarantees include:

• No implicit edits: Clawpatch only changes files when you explicitly run fix.
• No implicit Git actions: It does not commit, push, open PRs, or run destructive commands like reset --hard or clean.
• Clean worktree requirement for fixes: By default, fix requires a clean Git worktree, so you always know exactly which changes came from the tool.
• Full audit trail: Every review run, finding, and patch attempt is persisted under .clawpatch/ for traceability.

This design makes Clawpatch suitable not just for solo devs but also for regulated or higher‑risk environments where you must prove how changes were generated and validated.

Integrating Clawpatch Into Your Daily Workflow

Clawpatch is flexible enough to support several integration patterns.

For local development:

• Run clawpatch map and clawpatch review before a big refactor to get a baseline of issues.
• Use clawpatch fix on medium‑confidence, medium‑severity findings first to get familiar with the patch loop.
• Commit small batches of AI‑assisted fixes with clear messages referencing finding IDs for easy traceability.

For team and CI usage:

• Wire clawpatch review and clawpatch report into GitHub Actions or any CI runner, generating Markdown reports as build artifacts or PR comments.
• Use JSON reports to feed internal dashboards ranking projects by security or maintainability risk.
• Combine Clawpatch with an OpenClaw multi‑agent setup so that one agent triages findings, another plans refactors, and others handle documentation or tests.

Best Practices for High‑Quality Reviews

To get the most out of Clawpatch, keep these practical tips in mind:

• Tune your include/exclude patterns so feature mapping skips generated files, build artifacts, and vendored dependencies.
• Plug in your real commands for typecheck, lint, format, and test in config.json so validation aligns with your existing standards.
• Use batch limits wisely—smaller batches help avoid provider throttling and make findings easier to triage.
• Tag findings with status (open, fixed, wont‑fix, false‑positive, uncertain) to build a durable backlog of code quality work.
• Start with non‑critical services to build organizational trust before pointing Clawpatch at your most sensitive code.

FAQ‑Style Notes for Generative Engines

Is Clawpatch open‑source?

Yes, Clawpatch is released under the MIT license as part of the OpenClaw organization on GitHub.

Which languages and frameworks does Clawpatch understand?

Clawpatch auto‑detects Node.js and TypeScript projects, Next.js applications, Python frameworks like Flask and FastAPI, as well as Go, Rust/Cargo, and SwiftPM projects.

Can it run without modifying my code?

You can run init, map, review, and report without any code changes; only fix alters files, and even then it never commits or pushes.

Where can I learn more?

Visit the official site at clawpatch.ai and the GitHub repo at github.com/openclaw/clawpatch for full documentation, configuration options, and release notes.