Configuration Reference

Complete reference for all Claude Auto configuration options, files, and environment variables.

Configuration Files Overview

Claude Auto uses a layered configuration system with multiple files:

File	Purpose	Committed?	Auto-Created?
`.claude-auto/.claude.hooks.json`	Primary runtime hook state	No	Yes
`.claude/settings.json`	Merged hook configuration	No	Yes
`.claude/settings.project.json`	Project-level overrides	Yes	No
`.claude/settings.local.json`	Local/personal overrides	No	No
`.claude/settings.lock.json`	Merge cache	No	Yes
`.claude/deny-list.project.txt`	Project file protection	Yes	No
`.claude/deny-list.local.txt`	Local file protection	No	No
`.claude/state.json`	Project state for conditionals	No	No
`.claude-autorc.json` (or variants)	Cosmiconfig options	Yes	No
`.claude-auto/scripts/*.js`	Hook scripts	No	Yes (copied)
`.claude-auto/reminders/*.md`	Context injection reminders	Yes/No	Yes (copied)
`.claude-auto/validators/*.md`	Commit validation rules	Yes/No	Yes (copied)

Hook State (`.claude-auto/.claude.hooks.json`)

The primary runtime configuration file. Controls auto-continue, commit validation, and other behaviors.

Location: .claude-auto/.claude.hooks.json (inside the claude-auto directory)

Full Schema

json

{
  "autoContinue": {
    "mode": "smart",
    "maxIterations": 0,
    "iteration": 0,
    "skipModes": ["plan"]
  },
  "validateCommit": {
    "mode": "strict"
  },
  "denyList": {
    "enabled": true,
    "extraPatterns": []
  },
  "promptReminder": {
    "enabled": true,
    "customReminder": ""
  },
  "subagentHooks": {
    "validateCommitOnExplore": false,
    "validateCommitOnWork": true,
    "validateCommitOnUnknown": true
  },
  "updatedAt": "2026-01-21T00:00:00.000Z",
  "updatedBy": "init"
}

`autoContinue`

Controls automatic continuation after Claude stops.

Field	Type	Default	Description
`mode`	`'smart' \| 'non-stop' \| 'off'`	`'smart'`	Continuation strategy
`maxIterations`	`number`	`0`	Max iterations (0 = unlimited)
`iteration`	`number`	`0`	Current iteration count
`skipModes`	`string[]`	`['plan']`	Modes that skip auto-continue

Mode behaviors:

Mode	Behavior
`smart`	Analyzes transcript for continuation signals before deciding
`non-stop`	Always continues until `maxIterations` reached
`off`	Never auto-continues

`validateCommit`

Controls commit validation against project rules.

Field	Type	Default	Description
`mode`	`'strict' \| 'warn' \| 'off'`	`'strict'`	Validation strictness

Mode behaviors:

Mode	Behavior
`strict`	Blocks commits that violate rules (NACK)
`warn`	Warns but allows commits
`off`	No commit validation

`denyList`

Controls file protection.

Field	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable deny-list
`extraPatterns`	`string[]`	`[]`	Additional patterns beyond files

`promptReminder`

Controls prompt injection.

Field	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable reminders
`customReminder`	`string`	`''`	Custom text to inject

`subagentHooks`

Controls which subagent types trigger validation hooks.

Field	Type	Default	Description
`validateCommitOnExplore`	`boolean`	`false`	Validate explore agents
`validateCommitOnWork`	`boolean`	`true`	Validate work agents
`validateCommitOnUnknown`	`boolean`	`true`	Validate unknown agents

Settings Layering

Claude Auto merges settings from three sources in priority order:

Package defaults (node_modules/claude-auto/templates/settings.json)
Project overrides (.claude/settings.project.json)
Local overrides (.claude/settings.local.json)

The merged result is written to .claude/settings.json.

See Architecture Guide for detailed merge implementation.

Override Syntax

Disable specific hooks

json

{
  "hooks": {
    "PreToolUse": {
      "_disabled": ["node .claude-auto/scripts/pre-tool-use.js"]
    }
  }
}

Replace entire hook array

json

{
  "hooks": {
    "SessionStart": {
      "_mode": "replace",
      "_value": []
    }
  }
}

Add new hooks

New hooks are merged with existing ones (duplicates removed by command):

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "my-custom-validator" }
        ]
      }
    ]
  }
}

Default Hook Configuration

The package provides these default hooks:

json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "node .claude-auto/scripts/session-start.js" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit|Bash",
        "hooks": [
          { "type": "command", "command": "node .claude-auto/scripts/pre-tool-use.js" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "node .claude-auto/scripts/user-prompt-submit.js" }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "node .claude-auto/scripts/auto-continue.js" }
        ]
      }
    ]
  }
}

Deny-List Files

Protect files from AI modification using glob patterns.

See the Hooks Guide for detailed deny-list setup and pattern syntax.

Quick Reference

.claude/deny-list.project.txt - Project-wide patterns (committed to repo)
.claude/deny-list.local.txt - Personal patterns (gitignored)

Patterns use micromatch glob syntax.

Cosmiconfig Support

For advanced configuration, Claude Auto supports cosmiconfig.

Supported Files

.claude-autorc.json
.claude-autorc.yaml / .claude-autorc.yml
.claude-autorc.js
claude-auto.config.js
claude-auto key in package.json

Configuration Schema

typescript

interface AutoConfig {
  /** Directory for claude-auto data (reminders, validators). Default: '.claude-auto' */
  autoDir?: string;

  /** Validator configuration */
  validators?: {
    dirs?: string[];       // Additional validator directories
    enabled?: boolean;     // Enable/disable validators globally
    mode?: 'strict' | 'warn' | 'off';  // Validation strictness
  };

  /** Reminder configuration */
  reminders?: {
    dirs?: string[];       // Additional reminder directories
    enabled?: boolean;     // Enable/disable reminders globally
  };

  /** Hook configuration overrides */
  hooks?: {
    skipInstall?: boolean; // Skip postinstall setup
    logLevel?: 'debug' | 'info' | 'warn' | 'error';
  };
}

Example `.claude-autorc.json`

json

{
  "autoDir": ".claude-auto",
  "validators": {
    "dirs": ["./custom-validators", "./team-validators"],
    "mode": "strict"
  },
  "reminders": {
    "dirs": ["./project-reminders"],
    "enabled": true
  },
  "hooks": {
    "logLevel": "info"
  }
}

Example in `package.json`

json

{
  "name": "my-project",
  "claude-auto": {
    "validators": {
      "enabled": true,
      "mode": "warn"
    },
    "reminders": {
      "dirs": ["./docs/reminders"]
    }
  }
}

Example `.claude-autorc.js`

javascript

module.exports = {
  autoDir: process.env.CI ? '.claude-auto-ci' : '.claude-auto',
  validators: {
    enabled: process.env.NODE_ENV !== 'development',
    mode: process.env.STRICT_MODE ? 'strict' : 'warn'
  },
  reminders: {
    dirs: [
      './reminders',
      process.env.TEAM_REMINDERS_PATH
    ].filter(Boolean)
  }
};

Load Priority

Cosmiconfig searches for configuration in this order:

claude-auto property in package.json
.claude-autorc.json
.claude-autorc.yaml / .claude-autorc.yml
.claude-autorc.js
claude-auto.config.js

The first configuration found is used (no merging between different config files).

Environment Variables

Variable	Purpose	Default
`AUTO_ROOT`	Force project root path	Auto-detected
`INIT_CWD`	Starting directory for root search	`process.cwd()`
`DEBUG`	Enable debug logging	-
`AUTO_LOG`	Filter activity logging	Log everything
`AUTO_SKIP_POSTINSTALL`	Skip postinstall in CI	`false`
`CI`	Detect CI environment	-
`NODE_ENV`	Node environment	`development`
`AUTO_VALIDATOR_MODE`	Override validator mode	From config
`AUTO_AUTO_CONTINUE`	Override auto-continue mode	From config

`AUTO_ROOT`

Override automatic project root detection:

bash

AUTO_ROOT=/path/to/project claude

`DEBUG`

Enable debug logging:

bash

DEBUG=claude-auto* claude

Logs written to .claude-auto/logs/debug.log.

`AUTO_LOG`

Filter activity logging by hook name or pattern:

bash

# Only log session-start hook
AUTO_LOG="session-start" claude

# Log everything except 'allowed' messages
AUTO_LOG="*,-allowed" claude

# Log multiple specific patterns
AUTO_LOG="session-start,block" claude

Activity logs written to .claude-auto/logs/activity.log.

`AUTO_SKIP_POSTINSTALL`

Skip postinstall script (useful for CI):

bash

AUTO_SKIP_POSTINSTALL=true npm install

`AUTO_VALIDATOR_MODE`

Override the commit validation mode at runtime:

bash

# Temporarily disable validation
AUTO_VALIDATOR_MODE=off claude

# Force strict validation
AUTO_VALIDATOR_MODE=strict claude

# Use warning mode
AUTO_VALIDATOR_MODE=warn claude

Overrides the validateCommit.mode setting in .claude-auto/.claude.hooks.json.

`AUTO_AUTO_CONTINUE`

Override the auto-continue mode at runtime:

bash

# Enable non-stop mode
AUTO_AUTO_CONTINUE=non-stop claude

# Use smart mode
AUTO_AUTO_CONTINUE=smart claude

# Disable auto-continue
AUTO_AUTO_CONTINUE=off claude

Overrides the autoContinue.mode setting in .claude-auto/.claude.hooks.json.

State File (`.claude/state.json`)

Optional file for conditional skill/reminder loading.

Example

json

{
  "projectType": "typescript",
  "framework": "express",
  "testFramework": "vitest"
}

Usage in Reminders

Reminders can conditionally load based on state:

yaml

---
when:
  hook: SessionStart
  projectType: typescript
  framework: express
priority: 50
---

# Express TypeScript Guidelines

...

All conditions must match (AND logic).

Reminder Frontmatter

Reminders are Markdown files with YAML frontmatter that inject context into Claude sessions.

Location

Default reminders: .claude-auto/reminders/ (copied from package during install)
Custom reminders: .claude-auto/reminders/ (add your own .md files)

Frontmatter Schema

yaml

---
when:
  hook: SessionStart        # Which hook triggers this
  mode: plan               # Optional: 'plan' or 'code'
priority: 100              # Optional: Order (higher = earlier)
---

Field	Type	Default	Description
`when.hook`	`string`	Required	`SessionStart` or `UserPromptSubmit`
`when.mode`	`string`	-	Filter by mode: `plan` or `code`
`priority`	`number`	`0`	Execution order (higher first)

Validator Frontmatter

Validators are Markdown files with YAML frontmatter.

Location

Default validators: .claude-auto/validators/ (copied from package during install)
Custom validators: .claude-auto/validators/ (add your own .md files)

Frontmatter Schema

yaml

---
name: my-validator          # Unique identifier
description: What it validates
enabled: true              # Set to false to disable
---

Project Root Detection

Claude Auto finds the project root in this order:

AUTO_ROOT environment variable (if set and path exists)
Walk up from INIT_CWD or process.cwd() to find package.json
Walk up to find .git directory
Fall back to process.cwd()

Logging Configuration

Debug Logs

Location: .claude-auto/logs/debug.log

Enable: DEBUG=claude-auto*

Format: Timestamp, hook name, debug message

Activity Logs

Location: .claude-auto/logs/activity.log

Filter: AUTO_LOG environment variable

Format: MM-DD HH:MM:SS [session-id] hook-name: message

Levels: ACK, NACK, ERROR, WARN, SKIP, INFO, DENIED, CONTINUE

Quick Reference

Disable all hooks locally

json

// .claude/settings.local.json
{
  "hooks": {
    "SessionStart": { "_mode": "replace", "_value": [] },
    "PreToolUse": { "_mode": "replace", "_value": [] },
    "UserPromptSubmit": { "_mode": "replace", "_value": [] },
    "Stop": { "_mode": "replace", "_value": [] }
  }
}

Script Location

Hook scripts are located at .claude-auto/scripts/, not .claude/scripts/. The settings.json commands reference .claude-auto/scripts/*.js.

Enable non-stop mode

json

// .claude-auto/.claude.hooks.json
{
  "autoContinue": {
    "mode": "non-stop",
    "maxIterations": 50
  }
}

Disable commit validation

json

// .claude-auto/.claude.hooks.json
{
  "validateCommit": {
    "mode": "off"
  }
}

Add custom file protection

json

// .claude-auto/.claude.hooks.json
{
  "denyList": {
    "enabled": true,
    "extraPatterns": ["*.generated.ts", "migrations/**"]
  }
}

Skip validation for explore agents

json

// .claude-auto/.claude.hooks.json
{
  "subagentHooks": {
    "validateCommitOnExplore": false,
    "validateCommitOnWork": true,
    "validateCommitOnUnknown": true
  }
}

Configuration Reference ​

Configuration Files Overview ​

Hook State (.claude-auto/.claude.hooks.json) ​

Full Schema ​

autoContinue ​

validateCommit ​

denyList ​

promptReminder ​

subagentHooks ​

Settings Layering ​

Override Syntax ​

Disable specific hooks ​

Replace entire hook array ​

Add new hooks ​

Default Hook Configuration ​

Deny-List Files ​

Quick Reference ​

Cosmiconfig Support ​

Supported Files ​

Configuration Schema ​

Example .claude-autorc.json ​

Example in package.json ​

Example .claude-autorc.js ​

Load Priority ​

Environment Variables ​

AUTO_ROOT ​

DEBUG ​

AUTO_LOG ​

AUTO_SKIP_POSTINSTALL ​

AUTO_VALIDATOR_MODE ​

AUTO_AUTO_CONTINUE ​

State File (.claude/state.json) ​

Example ​

Usage in Reminders ​

Reminder Frontmatter ​

Location ​

Frontmatter Schema ​

Validator Frontmatter ​

Location ​

Frontmatter Schema ​

Project Root Detection ​

Logging Configuration ​

Debug Logs ​

Activity Logs ​

Quick Reference ​

Disable all hooks locally ​

Enable non-stop mode ​

Disable commit validation ​

Add custom file protection ​

Skip validation for explore agents ​

Configuration Reference

Configuration Files Overview

Hook State (`.claude-auto/.claude.hooks.json`)

Full Schema

`autoContinue`

`validateCommit`

`denyList`

`promptReminder`

`subagentHooks`

Settings Layering

Override Syntax

Disable specific hooks

Replace entire hook array

Add new hooks

Default Hook Configuration

Deny-List Files

Quick Reference

Cosmiconfig Support

Supported Files

Configuration Schema

Example `.claude-autorc.json`

Example in `package.json`

Example `.claude-autorc.js`

Load Priority

Environment Variables

`AUTO_ROOT`

`DEBUG`

`AUTO_LOG`

`AUTO_SKIP_POSTINSTALL`

`AUTO_VALIDATOR_MODE`

`AUTO_AUTO_CONTINUE`

State File (`.claude/state.json`)

Example

Usage in Reminders

Reminder Frontmatter

Location

Frontmatter Schema

Validator Frontmatter

Location

Frontmatter Schema

Project Root Detection

Logging Configuration

Debug Logs

Activity Logs

Quick Reference

Disable all hooks locally

Enable non-stop mode

Disable commit validation

Add custom file protection

Skip validation for explore agents