Claude Code

Claude Code supports PostToolUse hooks that fire after every tool call. vibecop uses this to scan files after each Edit, Write, or MultiEdit operation.

Auto Setup

npx vibecop init

If a .claude/ directory is detected, vibecop init generates the settings file automatically.

Manual Setup

Create .claude/settings.json in your project root:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx vibecop scan --diff HEAD --format agent"
          }
        ]
      }
    ]
  }
}

How It Works

1. The agent calls Edit, Write, or MultiEdit to modify a file
2. The PostToolUse hook fires and runs npx vibecop scan --diff HEAD --format agent
3. vibecop scans only the changed files (via --diff HEAD)
4. If findings are detected, vibecop exits with code 1 and prints findings to stdout
5. Claude Code reads the findings and the agent auto-corrects the code
6. The hook runs again — if clean (exit 0), the agent continues

The matcher Field

The matcher uses a regex pattern to match tool names. Edit|Write|MultiEdit catches all file-editing tools. You can narrow this if needed:

• Edit — only on file edits
• Write — only on new file creation
• Edit|Write|MultiEdit — all file modifications (recommended)

The --format agent Flag

This produces token-efficient output (one finding per line, ~30 tokens each), minimizing context window usage:

src/api.ts:42:1 error unsafe-shell-exec: execSync() with template literal. Use execFile() with argument array instead.

The --diff HEAD Flag

This scans only files with uncommitted changes, making the hook fast even in large repositories. Without this flag, vibecop would scan the entire project on every edit.

Existing Settings

If .claude/settings.json already exists, vibecop init will skip it to avoid overwriting your configuration. In that case, add the PostToolUse hook manually by merging the JSON above into your existing settings.

Context Optimization (Beta)

Beta: This feature is under active testing. After upgrading vibecop or reinstalling node_modules, re-run vibecop init --context to refresh hook paths.

vibecop can intercept Read tool calls to reduce token consumption on re-reads. When Claude Code reads a file it has already seen in the current session, vibecop smart-limits the read to 30 lines and injects an AST skeleton (imports, function signatures, class outlines) via additionalContext.

Requires bun runtime for SQLite caching. Claude Code only.

Setup

npx vibecop init --context

This adds three hooks to .claude/settings.json:

• PreToolUse Read — checks if the file was read before, smart-limits re-reads
• PostToolUse Read — caches the AST skeleton after each read
• PostCompact — prunes old session data

Benchmark First

Before enabling, see projected savings for your project:

npx vibecop context benchmark

This scans your codebase and shows per-file skeleton compression ratios and projected token savings. No bun required for the benchmark.

View Stats

After working with context optimization enabled:

npx vibecop context stats

Shows total reads, cache hits, hit rate, and tokens saved across sessions.

How It Works

1. First read — full file passes through, skeleton is cached in .vibecop/.vibecop-context.db
2. Re-read (unchanged) — smart-limited to 30 lines + skeleton injected via additionalContext
3. Re-read (changed) — full file passes through with “file changed” note

Conflict Detection

vibecop init --context checks for existing PreToolUse Read hooks before adding its own. If another tool already uses updatedInput on Read, vibecop skips to avoid conflicts (only one hook can modify updatedInput per tool call).

Troubleshooting

vibecop not found

If npx vibecop fails, install it as a dev dependency:

npm install --save-dev vibecop

Or install globally:

npm install -g vibecop

Hook not firing

Verify the hook is configured correctly:

1. Check that .claude/settings.json exists in your project root
2. Confirm the hooks.PostToolUse array contains the vibecop entry
3. Test the command manually: npx vibecop scan --diff HEAD --format agent

Slow scans

If the hook takes too long, scope the scan to a specific directory:

npx vibecop scan --diff HEAD --format agent --path src/