Pointbreak Review

Pointbreak Review is a durable, local-first review record for code changes that humans and coding agents build together. It is designed for the iteration that happens long before a pull request opens, where you might guide one agent to author a change and another to review it.

Coding agents generate far more activity than anyone can follow. Rather than store or replay full transcripts, Pointbreak keeps only the facts that move a review forward: what changed and why, the open questions, and each assessment. It records them as an append-only log you can read in the terminal, browse in a local web inspector, or consume as JSON.

Every fact carries the actor that asserted it, human or agent, and can be signed with an Ed25519 key. Signing never blocks a write, but when a signature is present the record becomes tamper-evident, and a reader can tell whether each fact is merely signed or bound to a trusted identity. See docs/signing-ux.md.

Watching a review in the Pointbreak Review inspector opened by shore inspect: the event timeline, each fact attributed to its track, with signature-trust badges.

Install the pointbreak crate; it provides the shore command:

cargo install pointbreak
shore --help

Download a prebuilt binary

Releases that include prebuilt binaries provide an archive for each supported target. Set the version and target first, then download the matching archive:

VERSION=0.6.0        # see the releases page for the current version
TARGET=darwin-arm64  # pick yours from the table below
curl -fsSL -O "https://github.com/kevinswiber/pointbreak/releases/download/v${VERSION}/pointbreak-${VERSION}-${TARGET}.tar.gz"
tar xzf "pointbreak-${VERSION}-${TARGET}.tar.gz"
./shore --version

Download checksums.txt from the same release and verify the archive. On Linux:

curl -fsSL -O "https://github.com/kevinswiber/pointbreak/releases/download/v${VERSION}/checksums.txt"
sha256sum -c --ignore-missing checksums.txt

On macOS, use the system-provided shasum instead:

shasum -a 256 -c --ignore-missing checksums.txt

The win32-* targets ship as .zip archives containing shore.exe. This PowerShell flow downloads an archive, verifies its checksum case-insensitively, and only then extracts it:

$Version = "0.6.0"
$Target = "win32-x64"
$Archive = "pointbreak-$Version-$Target.zip"
Invoke-WebRequest "https://github.com/kevinswiber/pointbreak/releases/download/v$Version/$Archive" -OutFile $Archive
Invoke-WebRequest "https://github.com/kevinswiber/pointbreak/releases/download/v$Version/checksums.txt" -OutFile checksums.txt
$Expected = (Select-String -Path checksums.txt -Pattern ([regex]::Escape($Archive))).Line.Split(' ')[0]
$Actual = (Get-FileHash $Archive -Algorithm SHA256).Hash.ToLower()
if ($Actual -ne $Expected) { throw "checksum mismatch for $Archive" }
Expand-Archive $Archive -DestinationPath .
.\shore.exe --version

Archives downloaded with curl on macOS need no quarantine adjustment. If a browser download is quarantined, remove the attribute after extraction with xattr -dr com.apple.quarantine ./shore.

See the GitHub releases page for available versions and assets.

Quick Start

Start with the first-review walkthrough:

• docs/getting-started.md

The short path is:

cd path/to/git-worktree
shore capture
shore revision show --format json-pretty

Then record what you learn:

shore observation add --track human:local --title "Check error handling"
shore input-request open --track human:local --title "Need decision" \
  --reason manual-decision-required --mode advisory
shore assessment add --track human:local --assessment needs-clarification \
  --summary "Small change, but one decision is still open."

In a real collaboration each actor records on its own track — the coding agent that authored the change (agent:codex), a reviewer that is a human or another agent, and you (human:local) — so every fact stays attributed to whoever asserted it. See the review workflow and agent authoring handoffs for how the author and reviewer hand off.

Or browse the whole store visually — event timeline, per-revision pages, and annotated diffs — in a local web UI:

shore inspect --open

Pointbreak stores local review facts in .shore/data/. Command output JSON is the integration surface; raw event files, artifact paths, and .shore/data/state.json are internal storage details unless a command explicitly documents them. Consumers that prefer to read and write those facts in process can use the supported library API instead of the CLI — see docs/library-api.md.

Commands

The shore command surface is still taking shape and will change before v1. See docs/cli-reference.md for the current commands, their options, output documents, schema names, and V1 limitations.

Agent Skills

Pointbreak ships a portable author-handoff skill under skills/. Install it with:

npx skills add kevinswiber/pointbreak

Documentation

For users:

• Getting started - first local review from a scratch Git repository.
• CLI reference - commands, options, output JSON, and V1 boundaries.
• Review workflow - when to use capture, observations, input requests, assessments, history, and revision show.
• Agent authoring handoffs - how a coding agent captures a durable handoff record before declaring implementation work done.
• Agent skills - install the portable Pointbreak author-handoff skill.
• Library API - the supported in-process library surface (reads, attributed writes, event ingest, documents) and its stability contract.
• Signing UX - human, agent, and CI signing flows and the unsigned/untrusted_key/valid verification ladder.

For contributors and maintainers:

• CONTRIBUTING.md - setup, hooks, branch names, commits, tests, and PR flow.
• docs/releasing.md - release planning and publish automation.
• docs/manual-testing.md - maintainer spot-check recipes.
• TRADEMARKS.md - trademark use for names and logos.

Architecture and model notes:

• docs/storage-model.md - durable events, artifacts, and rebuildable projections.
• docs/input-request-model.md - operative and advisory input requests.
• docs/assessment-model.md - review assessments and replacements.
• docs/adr/ - architectural decision records.

Project Status

Pointbreak Review is experimental and under active development. The published crate is pointbreak; the installed command stays shore because command names should remain short and practical.

The current focus is a headless, durable review model first:

• Git working-tree or commit-range (--base) capture into a revision
• append-only local events under .shore/data/events/
• immutable snapshot and note-body artifacts under .shore/data/artifacts/
• rebuildable projections and command-output JSON
• read-only terminal and local web views over the same model

Contributing

Read CONTRIBUTING.md before opening a pull request. The short validation path is:

just setup-hooks
just check

Security-sensitive reports should follow SECURITY.md, not public issues.

License And Trademarks

This repository's source code is licensed under Apache-2.0. See LICENSE.

Pointbreak, Pointbreak Review, and the Pointbreak logo are trademarks of Kevin Swiber. Trademark rights are reserved; see NOTICE and TRADEMARKS.md. The private Pointbreak debugger codebase is not part of this Apache-2.0 repository unless it is separately published under its own license.