Claude Auto

Husky-style hooks and skills management for Claude Code.

---

Purpose

Without Claude Auto, you babysit every AI coding session. You watch, nudge, correct, and context-switch constantly. One task at a time, full attention required.

Claude Auto installs a quality loop into Claude Code via hooks. Validators gate every commit. Reminders inject your guidelines into every prompt. Deny-lists protect files from modification. Auto-continue keeps the agent working until the plan is done. The system earns trust, and trust enables parallelization via git worktrees.

Key Concepts

• Hooks: Four integration points (SessionStart, PreToolUse, UserPromptSubmit, Stop) that let Claude Auto observe and control 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. Bad code auto-reverts
• Auto-Continue: Keeps the agent going until the plan is done

---

Installation

From the Marketplace (recommended)

Inside any Claude Code session:

/plugin marketplace add BeOnAuto/claude-auto
/plugin install claude-auto@beon-auto

As a Local Plugin

claude --plugin-dir /path/to/claude-auto

Claude Code sets CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA automatically. Validators and reminders load from the plugin package, with optional project-local overrides from .claude-auto/. State and logs go to the project's .claude-auto/ directory.

Quick Start

# Marketplace (inside Claude Code)
/plugin marketplace add BeOnAuto/claude-auto
/plugin install claude-auto@beon-auto

# Or local plugin mode
claude --plugin-dir /path/to/claude-auto

After installation, Claude Auto automatically:

• Injects hooks that validate every commit against your criteria
• Creates reminders that inject your guidelines into prompts
• Sets up file protection via deny-lists

Next steps:

• Getting Started guide
• The Ketchup Technique

---

Custom Validators and Reminders

Add project-specific rules by creating markdown files in .claude-auto/validators/ and .claude-auto/reminders/.

Custom Validator

Create .claude-auto/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 .claude-auto/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:

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.

Runtime Configuration

Toggle validators and reminders without editing files:

/claude-auto:config show
/claude-auto:config validators disable no-comments
/claude-auto:config reminders priority my-reminder 200
/claude-auto:config reminders add my-rule --hook UserPromptSubmit --priority 50 --content "Always use early returns"

---

Multiply with Git Worktrees

git worktree add ../feature-auth feature/auth
git worktree add ../feature-payments feature/payments

Each worktree runs its own Claude Auto instance, all quality-validated.

---

Configuration

{
  "autoContinue": { "mode": "smart" },
  "validateCommit": { "mode": "strict", "batchCount": 3 },
  "denyList": { "enabled": true },
  "promptReminder": { "enabled": true },
  "subagentHooks": {
    "validateCommitOnExplore": false,
    "validateCommitOnWork": true,
    "validateCommitOnUnknown": true
  }
}

Configuration lives in .claude-auto/.claude.hooks.json. See the Configuration guide for all options.

---

How It Works

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]
    C -->|Stop| G[Auto-Continue Decision]
    E -->|ACK| H[Allow]
    E -->|NACK| I[Block + Revert]

Loading

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.

---

Troubleshooting

Hooks Not Firing

Symptom: Commits go through without validation.

Cause: Plugin not installed or not enabled.

Solution:

/plugin install claude-auto@beon-auto

Enable Debug Logging

CLAUDE_AUTO_DEBUG=1 claude --plugin-dir /path/to/claude-auto

CLAUDE_AUTO_DEBUG writes diagnostics to .claude-auto/logs/plugin-debug.log.

---

Documentation

Guide	Description
Getting Started	First-time setup and core concepts
Installation	Detailed installation guide
The Ketchup Technique	The planning methodology
Configuration	All configuration options
Hooks Guide	Hook system deep-dive
Reminders Guide	Context injection system
Validators Guide	Commit validation rules
API Reference	Programmatic access
Architecture	System design internals
Origin Story	How Claude Auto came to be

---

Architecture

.claude-plugin/
└── plugin.json           # Plugin manifest (name, version, description)
hooks/
└── hooks.json            # Plugin hook definitions (SessionStart, PreToolUse, etc.)
validators/               # Default commit validators (17 rules)
reminders/                # Default context-injection reminders (10 files)
agents/                   # Sub-agent definitions (validator agent)
src/
├── hooks/                # Hook handlers (session-start, pre-tool-use, user-prompt-submit, auto-continue)
├── 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 (.claude.hooks.json)
├── validator-loader.ts   # Multi-directory validator loader
└── index.ts              # Public API barrel exports
scripts/
├── session-start.ts      # SessionStart hook entry-point
├── pre-tool-use.ts       # PreToolUse hook entry-point
├── user-prompt-submit.ts # UserPromptSubmit hook entry-point
└── auto-continue.ts      # Stop hook entry-point

Dependencies

Package	Usage
gray-matter	YAML frontmatter parsing for validators and reminders
micromatch	Glob pattern matching for deny-lists

---

Development

Prerequisites

• Node.js 18+
• pnpm 10+

Setup

git clone https://github.com/BeOnAuto/claude-auto.git
cd claude-auto
pnpm install
pnpm build

Commands

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

---

License

MIT © 2025 BeOnAuto, Inc.

See LICENSE for details.