Purpose
twoperson solves a very specific problem: when you have two AI coding agents collaborate (one responsible for writing code, one for reviewing), if the rule "review before delivery" is only written in the system prompt, over time the builder agent will decide on its own that review is optional, approve its own work, or after receiving a real review, rebase more commits on top of it and then push everything together. twoperson moves this rule out of the prompt and into the data format that the two agents use to communicate with each other, enforcing it with a schema.
Main capabilities
twoperson's core is five "refusal" mechanisms:
- A review verdict must answer a review packet that actually exists in the inbox.
- An approval must name the commit where that review packet is located, and not some other commit.
- A review packet cannot claim to have been pushed, deployed, or restarted without a review reference.
- The reference must be a verdict that actually exists, represents approval, and approves that commit.
- If the review packet's changed_files show that tests were modified (other than additions or copies), the referenced verdict must confirm those exact paths.
In addition to the refusal mechanisms, it also includes: recomputing changed_files and diff_summary from the git diff between two shas, and refusing claims that do not match head; checking whether base_sha is a true ancestor of head_sha (using git merge-base --is-ancestor); when base_ref can be resolved, also requiring base_sha to be reachable; performing strict schema validation on the review packet (rejecting unknown keys, limiting string lengths and list counts, and requiring paths to be repository-relative paths); scanning for suspected credentials (Anthropic, OpenAI, GitHub, AWS, Slack, Google keys, PEM blocks, bearer tokens, etc.); and when rendering the review packet, wrapping the body with BEGIN/END markers and declaring that this is data and not instructions.
How to use
The workflow is: the builder agent writes a review packet, that is, a JSON record containing what it is trying to do, the head sha, which files were changed, which tests were run and their results.twoperson publish Validate it and place it into .twoperson/pending/. The reviewer claims it, reads it, and writes a verdict.twoperson verdict --ack-test-changes is used to confirm test changes; it derives the confirmation paths from the reviewed --packet rather than a hand-typed list.twoperson verify runs the same checks as publish (including diff derivation) but writes nothing, and can be used for a dry run.check is designed to be pollable and does not touch the model.
It can also, via twoperson install , add a Stop hook to .claude/settings.json, dropping a small signal file into the inbox at the end of a session. On Mac,twoperson install-watch sets up a launchd agent that triggers when the inbox changes and runs the command you configured in TWOPERSON_ON_PACKET.
twoperson searches upward for the main worktree, so every worktree of the repository lands in the same .twoperson/, and it can be overridden with TWOPERSON_INBOX.twoperson tier Score the review package according to the validated fields, reporting low, medium, high, or critical, for reviewers to select by difficulty. There is also a consult channel (consult-publish / consult-next / consult-advise), used to seek opinions rather than audit, which does not produce conclusions and cannot unlock pushes.
Applicable scenarios
Suitable for scenarios where two AI programming agents collaborate on the same repository and where "review before delivery" is to be enforced at the data layer. Also suitable for teams that need to leave a traceable review record bound to a specific commit.
Limitations
twoperson explicitly does not run models; it only records conventions and tiers. Credential scanning is a "tripwire" rather than a guarantee. It does not require a server, API key, or network. The documentation also points out the differences from similar projects: it is not a review gate that blocks stop within the current turn, but rather leaves a persistent record bound to a specific commit. More specific billing, platform, or pricing information is not yet provided.
