# Stet: guardrails for AI coding agents (full documentation)

Website: https://getstet.dev · Source: https://github.com/shamazkhan/stet · Package: https://www.npmjs.com/package/stet-cli (command: `stet`) · Licence: MIT · Current version: 0.6.1

## What Stet is

Stet is a free, open-source command-line tool and MCP server that stops AI coding agents from breaking code that already works. "Stet" is the proofreader's mark for "let it stand": keep what is right.

AI coding agents (Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Gemini CLI) and AI chats (ChatGPT, Claude, Gemini) are fast, but they regularly:

- change files that have nothing to do with the task (scope creep),
- break working features while adding new ones (regressions), sometimes by quietly editing or weakening a test,
- ignore the rules written in AGENTS.md, CLAUDE.md or Cursor rules,
- lose project context between sessions, so decisions get reopened and source folders get re-uploaded.

Stet turns the human's intent into checks the agent cannot rewrite:

1. **Scope guard.** Before a task, agree which files it may touch: `stet scope set "Add dark mode" --allow "src/theme/**"`. After the task, `stet guard` lists every file changed outside that scope or in protected paths, including changes already committed. A git pre-commit hook can block out-of-scope commits.
2. **Locked behaviours.** Record the commands that prove features still work: `stet lock add "Login works" --cmd "npm test -- auth" --protect "src/auth/**"`. `stet check` runs them after every AI change. Snapshot locks save a command's output (an export, a route list, an API response shape) as the approved version and fail with a diff when it changes. The rule is "fix the change, not the check".
3. **One rulebook for every agent.** Stet keeps AGENTS.md and CLAUDE.md in sync with the project charter, the current scope, the locked behaviours and the decision log, so every tool reads the same rules.
4. **Git-synced context.** `stet context` builds a context pack from the live repository (rules, scope, locks, decisions, recent commits, uncommitted changes, file tree and chosen files) for any AI chat, so you stop uploading your source folder.
5. **Developer workflow.** `stet pr` writes the commit message and PR description from facts (diff, scope result, check results, decisions). `stet study "<topic>"` maps how part of the code works. `stet handoff` writes an onboarding pack. Linear tickets can drive the scope.

Stet runs locally. No account, no telemetry; code never leaves the machine. The only optional network call is fetching a Linear ticket by ID.

Stet complements tests, CI and AI code review rather than replacing them: it records which tests prove a feature works and which files a task may touch, and checks every AI change against both, before review.

## Install

Requires Node.js 18 or newer and a git repository.

```
npx stet-cli init            # try it in the current repo
npm install -g stet-cli      # or install the `stet` command globally
```

`stet init` detects the stack, creates `.stet/` (charter, config, locks, scope, decision log), writes AGENTS.md and CLAUDE.md, and locks the existing test suite as L1. Commit `.stet/`, AGENTS.md and CLAUDE.md so every agent and teammate shares the same rules.

## Workflow for one AI task

```
stet scope set "Add dark mode" --allow "src/theme/**,tests/theme/**"
# the AI agent does the task (Claude Code, Cursor, Codex, ChatGPT...)
stet guard                   # anything changed outside the task or in protected paths?
stet check                   # do all locked behaviours still pass?
stet scope done --commit     # guard + check, commit only the task's files, close the scope
```

Uncommitted work from an earlier task is "carried" when a new scope starts: guard ignores those files unless they change again during the new task. `--strict` refuses to start a scope until the working tree is clean.

## Connecting AI tools

- **Claude Code:** `stet init --mcp`, or `claude mcp add stet -- npx -y stet-cli mcp`. Claude Code reads CLAUDE.md, which imports AGENTS.md.
- **Cursor:** add `{ "mcpServers": { "stet": { "command": "npx", "args": ["-y", "stet-cli", "mcp"] } } }` to `.cursor/mcp.json`.
- **Codex, GitHub Copilot, Windsurf, Gemini CLI:** they read AGENTS.md directly.
- **ChatGPT, Claude.ai, Gemini (chat):** run `stet context --files "<globs>"` and paste the result.

MCP tools: `stet_context`, `stet_guard`, `stet_check`, `stet_scope` (read-only: only the human sets scope), `stet_pr`, `stet_study`, `stet_decide`.

## Commands

| Command | What it does |
|---|---|
| `stet init [--name X] [--mcp]` | Set up `.stet/`, AGENTS.md and CLAUDE.md; locks the test suite. Safe to re-run. |
| `stet scope set "<task>" --allow "<globs>" [--ticket LIN-142] [--strict]` | Agree the task and the files it may touch. |
| `stet scope carry <file,…>` / `--all` | Mark files as earlier work, not the agent's. |
| `stet scope done [--commit] [--force]` | Guard and check, commit the task's files, close the scope. |
| `stet scope [show\|clear\|ticket]` | Show or clear the scope. |
| `stet guard [--staged] [--base ref] [--warn]` | Flag changes outside scope or in protected paths. Exit 1 on violations. |
| `stet lock add "<behaviour>" --cmd "<cmd>" [--protect "<globs>"]` | Lock a behaviour with a command that proves it. |
| `stet lock add "<behaviour>" --snapshot "<cmd>" [--mask "<regex>"]` | Lock a command's output as an approved snapshot. |
| `stet lock approve L3 --why "<reason>"` | Accept an intended snapshot change; logged as a decision. |
| `stet lock [list\|rm L2\|rename L1 "<name>"]` | Manage locks. Duplicate commands are refused. |
| `stet check [--only L1,L2]` | Run locked behaviours. Exit 1 if any fail. |
| `stet context [--files "<globs>"] [--changed] [--diff] [--flow <topic>]` | Context pack for any AI chat, copied to the clipboard. |
| `stet decide "<decision>" [--why "<reason>"]` / `stet decisions` | Decision log that agents read. |
| `stet pr [--base main] [--check]` | Commit message and PR description from facts. |
| `stet study "<topic>"` | Map a flow: files, routes, Mermaid diagram, tests, protection gaps. |
| `stet handoff` | Onboarding pack for a new developer or CTO. |
| `stet ticket LIN-142` | Fetch a Linear ticket (needs LINEAR_API_KEY). |
| `stet hook install [--check]` | Git hooks: block out-of-scope commits; add ticket IDs to commit messages. |
| `stet status` | One-screen summary. |
| `stet mcp` / `stet mcp install` | Run the MCP server, or write `.mcp.json`. |

Add `--json` to any command for machine-readable output.

## In CI

```
- run: npx -y stet-cli guard --base origin/main --warn
- run: npx -y stet-cli check
```

## FAQ

**What problem does Stet solve?** AI coding agents change files outside the task and break features that already worked. Stet makes the task scope and the "must keep working" list explicit, and checks every change against them.

**How is Stet different from AGENTS.md, CLAUDE.md or Cursor rules?** Rules files tell an agent what to do; nothing checks that it did. Stet keeps those files current and verifies the result with `stet guard` and `stet check`. The agent can read the scope but cannot change it.

**How is Stet different from tests and CI?** Stet uses your tests. It adds the task scope (which files may change), protected paths, snapshot locks and the rule that the agent must not weaken a check, and it runs before review rather than after merge.

**How is Stet different from AI code review bots?** Review bots comment on a pull request after the fact and can miss intent. Stet enforces the agreed scope and locked behaviours deterministically, before the change is committed.

**Does it work with Claude Code, Cursor, Codex, Copilot and ChatGPT?** Yes: MCP for Claude Code and Cursor, AGENTS.md for Codex, Copilot, Windsurf and Gemini CLI, and a context pack for any chat.

**Does Stet send my code anywhere?** No. It is a local CLI with no telemetry.

**What languages does it support?** Any language: locks are commands you choose. Stack detection and `stet study` understand JavaScript/TypeScript and Python best.

**Is it free?** Yes, MIT-licensed. A hosted Stet Cloud for team-wide PR checks is planned.

**What if a locked behaviour has to change on purpose?** Update the test deliberately, re-lock it, and record why with `stet decide` (or `stet lock approve` for snapshots).