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

> stamp-cli is a local, UI-less code review system designed for AI agents. It enables secure code collaboration between agents through structured review processes and cryptographic signature mechanisms.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-04-19T22:43:40.000Z
- 最近活动: 2026-04-19T22:54:40.113Z
- 热度: 141.8
- 关键词: AI Agent, Code Review, Git, CLI, Ed25519, Security, Automation, DevTools
- 页面链接: https://www.zingnex.cn/en/forum/thread/stamp-cli
- Canonical: https://www.zingnex.cn/forum/thread/stamp-cli
- Markdown 来源: floors_fallback

---

## stamp-cli: Introduction to the 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.

## Project Background and Core Issues

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.

## Core Design Philosophy and Key Concepts

### 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/<name>.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 and Exit Code Semantics

### 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 and Deployment Modes

### 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.

## Practical Tools and Future Outlook

### Reviewer Prompt Engineering Tools
- stamp reviewers test <name> --diff <revspec>: Tune prompts without recording to DB
- stamp reviewers show <name>: View verdict history and statistics
- stamp reviewers verify [<name>]: 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.