Nudge is a Claude Code plugin for behavioral design and app psychology. It provides expert-level guidance for building, auditing, and optimizing digital products using research-backed behavioral science frameworks — the same knowledge employed by product psychologists at Meta, Google, Apple, TikTok, Duolingo, Netflix, and Spotify.
Elevator pitch: Build products people can't put down — using the same behavioral science that powers Meta, Spotify, and TikTok, but guided by principles instead of exploitation.
What it replaces: The $250–500/hr behavioral design consultant. Nudge democratizes access to behavioral design expertise through specialized AI agents that push back, ask smart questions, cite real research, and flag ethical concerns.
The plugin consists of three layers:
- Skill — Knowledge base with intelligent routing across three operational modes (Analyze, Design, Write)
- Agents — Nine specialized personas organized in three departments (Engagement + Color + Growth), each with distinct voices, expertise areas, and output formats
- MCP Server —
nudge-color-mcpprovides 7 color psychology tools backed by a 252-color database and a 31,891-color named library
nudge/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest (v0.2.0)
├── .mcp.json # MCP server configuration
├── agents/
│ ├── analyst.md # Evaluates existing apps/screens/metrics
│ ├── designer.md # Architects engagement systems
│ ├── writer.md # Generates psychologically-optimized copy
│ ├── color-psychologist.md # Defines psychological color constraints
│ ├── art-director.md # Curates exact palettes by vibe
│ ├── brand-identity-designer.md # Creates permanent brand color systems
│ ├── color-trend-forecaster.md # What's trending, dated, emerging
│ ├── lifecycle-strategist.md # Out-of-app retention — push, email, resurrection
│ └── monetization-architect.md # Pricing, paywalls, tiers, trials, LTV
├── hooks/
│ └── hooks.json # SessionStart hook for auto-installing deps
├── mcp-server/
│ ├── package.json # nudge-color-mcp package
│ ├── package-lock.json
│ ├── src/
│ │ └── index.js # 7 MCP tools — color psychology engine
│ └── data/
│ ├── colors-master.json # 252 psychology-backed colors
│ ├── colornames-31k.json # 31,891 named colors (meodai/color-name-list)
│ ├── colors-warm.json # Source: warm hue families
│ ├── colors-cool-blue.json # Source: cool blues
│ ├── colors-cool-green.json # Source: cool greens
│ ├── colors-neutral.json # Source: neutrals
│ ├── colors-gap-fill-1.json # Source: gap-fill batch 1
│ └── colors-gap-fill-2.json # Source: gap-fill batch 2
├── skills/
│ ├── analyzing-app-psychology/
│ │ ├── SKILL.md # Skill router — 3 modes, reference file dispatch
│ │ ├── analysis-reference.md # For Analyst (HEART + Octalysis)
│ │ ├── design-reference.md # For Designer (frameworks, onboarding, color)
│ │ ├── writing-reference.md # For Writer (microcopy, CTAs)
│ │ ├── lifecycle-reference.md # For Lifecycle Strategist (V3)
│ │ ├── monetization-reference.md # For Monetization Architect (V3)
│ │ ├── growth-reference.md # For Designer viral/referral loops (V3)
│ │ ├── academic-supplement.md # PhD-level foundations for all agents (V3)
│ │ ├── psychology-foundations.md # Shared deep reference
│ │ └── categories/
│ │ ├── journaling.md # Journaling, wellness, mood-tracking, habits
│ ├── fitness-health.md # Fitness, workout, health tracking
│ ├── education-learning.md # Language learning, courses, EdTech
│ ├── ecommerce.md # Stores, marketplaces, shopping
│ ├── social-community.md # Social networks, community, messaging
│ ├── fintech.md # Banking, investing, payments
│ ├── gaming.md # Mobile games, casual, competitive
│ ├── childrens-apps.md # Under-13, teen, family — COPPA/DSA compliance
│ ├── saas-productivity.md # B2B, productivity, collaboration
│ └── dating.md # Dating, matchmaking, relationships
│ └── nudge-360/
│ └── SKILL.md # Nudge 360 Boardroom — sequential agent orchestration
└── nudge-architecture.md # This document
Agents are organized into three departments — Engagement (the original behavioral design team), Color (a specialist color team), and Growth (lifecycle retention + monetization, added in V3). Within each department, agents are separated by the type of output they produce.
| Agent | Color | Output Type | Core Task |
|---|---|---|---|
| nudge-analyst | cyan | Evaluative reports (scores, diagnoses, comparisons) | Evaluates existing apps using HEART + Octalysis |
| nudge-designer | green | Prescriptive blueprints (plans, timelines, architectures) | Architects engagement systems (onboarding, retention, pricing, gamification). Does NOT pick colors — defines color intent and defers to the Color Department. |
| nudge-writer | magenta | Creative artifacts (copy variants with rationale) | Generates psychologically-optimized copy |
| Agent | Color | Output Type | Core Task |
|---|---|---|---|
| nudge-color-psychologist | yellow | Psychological color constraints | The WHY — defines what emotions and behaviors colors must evoke |
| nudge-art-director | red | Curated palettes by vibe | The WHICH — the taste-maker who picks exact colors |
| nudge-brand-identity | blue | Permanent brand color systems with usage rules | The FOREVER — creates enduring brand identity systems |
| nudge-color-trends | cyan | Trend reports (what's in, what's dated, what's emerging) | The WHEN — tracks color trends and forecasts shifts |
| Agent | Color | Output Type | Core Task |
|---|---|---|---|
| nudge-lifecycle-strategist | magenta | Lifecycle strategies (push, email, resurrection flows) | The RETENTION ENGINE — owns the out-of-app experience. Push notifications, email lifecycle, zombie user resurrection. Grounded in Spontaneous Recovery (Pavlov), COM-B Model (Michie). |
| nudge-monetization-architect | yellow | Revenue architectures (pricing, paywalls, tiers, trials) | The REVENUE ENGINE — owns pricing, paywall design, subscription tiers, trial optimization. Grounded in Van Westendorp PSM, Gabor-Granger, Ariely's decoy pricing. |
Each agent has a distinct voice to feel like hiring the real specialist:
| Agent | Voice | Personality |
|---|---|---|
| Analyst | Diagnostic, precise, brutally honest | Like a consultant delivering bad news with data. Pushes back when self-assessment doesn't match reality. |
| Designer | Strategic, opinionated, practical | Like a growth PM who's shipped 10 products. Makes specific decisions and explains why. Defers color choices to the Color Department. |
| Writer | Precise, playful, deeply intentional | Like a conversion copywriter with a psych degree. Strong opinions about every word. |
| Color Psychologist | Academic, precise, research-driven | Like a psychology professor who studies color perception. Cites studies, defines constraints, thinks in emotions. |
| Art Director | Opinionated, aesthetic, decisive | Like a creative director with impeccable taste. Picks the exact shade and tells you why the other one was wrong. |
| Brand Identity | Systematic, long-term, rules-oriented | Like a brand consultant building a 10-year identity system. Thinks in usage rules and consistency. |
| Color Trends | Current, data-informed, trend-aware | Like a trend forecaster who knows what's peaking and what's about to feel dated. |
| Lifecycle Strategist | Clinical, data-driven, strategically aggressive | Like a behavioral scientist who speaks in terms of Spontaneous Recovery and Extinction Prevention, not "send a push." |
| Monetization Architect | Revenue-focused, data-backed, unapologetically commercial | Like a pricing strategist who cites Van Westendorp and Ariely, not "try $9.99." |
All agents share these behaviors:
- Ask first — Clarifying questions before prescribing (Designer and Writer)
- Push back — Challenge assumptions and bad ideas
- Admit uncertainty — Rather than overstate confidence
- Cite evidence tiers — Distinguish peer-reviewed from industry data from blog claims
- Ethics always included — Not optional, not separate
The color MCP server provides computational color intelligence that agents cannot do through prompts alone — database lookups, color math, contrast calculations, and palette generation from a structured dataset.
- 252 psychology-backed colors (
colors-master.json) — Each color includes: hex, name, hue family, warmth, saturation, value, Wright tonal group, Kobayashi words, brand personality dimensions (Aaker), emotions, associations, mood, cultural meanings (5 regions), best-for app categories, avoid-for categories, and contrast pairings. - 31,891 named colors (
colornames-31k.json) — From the meodai/color-name-list open-source library. Beautifully named shades that map back to the 252 psychology profiles via nearest-color matching.
| Tool | What It Does |
|---|---|
nudge_color_psychology |
Full psychological profile for any color by name or hex. Returns emotions, associations, cultural meanings, brand personality, Wright group, best/avoid categories. |
nudge_color_by_emotion |
Find colors that evoke a specific emotion, mood, brand personality, or Wright tonal group. Multi-filter query across the 252-color database. |
nudge_palette_for_category |
Generate a psychologically-informed palette for an app category + target emotion. Returns primary, accent/CTA, background, semantic colors, dark mode variant, and WCAG contrast data. |
nudge_color_harmony |
Generate harmonious palettes from a starting color using color theory (complementary, analogous, triadic, split-complementary, tetradic, monochromatic, Wright group). |
nudge_contrast_check |
WCAG accessibility compliance check between two colors. Returns contrast ratio, AA/AAA pass status for normal text, large text, and UI components. |
nudge_palette_psychology |
Analyze an existing palette for psychological impact — Wright group harmony check, brand personality projection, cultural conflict detection, contrast matrix. |
nudge_find_named_color |
Search the 31,891-color named library by keyword, hex proximity, or psychology-color proximity. Returns beautiful color names with their nearest psychology profile. |
The hooks/hooks.json defines a SessionStart hook that auto-installs MCP server dependencies when the plugin loads. It compares package.json checksums and only runs npm install when dependencies have changed, keeping cold starts fast.
| Mode | Trigger | Agent | Reference File |
|---|---|---|---|
| ANALYZE | Evaluate existing app/screen/metrics/competitor | nudge-analyst | analysis-reference.md |
| DESIGN | Build new engagement system/onboarding/strategy | nudge-designer | design-reference.md |
| WRITE | Generate copy for specific UI element | nudge-writer | writing-reference.md |
Files are organized by task (what the agent needs to do), not by domain (what academic discipline the knowledge comes from):
| File | Lines | Purpose | Used By |
|---|---|---|---|
| analysis-reference.md | ~450 | Google HEART + Octalysis scoring, screenshot framework, dark patterns, ethics, benchmarks | Analyst |
| design-reference.md | ~508 | Frameworks, onboarding, retention timeline, color, pricing, gamification | Designer |
| writing-reference.md | ~274 | Microcopy, CTAs, notifications, errors, confirmshaming | Writer |
| psychology-foundations.md | ~289 | Case studies, academic canon, deep research | All (when needed) |
Context efficiency: Each agent loads only its task-specific file (~250-500 lines) instead of the old approach where every task loaded all 3 domain files (~1,345 lines). Worst case improved 37%, best case improved 69%.
This shared file is read only when needed — when the user's question requires specific research citations, case study references, or deeper framework explanation. It contains:
- UX Laws & Cognitive Biases (with full citations)
- Social Psychology in Apps
- Attention Engineering
- Neurodesign
- Company Case Studies (TikTok, Facebook, Duolingo, Netflix, Spotify, Amazon, Uber, LinkedIn)
- Academic Canon & Practitioner Curriculum (20+ textbooks, key papers, industry reports)
Category-specific knowledge lives in categories/[category].md files:
categories/
├── journaling.md # Journaling, wellness, mood-tracking, habits (Day One, Daylio)
├── fitness-health.md # Fitness, workout, health tracking (Strava, Peloton, Nike Run Club)
├── education-learning.md # Language learning, courses, EdTech (Duolingo, Khan Academy, Brilliant)
├── ecommerce.md # Stores, marketplaces, shopping (Amazon, Shein, Shopify)
├── social-community.md # Social networks, community, messaging (TikTok, Instagram, Snapchat, Discord)
├── fintech.md # Banking, investing, payments (Robinhood, Cash App, Revolut)
├── gaming.md # Mobile games, casual, competitive (Candy Crush, Fortnite, Genshin Impact)
├── childrens-apps.md # Under-13, teen, family — COPPA/DSA compliance
├── saas-productivity.md # B2B, productivity, collaboration (Slack, Notion, Figma)
└── dating.md # Dating, matchmaking, relationships (Tinder, Bumble, Hinge)
All 10 categories are built with ~300-340 lines each, covering case studies, recommendations, onboarding flows, retention timelines, and risk profiles.
The SKILL.md instructs: "If a category-specific file exists for the user's app type, read it as additional reference." Adding a new vertical = adding one file, not editing four.
These are enforced across all agents and modes:
- Name the psychology — Never "add a progress bar." Always "add a progress bar to leverage the Goal Gradient Effect (Hull, 1932; Kivetz, 2006) and Zeigarnik Effect..."
- Cite with evidence tiers — Peer-reviewed > industry A/B tests > industry reports > blog claims. Always state which tier.
- Be category-aware — Different app categories need different frameworks, benchmarks, and ethical considerations.
- Ethics first — Every recommendation passes the Alignment Test. Dark patterns flagged by Brignull classification. Enforcement precedents referenced ($520M Epic, $2.5B Amazon, $391.5M Google).
- Be specific and actionable — Not "improve onboarding" but "defer account creation until after first core action, then frame signup as saving progress (loss aversion)."
- Push back when appropriate — Challenge assumptions, flag bad ideas, admit uncertainty.
| Framework | Creator | Core Concept | Best For |
|---|---|---|---|
| Google HEART | Rodden, Hutchinson & Fu (Google, 2010) | Happiness, Engagement, Adoption, Retention, Task Success | UX metrics evaluation |
| AARRR | Dave McClure (500 Startups) | Acquisition, Activation, Retention, Revenue, Referral | Growth metrics and pirate funnel |
| Octalysis | Yu-kai Chou (2015) | 8 core drives, White Hat vs. Black Hat | Gamification design |
| B=MAP | BJ Fogg (Stanford, 1998) | Behavior = Motivation x Ability x Prompt | Reducing friction, habit design |
| Hook Model | Nir Eyal (2014) | Trigger, Action, Variable Reward, Investment | Habit-forming products |
| Cialdini's 7 | Robert Cialdini (1984/2016) | Reciprocity, Commitment, Social Proof, Authority, Liking, Scarcity, Unity | Persuasive design |
| SDT | Deci & Ryan (2000) | Autonomy, Competence, Relatedness | Intrinsic motivation |
| Prospect Theory | Kahneman & Tversky (1979) | Loss aversion, reference dependence | Pricing, retention |
All citations in reference files have been audited (March 2026). Standards:
- Peer-reviewed claims cite author, year, journal, and specific finding
- Industry data (RevenueCat, Adapty, Airship) cites report name and year, with caveat that numbers change annually
- Industry A/B tests (HubSpot, ContentVerve) are labeled as practitioner data, not peer-reviewed
- Compromised research (Wansink) includes misconduct caveat and cites independent replications
- Fabricated claims were removed and replaced with verified peer-reviewed alternatives
- Blog-level claims are labeled as such and not presented as research
| Audience | Pain Point | What They Want |
|---|---|---|
| Growth PMs at startups (primary) | "Engagement is stalling, we need to grow without burning money on acquisition" | Specific, testable recommendations they can ship this sprint |
| Indie devs / bootstrapped founders (secondary) | "I built a great product but nobody sticks around" | The shortcut — what actually works, not theory |
| UX/Product designers (tertiary) | "Stakeholders reject my designs because they don't understand the psychology" | Research backing for their design intuitions |
Nudge is to behavioral design what Figma is to visual design — the platform that makes expertise accessible and operationalized.
| Competitor Type | What They Do | How Nudge Wins |
|---|---|---|
| Behavioral design consultants ($250-500/hr) | Custom strategy for large companies | Democratizes access; instant availability |
| Product analytics (Amplitude, Mixpanel) | Tell you WHAT users do | Explains the WHY and tells you what to change |
| General AI (ChatGPT, Claude) | Generic advice without specialization | Specialized expertise + ethical guardrails |
| NNGroup / design system tools | General UX patterns | Behavioral psychology depth + scoring rubric |
- Plugin scaffold with manifest
- Skill with 3 operational modes (Analyze, Design, Write)
- 9 agents organized in three departments (Engagement + Color + Growth)
- 5 task-aligned reference files + category extension pattern
- Research audit — fabricated claims removed, evidence tiers established
- Replaced legacy scoring with industry-standard Google HEART + Octalysis
- Academic canon — 20+ textbooks, key papers, industry reports
- 10 category deep dives (~3,100 lines): journaling, fitness, education, e-commerce, social, fintech, gaming, children's, SaaS, dating
- Full app lifecycle review support (launched, WIP, pre-launch, post-launch)
- Bubamara marketplace listing
- PR review — tools scoped, roles accurate, ethics ungated
- MCP server: nudge-color-mcp with 7 tools
- 252 psychology-backed color database (Wright tonal groups, Kobayashi words, Aaker brand personality, 5-region cultural meanings)
- 31,891 named color library integration (meodai/color-name-list)
- SessionStart hook for automatic MCP dependency installation
- 4 Color Department agents: Color Psychologist, Art Director, Brand Identity, Color Trends
- Slash command:
/nudgefor explicit mode invocation - More company case studies with verified citations
- Community-contributed category files