stamp-cli: A Local Code Review Protocol for Agent Workflows

stamp-cli is a local, headless code review system designed for AI agents, aiming to solve efficiency and security issues in code reviews between agent clusters. It enables secure collaboration between agents through structured review processes and cryptographic signature mechanisms (Ed25519). It has no Web UI and runs on CLI and git hooks. Its core goal is to provide an efficient, verifiable, and auditable code review protocol for agents.

As AI agents play an increasingly important role in software development, traditional code review processes (relying on GitHub Web interfaces and human judgment) are neither efficient nor suitable for agent clusters. Thus, stamp-cli was born: it is a local headless pull request system designed specifically for agent-to-agent review workflows. The author agent opens a diff, the reviewer agent returns structured feedback, and after iterating until merge rules are met, it signs and merges before pushing—remote repositories will reject pushes that lack proper review and signature.

Design Philosophy

stamp-cli is not a GitHub replacement; it is designed for rapid iteration of agent clusters and keeping the main branch clean. It has no Web UI or human comment threads and relies only on CLI and git hooks. Design principles include: output as prose (easily understandable by LLMs), control flow via exit codes, state stored in files, and idempotent operations.

Key Concepts

• Reviewer: Defined by .stamp/reviewers/.md prompt files; stamp init scaffolds three initial reviewers: security, standards, and product.
• Verdict: The reviewer's judgment on the diff, recorded in .git/stamp/state.db by (base_sha, head_sha) to ensure traceability.
• Gate: The latest verdict of required reviewers must be 'approved', configured in .stamp/config.yml.
• Proof: stamp merge uses Ed25519 to sign the payload, which is attached to the merge commit's footer, providing non-repudiable audit trails.
• Hook: stamp-verify runs in the server-side pre-receive phase, re-executing client-side checks to prevent bypasses.

Typical Workflow

1. Initialization: stamp init scaffolds the .stamp/ directory and key pair
2. Review: stamp review --diff main..feature runs all configured reviewers in parallel
3. Status Check: stamp status --diff main..feature checks the gate status
4. Merge: stamp merge feature --into main creates a signed merge commit
5. Push: stamp push main pushes the main branch; the remote advances after hook verification passes

Exit Code Semantics

Command	Exit Code 0	Non-zero Exit
stamp review	Reviewers ran and recorded	Invocation failed (reviewer crash, DB error); follow with stamp status check
stamp status	Gate is open (all required reviewers approved)	Gate is closed
stamp merge	Merge is signed and on main branch	Gate closed, pre-merge check failed, or git conflict
stamp push	Remote accepted	Hook rejected or git error
stamp verify	Proof is valid	Verification step failed

Security Model

• Protective Measures: Author agents cannot merge unreviewed code; cannot forge merges (signature keys are securely stored); cannot bypass remote verification (enforced by server-side hooks).
• Security Boundary: Humans holding signature keys can generate valid signatures, but signatures provide non-repudiability (merge attribution is traceable).
• Pre-merge Check Risks: required_checks run before signing; non-zero exit blocks merging; changes to .stamp/config.yml require review.

Deployment Modes

1. Self-hosted Remote: User server runs git+sshd, installs pre-receive hooks, and rejects unsigned pushes.
2. Self-hosted + GitHub Mirror: stamp server is the source of truth; post-receive hooks mirror to GitHub; GitHub branch protection restricts pushes.
3. Pure Local: No server; generates signed merges, verifiable but cannot prevent bypasses; suitable for individuals or small teams.

Reviewer Prompt Engineering Tools

• stamp reviewers test --diff : Tune prompts without recording to DB
• stamp reviewers show : View verdict history and statistics
• stamp reviewers verify []: Check prompt/tool matching

Technical Dependencies and Licensing

• Requires Node 22.5+ (uses node:sqlite and Ed25519 API)
• MIT license, but depends on @anthropic-ai/claude-agent-sdk (Anthropic proprietary license)

Future Outlook

stamp-cli represents the direction of AI-native development tools: designing dedicated protocols for agents rather than adapting human tools. It will become an important part of the infrastructure for managing AI agent collaboration in the future.