What is Codewright?
Codewright is a curated, versioned knowledge base of terminal workflows — recipes — for tasks developers repeat constantly: killing a process on a port, undoing a commit, cleaning up Docker disk usage, resetting a dev database, and more. Every recipe is written once and generated out to five surfaces, so humans and coding agents get the exact same safety net wherever they work.
It exists because the alternative is re-Googling the same command, pasting it from a chat model unverified, or letting a coding agent invent a shell command on the fly — with no risk classification, no undo path, and no way to confirm it actually worked.
Why this exists
- Re-Google the same fix every few weeks
- Paste a command from a chat model, unverified
- An agent invents a shell command on the fly
- No idea if it's destructive, outdated, or right for your OS
- One reviewed recipe per task, versioned in git
- Risk classified before anything runs
- A documented undo path and a verification step
- The same recipe, on macOS, Linux, or Windows
Anatomy of a recipe
Every surface below is generated from documents that look like this one — an actual recipe from the library, in full.
Undo the last commit
git.undo_last_commit · v1 · category: git
Moves the current branch back one commit while keeping the removed commit's changes staged, so they can be amended or committed again.
Platforms
macOS · Linux · Windows — identical steps on all three
Steps
Inspect the working tree before changing branch history
git status --shortRemove the last commit while keeping its changes staged
git reset --soft HEAD~1Verify
git status --shortThe previous commit's changes are staged in the working tree.
Undo
Restore the branch tip to its position before the reset
git reset --soft 'HEAD@{1}'Pitfalls
Fails in a repository with only one commit, since HEAD~1 doesn't exist yet. Prefer git revert on a shared branch to avoid rewriting published history.
The safety system
Four risk levels, applied to every step of every recipe — not just the recipe as a whole. Anything above low can be gated behind explicit confirmation.
Inspects state without changing anything.
Reversible with a routine follow-up command.
Changes state; undo path documented.
Deletes or overwrites; confirmation required.
- 01
Inspect
Read the recipe's risk level, platform, and parameters before anything runs.
- 02
Act
Render the exact command for your platform. Nothing executes without your say-so.
- 03
Verify
Run the recipe's own verification command and confirm the outcome.
- 04
Undo
If it went wrong and an undo path exists, it's documented on the same recipe.
One recipe, five surfaces
Whichever way you found Codewright — this website, an MCP config, an npm package, or a GitHub repo — it's the same reviewed recipe library underneath. A recipe is authored once and can never drift out of sync across the five.
Website
Browse and search every recipe: platform tabs, risk badges, copy buttons, undo instructions, and troubleshooting notes.
curl "https://codewright.tools/api/v1/recipes/search?q=undo%20last%20commit"Public API
REST endpoints that return recipes as structured JSON — list, search, get, and render-with-parameters. No auth required, rate-limited per IP.
curl -X POST "https://codewright.tools/api/v1/recipes/git.undo_last_commit/render" -H "Content-Type: application/json" -d '{"platform": "macos"}'MCP server
Every recipe exposed as an MCP tool — search_recipes, get_recipe, render_recipe — so an MCP-compatible agent host calls a curated workflow instead of inventing a shell command.
claude mcp add codewright -- npx -y @codewright/mcpAgent skill
Encodes the same policy an experienced engineer would apply: inspect before you act, ask before anything destructive, verify after acting.
pnpm --filter @codewright/agent-skill recipe render git.undo_last_commit macosCompanion CLI
Preview a recipe, confirm if it's risky, execute, then verify the outcome — all from your terminal.
npx @codewright/cli run git.undo_last_commitDon't know which surface you need yet? One command detects your agent harness and wires up the MCP server and skill.
npx @codewright/installUnder the hood
The stack the five surfaces run on, and the two pipelines that keep the recipe library — and the codebase itself — moving.
| Layer | Choice | Role |
|---|---|---|
| Framework | Next.js, App Router, TypeScript | One app serves the website and the /api/v1 routes |
| Database | Supabase (Postgres) | Compiled recipe index, full-text search, favorites |
| Recipe source | Versioned YAML in-repo | Reviewed like code; compiled to DB/JSON at build time |
| Validation | Zod | One schema validates YAML in CI and API payloads at runtime |
| Hosting | Vercel | Persistent staging on staging, production on main |
| Auth | Clerk | Gates only personalization — favorites, saved runbooks |
Recipe curation pipeline
New recipes move through a fixed sequence — AI draft → schema validation → deterministic risk-score → human or agent review — before they ever reach the library. Nothing is published on an AI's say-so alone.
The build loop
Codewright is built by an autonomous fleet of agent sessions, coordinated through GitHub Issues and PRs — this page included.
Where it stands
Delivery runs in phases; issues within a phase run in parallel through the agent loop.
- pnpm + Turborepo monorepo
- Next.js App Router scaffold
- CI: lint, typecheck, test, build, recipes-validate
- Recipe schema + validator CLI
- Keyless agent-janitor workflow
- ~100 seed recipes across six categories
- YAML → JSON compile step
- Supabase index + full-text search sync
- Recipe style guide
- Website: browse, search, recipe pages
- Public API v1 + OpenAPI doc
- MCP server, published to npm
- Agent skill: risk policy + confirm/verify
- Landing page with real product copy
- Clerk sign-in + favorites (not yet shipped)
- User-submitted recipes + curation pipeline
- Team runbooks, versioned workflows
- Multi-step diagnostic workflow recipes
- Licensing decision — open-source, no paid tiers