Skip to content

quickstart.md

Latest commit

 

History

History
213 lines (148 loc) · 3.87 KB

quickstart.md

File metadata and controls

213 lines (148 loc) · 3.87 KB
Raw
title Quickstart
description Get started with clawpatch in five minutes

Quickstart

This guide walks through a complete review workflow from initialization to fixing findings.

Prerequisites

  • Install clawpatch
  • Install Codex CLI (brew install codex) for the default provider, or install the Grok Build CLI (curl -fsSL https://x.ai/cli/install.sh | bash) and pass --provider grok when reviewing
  • Have a project with code to review

1. Initialize

cd your-project
clawpatch init

This creates .clawpatch/ with:

  • config.json - project configuration
  • project.json - detected project metadata
  • features/ - feature records (created by map)
  • findings/ - review findings (created by review)
  • patches/ - patch attempts (created by fix)

Check project detection:

clawpatch status

2. Map features

clawpatch map

This discovers reviewable features:

  • npm package bins and root/workspace scripts
  • Next.js routes
  • Go packages and commands
  • Java/Kotlin Gradle and Maven modules
  • Python packages, console scripts, Flask/FastAPI/Django routes, and pytest suites
  • C#/.NET projects, ASP.NET endpoints, source groups, and test projects
  • JVM semantic role groups
  • Ruby packages, Rails apps, executables, and tests
  • Rust crates and binaries
  • C/C++ standalone binaries and CMake/autotools targets
  • SwiftPM targets and tests
  • Laravel controllers, requests, jobs, commands, services, models, migrations, and tests
  • Config files

Preview mapping without writing:

clawpatch map --dry-run

Check mapped features:

clawpatch status --json | jq '.features'

3. Review

Review a few features in parallel:

clawpatch review --limit 3 --jobs 3

Using Grok instead of the default Codex provider:

clawpatch review --provider grok --limit 3 --jobs 3

This:

  • Selects 3 pending features
  • Reviews them in parallel with 3 workers
  • Calls the selected provider (Codex or Grok CLI) for each
  • Persists findings under .clawpatch/findings/
  • Updates feature status

Progress goes to stderr, so you can pipe stdout:

clawpatch review --limit 5 --json | jq '.findings'

4. Generate report

clawpatch report

Filter by severity:

clawpatch report --severity high

Save to file:

clawpatch report -o report.md

5. Fix a finding

List findings:

clawpatch report --status open

Fix one:

clawpatch fix --finding <findingId>

This:

  • Validates worktree is clean
  • Calls provider with patch instructions
  • Runs validation commands
  • Records patch attempt
  • Shows diff

Review the changes and commit manually if satisfied.

6. Revalidate

After manual edits or to re-check a finding:

clawpatch revalidate --finding <findingId>

Common workflows

Review entire project

clawpatch review --limit 999 --jobs 4

Review specific feature

clawpatch review --feature <featureId>

Review with different model

clawpatch review --model claude-opus-4-20250514 --limit 5

Review with explicit Codex reasoning effort

clawpatch review --model gpt-5.5 --reasoning-effort xhigh --limit 5

Filter report by category

clawpatch report --category security

Check provider status

clawpatch doctor

Clean stale locks

If a review run was interrupted:

clawpatch clean-locks

Output formats

All commands support --json for machine-readable output:

clawpatch map --json
clawpatch review --json
clawpatch status --json

Next steps