DOCSEARCHbyAlgolia
Submit Docs

clawpatch

repository·main·Indexed 20 days ago

https://github.com/openclaw/clawpatch

An automated code review tool for repository maintainers that maps codebases into semantic feature slices to enable structured, agent-assisted reviews and repairs. It provides a resumable workflow for finding, patching, and validating code issues across multiple languages, including Node.js/TypeScript, Python, Ruby, PHP, Go, Rust, C/C++, Java/Kotlin, .NET, and Swift. It integrates with coding providers such as Codex CLI, Claude Code, and Grok Build to perform bounded reviews and apply fixes.

Tokens
32.3K
Snippets
92
Records
137
Agent score
73%

What's inside clawpatch

  1. Understand the current clawpatch CLI capabilities

    main

    The current implementation of the clawpatch CLI focuses on feature review and finding-based fixes. Note the following constraints and capabilities:

    • Providers: Uses the local Codex CLI and includes test mocks.
    • Review Workflow: Performs sequential feature reviews.
    • Fix Workflow: Use the command clawpatch fix --finding <id> to apply a fix.
    • Limitations: There is currently no auto-commit, no automatic PR creation, and no direct model API providers (it uses coding harnesses only).
    clawpatch fix --finding <id>

  2. What clawpatch does

    main

    clawpatch is an automated code review tool designed to slice repositories into semantic features and review them using AI providers.

    Core Capabilities

    • Semantic Feature Mapping: Automatically detects reviewable units such as npm bins, Next.js/React Router routes, Python packages (Flask/FastAPI/Django), Ruby/Rails slices, Laravel/PHP slices, Java/Kotlin modules, C#/.NET projects, Go packages, Rust crates, and more.
    • Automated Code Review: Uses AI providers (e.g., Codex CLI) to review features and persists findings with severity, category, and line locations.
    • Explicit Fix Workflow: Provides a controlled way to apply patches via clawpatch fix for one finding at a time. It never commits or pushes automatically.
    • Stable State Model: All features, findings, and patches are persisted in .clawpatch/ as JSON, allowing the process to be resumable.

    Safety Principles

    • Read-only Review: The review process does not modify your code.
    • Dirty Worktree Protection: The fix command refuses to run if the worktree is dirty.
    • No Auto-commits: Patches are validated before being accepted, and the tool never performs automatic commits or pushes.

  3. Safety and security in clawpatch

    main

    Clawpatch is designed with safety boundaries in mind:

    • Review/Revalidation: Requests read-only execution from providers.
    • Repair (fix): Requires a specific finding ID. It refuses to run on a dirty source worktree by default. It records changed files and validation results but does not commit or push changes.
    • Publishing: Commits and pushes are only performed via the explicit clawpatch open-pr command.

    Warning: Read the Safety documentation before using write-capable providers on untrusted code.

  4. Understand the Clawpatch Core Boundary

    main

    Clawpatch is designed to integrate coding harnesses and agent CLIs, rather than direct model APIs.

    What is included

    An adapter is considered part of Clawpatch if it launches an installed coding harness that manages:

    • Model transport and authentication
    • Tool use and permissions
    • Coding-agent behavior

    Examples of supported coding harnesses include Codex, ACPX, Claude Code, Cursor Agent, Grok Build, OpenCode, and Pi.

    What is excluded

    Clawpatch does not provide direct model inference integrations. This means the following are out of scope:

    • HTTP clients or SDKs for chat, responses, or model inference APIs.
    • Clawpatch-owned provider API keys, base URLs, or billing behavior.
    • Model-specific retry, quota, streaming, or structured-output transports.
    • Read-only chat providers that cannot function as coding harnesses.

    If you need to support a new model provider, you must first add it to a coding harness or ACP adapter, then integrate that harness via its stable CLI or protocol.

  5. Simplify code using `--mode deslopify`

    main

    The --mode deslopify flag enables a specialized review mode focused exclusively on improving maintainability and performance by removing "code slop" (accidental complexity, inefficient indirection, etc.).

    Behavior:

    • It restricts findings to maintainability or performance issues.
    • It discards findings related to correctness, security, API contracts, data loss, or build/release issues.
    • It prioritizes patterns where the fix is deletion, consolidation, or reuse.

    Targeted Slop Patterns:

    • Semantic duplication (files, tests, SQL, etc.).
    • Shadow modules and thin pass-through wrappers.
    • Concrete code bloat (generated mass, test artifacts in production, wrapper swarms).
    • Dead legacy paths.
    • Cargo-cult defensive code.
    • Tautological or coupled tests.
    • Type/build silencing (e.g., any, type-ignore, broad disables, sleeps/timeouts).

  6. The Fix Pipeline and Revalidation

    main

    The fix pipeline attempts to resolve identified findings.

    Fix Pipeline Stages

    1. Validate requested findings.
    2. Check worktree safety (refuses fixes on dirty worktrees by default).
    3. Claim patch attempt.
    4. Build fix plan.
    5. Apply patch.
    6. Run formatter/linter/typecheck/tests.
    7. Persist command results.
    8. Revalidate.
    9. Update finding/patch status.
    10. Report next action.

    Revalidation

    Revalidation determines if a finding is truly resolved. It uses the original finding, evidence, patch diff, and command results.

    Outcomes:

    • fixed: Issue no longer present and validation supports fix.
    • open: Issue still present.
    • false-positive: Original finding was invalid.
    • uncertain: Insufficient evidence.

    Note: Revalidation must not mark an issue as fixed based on model opinion alone if targeted commands fail.

  7. Review CUDA sources with specialized guidance

    main

    When a feature owns CUDA sources (.cu or .cuh), clawpatch review (and clawpatch fix) automatically injects CUDA-specific guidance into the provider prompt. This includes checking for:

    • Kernel data races and synchronization barriers.
    • Unchecked CUDA runtime calls and missing post-launch error checks.
    • Host vs. device pointer confusion.
    • Unsafe global- and shared-memory access.
    • Stream and event synchronization.
    • Device-memory leaks.

    Findings still use standard categories (e.g., bug, performance) rather than CUDA-specific ones. Note that --mode deslopify is unaffected by this specialized guidance.

  8. The Review Pipeline and Output

    main

    The review pipeline automates the inspection of features using AI providers.

    Pipeline Stages

    1. Load project/config/state.
    2. Select features.
    3. Claim locks (to prevent concurrent reviews).
    4. Assemble prompt context (prioritizing entrypoints, owned files, and tests).
    5. Call provider.
    6. Parse strict JSON output.
    7. Normalize/dedupe finding signatures.
    8. Persist findings and analysis entries.
    9. Release locks.
    10. Write run summary.

    Review Output Schema

    Providers must return a ReviewOutput object. Empty findings are valid only as {"findings":[],"inspected":...}. Markdown wrappers around JSON are invalid.

    type ReviewOutput = {
  findings: Array<{ 
    title: string; 
    category: FindingCategory; 
    severity: "critical" | "high" | "medium" | "low"; 
    confidence: "high" | "medium" | "low"; 
    evidence: EvidenceRef[]; 
    reasoning: string; 
    reproduction: string | null; 
    recommendation: string; 
  }>;
  inspected: {
    files: string[];
    symbols: string[];
    notes: string[];
  };
};

  9. Understand the structure of a Finding

    main

    A Finding is a record of a discovered issue, stored as a JSON file in .clawpatch/findings/<findingId>.json. Each finding contains metadata for tracking, triage, and remediation, including:

    • Identification: feature ID, title, category, severity, confidence.
    • Context: evidence, reasoning, reproduction notes, recommendation.
    • Testing Context: why included tests do not already cover or define the behavior, suggested regression test.
    • Remediation: minimum fix scope.
    • Lifecycle: status, triage/revalidation history, linked patch attempts.
    • Triage: triage.

  10. Safety rules and constraints in clawpatch

    main

    clawpatch implements several safety mechanisms to prevent accidental source code modification and ensure state integrity.

    Read-only Operations

    The following commands are guaranteed to be non-destructive and do not edit source files:

    • review
    • status
    • report
    • doctor
    • map --dry-run

    Modification Constraints

    To prevent unintended changes, the fix command is subject to these constraints:

    • Explicit Targeting: fix requires an explicit --finding <id> to operate.
    • Worktree Integrity: fix will refuse to run if the source worktree is dirty by default.
    • Git Responsibility: clawpatch does not perform automatic commits, PRs, or rollbacks. Users are responsible for inspecting git diff and running project tests before committing any changes produced by a fix.

  11. State, configuration, and safety

    main

    State Management

    All configuration, feature records, findings, patch attempts, reports, and run history are stored in the .clawpatch/ directory. Commands supporting the --json flag will output machine-readable results to stdout while sending human-readable progress to stderr.

  12. Manage Finding statuses

    main

    Findings in clawpatch transition through several statuses to manage the lifecycle of a bug or issue. The available statuses are:

    • open: The finding requires attention.
    • false-positive: The finding was determined to be incorrect.
    • fixed: The issue has been resolved.
    • wont-fix: The issue will not be addressed.
    • uncertain: The status of the finding is currently unclear.