What Is Claude Nudge? A Guide to the Automatic Rule Enforcement Tool for Claude Code

What Is Nudge — An "Instant Guardrail" OSS for Claude Code

Nudge is an open-source project published on GitHub by attunehq (Apache-2.0 license). In a nutshell, it is a guardrail system that intercepts Claude Code the moment it is about to write non-compliant code and guides it toward the correct approach.

Traditionally, coding conventions were communicated via CLAUDE.md or system prompts. But no matter how carefully you write them, their weight tends to diminish as the number of turns in a session increases. Nudge solves this problem not with prompts, but with a mechanism built around Hooks.

Supported tools are Claude Code and Codex CLI, and hook configuration for either is completed with a single nudge setup command.

Why Rules Stop Being Followed in Long Sessions

Even if you tell Claude Code to "place use statements at the top of the file" or "never omit type annotations," those instructions tend to take a back seat as complex refactoring progresses.

This is a phenomenon known as instruction compliance drift. The Attune blog post (Just-in-Time Guardrails for Agents) explains that within long contexts, the model's attention shifts away from style guides and toward "producing working code."

Writing rules in system prompts or CLAUDE.md is important, but there is a practical limit: even written rules get lost in long-running sessions. Nudge is designed as a layer that compensates for that limitation.

4 Operating Modes — Integration with the Hooks API

Nudge leverages Claude Code's Hooks API to evaluate rules immediately before and after tool calls. It operates in four modes.

Interrupt The PreToolUse hook stops a file write and returns feedback explaining the violation along with a prompt to fix it. The moment Claude Code tries to write code, it receives a message like "This approach violates the rules. Please use ○○ instead."

Substitute For deterministic operations like Bash commands, the command is automatically rewritten to an alternative. This preserves the developer's intended behavior while converting it into a convention-compliant form.

Continue (Inject) The UserPromptSubmit hook injects additional context at the time of prompt submission. It automatically appends a note like "This project uses the ○○ pattern" to every turn.

Passthrough Operations that match no rules are passed through unchanged. The design reacts only to defined patterns rather than blocking all operations.

Writing Rules — 3 Types of Matchers

Nudge rules are written in a configuration file. There are three types of matchers used to determine whether something is flagged.

1. Regex Matcher — Detects violations using text patterns. Well-suited for simple string-based rules.
2. Syntax Tree Query — Analyzes the code's AST (Abstract Syntax Tree) to detect structural violations. Ideal for context-dependent rules such as import placement or how type annotations are written.
3. External Command Validator — Calls a custom script as a validator. Can be combined with existing lint tools or custom checkers.

Rules can also target Markdown code blocks, so conventions can be applied even to sample code within documentation.

The configuration file can be generated by Claude Code itself. The GitHub repository describes a workflow where you pass your existing coding style document to Claude Code and have it generate the Nudge configuration file.

Practical Examples — Usage in a Rust Project

Looking at the concrete examples introduced in the Attune blog makes it easy to grasp the use cases.

Keeping imports at the top (Rust) In Rust, the convention is to place use statements at the top of the file. If Claude Code attempts to insert a use statement in the middle of a file, Nudge's syntax tree matcher detects this and pushes it back in Interrupt mode.

Enforcing consistent type annotations Conventions such as "always attach type annotations to variable declarations" or "use a specific type alias" can be defined with regex or syntax tree queries. When Claude Code starts omitting annotations during a long session, Nudge immediately flags it.

Unifying string creation methods Rules like standardizing on either String::from("...") or "...".to_string() can be handled with the regex matcher.

CI Integration — The nudge check Command

Beyond real-time Hooks integration, Nudge also provides a standalone nudge check command.

nudge check

By incorporating this command into pre-commit hooks or a CI pipeline, you can run a batch check of the entire codebase against your rules. Since it applies convention checks to hand-written code and code written by other developers — not just Claude Code output — it also functions as a code quality management tool for the entire team.

Difference from Nudge Security — Watch Out for a Similarly Named Service

When you search for "claude nudge," another service called Nudge Security also appears near the top. Nudge Security is an enterprise-grade security platform for centrally managing and governing Claude Managed Agents within an organization.

It handles discovery of deployed Claude Managed Agents, detection of hardcoded credentials, identification of unauthenticated connection risks, and management of approval workflows.

The attunehq Nudge (coding convention enforcement) and Nudge Security (organizational governance) merely share a similar name — their targets and functionality are entirely different. Be careful not to confuse them in search results.

Setup Instructions

Installation is available via package installers for macOS, Linux, and Windows. To build from source, use Rust's Cargo.

1. Install Nudge by following the README on GitHub
2. Run nudge claude setup in your project root
3. Write your rules in the generated configuration file
4. Launch Claude Code and Hooks will be enabled automatically

If using Codex CLI, replace step 2 with nudge codex setup.

Current Maturity and Caveats

The GitHub repository explicitly states it is "not yet production-grade software." As of June 2026, the project has 24 stars, indicating it is still in an early phase.

When introducing it to a production project, we recommend starting with a limited rule set and gradually expanding while verifying that Interrupt does not fire in unintended situations. Since Claude Code's Hooks API itself is an interface expected to evolve further, check the Nudge GitHub Releases page to confirm compatibility when major updates occur.

The problem of coding conventions being "written but not followed" is a common frustration for many teams. Nudge is lightweight, has a low barrier to entry, and is worth trying first on a small-scale project.