N4darae/shrt

What it does

shrt tests a backend by replaying ordered chains of API calls such as login, create item, add stock and read back. Chains are written as YAML, a person approves a passing run as the baseline, and later releases are replayed against that baseline. When a response field changes, shrt reports the failing step, the field and the write it suspects caused the drift.

Contracts describe what each RPC should do: required fields, where values come from, how errors are returned, and what writes do to numbers. From a contract, shrt can plan chains automatically, including boundary probes, missing or bad tokens, unknown IDs and duplicate keys. The tool is designed to be driven by a coding agent (shrt init installs a Claude Code skill), but every command also works by hand README.

Requirements and protocol

shrt is installed with Go and needs Go 1.26 or later plus buf on PATH, because it compiles the backend's .proto files with buf build install notes. It speaks the Connect protocol (JSON over HTTP POST) and works against servers built with connect-go, which serves Connect and gRPC side by side. A server that speaks only binary gRPC over HTTP/2 is not supported. Unary and server-streaming RPCs are supported; a streaming step reads the first message.

go install github.com/N4darae/shrt/cmd/shrt@latest
shrt version

Or build from a checkout with go build -o shrt ./cmd/shrt build instructions.

Quick start: the inventory demo

The repository ships a small connect-go service under examples/inventory with four RPCs; with -release 2 it serves GetItem from a stale cache, which the demo catches. Copy it out first, since shrt init writes .shrt/, .claude/ and .gitignore into the current directory demo setup.

git clone https://github.com/N4darae/shrt
cp -r shrt/examples/inventory /tmp/inventory-demo
cd /tmp/inventory-demo
go build -o inventory . && ./inventory &
export API_USER=demo API_PASSWORD=demo-password
shrt init
shrt doctor

init builds the descriptor from the protos, guesses the login RPC and reads one answer to learn the success envelope; credentials stay in the environment and secrets are redacted from run records init output. Then load the example contract and let it plan chains:

shrt contract init -all
cp contracts/inventory.yaml .shrt/contracts/
shrt contract lint
shrt contract plan -all -write
shrt gate
shrt confirm -all -note "release 1 of the inventory demo"
shrt confirm -all -approve -by you@example.com

plan writes one chain per RPC (four chains, 53 steps in the example), and gate runs every chain once. A person must approve the proposed passing run before each response field becomes part of the baseline approval step. To see a regression, restart the service on release 2 and run shrt gate again:

kill %1
./inventory -release 2 &
shrt gate

The gate should fail the inventory-addstock chain with a message naming item.qty_on_hand want=5 got=0 and the write it suspects, and exit 1 so CI fails the build expected failure.

Limits and safety

Chains create records and send deliberately bad requests, so the tool restricts targets: it only sends to localhost, 127.0.0.1 or ::1 unless the host is listed under target.allow_hosts; otherwise run, verify, gate and init's login refuse before the first call. run -dry-run still works because it sends nothing. shrt cannot tell staging from production, so list only backends whose data you accept being changed target rules.

Contracts and chains can carry credentials by environment-variable reference, and the run records redact passwords and tokens. The project is MIT licensed license.

HotRepo's take

The repository's recorded monthly Go ranking shows 2,110 stars and 1,711 stars gained in that period, ranked 10th on the Go monthly list on 2026-11-03. That is the only snapshot available, and no daily all-language rank or star-curve samples were recorded, so the data supports one strong monthly showing rather than a trend. The design detail worth noting is the approval gate: an agent can propose baselines, but a human must confirm them, which fits the project's claim of being agent-driven without handing regression decisions entirely to a model.

Using it with an agent

shrt init installs .claude/skills/shrt/SKILL.md, a subagent for writing contracts, and agent documentation under .shrt/docs/; the sources are in docs/agent/, including a command reference, config and chain keys, procedures and a symptom-to-fix list. Design and limits are in docs/OVERVIEW.md. Every command prints its flags and exit codes with -h.