Ketchup
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.
Why
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.
In the stack
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.
Key Concepts
- 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.md carries dependency notation so independent bursts launch in parallel sub-agents
Installation
From the Marketplace (recommended)
Inside any Claude Code session:
/plugin marketplace add BeOnAuto/auto-plugins
/plugin install ketchup
As a Local Plugin
claude --plugin-dir /path/to/ketchup
Claude Code sets CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA automatically. Run /ketchup:init inside a session to activate per-project configuration, validators, and logging.
Quick Start
# Marketplace (inside Claude Code)
/plugin marketplace add BeOnAuto/auto-plugins
/plugin install ketchup
# Or local plugin mode
claude --plugin-dir /path/to/ketchup
After 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:
Custom Validators and Reminders
Add project-specific rules by creating markdown files in .ketchup/validators/ and .ketchup/reminders/.
Custom Validator
Create .ketchup/validators/my-rule.md:
---
name: my-rule
description: Enforce my custom rule
enabled: 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.
Custom Reminder
Create .ketchup/reminders/my-reminder.md:
---
when:
hook: UserPromptSubmit
priority: 50
---
Your reminder content here. This gets injected on every prompt.
The when field controls when the reminder fires:
