Agent hooks

Agent hooks.

The agent runs aislop on every file it edits. Findings come back as machine-readable feedback on the turn the code was written. No manual fix call, no reviewer chase, no drift.

New in 0.6.0

aislop hook install turns any supported agent into one that self-checks against the quality gate on every edit. When the agent writes a file, the hook fires, aislop scans the changed files, and the agent receives score, counts, findings, and next steps before the turn completes. The agent can fix what it just broke, in the same turn.

Three ways to integrate

aislop connects to coding agents three different ways. They stack.

Hook

Runtime

Automatic scan on every agent edit. Machine-readable feedback to the agent. What this page covers.

Skill

Knowledge

Teaches the agent when to run aislop and how to read findings. Works on agents without hook support. Skill docs.

Handoff

Manual

aislop fix --<agent> opens the agent with every remaining diagnostic as a prompt. Handoff docs.

Quick start

One command per agent. Installs to user-scope by default (global), or pass --project for this-repo-only.

# Claude Code PostToolUse

$ npx aislop hook install --agent claude

# Cursor afterFileEdit

$ npx aislop hook install --agent cursor

# Gemini CLI AfterTool

$ npx aislop hook install --agent gemini

# every supported agent at once

$ npx aislop hook install

Supported agents

Nine agents. Three have a native hook lifecycle; six don't, so aislop writes a rules file they read on every turn.

Runtime adapters (hook fires every edit)

claude

Claude Code

PostToolUse on Edit|Write|MultiEdit, writes to ~/.claude/settings.json and ~/.claude/AISLOP.md.

cursor

Cursor

afterFileEdit in ~/.cursor/hooks.json. Project scope adds .cursor/rules/aislop.mdc.

gemini

Gemini CLI

AfterTool matcher in ~/.gemini/settings.json, plus AISLOP.md referenced from GEMINI.md.

Rules-only installers (agent reads rules on every turn)

codex

OpenAI Codex CLI

Writes ~/.codex/AGENTS.md (global) or AGENTS.md (project).

windsurf

Windsurf

Writes .windsurfrules at the repo root.

cline

Cline + Roo

Writes .clinerules and .roo/rules/aislop.md.

kilocode

Kilo Code

Writes .kilocode/rules/aislop-rules.md.

antigravity

Antigravity

Writes .agents/rules/antigravity-aislop-rules.md.

copilot

GitHub Copilot

Writes .github/copilot-instructions.md.

The feedback the agent sees

Every hook fire emits a aislop.hook.v1 envelope. The agent reads it and can self-correct.

{
  "schemaVersion": "aislop.hook.v1",
  "cliVersion": "0.6.0",
  "score": 94,
  "label": "Healthy",
  "counts": { "errors": 0, "warnings": 3, "fixable": 1 },
  "findings": [
    {
      "filePath": "src/routes/auth.ts",
      "line": 42,
      "rule": "ai-slop/narrative-comment",
      "severity": "warning",
      "message": "Narrative comment block before declaration",
      "fixable": true
    }
    // …up to 20 findings
  ],
  "elided": 0,
  "nextSteps": [
    "Run aislop fix to auto-resolve 1 issue",
    "Address 3 warnings in files you just touched"
  ],
  "baseline": 95,
  "regressed": true
}

Top 20 findings cap: larger diff bursts are elided so the agent's context window isn't flooded. The agent can re-run a full scan if it needs more.

Quality-gate mode

Opt-in. Captures your current score as the baseline and blocks the Claude Stop hook if the project score drops below it.

# baseline captured at install time

$ npx aislop hook install --agent claude --quality-gate

# re-baseline after an intentional drop

$ npx aislop hook baseline

# inspect the captured score

$ cat .aislop/baseline.json

When it fires:

Claude finishes its turn and sends Stop.
aislop runs a full scan of the project.
If score < baseline, the hook returns {"decision":"block","reason":"..."}.
Claude sees the reason and can keep working to get the score back.

Non-Claude agents still receive the regressed flag in feedback; only the Claude Stop hook blocks.

Safety rails

Sentinel-guarded writes

Every install stamps a __aislop.hash field (SHA-256 of the canonical install payload) into the file it writes. Uninstall checks the hash before deleting. If you edited the hook by hand, aislop leaves your changes alone and flags a mismatch in aislop hook status.

Atomic writes

JSON is written to a temp file and renamed into place. Markdown is wrapped in  /  so we never overwrite your hand-written prose.

Recursion guard

.aislop/hook.lock with a 30-second stale window. If aislop's own scan touches a file and re-triggers the hook, the second call short-circuits.

git diff fallback

If the hook payload doesn't carry a file path (some agents omit it on certain tool calls), aislop reads git diff --name-only HEAD instead of scanning the whole repo. Keeps the scan scoped to what the agent just touched.

Manage your installs

# which agents are wired up and where

$ npx aislop hook status

# preview the exact diff without writing

$ npx aislop hook install --dry-run --agent claude

# remove just one agent

$ npx aislop hook uninstall --agent cursor

# remove every aislop entry across all agents

$ npx aislop hook uninstall

Uninstall only removes entries with a matching sentinel hash. Any edits you made by hand are preserved; aislop's managed block is the only thing that disappears.

Scopes

Runtime adapters (Claude, Cursor, Gemini) default to user-scope (~/.claude, ~/.cursor, ~/.gemini) so one install covers every repo you work on. Pass --project to scope to this repo only (writes to .claude/, .cursor/, etc.).

Rules-only installers (Codex, Windsurf, Cline, Kilo Code, Antigravity, Copilot) are project-scope by default because that's where those agents read rules from. Codex and a few others support -g / --global too.