Stamp

A beautiful CLI for managing Architecture Decision Records (ADRs).

Inspired by adr-tools, built with Go and the Charmbracelet ecosystem for a delightful terminal experience.

What are ADRs?

Architecture Decision Records are short documents that capture important architectural decisions made along with their context and consequences. They help teams:

• Remember why decisions were made
• Onboard new team members quickly
• Avoid revisiting the same discussions
• Understand the evolution of a system

Learn more at adr.github.io.

Features

• Create, list, and manage ADRs from the command line
• Beautiful terminal output with colored status badges and styled tables
• Link related ADRs together (supersedes, amends, clarifies)
• Visualize ADR relationships with Mermaid or Graphviz graphs
• Rendered markdown viewing with glamour
• Open ADRs in your favorite editor
• Self-updating binary

Installation

Homebrew (macOS/Linux)

brew install stef16robbe/tap/stamp

Quick install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/stef16robbe/stamp/main/install.sh | sh

Download binary

Download the latest binary for your platform from GitHub Releases.

Go install

go install github.com/stef16robbe/stamp/cmd/stamp@latest

Build from source

git clone https://github.com/stef16robbe/stamp.git
cd stamp
go build -o stamp ./cmd/stamp

Quick Start

# Initialize ADR directory in your project
stamp init

# Create a new ADR
stamp new "Use PostgreSQL for persistence"

# List all ADRs
stamp list

# View an ADR
stamp show 1

# Update status
stamp status 2 accepted

# Link ADRs together
stamp link 2 1 supersedes

# Edit an ADR
stamp edit 1

# Generate relationship graph (Mermaid)
stamp graph

# Generate relationship graph (Graphviz DOT)
stamp graph --format dot

Updating

Stamp can update itself to the latest version:

# Check current version
stamp version

# Update to latest release
stamp update

Configuration

Stamp stores its configuration in .stamp.yaml in your project root:

directory: docs/adr

ADR Format

ADRs are stored as Markdown files with the following structure:

# 1. Title of Decision

Date: 2026-01-13

## Status

Accepted

## Context

[Why is this decision needed?]

## Decision

[What was decided?]

## Consequences

[What are the implications?]

AI disclaimer

This project has been built alongside with Claude Code

License

See LICENSE