Nudge

Nudge is a collaborative memory layer for Claude Code and Codex CLI hooks. It remembers the coding conventions, workflow preferences, and repo-local debugging lessons that agents should use while they work.

Write the reminder once. Let Nudge deliver it at the moment an agent is about to write a file, run a command, fetch a URL, or start a turn.

Why Use It

Agents do better work when they can focus on the actual task instead of holding every project preference in working memory. Nudge moves those preferences into small, testable rules and learned notes:

• Rules catch deterministic conventions before an operation lands.
• Bash substitutions rewrite simple command mistakes automatically.
• Prompt reminders add project context when a user asks for something specific.
• Learned incident notes keep future agents from rediscovering old debugging fixes.
• nudge check brings the same file-rule enforcement to CI and scripts.

Nudge is direct by design. A good message says what is wrong, how to fix it, and that the agent should retry.

Quick Start

Install:

curl -sSfL https://raw.githubusercontent.com/attunehq/nudge/main/scripts/install.sh | bash

Release binaries support macOS, Linux, and Windows x64. BM25 learned-note search is always available. Local semantic embeddings are included on Apple Silicon macOS and x64 GNU Linux; Intel macOS, musl Linux, arm64 GNU Linux, and Windows GNU builds omit local semantic embeddings.

Windows PowerShell:

irm https://raw.githubusercontent.com/attunehq/nudge/main/scripts/install.ps1 | iex

Set up hooks in a project. Run the setup command for the agent you use, or both commands if you use both agents:

nudge claude setup
nudge codex setup
nudge grok setup
nudge cursor setup

Add a .nudge.yaml:

version: 1
rules:
  - name: no-unwrap
    message: 'Use `.expect("descriptive error message")` instead of `.unwrap()`, then retry.'
    on:
      - hook: PreToolUse
        tool: Write
        file: "**/*.rs"
        content:
          - kind: Regex
            pattern: "\\.unwrap\\(\\)"
      - hook: PreToolUse
        tool: Edit
        file: "**/*.rs"
        new_content:
          - kind: Regex
            pattern: "\\.unwrap\\(\\)"

Restart open agent sessions, then use Claude Code, Codex CLI, Grok Build, or Cursor normally. Run /hooks in the agent to verify setup. After a useful debugging session, ask the agent to use nudge-learnings to record durable repo-local learnings for future work; Claude setup also installs a nudge:learn slash command for this workflow.

Guides

• User Guide: install, setup, rule examples, learned notes, agent behavior, and troubleshooting.
• Developer Guide: architecture, local development, tests, dogfooding, live-agent testing, and PR expectations.
• CI and Programmatic Checks: using nudge check in CI, pre-commit hooks, and scripts.

The bundled nudge skill is the agent-facing rule reference. The bundled nudge-learnings skill is the proactive debugging-memory workflow for searching, applying, and recording repo-local learned incident notes.

Copyable starter rules live in examples/rules.

How It Works

Nudge watches supported hook surfaces:

• PreToolUse for file writes/edits, Bash, and WebFetch where the provider exposes them.
• UserPromptSubmit for prompt-time context.
• Codex apply_patch inputs, normalized into Write/Edit/Delete where possible.
• Grok Build tool aliases such as run_terminal_command, search_replace, write_file, and web_fetch.
• Cursor / cursor-agent tools such as Shell, Write, and Delete, plus beforeShellExecution and beforeSubmitPrompt.

When a rule or learned note matches, Nudge returns one of these outcomes:

Rules are loaded from user-level config, .nudge.yaml, .nudge.yml, and YAML files under .nudge/. Learned notes are plain Markdown files under .nudge/learned/.

Learned Notes

Rules are best for deterministic conventions. Learned notes are for incidents: what went wrong, how it was fixed, and how the fix was verified.

This is intentionally narrower than built-in agent memory. Built-in Claude or Codex memory can be useful for broad personal preferences, but it can also follow an agent across repos, branches, or worktrees before the checked-out code supports the remembered fact. nudge learn stores Markdown notes in Git, so each checkout only sees the learnings present with that code. A note added on an unmerged branch does not appear in another worktree.

The incident shape matters too. Notes are written as problem, fix, and verification instead of "anything about this project", which gives retrieval concrete symptoms and commands to match. That keeps learned context quieter and less likely to pollute unrelated tasks.

nudge learn add --title "Expo Metro resolver cache" --body "What went wrong: Expo could not resolve modules after a dependency update.

Fix: clear the Metro cache and restart the dev server.

Verification: expo start completed and the app loaded."

nudge learn search expo metro cannot resolve module
nudge learn list

BM25 search is always available. Projects can opt into local semantic retrieval:

nudge learn embeddings enable
nudge learn embeddings status

Setup installs the bundled nudge and nudge-learnings skills so agents know how to respond to hook messages, write or debug rules, wire CI checks, and search, apply, or record repo-local learnings. Setup does not edit project CLAUDE.md or AGENTS.md files.

Development

Build and test:

cargo build -p nudge
cargo test -p nudge
cargo clippy -p nudge --all-targets --all-features -- -D warnings

See the Developer Guide for the full development and live-agent dogfood workflow.