Reviving Nudge: Building an AI-Powered Runtime Agent for App Onboarding

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

Nudge is a dynamic, AI-powered runtime agent designed to replace brittle, old-school product onboarding walkthroughs. Traditional onboarding tools rely on rigid CSS selectors that break the moment your app updates, or they force users to leave the app to watch a tutorial video.

Nudge takes a completely different approach. It is a thin, zero-dependency Node package (SDK) that embeds within a closed shadow DOM inside your application. When an end-user types a free-form goal (like "how do I export a CSV?"), Nudge orchestrates a multi-stage backend pipeline to evaluate the live DOM and gently guide the user's cursor to the right elements in real time. If the DOM drifts or the user takes a wrong turn, the agent recovers gracefully.

The Tech Stack

• SDK (nudge-sdk): TypeScript, esbuild, closed shadow DOM primitives, published to npm.
• Backend Brain: Node 20, Express 5, Zod validation, and OpenAI/Anthropic SDKs.
• Database & Vector Search: Postgres via Supabase, using pgvector for exact and semantic flow matching.
• Dashboard: Next.js 16, React 19, and Tailwind 4.
• Tooling & Infrastructure: Monorepo managed via pnpm workspaces and Turborepo.

Demo

• Source Code: GitHub Repository
• Production Landing Page: heynudge.in

The Comeback Story

Before this challenge, Nudge was a massive, ambitious monorepo that had stalled mid-execution. Previously, my architecture and attention were split between a standalone Chrome extension and a very early-stage SDK. Maintaining both diluted my focus, and the real core vision—a complex, multi-stage v1 Agent Harness—was trapped on paper inside my design docs. It was the classic "built under pressure, abandoned when it got too complicated" project.

During this Finish-Up-A-Thon, my goal is to make a major architectural pivot: going all-in on the Node package. I am shifting away from the Chrome extension to focus entirely on making nudge-sdk a powerful, embeddable npm package. This pivot unlocks massive distribution potential, allowing any developer to drop Nudge into their app with a simple npm install and a quick .init() call.

By dropping the extension overhead, I plan to push the core package across the finish line by tackling the following:

1. The Core Agent Harness: Implementing the full match → tweak → generate → play serving loop directly backing the SDK, ensuring every stage runs as an independently traceable OpenTelemetry span.
2. The LLM Chokepoint: Building strict schema validation, exact + semantic caching layers, and hard budget-enforcement filters to prevent rogue token spending.
3. Dashboard & SDK Polishing: Upgrading the nudge-sdk payload and the administrative Next.js dashboard to smoothly manage API keys, privacy redactions ([data-nudge-skip]), and custom theme injections for the host app.

My Experience with GitHub Copilot

Bringing an intricate, multi-agent AI system to life as a solo developer is an intimidating task. Throughout this challenge, GitHub Copilot will act as my ultimate engineering partner to help me execute this pivot and stitch together the complex components of the monorepo.

Here is exactly how I plan to leverage Copilot to finish Nudge:

• Navigating Complex Type Systems: With a monorepo spanning internal packages (@nudge/core, @nudge/api-client) and multiple apps, keeping TypeScript types synced can be tedious. I will rely on Copilot to predict the boilerplate required to bridge our Express backend types with the new npm package structure.
• Writing the Math & Logic for pgvector Queries: I plan to use Copilot Chat to quickly draft and optimize the raw SQL and semantic-match re-ranking logic needed to query embeddings inside Supabase efficiently.
• Bulletproofing Zod Schemas: Since every single stage of our serving path goes through a validation chokepoint, I need highly explicit, strict Zod schemas for our input/output guards. I will use Copilot to instantly generate these schemas based on my raw TypeScript interfaces, saving me hours of manual coding.
• Isolating the Shadow DOM: Ensuring the SDK UI remains completely impervious to host-app CSS leaks requires precise manipulation of web components. I will have Copilot help me write robust shadow DOM styling primitives and element-redaction selectors to protect end-user privacy flawlessly.