Your agent is only as smart as the context you give it. Whale makes that context automatic.

AI agents — Claude Code, Codex, Cursor, Copilot — are powerful but amnesiac by design. Every conversation starts from zero. They don't know what you decided, why you decided it, or which exceptions are intentional. Without structure, they guess.

Whale Igniter gives your repo a living memory: design foundations, components, decisions, and approved exceptions — kept in sync by the CLI, readable by any agent, and never dependent on a chat history that will disappear.

How it works

npm install -g whale-igniter
whale ignite my-app

That single command creates a structured intelligence layer inside your project:

my-app/
├── whale.config.json          # foundations, stack, theme, AI targets
├── CLAUDE.md                  # agent-readable project brief, auto-synced
├── intelligence/
│   ├── components.json        # component catalog with variants and states
│   ├── decisions/             # one Markdown ADR per decision
│   └── refinements/           # one Markdown file per approved exception
└── llm-wiki/                  # generated markdown, one file per concern

whale.config.json and intelligence/ are the source of truth. Decisions and refinements use individual Markdown files with frontmatter; component metadata remains structured JSON. When you run whale sync, everything regenerates — CLAUDE.md, the wiki, and the context your agent reads on the next conversation.

The agent doesn't guess anymore. It reads.

Generated output belongs to you. Files created by Whale Igniter, including generated HTML, CSS, CLAUDE.md, AGENTS.md, wiki pages, and copied theme files, are yours to use and modify; they are not restricted by this project's MIT license.

What agents can read — and write

Whale ships an MCP server that exposes your project intelligence as structured tools any compatible client can call:

whale mcp config --client claude-code
whale mcp config --client cursor
whale mcp config --client zed

| Tool | What it does | |---|---| | whale_project_overview | Full project brief: stack, foundations, packs, context | | whale_list_components | Component catalog with files, variants, states, tokens | | whale_list_decisions | Architectural decisions with rationale and status | | whale_list_refinements | Approved exceptions — context for drift that's intentional | | whale_insights | Live analysis: orphans, coverage gaps, tensions, drift | | whale_register_component | Add a component to the catalog | | whale_record_decision | Log an architectural decision | | whale_record_refinement | Mark a drift exception as approved |

Agents don't just read context — they can write back to it.

Design intelligence

Whale tracks your design system and detects when reality drifts from it.

whale insights drift spacing    # find off-grid spacing in CSS, JSX, Vue, Svelte
whale insights drift color      # find raw hex values outside your token set
whale insights drift radii      # find radius values not in your foundations
whale insights drift spacing --review   # interactively accept or queue each issue

When something drifts intentionally — a one-off exception, a product decision — you record it as a refinement. Whale stops flagging it. The agent knows it's approved.

Theme engine

Landing pages and generated UI are fully theme-driven. No hardcoded tokens.

whale themes list
whale create landing --theme harbor     # royal blue on paper — the Whale brand
whale create landing --theme aurora     # modern SaaS, indigo, generous whitespace
whale create landing --theme atlas      # enterprise minimal, dense, neutral (default)

Each theme defines four tiers — Identity, Typography, Structural, Interaction — and emits a complete CSS custom property block. Swap themes; everything updates.

Landing copy can be customized without AI:

whale create landing --theme harbor --title "FuelForge" --tagline "Meal planning for athletes who train hard."
whale create landing --theme aurora --content landing.json
whale create landing --brief

landing.json can define the brand, hero copy, CTA, features, proof, and contact copy. CLI flags override the JSON, so quick edits stay fast. Use --sample-content to generate an editable starter file, or --brief for a short local questionnaire that creates the JSON and landing together.

Implementation intelligence

Once a component exists, Whale helps you build it right and document it thoroughly. Three commands, one chain:

# 1. Generate a typed component scaffold
whale create component Button --variants primary,secondary,ghost --states hover,focus,disabled

# 2. Generate an implementation contract — spec, tokens, checklist
whale forge Button

# 3. Generate a developer README using AI
whale scribe readme Button

whale forge produces a Markdown contract in docs/forge/ with the component's foundation spec (grid, radius, padding), derived design tokens, and an implementation checklist. No API key required.

whale scribe readme calls your configured AI provider (Anthropic or OpenAI) and writes a developer-ready README to docs/scribe/. Use --prompt-only to get the prompt without an API call.

whale scribe overview generates a full project README — foundations, component catalog, architectural decisions — in one pass.

Project health (Atlas)

Atlas gives product managers and tech leads a narrative view of the project's operational health.

whale atlas health       # AI-generated health report: errors, risk areas, next steps
whale atlas decisions    # list active architectural decisions by category
whale atlas decisions --category design-system

whale atlas health scans validation issues, component coverage, and recorded decisions, then generates a prioritized health report in docs/atlas/health.md. Use --prompt-only without an API key.

whale atlas decisions lists active decisions inline, grouped by category, with rationale and consequences.

Core commands

| Command | What it does | |---|---| | whale ignite my-app | Bootstrap a new Whale workspace | | whale ignite my-app --interactive | Wizard: project type, stack, team size, packs | | whale adopt | Scan an existing project and propose components and foundations | | whale sync | Regenerate CLAUDE.md, wiki, and agent context | | whale check | Validation + project insights | | whale changes --since HEAD~5 | What changed in intelligence stores since a git ref | | whale themes list | Browse available UI themes | | whale create landing --theme <name> | Generate a themed HTML/CSS landing page | | whale create component <Name> | Generate a typed component with intelligence registration | | whale forge <Component> | Generate an implementation contract for a registered component | | whale scribe readme <Component> | Generate a developer README for a component using AI | | whale scribe overview | Generate a full project README using AI | | whale atlas health | Generate an AI-powered project health report | | whale atlas decisions | List active architectural decisions | | whale selene suggest | AI-powered improvement suggestions (API key optional) | | whale mcp config --client cursor | Configure an MCP client |

Operating packs

Packs add structured operational context to your project. forge, scribe, and atlas are available as both standalone commands and installable packs — installing a pack makes its context visible to AI agents via CLAUDE.md and the MCP server.

whale team add lighthouse   # quality and accessibility validation
whale team add scribe       # documentation generation
whale team add forge        # implementation contracts and handoff
whale team add atlas        # product health and decision tracking
whale team add selene       # AI suggestions and component audits

AI bridge (Selene)

Selene packages your project context into structured prompts. With an API key it calls the model directly; without one it prints a prompt you can paste anywhere.

export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY

whale selene status
whale selene suggest --focus all
whale selene audit src/components/Hero.tsx
whale selene describe src/components/Button.tsx

Data & privacy

Whale Igniter runs offline by default. Core flows such as themes, drift detection, wiki generation, MCP, and local project analysis do not require an API key and do not send project data over the network.

AI features are opt-in. When you enable Selene API mode or use whale scribe / whale atlas health, Whale sends the prompt and project context to the selected provider, Anthropic or OpenAI, under that provider's terms. You are responsible for reviewing context before sending it and for keeping secrets or sensitive data out of prompts.

API keys are read from environment variables only: ANTHROPIC_API_KEY or OPENAI_API_KEY. The key is used only in request headers, and Whale does not log it, write it to config, or persist it on disk.

Selene's local cache stores response text under .whale/selene/cache in the target project. It does not store API keys. Whale also ensures .whale/ is ignored by the target project's .gitignore when writing Selene cache entries.

Whale Igniter has no telemetry or analytics.

Requirements

• Node ≥ 20
• No API key required for any core flow — themes, drift detection, wiki generation, MCP, whale forge, and whale atlas decisions are fully local and deterministic

Credits

Brand assets reference JetBrains Mono (SIL Open Font License 1.1) and Special Elite (Apache License 2.0). No font binaries are shipped.

Links

• Roadmap: docs/ROADMAP.md
• Package: npmjs.com/package/whale-igniter
• License: MIT