What are test hooks in AI-native development?

AI coding agents write code at a pace where stopping to manually run tests breaks your flow. The obvious fix is to ask the agent to run them. But that’s inconsistent. You can put the instruction in CLAUDE.md or your system prompt, and it works most of the time. But in long sessions, after context compaction, or during complex multi-file changes, “most of the time” stops being good enough.

What you need is a deterministic way to run lightweight tests as you iterate, before pushing code to CI for more comprehensive validation. That’s what test hooks provide. Test hooks wire your existing test and lint commands into the agent’s lifecycle so those commands fire every time, regardless of the prompt, session length, or agent’s preferences. Without them, CI becomes the first place failures surface. By then you’ve moved on to other work, and now you’re context-switching back to debug a problem the agent could have caught before committing.

This post covers how test hooks work, why and how to add them to your workflow, and how CircleCI’s Chunk CLI can simplify the whole process.

How test hooks work

A test hook is built on three core components:

1. The event: A specific, deterministic point in the agent’s lifecycle. For example, Claude Code exposes events like PreToolUse (before the agent takes an action), PostToolUse (after), and Stop (when it finishes). Cursor has a similar set of lifecycle events. These are deterministic firing points, not LLM-mediated decisions. When the event occurs, the hook runs.

2. The command: Whatever standard CLI tool you want the agent to execute. This could be your test runner, your linter, or a code review script. The hook doesn’t generate new tests or create new checks. It takes what you have and makes sure it runs.

3. The blocking behavior: This is what turns a hook into an enforcement mechanism. If the command exits with a nonzero code, the agent’s action is blocked. The agent sees the failure, reads the error output, and is forced to fix the code before proceeding.

Here’s what this looks like in practice using Claude Code’s .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --no-warn-ignored \"$CLAUDE_TOOL_INPUT_FILE_PATH\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "npm test"
          }
        ]
      }
    ]
  }
}

These two hooks serve two distinct purposes across the agent’s lifecycle. The first runs ESLint after every file edit, catching style and syntax issues while the agent is still working on that file. The second runs the test suite when the agent finishes its work, blocking it from completing if tests fail.

The lifecycle events where hooks matter most for testing break down roughly like this:

• After a file edit. Run lint immediately. The agent just wrote or modified a file, and catching issues now means the agent fixes them in context rather than later, after it’s moved on to something else.

• Before or at the point of completion. Run your test suite, or the affected subset. If tests fail, the agent sees the output and iterates. This is the critical enforcement point. Code that passes this gate is validated code.

• At session end. Run broader checks. This is where an AI code review step can add value: a subagent that reviews the session’s diff against your team’s standards and flags issues before the developer closes the session.

The key detail is that these hooks don’t depend on the agent’s context window, its instructions, or its judgment. They’re external to the model. A PostToolUse hook on file writes runs every time a file is written, the same way a git pre-commit hook runs every time you commit. The agent can’t skip it, forget it, or decide it isn’t needed.

For Claude Code’s full hook event reference, see the hooks guide and hooks reference. Cursor has its own hooks system with a similar lifecycle model; the GitButler deep dive is a solid practitioner-level writeup of how those work in practice.

Why this matters now

Developers have been running tests before committing for decades. The difference now is that the entity writing the code can also run the tests and iterate on failures, automatically, in a tight loop. Two things changed that make test hooks worth implementing today:

1. AI coding agents now have lifecycle events. Claude Code shipped its hooks system with support for events across the full agent lifecycle. Cursor followed with its own hooks implementation. Both are production infrastructure that gives developers programmatic control over agent behavior at specific, well-defined points. The plumbing for test hook enforcement didn’t exist two years ago. It does now.

2. The volume and pace of code generation is different. An experienced developer writing code manually might touch a handful of files in a focused session. An AI agent can generate or modify dozens of files in minutes. The surface area for regressions scales with the volume of changes, and the speed means problems pile up faster when they go unchecked. Manual review can’t keep up at this velocity. Deterministic enforcement can.

Test hooks turn the AI coding agent from something that generates code into something that generates validated code. That distinction matters more as agents take on more of the authoring workload.

How to set up test hooks effectively

Not all hook configurations improve quality. A poorly designed setup slows the agent down without catching meaningful problems. Here’s what separates useful test hook setups from counterproductive ones.

Match the check to the moment

The examples in the previous section show lint running on every file edit and the test suite running at session end. That layering is deliberate. You should always aim to run the lightest relevant check as early as possible and save heavier checks for later.

The reason is context. When a linting error surfaces immediately after the agent writes a file, the agent has full context on what it just did. It can fix the issue in one step. If the same error surfaces twenty file edits later in a session-end check, the agent has to reconstruct context, and the fix is more expensive in tokens and time.

The same logic applies to test speed. If your test suite takes ten minutes, using it as a blocking hook on every file edit will bottleneck the agent. Instead, scope your hooks. Use file extension filtering to skip checks when the change doesn’t touch relevant code, run affected tests at the commit point rather than the full suite, and save comprehensive runs for session end or CI.

Cap retries to prevent infinite loops

If a test keeps failing and the agent keeps retrying the same fix, you have a loop. A good hook setup includes a cap on consecutive blocks. After N retries without progress, let the code through and flag it for human review. The alternative is the agent burning tokens and time on a problem it can’t solve autonomously.

Add a review layer at session end

An AI code review step at session end, using your team’s specific patterns and conventions, catches things tests don’t: naming conventions, architectural decisions, patterns your senior engineers care about. A review informed by your team’s real PR review history, run by a subagent that checks the session’s changes against those patterns, adds a layer of quality enforcement that pure test coverage misses.

What about CI?

Test hooks and continuous integration (CI) serve different purposes. Hooks handle fast, local validation. CI handles the broader, more expensive checks that require shared infrastructure. When the two work together, hooks reduce the number of broken commits that reach CI in the first place.

When the agent pushes code that’s already passed local tests, lint, and review, CI can focus on the work that only CI can do: integration tests across services, e2e tests against staging, security scans, compliance gates. These are the checks that catch problems local validation can’t reach. Without hooks enforcing the inner loop, CI ends up re-running the same unit tests and lint checks the agent should have caught locally, wasting pipeline time and delaying the deeper validation that actually needs CI to run.

The inner loop and the outer loop have different testing responsibilities. Test hooks are what makes the inner loop actually enforce its share. For the full framework and how CLI and MCP tools map to each loop, see MCP vs. CLI for AI-native development.

CircleCI’s approach

Everything described above–wiring commands into lifecycles, scoping file types, and managing AI reviews–requires configuring multiple JSON/YAML files. Multiply that across a team, and the setup cost gets heavy.

That’s exactly why we built the open-source Chunk CLI. It handles the scaffolding for you.

Run chunk hook repo init in your project root and the Chunk CLI generates the config files, wires hooks into your agent’s lifecycle, and gives you a single place to define your test and lint commands:

execs:
  tests:
    command: "go test ./..."
    fileExt: ".go"
  lint:
    command: "golangci-lint run"
    timeout: 60

The fileExt field scopes the hook to only fire when the agent changes a matching file, keeping the feedback loop fast. Chunk manages state across hook events so your test, lint, and review checks run in the right order without racing each other.

Where the Chunk CLI adds value beyond scaffolding is the AI code review layer. Its build-prompt command mines PR review comments from your GitHub org and generates a context prompt tuned to your team’s actual review standards. That prompt powers a review subagent at session end that checks the session’s changes against patterns derived from your team’s real review history. The result is a review layer that reflects how your senior engineers actually review code, running automatically as part of the hook lifecycle.

The Chunk CLI also bridges local development to CircleCI’s Chunk CI/CD agent, which handles heavier work in the cloud. When a hook catches a problem that needs deeper attention, like a flaky test that keeps blocking the agent, you can kick off a Chunk task with chunk task run and hand it off. The Chunk agent runs autonomously on CircleCI’s cloud infrastructure and opens a PR in your repo when it’s done. Local hooks handle the fast, iterative validation. The Chunk agent handles the work that benefits from running in the background on dedicated compute.

Get started with test hooks

AI coding agents generate code faster than developers can manually validate it, and prompt-based instructions to “run the tests” aren’t reliable enough to close the gap. Test hooks give you a deterministic enforcement layer that runs your existing test and lint commands at the right points in the agent’s workflow, catching failures locally before they reach CI.

The Chunk CLI is open source and scaffolds the full setup. Sign up for a free CircleCI account to access the Chunk agent for heavier work in the cloud.

FAQ

What is a test hook in AI-native development? A test hook is a command registered against a lifecycle event in an AI coding agent like Claude Code or Cursor. When that event fires (for example, after a file edit or before the agent completes), the command executes automatically. If the command fails, the agent’s action is blocked. Hooks enforce local testing, linting, and code review without relying on the agent to remember or the developer to ask.

How are test hooks different from git hooks? Git hooks run at specific points in the git workflow (pre-commit, pre-push). Test hooks in AI-native development run at points in the agent’s workflow: after the agent edits a file, before the agent commits, or when the agent finishes a session. The scope is different. An agent might edit dozens of files before making a commit. Test hooks let you enforce checks at each edit, not just at the commit boundary. They also feed failure output back to the agent, which can fix the code and retry, something git hooks can’t do.

Do test hooks replace CI/CD testing? No. Test hooks handle inner-loop validation: fast, local checks that catch regressions before code is pushed. CI handles outer-loop testing: integration tests, e2e tests, security scans, and compliance checks that require shared infrastructure. Test hooks reduce the number of broken commits reaching CI, which means less wasted pipeline time and fewer context switches back to already-shipped code.

Which AI coding agents support test hooks? Claude Code has the most mature hooks system, with lifecycle events covering file edits, command execution, agent completion, session start, and more. Cursor shipped hooks in version 1.7 with a similar lifecycle model. Both support blocking behavior and structured output. The specific event names and configuration formats differ, but the concept is the same.