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.
Decisions outlive conversations. 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 pointbreak inspect: the event timeline, each fact attributed to its track, with signature-trust badges.
On macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.sh | shOn Windows PowerShell:
irm https://raw.githubusercontent.com/withpointbreak/pointbreak/main/scripts/install.ps1 | iexThe installers select the correct release archive, verify its SHA-256 checksum, and install the
pointbreak command. The published pointbreak crate also provides the pointbreak command and can be
installed with cargo install pointbreak.
Release 0.7.0 is a hard operational cutover to this executable and the canonical Pointbreak
environment and storage names. Existing installations must move local state offline before use; see
Upgrading to 0.7.0.
See Installation for version pinning, custom install directories, supported platforms, manual downloads, and checksum verification.
Make a real change in a Git repository — modify a tracked file — then capture it with a useful summary and open Review:
cd path/to/git-worktree
pointbreak capture --summary "Explain the fallback behavior"
pointbreak inspect --openReview is a local, read-only view of the durable record: the captured diff, every fact on its
author's track, and the current call. A review moves through five stages —
Work -> Claims -> Evidence -> Questions -> Call — owned by the existing capture/revision/
inspect, observation, validation, input-request, and assessment command families.
Continue with the complete paired author/reviewer loop — claims, validation evidence, questions, the call, and landing the commit on the same revision — in docs/getting-started.md.
In a real collaboration each actor records on its own track — the coding agent that authored the change, a reviewer that is a human or another agent, and you — 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.
Repository config lives in .pointbreak/. Review facts normally live in the Git common directory's
pointbreak/ store, shared by every linked worktree; an ephemeral worktree uses .pointbreak/data/.
Run pointbreak store paths --format text to see the canonical locations for a repository. Command
output JSON is the integration surface; raw event files, artifact paths, and 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.
The pointbreak 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.
Pointbreak ships a portable author-handoff skill under skills/. Install it with:
npx skills add withpointbreak/pointbreakFor users:
- Getting started - first local review from a scratch Git repository.
- Installation - installers, releases, supported platforms, and checksums.
- CLI reference - commands, options, output JSON, and V1 boundaries.
- Review workflow - the five review stages, the author and reviewer roles, and when to reach for each command family.
- 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.
Pointbreak Review is experimental and under active development. The crate and sole installed command
are both pointbreak.
The current focus is a headless, durable review model and the surfaces derived from it:
- Git working-tree or commit-range (
--base) capture into a revision - append-only local events in the resolved Pointbreak store
- immutable snapshot and note-body artifacts in that store
- rebuildable projections and command-output JSON
- read-only terminal and local web views over the same model
Read CONTRIBUTING.md before opening a pull request. The short validation path is:
just setup-hooks
just checkSecurity-sensitive reports should follow SECURITY.md, not public issues.
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.