Turn every AI mistake into a rule AI can't repeat.
Ketchup runs 20+ LLM-powered guardrails on every AI commit, so bad commits don't land.
/plugin install ketchup
Ketchup is an open-source guardrail engine for Claude Code, from the team at Auto.
Today: Claude Code only. If your agent exposes hooks or an equivalent integration surface, open an issue.
AI coding agents have three problems: they're biased for delivery, they have no negative knowledge about your system, and every prompt is a clean slate that forgets yesterday's lessons. Static tools (eslint, husky, commitlint) can't catch semantic failures: a test that asserts nothing, a commit that bundles three unrelated concerns, a "fix" that rationalizes a shortcut, an architectural rule violated three months after you wrote it.
Ketchup runs a separate Claude subagent against every commit, with your rules as its context and no investment in whether the commit ships. When it finds a violation, it blocks the commit and tells you why.
The workflow is: observe an AI mistake, encode it as a rule, AI can't repeat it. The codebase gets permanently safer as you keep working, not just temporarily cleaner. See Guardrail Engineering for the mechanism and the Ketchup Technique for the planning rhythm that feeds clean work into it.
Ketchup comes from the team building Auto, a spec-driven development platform: Auto decides what to build, and Ketchup enforces how. Use them together or use Ketchup on its own; both work.
- Hooks: Three integration points (SessionStart, PreToolUse, UserPromptSubmit) that let Ketchup observe and gate Claude Code's behavior
- Validators: Markdown files with YAML frontmatter that ACK or NACK commits based on your criteria
- Reminders: Context-injection files that surface your guidelines at the right moment
- Deny-list: Glob patterns that protect files from modification
- TCR Discipline: Test && Commit || Revert, so bad code auto-reverts
- Parallel subagent planning:
ketchup-plan.mdcarries dependency notation so independent bursts launch in parallel sub-agents
Inside any Claude Code session:
/plugin marketplace add BeOnAuto/auto-plugins
/plugin install ketchup
claude --plugin-dir /path/to/ketchupClaude Code sets CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA automatically. Run /ketchup:init inside a session to activate per-project configuration, validators, and logging.
# Marketplace (inside Claude Code)
/plugin marketplace add BeOnAuto/auto-plugins
/plugin install ketchup
# Or local plugin mode
claude --plugin-dir /path/to/ketchupAfter installation, Claude will mention that Ketchup is available. To activate it in a project:
/ketchup:init
This creates .ketchup/ with default configuration. You can add it to .gitignore for personal use, or commit it for the whole team.
If you're upgrading from claude-auto, your existing .claude-auto/ directory will be auto-renamed to .ketchup/ on first session-start. No manual action required.
Next steps:
Add project-specific rules by creating markdown files in .ketchup/validators/ and .ketchup/reminders/.
Create .ketchup/validators/my-rule.md:
---name: my-ruledescription: Enforce my custom ruleenabled: true---
You are validating a git commit. Check that [your criteria here].
Respond with JSON only:
- If the commit passes: {"decision":"ACK"}
- If the commit fails: {"decision":"NACK","reason":"explanation"}Validators receive the staged diff, file list, and commit message. They must return ACK or NACK as JSON.
Create .ketchup/reminders/my-reminder.md:
---when:
hook: UserPromptSubmitpriority: 50---
Your reminder content here. This gets injected on every prompt.The when field controls when the reminder fires:
| Condition | Fires when |
|---|---|
hook: SessionStart | Once at session start |
hook: UserPromptSubmit | Every user prompt |
hook: PreToolUse | Before tool execution |
hook: PreToolUse + toolName: Bash | Only before Bash tool |
(no when) | All hooks |
Higher priority = appears first. Project-local files are loaded alongside plugin defaults. If filenames collide, plugin versions take precedence.
Toggle validators and reminders without editing files:
/ketchup:config show
/ketchup:config validators disable no-comments
/ketchup:config reminders priority my-reminder 200
/ketchup:config reminders add my-rule --hook UserPromptSubmit --priority 50 --content "Always use early returns"git worktree add ../feature-auth feature/auth
git worktree add ../feature-payments feature/paymentsEach worktree runs its own Ketchup instance, all quality-validated.
{
"validateCommit": { "mode": "strict", "batchCount": 3 },
"denyList": { "enabled": true },
"promptReminder": { "enabled": true },
"subagentHooks": {
"validateCommitOnExplore": false,
"validateCommitOnWork": true,
"validateCommitOnUnknown": true
}
}Configuration lives in .ketchup/state.json. See the Configuration guide for all options.
flowchart LR
A[Claude Code] --> B[Hook Scripts]
B --> C{Hook Type}
C -->|SessionStart| D[Load Reminders]
C -->|PreToolUse| E[Validate Commits + Deny-list]
C -->|UserPromptSubmit| F[Inject Reminders]
E -->|ACK| H[Allow]
E -->|NACK| I[Block + Revert]
Hook scripts read JSON from stdin, delegate to handlers in src/hooks/, log results, and output JSON to stdout. Validators are batched (default 3 per Claude CLI call) for efficient parallel validation. Reminders are matched by hook type, mode, and tool name, then injected as <system-reminder> blocks.
Ketchup is Claude Code-first today. The Ketchup Technique (the methodology) works with any AI coding agent by hand. If your agent exposes hooks or an equivalent integration surface, open an issue so we can scope adapter work.
Symptom: Commits go through without validation.
Cause: Plugin not installed or not enabled.
Solution:
/plugin install ketchup
DEBUG=ketchup claude --plugin-dir /path/to/ketchupDEBUG=ketchup writes diagnostics to .ketchup/logs/ketchup/debug.log.
| Guide | Description |
|---|---|
| Getting Started | First-time setup and core concepts |
| Installation | Detailed installation guide |
| The Ketchup Technique | The planning methodology |
| In the Stack | How Ketchup fits with Auto and spec-driven development |
| Configuration | All configuration options |
| Hooks Guide | Hook system deep-dive |
| Reminders Guide | Context injection system |
| Validators Guide | Commit validation rules |
| Architecture | System design internals |
| Origin Story | How Ketchup came to be |
.claude-plugin/
└── plugin.json # Plugin manifest (name, version, description)
hooks/
└── hooks.json # Plugin hook definitions (SessionStart, PreToolUse, etc.)
validators/ # Default commit validators
reminders/ # Default context-injection reminders (10 files)
agents/ # Sub-agent definitions (validator agent)
src/
├── brand.ts # BRAND constants (single source of truth for naming)
├── hooks/ # Hook handlers (session-start, pre-tool-use, user-prompt-submit)
├── migrate.ts # .claude-auto -> .ketchup auto-migration
├── path-resolver.ts # Plugin-mode path resolution
├── commit-validator.ts # Batched commit validation with appeal support
├── deny-list.ts # File protection via micromatch patterns
├── reminder-loader.ts # Multi-directory reminder system with deduplication
├── hook-state.ts # Hook state management (state.json)
├── validator-loader.ts # Multi-directory validator loader
└── index.ts # Public API barrel exports
scripts/
├── session-start.ts # SessionStart hook entry-point (runs migration first)
├── pre-tool-use.ts # PreToolUse hook entry-point
└── user-prompt-submit.ts # UserPromptSubmit hook entry-point
| Package | Usage |
|---|---|
| gray-matter | YAML frontmatter parsing for validators and reminders |
| micromatch | Glob pattern matching for deny-lists |
- Node.js 18+
- pnpm 10+
git clone https://github.com/BeOnAuto/ketchup.git
cd ketchup
pnpm install
pnpm build| Command | Description |
|---|---|
pnpm build | TypeScript compile + esbuild bundle scripts |
pnpm test | Run all tests (vitest) |
pnpm type-check | TypeScript type checking |
pnpm lint | Biome lint check |
pnpm check | Full CI: build + type-check + test + lint |
MIT © 2025 BeOnAuto, Inc.
See LICENSE for details.