Pocketlantern

PocketLantern

[npm version] [npm downloads] [CI] [License: MIT]

Your AI agent sounds confident. It missed the blockers.

Prices shift, versions break, licenses change. PocketLantern is a blocker-aware decision layer for AI coding agents, grounded in source-linked, time-sensitive facts.

Try these queries

Ask your AI agent after installing PocketLantern:

"Which auth provider — Clerk, Auth0, or Cognito?"

⚠️ Cognito password hashes are permanently non-exportable⚠️ Auth0 password export requires support ticket — Free tier excluded⚠️ Auth0 Rules/Hooks EOL 2026-11-18 — Actions not portable✅ Clerk has the most flexible migration path

"Should I upgrade to Next.js 16?"

⚠️ Sync API access fully removed — all dynamic calls must be awaited⚠️ Custom webpack config breaks next build⚠️ next lint removed — switch to Biome or ESLint CLI⚠️ Requires Node.js 20.9.0+, TypeScript 5.1.0+, React 19.0+✅ Plan phased migration — codemod doesn't cover webpack or middleware

"Can I use the OpenAI Realtime API?"

⚠️ gpt-4o-realtime-preview removed 2026-05-07⚠️ Beta interface (realtime=v1 header) removed same date⚠️ GA event schema incompatible — 4 event renames✅ Start on GA from day one — or plan dual-stack migration

Three questions. Three blocker types. Same AI, different facts.

[PocketLantern demo — Node.js 20→24 upgrade blockers surfaced in seconds]

Quick start

Prerequisites: Node.js >= 22, an MCP client (Claude Code, Cursor, etc.)

npm install -g pocketlantern

Claude Code

In your project directory:

cd your-projectpocketlantern init

init registers the MCP server in ~/.claude.json and adds a one-line rule to your project's CLAUDE.md. Restart Claude Code (Ctrl+C, then run claude again), then ask your first query.

Cursor / Windsurf / other MCP clients

Add to your MCP config (Cursor: ~/.cursor/mcp.json):

{  "mcpServers": {    "pocketlantern": {      "command": "pocketlantern-mcp"    }  }}

Then add this line to your project rules (.cursorrules, Kiro steering file, etc.):

For technology decisions, upgrades, migrations, or licensing questions: before finalizing your answer, check the PocketLantern MCP server's search_cards tool for blockers in these bundled decision cards — your training data may be stale.

Reload MCP servers: Cursor — Cmd+Shift+P -> "MCP: Restart Servers". Windsurf — restart the editor.

More queries to try

4. "How did Vercel pricing change with Fluid Compute?" Billing split to Active CPU + Memory, shared-process concurrency breaks isolation

5. "Prisma or Drizzle for Edge/serverless?" Prisma v7 ESM + driver adapter breaking, Edge preview-only; Drizzle 0.30-1.0 also breaking

Verify installation

pocketlantern doctor               # check installation statuspocketlantern search "auth pricing" # search cards from CLI

How it works

PocketLantern is an MCP server. Your AI agent calls search_cards — and gets source-linked decision cards plus source-linked blocker warnings where available.

Agent asks question  -> search_cards("clerk vs auth0 authentication")  -> 3 cards + 5 blocker warnings (lock-in, EOL, export restrictions)  -> Agent answers with source-linked constraints

Local cardset. Instant lookup. No vector database. No embeddings. Keyword search, card links, and source-linked blocker warnings where available. The value is in source-linked decision cards, not clever retrieval alone.

search_cards("auth", constraints:["serverless"]) -> cards + blockersget_card("auth/clerk-vs-auth0-vs-cognito-2026")  -> full card with factsget_related_cards(...)                           -> connected topics

What's included

Blocker-aware decision cards across 27 categories — plus source-linked blocker warnings from the bundled graph index. Ships with the npm package, works immediately, no network, no account:

What a card looks like

Each card is a structured YAML file with source-linked facts and official reference links:

id: auth/clerk-vs-auth0-vs-cognito-2026title: Clerk vs Auth0 vs Cognito Under Current Pricing and Feature Changesproblem: Select an auth vendor given recent pricing shifts, MAU economics, ...constraints: [cost-sensitive, low-ops, enterprise, compliance, serverless]candidates:  - name: Clerk    summary: "Pro starts at $20/mo, includes 50,000 MRUs per app..."    when_to_use: "Choose for small-team + low-ops + cost-sensitive SaaS..."    tradeoffs: "Best DX and fastest implementation..."    cautions: "Be precise about org-member limits..."    links:      - https://clerk.com/pricing      - https://clerk.com/docs/guides/organizations/configure  - name: Auth0    # ...  - name: Amazon Cognito    # ...tags: [auth, clerk, auth0, pricing, passkeys, b2b, compliance]related_cards: [auth/sso-for-b2b-saas, auth/rbac-vs-abac-vs-rebac]updated: 2026-03-14

See packages/schema/src/card.ts for the full schema definition.

Project structure

pocketlantern/  packages/schema/       <- Card schema (zod + TypeScript types)  apps/mcp-server/       <- MCP server (search, retrieval, tool handlers)  apps/cli/              <- CLI (validate, search, init, doctor)  packages/knowledge/    <- Decision cards + graph index (data package)  docs/                  <- User guides & roadmap

Monorepo: pnpm workspace. Build order: schema -> knowledge (no build) -> mcp-server -> cli.

Development

pnpm build              # Build all packagespnpm test               # Run tests (299 tests)pnpm test:coverage      # Run with coverage reportpnpm lint               # ESLintpnpm format:check       # Prettier check

Missing a topic? Request coverage in Card Requests.

Contributing

Contributions to the tool (schema, MCP server, CLI, search) are welcome. See CONTRIBUTING.md for guidelines.

License

MIT