The Atheist Hook

Fighting the proliferation of God Files.

A Claude Code hook that automatically warns when any file grows beyond a configurable line-count threshold. Fires after every Write or Edit tool call, injecting a context warning that nudges the AI toward decomposition before the file becomes unmaintainable.

The Problem

AI coding assistants love to dump everything into one file. A 200-line module becomes 400, then 800, then 1,500 -- and suddenly you have a God File that nobody wants to refactor. The Atheist Hook catches this at the source.

How It Works

You (or Claude) edits a file
       |
  PostToolUse fires
       |
  atheist_hook.py counts lines
       |
  <= 400 lines?  --> silence (carry on)
  401-500 lines?  --> soft warning injected into context
  > 500 lines?    --> hard warning: "GOD FILE DETECTED"

The warning is injected directly into Claude's context window via the hook protocol, so Claude sees it and can act on it immediately.

Install

Quick Install

git clone https://github.com/jmm2020/atheist-hook.git
cd atheist-hook
chmod +x install.sh
./install.sh

Manual Install

1. Copy atheist_hook.py somewhere permanent:

mkdir -p ~/.claude/hooks
cp atheist_hook.py ~/.claude/hooks/

2. Add to your .claude/settings.local.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/atheist_hook.py",
            "timeout": 5,
            "statusMessage": "God file check..."
          }
        ]
      }
    ]
  }
}

3. Restart Claude Code.

Configuration

All thresholds are configurable via environment variables:

Variable	Default	Description
ATHEIST_WARN_LINES	400	Soft warning threshold
ATHEIST_HARD_LINES	500	Hard "GOD FILE" warning threshold
ATHEIST_SKIP_DIRS	node_modules:.next:vendor:__pycache__:.git:dist:build	Colon-separated directories to ignore
ATHEIST_SKIP_EXTS	.json:.lock:.svg:.xml:.csv:.jsonl:.log:.html:.css:.md:.txt:.yaml:.yml:.toml	Colon-separated extensions to ignore

Set them in your shell profile or .env:

export ATHEIST_WARN_LINES=300
export ATHEIST_HARD_LINES=400

What You'll See

Soft warning (401-500 lines):

NOTE God file warning: `src/services/api.py` is 432 lines (soft limit: 400).
  Consider extracting before it grows further. Prevention > refactoring.

Hard warning (500+ lines):

WARNING GOD FILE DETECTED: `src/services/api.py` is 623 lines (limit: 500).
  This file MUST be decomposed. Extract cohesive blocks into separate modules.
  Rule of thumb: each module should have ONE clear responsibility under 500 lines.

Requirements

• Python 3.8+
• Claude Code CLI (the hook protocol is Claude Code specific)
• No external dependencies (stdlib only)

Why "Atheist"?

Because we don't believe in God Objects, God Files, or God Classes. Every module should have one clear responsibility, and no file should try to be Trumpnicient.

License

MIT