Ask Ivy

AI browser extension that takes real human inputs to personalize content, flag eligible benefits, fill out forms, and provide data-driven, actionable improvements for government websites.

Features

• Content Simplification -- Rewrites web pages at a reading level you choose, adds plain-language tooltips for jargon, and adjusts font size, contrast, and motion
• Benefits Discovery -- Matches your profile against federal benefit programs using a deterministic rules engine, then ranks and explains results in plain language via AI
• Highlight-to-Ask -- Select any text on a page and ask Ivy to explain it in a centered dialog with markdown rendering. Responses are cached per URL so repeat queries are instant across all users
• Form Guidance -- Detects form fields on any page, generates plain-language explanations via AI, and displays hover tooltips next to each field. Maps fields to vault types for future auto-fill
• Feedback Loop -- Users leave anchored feedback on specific page elements via "Leave site feedback" on the highlight-ask dialog or the Feedback tab. AI categorizes comments (confusing language, missing info, accessibility, etc.) and stores them with CSS selector location data
• Government Dashboard -- Web app for site owners showing aggregated user interactions per domain and page. Renders a proxied page preview with highlighted elements where users interacted. Shows Ivy's AI responses, commonly asked questions, and feedback category distribution. Site owners can edit Ivy's cached responses via API

Wireframes

Design wireframes for planned features, including the natural language setup flow, contextual text selection, and the government agency dashboard for aggregated user feedback and accessibility insights.

Extension UI

Government Dashboard

A dashboard for government website owners showing accessibility scores, user behavior analytics, page-level insights, and commonly asked questions aggregated from Ivy users.

Screenshots from prototype

Onboarding

Ivy greets new users with a conversational setup flow, asking about reading comfort, jargon preferences, and visual needs.

Home & Settings

Content Simplification

Click "Simplify this page" and Ivy rewrites complex text at your reading level, with jargon tooltips. Simplified sections are marked with a purple left border. There is an option to toggle between the original and simplified content. Tooltips appear on hover that help provide simple definitions for terms.

Highlight-to-Ask

Select any text on a page and click "Ask Ivy" for a plain-language explanation.

Benefits Discovery

Fill out a short eligibility profile and Ivy matches you against federal benefit programs, ranked by likelihood with plain-language explanations.

Screen Recording of extension in action

Screen.Recording.2026-03-16.at.18.56.58.mov

Architecture

Chrome Extension (WXT)
├── Sidebar UI (React + Radix UI + Tailwind)
├── Content Script (DOM transforms, highlight-to-ask)
└── Service Worker (orchestration, messaging)
        │
        ▼  HTTPS
Server (Node.js + Hono)
├── AI Transform Pipeline (Claude API)
├── Explain Endpoint (with response caching)
├── Form Guidance Endpoint
├── Feedback + Categorization (Claude Haiku)
├── Benefits Evaluation
│   ├── Deterministic Rules Engine (@ivy/benefits-engine)
│   └── AI Ranking & Explanation (Claude Haiku)
└── Dashboard API
    ├── Domain/page aggregation
    ├── Page proxy for preview
    └── Response management

Dashboard (Vite + React)
├── Domain Overview (page list, category chart, top questions)
└── Page Detail (proxied page preview with element highlights, insights panel)

Monorepo Structure

ivy/
├── packages/
│   ├── shared/           # Types, message protocol, encryption utils, constants
│   ├── extension/        # WXT Chrome extension (MV3)
│   ├── server/           # Node.js API server (Hono)
│   ├── dashboard/        # Site owner dashboard (Vite + React)
│   └── benefits-engine/  # Deterministic eligibility rules
├── scripts/              # Version bump and packaging scripts
├── .github/workflows/    # CI (build, test, typecheck)
├── Dockerfile            # Multi-stage production build for server
├── turbo.json
└── pnpm-workspace.yaml

Tech Stack

Layer	Technology
Extension framework	WXT (MV3, cross-browser)
Extension UI	React 19, Radix UI, Tailwind CSS 4, Zustand
Dashboard	Vite, React 19, React Router, Tailwind CSS 4
Server	Node.js 22, Hono
AI	Claude API via @anthropic-ai/sdk (Haiku for most tasks, Sonnet for translation)
Benefits engine	Deterministic rules with AI ranking
Monorepo	Turborepo, pnpm workspaces
Testing	Vitest (180 tests)
Client encryption	Web Crypto API (AES-256-GCM)
Deployment	Railway (server), GitHub Actions (CI)

Getting Started

Prerequisites

• Node.js 22+
• pnpm 9+ (enabled via corepack: corepack enable)
• An Anthropic API key

Setup

# Install dependencies
pnpm install

# Configure environment
cp .env.example .env.local
# Edit .env.local and add your ANTHROPIC_API_KEY

Development

Run the server, extension, and dashboard in separate terminals:

# Terminal 1: Start the API server (port 3001)
pnpm --filter @ivy/server dev

# Terminal 2: Start the extension dev server (opens Chrome with extension loaded)
pnpm --filter @ivy/extension dev

# Terminal 3: Start the dashboard dev server (port 5173)
pnpm --filter @ivy/dashboard dev

The extension dev server uses WXT's hot module replacement. The Chrome profile is stored in packages/extension/.chrome-profile/ so your extension state persists across restarts.

Package Extension for Testing

# Bump version and build/zip the extension
pnpm version:bump        # patch by default, or: ./scripts/bump-version.sh minor
pnpm package:extension   # builds and zips to dist/ivy-extension-{version}.zip

Build

# Build all packages
pnpm build

# Build just the extension (outputs to packages/extension/.output/chrome-mv3/)
pnpm --filter @ivy/extension build

Test

# Run all tests
pnpm test

# Watch mode
pnpm test:watch

Docker (server only)

docker build -t ivy-server .
docker run -p 3001:3001 -e ANTHROPIC_API_KEY=sk-ant-... ivy-server

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes	Claude API key for AI features
IVY_API_KEY	No	Bearer token to protect API endpoints (skipped if unset)
PORT	No	Server port (default: 3001)
DATABASE_URL	No	Neon Postgres connection string (planned)
UPSTASH_REDIS_REST_URL	No	Redis URL for transform caching (planned)
UPSTASH_REDIS_REST_TOKEN	No	Redis auth token (planned)

The extension reads VITE_API_URL (default: http://localhost:3001) and optionally VITE_API_KEY from its .env.development file.

Security

• All AI prompts use XML tag isolation to prevent prompt injection
• Content script uses DOMParser and textContent instead of innerHTML to prevent XSS
• Client-side AES-256-GCM encryption for PII vault (Web Crypto API)
• API key authentication middleware on all /api/* endpoints
• CORS restricted to extension origins and explicit localhost ports
• Extension message listener validates sender.id
• Request validation with size limits on all endpoints

License

Apache 2.0 -- see LICENSE.