{"id":"66f934d8-24e8-48aa-a161-b6ef1694d3ec","slug":"nudge-claude-code-plugin","kind":"mcp","name":"Nudge-Claude-Code-Plugin","summary":"Behavioral design consultancy as a Claude Code plugin. 9 agents, 3 departments, 252-color psychology MCP, 31K color library, 10 verticals. Nudge 360 orchestrates all agents into one boardroom-ready st","owner":"mermaidsinhell-stack","repoUrl":"https://github.com/mermaidsinhell-stack/Nudge-Claude-Code-Plugin","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-03-21T16:22:07.000Z","addedAt":"2026-10-21T04:21:59.872Z","logoUrl":"https://avatars.githubusercontent.com/u/239520756?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","design-media","cloud-infra"],"tags":["behavioral-design","claude-code-plugin","color-psychology","dark-patterns","engagement","gamification","growth","monetization"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T02:15:11.873Z","sample":false,"url":"https://conduits.dev/tools/nudge-claude-code-plugin","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Nudge\n\n**Build products people can't put down**\n\nNudge is a Claude Code plugin that brings behavioral design and color psychology expertise to your workflow. It gives you the same psychological frameworks used by product teams at Meta, Google, Duolingo, Netflix, and Spotify — plus a research-grade color system — without the $250-500/hr consulting fee.\n\nWhether you're auditing an existing app for engagement patterns, designing onboarding from scratch, writing button copy that actually converts, or building a brand color system from the ground up — Nudge has a specialist agent for that.\n\n---\n\n## What You Get\n\n### 9 Specialized Agents — Three Departments\n\n**Engagement Department**\n\n| Agent | What It Does | Example |\n|-------|-------------|---------|\n| **Analyst** | Evaluates existing apps using Google HEART + Octalysis scoring, dark pattern detection, and category benchmarks | *\"Audit this screenshot for psychological patterns\"* |\n| **Designer** | Architects in-app engagement systems — onboarding flows, retention mechanics, reward systems, viral/referral loops | *\"I'm building a fitness app. How do I keep users past Day 7?\"* |\n| **Writer** | Generates psychologically-optimized microcopy with 3-5 variants per element, each citing the principle behind it | *\"Write empty state copy for my journaling app\"* |\n\n**Color Department**\n\n| Agent | What It Does | Example |\n|-------|-------------|---------|\n| **Color Psychologist** | Defines psychological color constraints — which hue families, saturation levels, Wright tonal group, and brand personality fit your product | *\"What colors should my meditation app use?\"* |\n| **Art Director** | The taste-maker — curates exact hex codes by vibe (editorial, gaming, luxury, brutalist) | *\"Build me a palette around this teal\"* |\n| **Brand Identity Designer** | Creates the permanent brand color system — the 5 colors + usage rules + brand bible | *\"I need my brand colors — the permanent system\"* |\n| **Color Trend Forecaster** | What's trending, what's dated, what's emerging — with receipts | *\"Does my app look dated? What should I move to?\"* |\n\n**Growth Department**\n\n| Agent | What It Does | Example |\n|-------|-------------|---------|\n| **Lifecycle Strategist** | The Retention Engine — owns push notifications, email lifecycle, resurrection flows for churned users, zombie user win-back | *\"Users stop opening my app after 2 weeks. How do I get them back?\"* |\n| **Monetization Architect** | The Revenue Engine — owns pricing, paywalls, subscription tiers, trial optimization, LTV maximization | *\"Should I use a hard paywall or freemium? What price maximizes LTV?\"* |\n\nEach agent has a distinct personality. They ask clarifying questions before answering. They push back on bad ideas. They cite real research and distinguish peer-reviewed studies from industry data.\n\n### Nudge 360 — The Boardroom\n\nInstead of asking one agent at a time, say **\"Nudge 360\"** and get a complete product strategy. All 9 agents run sequentially — each building on the previous — with a conflict resolution matrix that prevents contradictions:\n\n1. **Analyst** sets the truth (gaps, benchmarks)\n2. **Designer** draws the engagement map\n3. **Monetization Architect** marks the revenue points\n4. **Lifecycle Strategist** builds the retention safety net\n5. **Color team** paints the map to match the emotional goals\n6. **Writer** writes the signage for every touchpoint\n\n**When agents disagree, the matrix resolves it:**\n- Retention > Revenue — aha moment must happen before the paywall\n- Cognitive Load > Persuasion — clarity beats cleverness\n- Psychology > Aesthetics — emotional utility beats cool design\n\nOutput: one cohesive **Boardroom Report** with executive summary, consensus notes (where agents compromised), integrated blueprint, and implementation priority.\n\n> Instead of asking \"What color should my button be?\", say: **\"Nudge 360: Build me a strategy to reach 20% Day-30 retention and $1M ARR.\"**\n\n### 2 Auto-Activating Skills\n\nThe `analyzing-app-psychology` skill activates whenever you ask about engagement, retention, onboarding, color psychology, microcopy, dark patterns, pricing strategy, gamification, or behavioral design. It routes to the right mode automatically:\n\n- **Analyze** — evaluate something that exists\n- **Design** — create something new\n- **Write** — generate copy for a specific UI element\n\nThe `nudge-360-product-strategy` skill activates when you ask for a complete product strategy, full consulting engagement, or Nudge 360. It orchestrates all 9 agents sequentially.\n\nThe color agents handle all color-specific work — palette creation, brand systems, trend analysis, and psychological color selection — using the MCP server's tools and databases.\n\n### MCP Server — 7 Color Psychology Tools\n\nThe color department is backed by a local MCP server that gives agents real data instead of guesswork:\n\n| Tool | What It Does |\n|------|-------------|\n| `nudge_color_psychology` | Full psychological profile for any color — emotions, associations, cultural meanings, brand personality, Wright tonal group, best/avoid categories |\n| `nudge_color_by_emotion` | Find colors by emotion, mood, brand personality, warmth, saturation, hue family, or Wright group |\n| `nudge_palette_for_category` | Generate a psychologically-informed palette for a specific app category and target emotion |\n| `nudge_color_harmony` | Generate harmonious palettes using color theory (complementary, analogous, triadic, split-complementary, tetradic, monochromatic, Wright group) |\n| `nudge_contrast_check` | WCAG accessibility compliance between two colors — AA, AAA, normal text, large text, UI components |\n| `nudge_palette_psychology` | Analyze an existing palette for psychological impact, Wright group harmony, brand personality consistency, and cultural conflict detection |\n| `nudge_find_named_color` | Search the 31,891-color named library for beautifully named shades by keyword, hex proximity, or psychology color similarity |\n\n**What powers it:**\n- **252 psychology-backed colors** with 13+ attributes each (emotions, associations, cultural meanings, Wright tonal group, brand personality, best/avoid categories, contrast pairings, Kobayashi descriptors)\n- **31,891 named color library** for artsy shade selection — every color mapped to its nearest psychology profile\n- **Auto-installs dependencies** on first session via hooks — no manual setup needed\n\n### Research-Backed Knowledge Base\n\n1,800+ lines of curated behavioral science across 6 reference files:\n\n- **Google HEART + Octalysis** — Industry-standard UX metrics (HEART) combined with psychological design scoring (Octalysis, 8 Core Drives, 0-800 scale)\n- **6-layer screenshot analysis** — Color, IA, Persuasion, Engagement, Friction, Dark Patterns\n- **Behavioral frameworks** — Fogg B=MAP, Hook Model, Cialdini's 7, SDT, Octalysis, Prospect Theory\n- **Dark patterns taxonomy** — Full Brignull classification with $3.4B+ in enforcement cases\n- **20+ foundational textbooks** mapped to real programs (Stanford, Penn, NNGroup, Irrational Labs)\n- **Retention benchmarks** — Category-specific data from RevenueCat, Adapty, and industry research\n- **Onboarding patterns** — 4 archetypes, commitment escalation, permission timing\n- **Pricing psychology** — Anchoring, decoy pricing, paywall timing strategies\n- **Color psychology** — Wright tonal groups, Kobayashi color image scales, cultural meaning databases, WCAG contrast compliance\n\nEvery citation has been audited. Peer-reviewed studies are distinguished from industry data. Compromised research is flagged with caveats and independent replications.\n\n---\n\n## Installation\n\n```bash\nclaude plugin add /path/to/nudge\n```\n\nOr for development/testing:\n\n```bash\nclaude --plugin-dir /path/to/nudge\n```\n\nNo API keys. No external services. The MCP server runs locally and auto-installs its dependencies on first session.\n\n---\n\n## Usage Examples\n\n### Audit an existing app\n\n> \"Audit this fitness app screenshot. What psychological patterns are they using and what are they missing?\"\n\nThe Analyst agent applies the 6-layer analysis framework, scores all 8 Octalysis Core Drives (assessing White Hat vs Black Hat balance), evaluates relevant HEART dimensions, names every pattern with the researcher behind it, checks for dark patterns, and provides prioritized recommendations with expected impact.\n\n### Design engagement from scratch\n\n> \"I'm building a meditation app for busy professionals. Help me design the engagement strategy.\"\n\nThe Designer agent asks about your target audience and aha moment, selects the right behavioral frameworks for your category, designs onboarding with commitment escalation, builds a Day 0-90+ retention timeline, recommends a color palette with research citations, and includes ethical guardrails.\n\n### Write psychologically-optimized copy\n\n> \"What should the CTA say on my paywall screen?\"\n\nThe Writer agent generates 3-5 variants — each applying a different psychological principle (endowment effect, loss aversion, social proof, etc.), explains why it works, rates its ethical impact, recommends the best pick, and tells you what NOT to write.\n\n### Build a brand color system\n\n> \"I need a complete brand color system for my fintech app targeting millennials.\"\n\nThe Color Psychologist defines the psychological constraints, the Art Director curates the exact hex codes, and the Brand Identity Designer assembles the final system — 5 colors with usage rules, accessibility compliance, dark mode variants, and a brand bible.\n\n### Check for dark patterns\n\n> \"Is our cancellation flow manipulative? Users have to click through 4 pages.\"\n\nThe Analyst agent classifies the pattern using Brignull's taxonomy, assesses regulatory risk (EU DSA, CPRA, FTC precedent), references enforcement cases with dollar amounts, and provides ethical alternatives.\n\n### Quick questions work too\n\n> \"What color should my fintech app be?\"\n\nThe skill handles it directly — blue for trust (Singh, 2006), green accent for growth/money, high-contrast CTA, WCAG AA compliance, dark mode variant. Or route to the Color Psychologist for a deeper dive with the full 252-color database.\n\n---\n\n## The Full Toolkit — Nothing Gatekept\n\nThe app industry is competitive. The top apps use psychological manipulation to dominate — variable ratio reinforcement, loss aversion, FOMO, scarcity, dark patterns. Nudge teaches **all of it**.\n\n- **Every technique in the playbook.** From gentle nudges to aggressive Black Hat gamification. If TikTok, Duolingo, or Amazon uses it, it's in the knowledge base.\n- **Risk-labeled, not censored.** When a tactic carries regulatory risk, Nudge flags the Brignull classification and enforcement precedent ($520M Epic, $2.5B Amazon, $391.5M Google). That's intelligence, not moralizing.\n- **Alternatives alongside aggressive options.** You get the aggressive version AND a less aggressive alternative. You pick your position on the spectrum.\n- **Never refuses a request.** If you want confirmshaming copy, loss-exploiting notifications, or FOMO mechanics — you get them. With the risk label attached so you go in with eyes open.\n\n---\n\n## What's Inside\n\n```\nnudge/\n├── .claude-plugin/plugin.json         # Plugin manifest (v0.2.0)\n├── agents/\n│   ├── analyst.md                     # HEART + Octalysis scoring, screenshot analysis, dark patterns\n│   ├── designer.md                    # Engagement architecture, onboarding, retention, pricing\n│   ├── writer.md                      # Microcopy, CTAs, notifications, empty states\n│   ├── color-psychologist.md          # Psychological color constraints, Wright groups, brand personality\n│   ├── art-director.md                # Exact hex curation by vibe and aesthetic\n│   ├── brand-identity-designer.md     # Permanent brand color systems + brand bibles\n│   └── color-trend-forecaster.md      # Trend analysis, what's dated, what's emerging\n├── skills/\n│   └── analyzing-app-psychology/\n│       ├── SKILL.md                   # Auto-routing skill (Analyze/Design/Write)\n│       ├── analysis-reference.md      # HEART, Octalysis, 6-layer analysis, dark patterns\n│       ├── design-reference.md        # Behavioral frameworks, onboarding, retention, pricing\n│       ├── writing-reference.md       # Microcopy psychology, CTAs, notifications, empty states\n│       ├── psychology-foundations.md   # Academic canon, UX laws, cognitive biases, case studies\n│       └── categories/                # 10 industry vertical deep dives\n│           ├── journaling.md\n│           ├── fitness-health.md\n│           ├── education-learning.md\n│           ├── ecommerce.md\n│           ├── social-community.md\n│           ├── fintech.md\n│           ├── gaming.md\n│           ├── childrens-apps.md\n│           ├── saas-productivity.md\n│           └── dating.md\n├── mcp-server/\n│   ├── package.json                   # Dependencies (auto-installed via hooks)\n│   ├── src/\n│   │   └── index.js                   # 7 color psychology MCP tools\n│   └── data/\n│       ├── colors-master.json         # 252 psychology-backed colors (13+ attributes each)\n│       ├── colornames-31k.json        # 31,891 named colors for artsy shade selection\n│       ├── colors-warm.json           # Warm hue source data\n│       ├── colors-cool-blue.json      # Cool blue hue source data\n│       ├── colors-cool-green.json     # Cool green hue source data\n│       ├── colors-neutral.json        # Neutral hue source data\n│       ├── colors-gap-fill-1.json     # Gap-fill expansion set 1\n│       └── colors-gap-fill-2.json     # Gap-fill expansion set 2\n├── hooks/\n│   └── hooks.json                     # SessionStart hook — auto-installs MCP dependencies\n├── nudge-architecture.md              # Full architecture documentation\n├── README.md\n└── LICENSE\n```\n\n### 10 Industry Verticals\n\nEach category file (~300-340 lines) includes retention challenges, case studies, psychological manipulation playbooks, onboarding flows, paywall timing, retention timelines, and risk profiles:\n\n| Category | Key Case Studies |\n|----------|-----------------|\n| Journaling & Wellness | Day One, Daylio |\n| Fitness & Health | Strava, Peloton, Nike Run Club, MyFitnessPal |\n| Education & Learning | Duolingo, Khan Academy, Brilliant, Coursera |\n| E-commerce & Shopping | Amazon, Shein, Shopify, Wish/Temu |\n| Social & Community | TikTok, Instagram, Snapchat, Discord, BeReal |\n| Fintech & Banking | Robinhood, Cash App, Revolut, Acorns |\n| Gaming | Candy Crush, Fortnite, Genshin Impact, Wordle |\n| Children's Apps | Epic $520M, TikTok €345M, YouTube $170M (COPPA/DSA) |\n| SaaS & Productivity | Slack, Notion, Figma, Calendly |\n| Dating | Tinder, Bumble, Hinge, Grindr |\n\nNew categories can be added as single files without modifying the core plugin.\n\n---\n\n## The Research Behind It\n\nNudge is built on the academic canon that real behavioral designers study:\n\n**Core Texts:** Kahneman's *Thinking, Fast and Slow*, Cialdini's *Influence*, Fogg's *Tiny Habits*, Eyal's *Hooked*, Norman's *The Design of Everyday Things*, Thaler's *Nudge*, Chou's *Actionable Gamification*\n\n**Key Papers:** Kahneman & Tversky (1979) Prospect Theory, Johnson & Goldstein (2003) defaults study, Iyengar & Lepper (2000) jam study, Schultz (1997) dopamine prediction error, Przybylski (2013) FOMO operationalization\n\n**Industry Data:** RevenueCat State of Subscription Apps, Adapty State of In-App Subscriptions, Airship Mobile App Experience Reports\n\n**Color Science:** Angela Wright's Colour Affects System (4 tonal groups), Kobayashi's Color Image Scale, Singh (2006) color-emotion associations, Labrecque & Milne (2012) brand personality-color mapping, Elliot & Maier (2014) color-in-context theory\n\n---\n\n## Contributing\n\nWant to add a category deep dive (fitness, education, e-commerce, fintech)? Create a file in `skills/analyzing-app-psychology/categories/` following the pattern in `journaling.md`. The plugin auto-discovers new category files. Ask Claude to update agents to include the new category.\n\nWant to add colors to the psychology database? Add entries to the appropriate data file in `mcp-server/data/` following the 13-attribute schema in `colors-master.json`.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n"}