claude-enchant

Auto-triggering behavioral rules for Claude Code

Enchantments that make your AI coding assistant smarter, safer, and more productive.

---

What are Enchantments?

Enchantments are behavioral rules that Claude Code follows automatically — no slash commands needed. They activate based on context, like a reflex system for your AI assistant.

Think of them as .cursorrules on steroids: instead of static instructions, enchantments react to what you're doing and activate the right behavior at the right time.

You: "commit this"
                                    ┌─────────────────────────┐
Guardian activates ──────────────►  │ ✓ Conventional format   │
                                    │ ✓ Stage specific files  │
Sentinel activates ──────────────►  │ ✓ No secrets in diff    │
                                    │ ✓ No .env files staged  │
Reviewer activates ──────────────►  │ ✓ No debug statements   │
                                    │ ✓ Tests still passing   │
                                    └─────────────────────────┘

Without enchantments: You get whatever Claude's default behavior is. With enchantments: You get a disciplined, security-conscious, convention-following coding partner that learns from past mistakes.

---

Install

npx claude-enchant init

This will:

1. Scan your project and detect the stack
2. Create a CLAUDE.md with all enchantments
3. Set up a persistent memory system at ~/.claude/memory/

Or add enchantments to an existing CLAUDE.md:

npx claude-enchant install

Or install a specific enchantment:

npx claude-enchant install guardian
npx claude-enchant install sentinel
npx claude-enchant install tdd

---

Enchantments

12 battle-tested enchantments organized by priority level.

Safety (Always Active)

Enchantment	Level	Auto-Trigger
Guardian	Lv.1	After code tasks, on "commit"
Sentinel	Lv.2	Before commits, when writing auth code
SafetyNet	Lv.3	Before rm -rf, git reset --hard, force push

Code Quality

Enchantment	Level	Auto-Trigger
Explorer	Lv.1	When modifying existing code
Minimalist	Lv.2	When implementing anything
Architect	Lv.2	Files > 500 lines, "break this down"
Reviewer	Lv.2	Before declaring "done"
TDD	Lv.3	"Write tests", "add tests", "TDD"
Planner	Lv.2	Multi-file changes, architectural decisions

Intelligence

Enchantment	Level	Auto-Trigger
Recall	Lv.3	Session start, "do you remember", "last time"
Evolve	Lv.4	After significant work, when mistakes are caught
Diplomat	Lv.1	Always active

---

Memory System

Enchantments include a persistent memory system that survives across sessions:

~/.claude/memory/
├── MEMORY.md          # Key patterns and decisions (auto-loaded every session)
├── learnings.md       # Past mistakes to avoid repeating
└── preferences.md     # Your workflow preferences (learned over time)

The Recall enchantment reads these on session start. The Evolve enchantment updates them after significant work. Your Claude gets smarter every session.

---

Hook Recipes

Pre-built hook configs for ~/.claude/settings.json:

Hook	Event	What it does
pre-commit-secrets	PreToolUse	Blocks commits with .env or credential files
auto-lint	PostToolUse	Runs linter after file modifications
test-on-change	PostToolUse	Suggests running tests when source files change

Copy from the hooks/ directory to your Claude Code settings.

---

How It Works

Enchantments are injected into your CLAUDE.md file — the instruction file Claude Code reads on every session. They use a simple format:

### 1. Guardian (Lv.1) — Git Commit Safety

**Auto-trigger:** After completing any coding task, when user says "commit"

**Behavior:** Format commits as `<type>(<scope>): <description>`. Stage specific files.
Check for secrets before committing. Never force-push without permission.

Claude Code reads these instructions and follows them automatically. No plugins, no extensions, no API keys — just markdown that makes your AI smarter.

---

CLI Commands

npx claude-enchant init              # Create CLAUDE.md + memory system
npx claude-enchant install           # Add all enchantments to existing CLAUDE.md
npx claude-enchant install <name>    # Add specific enchantment
npx claude-enchant list              # Show available enchantments
npx claude-enchant scan              # Detect project stack
npx claude-enchant hooks             # Show available hook recipes

---

FAQ

Do enchantments work with other AI editors? Yes. The enchantments are markdown instructions in CLAUDE.md. Cursor reads .cursorrules, Windsurf reads .windsurfrules — the concept is the same. You can adapt these for any AI coding tool.

Can I write my own enchantments? Absolutely. Add a .md file to the enchantments/ directory following the format: name, level, auto-trigger condition, and behavior description. Run npx claude-enchant install to add it.

Do enchantments use tokens? Yes — they're part of your CLAUDE.md which is loaded into context. The 12 included enchantments add ~2K tokens. This is negligible compared to the value they provide.

How is this different from .cursorrules or slash commands? Slash commands are manual — you invoke them. Enchantments are automatic — they activate based on context. .cursorrules are static instructions. Enchantments are reactive behaviors with priority levels and trigger conditions.

---

Contributing

1. Fork this repo
2. Add your enchantment to enchantments/ following the naming format
3. Test it by running npx claude-enchant install <name> in a project
4. Submit a PR with a description of what it does and when it triggers

---

License

MIT — use it however you want.

---

_{Built by Anuar AX — making Claude Code work the way it should.}