Getting started

This tutorial takes you from an empty machine to your first completed pull-request review. Follow the steps in order; by the end you will have run planwerk-agent against a real PR and read its report.

Prerequisites

Before you start, make sure you have:

1. Go 1.25+ installed (or download a release binary).
2. Claude Code installed and authenticated (claude in PATH).
3. The gh CLI installed and authenticated (gh auth login).
4. Access to the target repository (for checkout/clone).

planwerk-agent also relies on git as the underlying VCS for gh repo clone and local git operations.

Step 1: Install planwerk-agent

Install the latest release with go install:

go install github.com/planwerk/planwerk-agent/cmd/planwerk-agent@latest

Or, on macOS / Linux with Homebrew:

brew install planwerk/tap/planwerk-agent

Confirm the binary is on your PATH:

planwerk-agent --version

Step 2: Review your first pull request

Point the tool at any pull request you can access. Use either the full URL or the short owner/repo#number form:

planwerk-agent owner/repo#123

planwerk-agent checks out the PR, loads its review patterns, runs a Claude Code session with a structured review prompt, and aggregates the results. The structured report is written to stdout.

Step 3: Read the report

The report is Markdown. It opens with a machine-readable summary comment, followed by findings grouped by severity (BLOCKING, CRITICAL, WARNING, INFO) and a closing summary with a merge recommendation:

# Review: owner/repo#123

<!-- planwerk-agent: blocking=1 critical=2 warning=3 info=1 recommendation=HOLD -->

## BLOCKING (1)

### B-001: Hardcoded secrets in configuration
**File**: `config/auth.go:42` — **Fix**: ASK — **Confidence**: verified

**Problem**: API secret is hardcoded directly in the source code.

**Action Required**: Remove secret from code and provide it via
environment variable or secret manager.

To keep the report, redirect it to a file:

planwerk-agent owner/repo#123 > review.md

Next steps

• Post the review directly onto the PR with --inline — see Review a pull request.
• Learn what every field in the report means — see Output format.
• Turn a whole repository into tracked work — see From repo to GitHub issues.