--- title: "AI Ecosystem: Maximizing Claude Code with Complementary Tools" description: "When to use Claude Code vs complementary AI tools and how to chain them for optimal workflows" tags: [ai-ecosystem, guide, workflows, integration] --- # AI Ecosystem: Maximizing Claude Code with Complementary Tools > **Reading time**: ~25 minutes > > **Purpose**: This guide helps you understand when to use Claude Code vs. complementary AI tools, and how to chain them for optimal workflows. --- ## Choose the Layer Before Choosing a Product The model is not the runtime harness, and a framework, dashboard, or fleet manager is not automatically a runtime either. A runtime harness owns the iterative model-and-tool loop. A repository harness makes one codebase legible and verifiable. An orchestrator coordinates multiple runtime sessions. This distinction prevents a feature list from becoming a false comparison. Read the [Agent Harness Map](./agent-harness-landscape.md) for the strict runtime comparison and its wider, sourced directory. Read [Agent Harness Engineering](../core/agent-harness.md) for the four-layer model, [Agent Tools: Beyond Claude Code](./agentic-tools.md) for frameworks and control planes, and the [glossary](../core/glossary.md) for terminology. The operational follow-through belongs in [Agent Evaluation](../roles/agent-evaluation.md), [Session Observability](../ops/observability.md), and [Security Hardening](../security/security-hardening.md). --- ## Table of Contents - [Introduction](#introduction) - [1. Perplexity AI (Research & Sourcing)](#1-perplexity-ai-research--sourcing) - [2. Google Gemini (Visual Understanding)](#2-google-gemini-visual-understanding) - [3. Kimi (PPTX & Long Document Generation)](#3-kimi-pptx--long-document-generation) - [4. NotebookLM (Synthesis & Audio)](#4-notebooklm-synthesis--audio) - [5. Voice-to-Text Tools (Wispr Flow, Superwhisper)](#5-voice-to-text-tools-wispr-flow-superwhisper) - [6. IDE, ADE, and Hybrid Coding Environments](#6-ide-ade-and-hybrid-coding-environments) - [6.1 Google Antigravity (Agent-First IDE)](#61-google-antigravity-agent-first-ide) - [7. UI Prototypers (v0, Bolt, Lovable)](#7-ui-prototypers-v0-bolt-lovable) - [7.1 Generative UI: Agent-Driven Interactive Output Formats](#71-generative-ui-agent-driven-interactive-output-formats) - [8. Workflow Orchestration](#8-workflow-orchestration) - [9. Cost & Subscription Strategy](#9-cost--subscription-strategy) - [10. Claude Cowork (Research Preview)](#10-claude-cowork-research-preview) - [11. AI Coding Agents Matrix](#11-ai-coding-agents-matrix) - [11.1 Goose: Open-Source Alternative (Block)](#111-goose-open-source-alternative-block) - [11.2 Practitioner Insights](#112-practitioner-insights) - [11.3 When to Build vs Use](#113-when-to-build-vs-use) - [11.4 Skills Distribution Platforms](#114-skills-distribution-platforms) - [12. Context Packing Tools](#12-context-packing-tools) - [14. Claude Managed Agents (Cloud-Hosted Platform)](#14-claude-managed-agents-cloud-hosted-platform) - [15. Project Glasswing & Claude Mythos Preview (Defensive Security)](#15-project-glasswing--claude-mythos-preview-defensive-security) - [16. Step by Token: How LLMs Work (Interactive Guide)](#16-step-by-token-how-llms-work-interactive-guide) - [Appendix: Ready-to-Use Prompts](#appendix-ready-to-use-prompts) - [Alternative Providers (Community Workarounds)](#alternative-providers-community-workarounds) --- ## Introduction ### Philosophy: Augmentation, Not Replacement Claude Code excels at: - **Contextual reasoning** across entire codebases - **Multi-file implementation** with test integration - **Persistent memory** via CLAUDE.md files - **CLI automation** for CI/CD pipelines - **Agentic task completion** with minimal supervision What Claude Code doesn't do well (by design): - **Real-time web search with source verification** (WebSearch exists but limited) - **Image generation** (no native capability) - **PowerPoint/slide generation** (no PPTX output) - **Audio synthesis** (no TTS) - **Browser-based prototyping** (no visual preview) The goal is not to find "better" tools, but to chain the **right tool for each step**. > The same persona/agent pattern that chains complementary tools here is being applied one level up, to named business executive roles (CFO, CMO, board of directors) rather than dev tools. See [AI Executive Agents](./ai-executive-agents.md) for that landscape. ### The Complementarity Matrix | Task | Claude Code | Better Alternative | Why | |------|-------------|-------------------|-----| | **Code implementation** | ✅ Best | - | Contextual reasoning + file editing | | **Deep research with sources** | ⚠️ Limited | Perplexity Pro | 100+ verified sources | | **Image → Code** | ⚠️ Limited | Gemini 2.5+ | Superior visual understanding | | **Slide generation** | ❌ None | Kimi.com | Native PPTX export | | **Audio overview** | ❌ None | NotebookLM | Podcast-style synthesis | | **Browser prototyping** | ❌ None | v0.dev, Bolt | Live preview | | **IDE autocomplete** | ❌ None | Copilot, Cursor | Inline suggestions | --- ## 1. Perplexity AI (Research & Sourcing) ### Complementarity Diagram The following diagram illustrates how Perplexity and Claude Code complement each other across the development workflow: ```mermaid flowchart TB subgraph PERPLEXITY["🔍 PERPLEXITY DOMAIN"] direction TB P1["Deep Research
100+ sources synthesis"] P2["Real-time Information
Latest APIs, versions"] P3["Source Verification
Cited, verifiable facts"] P4["Spec Generation
Structured requirements"] end subgraph CLAUDE["⚡ CLAUDE CODE DOMAIN"] direction TB C1["Contextual Implementation
Full codebase access"] C2["Multi-file Editing
Atomic changes"] C3["Test Generation
Pattern-aware"] C4["CI/CD Integration
Automated pipelines"] end subgraph OVERLAP["🔄 OVERLAP ZONE"] direction TB O1["Quick Factual Lookups
→ Use Claude WebSearch"] O2["Code Explanation
→ Use Claude (contextual)"] end P4 -->|"spec.md"| C1 style PERPLEXITY fill:#e8f4f8,stroke:#0ea5e9 style CLAUDE fill:#fef3c7,stroke:#f59e0b style OVERLAP fill:#f3e8ff,stroke:#a855f7 ``` **Key Insight**: Perplexity answers "What should we build?" → Claude Code answers "How do we build it here?" ### Decision Flow ```mermaid flowchart LR Q["Developer Question"] --> D{Need verified
sources?} D -->|Yes| P["Perplexity"] D -->|No| D2{Need current
context?} D2 -->|Yes| C["Claude Code"] D2 -->|No| D3{Quick lookup
or deep research?} D3 -->|Quick| CW["Claude WebSearch"] D3 -->|Deep| P P -->|"spec.md"| C CW --> C style P fill:#e8f4f8,stroke:#0ea5e9 style C fill:#fef3c7,stroke:#f59e0b style CW fill:#fef3c7,stroke:#f59e0b ``` ### When to Use Perplexity Over Claude | Scenario | Use Perplexity | Use Claude | |----------|---------------|------------| | "What's the latest API for X?" | ✅ | ⚠️ Knowledge cutoff | | "Compare 5 libraries for auth" | ✅ Sources | ⚠️ May hallucinate | | "Explain this error message" | ⚠️ Generic | ✅ Contextual | | "Implement auth in my codebase" | ❌ No files | ✅ Full access | ### Perplexity Pro Features for Developers **Deep Research Mode** - Synthesizes 100+ sources into structured output - Takes 3-5 minutes but produces comprehensive specs - Export as markdown → Feed to Claude Code **Model Selection** - Claude Sonnet 4: Best for technical prose and documentation - GPT-4o: Good for code snippets - Sonar Pro: Fast factual lookups **Labs Features** - Spaces: Persistent project contexts - Code blocks: Syntax-highlighted exports - Charts: Auto-generated from data ### Integration Workflow #### Pattern 1: Research → Spec → Code ``` ┌─────────────────────────────────────────────────────────┐ │ 1. PERPLEXITY (Deep Research) │ │ "Research best practices for JWT refresh tokens │ │ in Next.js 15. Include security considerations, │ │ common pitfalls, and library recommendations." │ │ │ │ → Output: 2000-word spec with sources │ └───────────────────────────┬─────────────────────────────┘ ↓ Export as spec.md ┌─────────────────────────────────────────────────────────┐ │ 2. CLAUDE CODE │ │ > claude │ │ "Implement JWT refresh tokens following spec.md. │ │ Use the jose library as recommended." │ │ │ │ → Output: Working implementation with tests │ └─────────────────────────────────────────────────────────┘ ``` #### Pattern 2: Parallel Pane Workflow Using tmux or terminal split: ```bash # Left pane: Perplexity (browser or CLI) perplexity "Best practices for rate limiting in Express" # Right pane: Claude Code (implementing) claude "Add rate limiting to API. Check spec.md for approach." ``` ### Comparison: Claude WebSearch vs Perplexity | Feature | Claude WebSearch | Perplexity Pro | |---------|-----------------|----------------| | Source count | ~5-10 | 100+ (Deep Research) | | Source verification | Basic | Full citations | | Real-time data | Yes | Yes | | Export format | Text in context | Markdown, code blocks | | Best for | Quick lookups | Comprehensive research | | Cost | Included | $20/month Pro | **Recommendation**: Use Claude WebSearch for quick factual checks. Use Perplexity Deep Research before any significant implementation that requires understanding the ecosystem. --- ## 2. Google Gemini (Visual Understanding) ### Developer Use Cases **Gemini's Visual Superpowers**: - UI mockup → HTML/CSS/React code (90%+ fidelity) - Diagram interpretation (flowcharts → Mermaid/code) - Screenshot debugging ("why does this look broken?") - Design token extraction (colors, spacing from images) ### Gemini 2.5 Pro for Development Best-in-class for: - **Complex UI conversion**: Upload Figma screenshot → Get Tailwind components - **Diagram comprehension**: Architecture diagrams → Implementation plan - **Error analysis**: Upload error screenshot → Get debugging steps Model selection: - **Gemini 2.5 Pro**: Complex visual reasoning, long context - **Gemini 2.5 Flash**: Quick visual tasks, lower cost ### Integration Workflow #### Pattern: Visual → Code ``` ┌─────────────────────────────────────────────────────────┐ │ 1. GEMINI 2.5 PRO │ │ Upload: screenshot.png of Figma design │ │ Prompt: "Convert this to a React component using │ │ Tailwind CSS. Use semantic HTML and │ │ include responsive breakpoints." │ │ │ │ → Output: JSX + Tailwind code │ └───────────────────────────┬─────────────────────────────┘ ↓ Copy to clipboard ┌─────────────────────────────────────────────────────────┐ │ 2. CLAUDE CODE │ │ > claude │ │ "Refine this component for our Next.js project. │ │ Add proper TypeScript types, our Button component, │ │ and connect to the auth context." │ │ │ │ → Output: Production-ready component │ └─────────────────────────────────────────────────────────┘ ``` #### Pattern: Diagram → Implementation Plan ``` ┌─────────────────────────────────────────────────────────┐ │ 1. GEMINI │ │ Upload: architecture-diagram.png │ │ Prompt: "Analyze this architecture diagram. │ │ Output a Mermaid diagram with the same │ │ structure, and list the components." │ │ │ │ → Output: Mermaid code + component list │ └───────────────────────────┬─────────────────────────────┘ ↓ Paste mermaid to CLAUDE.md ┌─────────────────────────────────────────────────────────┐ │ 2. CLAUDE CODE │ │ "Implement the UserService component from the │ │ architecture in CLAUDE.md. Start with the │ │ interface, then the implementation." │ │ │ │ → Output: Implemented service │ └─────────────────────────────────────────────────────────┘ ``` ### Image Generation Alternatives For generating diagrams, mockups, or visual assets: | Tool | Best For | Format | Quality | |------|----------|--------|---------| | Ideogram 3.0 | UI mockups, icons | PNG, SVG | High | | Recraft v3 | Vectors, logos | SVG, PNG | Very high | | Midjourney | Artistic visuals | PNG | Artistic | | DALL-E 3 | Quick concepts | PNG | Good | **Workflow for generated images**: 1. Generate image with tool of choice 2. Upload to Gemini for → code conversion 3. Refine with Claude Code --- ## 3. Kimi (PPTX & Long Document Generation) ### What is Kimi? [Kimi](https://kimi.ai) is Moonshot AI's assistant, notable for: - **Native PPTX generation** (actual slides, not markdown) - **128K+ token context** (entire codebases) - **Code-aware layouts** (syntax highlighting in slides) - **Multilingual** (excellent Chinese/English) ### Developer Use Cases **Presentation Generation**: - PR summary → stakeholder deck - Architecture docs → visual presentation - Technical spec → team onboarding slides - Code walkthrough → training materials ### Integration Workflow #### Pattern: Code → Presentation ``` ┌─────────────────────────────────────────────────────────┐ │ 1. CLAUDE CODE │ │ "Generate a summary of all changes in the last │ │ 5 commits. Format as markdown with sections: │ │ Overview, Key Changes, Breaking Changes, Migration."│ │ │ │ → Output: changes-summary.md │ └───────────────────────────┬─────────────────────────────┘ ↓ Upload to Kimi ┌─────────────────────────────────────────────────────────┐ │ 2. KIMI │ │ Prompt: "Create a 10-slide presentation from this │ │ summary for non-technical stakeholders. │ │ Use business-friendly language. │ │ Include one slide per major feature." │ │ │ │ → Output: stakeholder-update.pptx │ └─────────────────────────────────────────────────────────┘ ``` #### Pattern: Architecture → Training ``` ┌─────────────────────────────────────────────────────────┐ │ 1. CLAUDE CODE (using /explain or equivalent) │ │ "Explain the authentication flow in this project. │ │ Include sequence diagrams (mermaid) and key files." │ │ │ │ → Output: auth-explanation.md with diagrams │ └───────────────────────────┬─────────────────────────────┘ ↓ Upload to Kimi ┌─────────────────────────────────────────────────────────┐ │ 2. KIMI │ │ "Create an onboarding presentation for new devs. │ │ 20 slides covering the auth system. Include │ │ code snippets and diagrams where relevant." │ │ │ │ → Output: auth-onboarding.pptx │ └─────────────────────────────────────────────────────────┘ ``` ### Comparison: Presentation Tools | Tool | Strengths | Weaknesses | Best For | |------|-----------|------------|----------| | **Kimi** | Native PPTX, code-aware | Less design polish | Technical decks | | **Gamma.app** | Beautiful templates | Less code support | Business decks | | **Tome** | AI-native, visual | Expensive | Marketing | | **Beautiful.ai** | Smart templates | Manual | Design-focused | | **Marp** | Markdown → slides | Manual styling | Developer decks | **Recommendation**: Use Kimi for technical content with code. Use Gamma for business/investor decks. --- ## 4. NotebookLM (Synthesis & Audio) ### Developer Use Cases **Documentation Synthesis**: - Upload 50+ files → Get unified understanding - Ask questions about your codebase - Generate audio overview for commute learning **Audio Overview Feature**: - Generates 10-15 minute "podcast" from uploaded content - Two AI hosts discuss your documentation - Perfect for onboarding or reviewing large systems ### Integration Workflow #### Pattern: Codebase → Audio Onboarding ``` ┌─────────────────────────────────────────────────────────┐ │ 1. EXPORT (via Claude Code or manual) │ │ "Export all markdown files from docs/ and the │ │ main README to a single combined-docs.md file." │ │ │ │ → Output: combined-docs.md (50K tokens) │ └───────────────────────────┬─────────────────────────────┘ ↓ Upload to NotebookLM ┌─────────────────────────────────────────────────────────┐ │ 2. NOTEBOOKLM │ │ - Add combined-docs.md as source │ │ - Click "Generate Audio Overview" │ │ - Wait 3-5 minutes for generation │ │ │ │ → Output: 12-minute audio explaining your system │ └───────────────────────────┬─────────────────────────────┘ ↓ Listen during commute ┌─────────────────────────────────────────────────────────┐ │ 3. BACK TO CLAUDE CODE │ │ "Based on my notes from the audio overview: │ │ [paste notes] │ │ Help me understand the auth flow in more detail." │ │ │ │ → Output: Contextual deep-dive │ └─────────────────────────────────────────────────────────┘ ``` #### Pattern: Multi-Source Synthesis ``` ┌─────────────────────────────────────────────────────────┐ │ NOTEBOOKLM │ │ Upload multiple sources: │ │ - Your codebase docs (combined-docs.md) │ │ - Framework documentation (Next.js docs PDF) │ │ - Related articles (URLs or PDFs) │ │ │ │ Ask: "How does our auth implementation compare to │ │ Next.js best practices?" │ │ │ │ → Output: Comparative analysis with citations │ └─────────────────────────────────────────────────────────┘ ``` ### Export to CLAUDE.md After NotebookLM synthesis, export key insights to your project: ```markdown ## Architecture Insights (from NotebookLM synthesis) ### Key Patterns - Service layer uses repository pattern - Auth flow follows OAuth2 with PKCE - State management via React Query ### Potential Issues Identified - Token refresh logic not documented - Missing error boundaries in critical paths ### Recommendations - Add token refresh documentation - Implement error boundary audit ``` --- ## 4.1 NotebookLM MCP Integration **Available since**: Claude Code v2.1+ with MCP support **What it does**: Query your NotebookLM notebooks directly from Claude Code, maintaining conversation context across multiple questions. ### Installation ```bash # Install NotebookLM MCP server claude mcp add notebooklm npx notebooklm-mcp@latest # Configure profile (optional, add to ~/.zshrc or ~/.bashrc) export NOTEBOOKLM_PROFILE=standard # minimal (5 tools) | standard (10 tools) | full (16 tools) # Verify installation claude mcp list # Should show: notebooklm: npx notebooklm-mcp@latest - ✓ Connected ``` **Profile comparison**: | Profile | Tools | Use Case | |---------|-------|----------| | `minimal` | 5 | Basic queries, token-constrained environments | | `standard` | 10 | **Recommended** - Queries + library management | | `full` | 16 | Advanced (browser control, cleanup, re-auth) | **Detailed tool breakdown**: | Tool | minimal | standard | full | Description | |------|---------|----------|------|-------------| | `ask_question` | ✅ | ✅ | ✅ | Query notebooks with conversation context | | `add_notebook` | ✅ | ✅ | ✅ | Add notebook to library | | `list_notebooks` | ✅ | ✅ | ✅ | List all notebooks in library | | `get_notebook` | ✅ | ✅ | ✅ | Get notebook details by ID | | `setup_auth` | ✅ | ✅ | ✅ | Initial Google authentication | | `select_notebook` | ❌ | ✅ | ✅ | Set active notebook | | `update_notebook` | ❌ | ✅ | ✅ | Update notebook metadata | | `search_notebooks` | ❌ | ✅ | ✅ | Search library by keywords | | `list_sessions` | ❌ | ✅ | ✅ | List active conversation sessions | | `get_health` | ❌ | ✅ | ✅ | Check auth status and config | | `remove_notebook` | ❌ | ❌ | ✅ | Remove notebook from library | | `re_auth` | ❌ | ❌ | ✅ | Switch Google account | | `cleanup_data` | ❌ | ❌ | ✅ | Clear browser data and sessions | | `get_browser_state` | ❌ | ❌ | ✅ | Manual browser state inspection | | `execute_browser_action` | ❌ | ❌ | ✅ | Manual browser control | | `wait_for_element` | ❌ | ❌ | ✅ | Manual browser element waiting | ### Authentication **Important**: NotebookLM MCP uses isolated Chrome profile, separate from your main browser session. ```bash # In Claude Code, first-time setup: "Log me in to NotebookLM" # Browser opens automatically for Google authentication # Select your Google account (pro tip: use authuser=1 for secondary accounts) # Session persists in: ~/Library/Application Support/notebooklm-mcp/ ``` **Multi-account setup**: If you have multiple Google accounts and want to use a specific one: 1. **Pre-configure in browser**: Open `https://notebooklm.google.com/?authuser=1` (change number for different accounts) 2. Sign in with desired account 3. **Then** run authentication in Claude Code The MCP stores credentials in an isolated Chrome profile, so your main browser cookies don't affect it. **Verify authentication**: ```bash "Check NotebookLM health status" # Expected output after successful auth: # { # "authenticated": true, # "account": "your-email@gmail.com", # "notebooks": # } ``` ### Building Your Notebook Library Unlike the web UI, the MCP works with **share links** rather than auto-syncing all notebooks. **Add a notebook**: ```bash # 1. In NotebookLM web UI: # - Open notebook # - Click "Share" → "Anyone with the link" # - Copy share URL # 2. In Claude Code: "Add notebook: https://notebooklm.google.com/notebook/abc123... Name: LLM Engineer Handbook Description: Comprehensive guide on LLM engineering practices Topics: LLM, fine-tuning, RAG, deployment" # Minimal metadata required - the MCP will analyze content automatically ``` **List your library**: ```bash "List my NotebookLM notebooks" # Shows all added notebooks with topics, use cases, last used ``` **Search library**: ```bash "Search NotebookLM library for: React patterns" # Returns relevant notebooks based on name, description, topics ``` ### Querying Notebooks **Direct query** (specify notebook): ```bash "In LLM Engineer Handbook, how do I implement RAG with embeddings?" # Claude will: # 1. Select the specified notebook # 2. Query NotebookLM with your question # 3. Return answer with precise citations # 4. Maintain session_id for follow-up questions ``` **Contextual conversation**: ```bash # First question "In Building Large-Scale Web Apps notebook, what are the caching strategies?" # Follow-up (uses same session_id) "How would that apply to a Next.js application?" # Another follow-up "What about Redis vs in-memory cache trade-offs?" # Session context is maintained across all queries ``` **Select active notebook**: ```bash "Select LLM Engineer Handbook as active notebook" # Now you can ask without specifying notebook each time "What are the fine-tuning techniques?" "How does DPO compare to RLHF?" ``` ### Advanced Workflows **Multi-notebook research**: ```bash # Compare insights across notebooks "What does LLM Engineer Handbook say about embeddings?" "Now check Playwright Automation guide for testing strategies" "How can I combine these approaches?" ``` **Update notebook metadata**: ```bash # As you use notebooks, refine their metadata "Update LLM Engineer Handbook: - Add topic: prompt engineering - Add use case: When designing LLM architectures" # This helps Claude auto-select the right notebook for future queries ``` **Session management**: ```bash "List active NotebookLM sessions" # Shows all conversation sessions with message counts, age # Useful to resume previous research threads ``` ### Comparison: MCP vs Web UI | Feature | MCP Integration | Web UI | |---------|----------------|--------| | Access from Claude Code | ✅ Direct | ❌ Manual copy-paste | | Conversation context | ✅ Persistent session_id | ⚠️ Web chat only | | Multi-notebook queries | ✅ Switch seamlessly | ⚠️ Manual navigation | | Audio generation | ❌ Use web UI | ✅ Native | | Share notebooks | ✅ Via library | ✅ Native | | Query speed | ✅ Instant | ⚠️ Browser navigation | **Best practice**: Use **MCP for queries** during development, **web UI for audio generation** during onboarding. ### Troubleshooting | Issue | Solution | |-------|----------| | `notebooklm: not connected` | Run `source ~/.zshrc` (or restart terminal), then restart Claude Code | | Empty notebook list after auth | You're authenticated but haven't added notebooks yet - use share links workflow | | Wrong Google account | Clear auth: delete `~/Library/Application Support/notebooklm-mcp/chrome_profile/`, re-authenticate | | "Tool not found" | Check `NOTEBOOKLM_PROFILE` variable is set correctly | | Rate limit errors | Wait 24h or re-authenticate with different Google account | **Check MCP configuration**: ```bash # View your .claude.json MCP config cat ~/.claude.json | jq '.mcpServers.notebooklm' # Should show: # { # "type": "stdio", # "command": "npx", # "args": ["notebooklm-mcp@latest"], # "env": {} # } ``` ### Example: Onboarding Workflow ```bash # Day 1: Setup "Log me in to NotebookLM" "Add notebook: - Codebase Architecture" "Add notebook: - API Documentation" # Day 2: Research "In Codebase Architecture, what's the auth flow?" "How does that integrate with the API docs?" "Select API Documentation notebook" "What are the rate limiting strategies?" # Week 2: Advanced "Search library for: database patterns" "In Database Patterns notebook, explain connection pooling" "How would I implement this in our codebase?" ``` --- ## 4.2 Advanced Features (Full Profile) **When to use `full` profile**: - Need to switch Google accounts frequently (`re_auth`) - Want to clean up MCP data without manual file deletion (`cleanup_data`) - Need to remove notebooks from library (`remove_notebook`) - Advanced debugging requiring manual browser control **Enable full profile**: ```bash # Add to ~/.zshrc or ~/.bashrc export NOTEBOOKLM_PROFILE=full # Restart Claude Code ``` ### Remove Notebook from Library ```bash "Remove notebook: LLM Engineer Handbook" # Or by ID: "Remove notebook with ID: llm-engineer-handbook" ``` **Use case**: Declutter library, remove outdated notebooks, fix duplicate entries. ### Re-authentication (Account Switching) **Scenario**: You want to switch from personal Google account to work account. ```bash "Re-authenticate NotebookLM with different account" # Browser opens, select different Google account # New credentials saved, old session cleared ``` **Difference vs `setup_auth`**: - `setup_auth`: First-time authentication - `re_auth`: Switch accounts (clears existing session) **Important**: After re-auth, your notebook library is **preserved** (stored locally), but you'll need to verify access to notebooks (they must be shared with new account). ### Cleanup Data **Scenario**: Start fresh, clear all MCP data (auth, library, browser profile). ```bash "Clean up NotebookLM MCP data" # Options: # - preserve_library: Keep notebook metadata (default: false) # - confirm: Safety confirmation (default: false) ``` **What gets deleted**: - Browser profile (`~/Library/Application Support/notebooklm-mcp/chrome_profile/`) - Authentication cookies - Active sessions - Notebook library (unless `preserve_library=true`) **When to use**: - Authentication issues not resolved by re-auth - Browser conflicts or corruption - Starting fresh after testing - Before uninstalling MCP **Example**: ```bash "Clean NotebookLM data but keep my library" # → cleanup_data(preserve_library=true, confirm=true) "Completely reset NotebookLM MCP" # → cleanup_data(preserve_library=false, confirm=true) ``` ### Manual Browser Control **Advanced debugging tools** (full profile only): **1. Get browser state**: ```bash "Show NotebookLM browser state" # Returns: current_url, cookies, local_storage, session_storage ``` **2. Execute browser action**: ```bash "Navigate NotebookLM browser to specific notebook URL" "Click element in NotebookLM browser" "Type text in NotebookLM browser" ``` **3. Wait for element**: ```bash "Wait for element to load in NotebookLM browser" ``` **Use case**: Debugging authentication issues, inspecting browser state during failures, manual notebook navigation. --- ## 4.3 Browser Options (All Profiles) Control browser behavior for queries and authentication. ### Available Options ```javascript { // Visibility "headless": true, // Run without visible window (default: true) "show": false, // Show browser window (default: false) // Performance "timeout_ms": 30000, // Operation timeout (default: 30000) // Viewport "viewport": { "width": 1920, // Default: 1920 "height": 1080 // Default: 1080 }, // Stealth mode (human-like behavior) "stealth": { "enabled": true, // Master switch (default: true) "human_typing": true, // Simulate typing speed (default: true) "random_delays": true, // Random pauses (default: true) "mouse_movements": true, // Realistic mouse moves (default: true) "typing_wpm_min": 160, // Min typing speed (default: 160) "typing_wpm_max": 240, // Max typing speed (default: 240) "delay_min_ms": 100, // Min delay between actions (default: 100) "delay_max_ms": 400 // Max delay between actions (default: 400) } } ``` ### Usage Examples **Debug authentication visually**: ```bash "Log me in to NotebookLM with visible browser" # Claude calls: setup_auth(show_browser=true) ``` **Custom timeout for slow connections**: ```bash "Ask NotebookLM (with 60s timeout): What are the main concepts?" # Claude calls: ask_question(timeout_ms=60000, ...) ``` **Disable stealth for faster queries** (if rate limits not a concern): ```bash # Advanced: requires direct tool call (not natural language) ask_question( question="...", browser_options={ "stealth": {"enabled": false}, "timeout_ms": 10000 } ) ``` **When to customize**: - **Show browser**: Debugging auth issues, verifying account selection - **Increase timeout**: Slow network, large notebooks, complex queries - **Disable stealth**: Local testing, debugging, speed priority - **Custom viewport**: Testing responsive notebook UI (rare) --- ## 4.4 Session Management NotebookLM MCP maintains conversation context across queries via `session_id`. ### How Sessions Work ```bash # First query → Creates session "In LLM Engineer Handbook, what is RAG?" # → Returns session_id: "abc123" # Follow-up → Uses same session "How does it compare to fine-tuning?" # → Uses session_id: "abc123" automatically # Another notebook → New session "In Playwright Guide, how do I test?" # → New session_id: "xyz789" ``` **Session properties**: - **Automatic**: Claude manages session_id for follow-up questions - **Scoped**: One session per notebook per conversation - **Timeout**: 15 minutes of inactivity (configurable) - **Max sessions**: 10 concurrent (configurable) ### List Active Sessions ```bash "List my active NotebookLM sessions" # Returns: # - session_id # - notebook_name # - age_seconds # - message_count # - last_activity (timestamp) ``` **Use case**: Resume previous research threads, understand query history, debug context issues. ### Manual Session Control **Resume specific session**: ```bash "Continue NotebookLM session abc123 with question: What about embeddings?" # Claude calls: ask_question(session_id="abc123", question="...") ``` **Force new session** (ignore context): ```bash "Ask NotebookLM in fresh session: What is RAG?" # Claude omits session_id to create new session ``` **Session cleanup**: Sessions auto-expire after 15 minutes. Manual cleanup via `cleanup_data`. --- ## 4.5 Library Management Best Practices ### Organizing Notebooks **Naming conventions**: ```bash # Good: Descriptive, searchable "LLM Engineer Handbook" "Playwright Testing Guide" "Next.js Architecture Patterns" # Bad: Vague, unhelpful "Notebook 1" "My Docs" "Tech Stuff" ``` **Topics strategy**: ```bash # Specific, hierarchical topics: ["RAG", "embeddings", "vector databases", "LLM fine-tuning"] # Too broad topics: ["AI", "programming"] ``` **Use cases** (helps Claude auto-select): ```bash # Action-oriented use_cases: [ "When implementing RAG systems", "For fine-tuning LLM models", "To understand embeddings architecture" ] ``` ### Metadata Refinement Workflow After using a notebook, refine its metadata: ```bash # Initial add (minimal) "Add notebook: Name: TypeScript Guide Description: TypeScript best practices Topics: TypeScript, types" # After usage (refine) "Update TypeScript Guide: - Add topic: generics - Add topic: utility types - Add use case: When designing type-safe APIs - Add tag: advanced" ``` ### Search and Discovery **Keyword search**: ```bash "Search library for: React hooks" "Search library for: testing" "Search library for: architecture patterns" ``` **Smart selection** (Claude decides): ```bash "Which notebook should I consult about database design?" # Claude searches library, proposes best match "I need help with TypeScript generics" # Claude auto-selects TypeScript Guide if metadata matches ``` ### Notebook Lifecycle ```bash # 1. Add "Add notebook: - Name: X, Description: Y, Topics: Z" # 2. Use "In X notebook, ask: ..." # 3. Refine "Update X: Add topic: ..., Add use case: ..." # 4. Archive (full profile) "Remove notebook: X" # If outdated or duplicate ``` ### Cost **Free**: NotebookLM (including MCP integration) is free with Google account **Limits**: - Free tier: 100 notebooks, 50 sources per notebook, 500K words, 50 daily queries - Google AI Premium/Ultra: 5x higher limits --- ## 5. Voice-to-Text Tools (Wispr Flow, Superwhisper) **Philosophy**: "Vibe coding," dictate intent and let AI implement Voice input delivers ~4x typing speed (~150 WPM vs ~40 WPM) with richer context. You say more when you don't have to type it. ### Tool Comparison | Tool | Processing | Latency | Privacy | Price | Platform | |------|------------|---------|---------|-------|----------| | **Wispr Flow** | Cloud | ~500ms | SOC 2 certified | $12/mo | Mac, Win, iOS | | **Superwhisper** | Local | 1-2s | 100% offline | ~$50 one-time | Mac only | | **MacWhisper** | Local | Variable | 100% offline | $49 one-time | Mac only | ### When Voice + Claude Code Shines | Scenario | Why voice wins | |----------|---------------| | Long context dumps | You naturally include constraints, edge cases, business context | | Brainstorming | Less self-filtering, more raw ideas | | Multi-agent management | Dictate to 3-4 Claude sessions simultaneously | | Accessibility | RSI, mobility constraints, eye strain | ### Vibe Coding Workflow 1. Open Claude Code or Cursor 2. Activate voice (Wispr hotkey or system dictation) 3. Dictate naturally: "I need a component that shows user stats, it should have pagination because we have thousands of users, and sorting by name or signup date, use our existing Tailwind setup" 4. Let Claude process the verbose input 5. Iterate vocally: "Add loading state and error handling" ### Trade-offs | Advantage | Limitation | |-----------|------------| | ~4x faster input | ~3x more verbose output | | Richer context | Cloud privacy (Wispr) | | Flow state preserved | ~800MB RAM overhead | | Natural expression | Technical terms need training | ### Recommendation | Profile | Tool | |---------|------| | Productivity-first | Wispr Flow Pro ($12/mo) | | Privacy-required | Superwhisper (Mac) | | Budget-conscious | MacWhisper ($49 one-time) | | Windows user | Wait for Wispr stability improvements | **Pro tip**: For complex prompts, consider a "refine" step to compress verbose voice input into structured prompts before sending to Claude. See `/voice-refine` skill template in `examples/skills/`. --- ## 5.1 Text-to-Speech Tools (Agent Vibes) **Philosophy**: Audible narration frees your eyes for multitasking Text-to-speech adds audio narration to Claude Code responses, enabling: - **Code reviews while multitasking** (listen while reviewing diffs visually) - **Long debugging sessions** (audio notifications keep you informed) - **Accessibility** (visual impairment, eye strain, RSI) - **Background monitoring** (alerts for errors/completion) ### Tool: Agent Vibes (Community MCP Server) **Status**: Optional integration (not official Claude Code feature) **Cost**: 100% free (offline TTS) **Maintenance**: Community-driven (Paul Preibisch) | Feature | Value | |---------|-------| | **Provider** | Piper TTS (offline neural) + macOS Say (native) | | **Voices** | 15+ (12 English, 4 French including 124 multi-speakers) | | **Quality** | ⭐️⭐️⭐️⭐️ (Piper medium), ⭐️⭐️⭐️⭐️⭐️ (Piper high) | | **Latency** | ~280ms (Piper medium), ~50ms (macOS Say) | | **Disk Space** | ~1.3GB (Piper + voices + audio effects) | | **Installation** | ~18 minutes (5 phases, interactive) | ### When TTS Shines | Scenario | Benefit | |----------|---------| | Code reviews | Listen to Claude's analysis while viewing code | | Long-running tasks | Audio notification when tests/builds complete | | Debugging sessions | Error alerts without constant screen checking | | Learning mode | Dual-language narration (main + target language) | | Pair programming | One person codes, both hear Claude's feedback | ### Trade-offs | Advantage | Limitation | |-----------|------------| | 100% offline | No cloud-quality voices (vs ElevenLabs) | | Zero cost | ~280ms latency (vs instant macOS Say) | | Multi-language (50+) | ~1GB disk space for voice models | | 124 voice variety | Installation requires Homebrew, Bash 5.x | ### Quick Start **Installation**: [TTS Setup Workflow](../workflows/tts-setup.md) (18 min) **Basic usage**: ```bash # In Claude Code /agent-vibes:whoami # Check current voice & provider /agent-vibes:list # List all 15 voices /agent-vibes:switch fr_FR-tom-medium # French male voice # Test > "Say hello in French" # Audio narration plays ``` **Mute temporarily**: ```bash /agent-vibes:mute # Silent work # ... focus time ... /agent-vibes:unmute # Re-enable ``` ### Recommendation | Profile | Setup | |---------|-------| | **Code reviewer** | ✅ Install with `fr_FR-tom-medium`, `verbosity: low` | | **Focus worker** | ⚠️ Install but mute by default, unmute for notifications | | **Battery-conscious** | Use macOS Say provider (instant, lower quality) | | **Public workspace** | ❌ Skip TTS (audio distraction to others) | ### Complete Documentation - **[Agent Vibes Integration Guide](../../examples/integrations/agent-vibes/README.md)** - Overview, commands, use cases - **[Installation Guide](../../examples/integrations/agent-vibes/installation.md)** - 18-minute setup procedure - **[Voice Catalog](../../examples/integrations/agent-vibes/voice-catalog.md)** - 15 voices with audio samples - **[Troubleshooting](../../examples/integrations/agent-vibes/troubleshooting.md)** - Common issues & solutions **Resources**: - GitHub: https://github.com/paulpreibisch/AgentVibes - Voice Samples: https://rhasspy.github.io/piper-samples/ --- ## 6. IDE, ADE, and Hybrid Coding Environments > **Technical Comparison**: For an objective comparison of Claude Code vs 22+ alternatives across 11 criteria (MCP support, Skills, Commands, Subagents, Plan Mode), see the [AI Coding Agents Matrix](https://coding-agents-matrix.dev/) (updated Jan 2026). Product labels are no longer reliable boundaries. An agentic development environment, or ADE, may combine an IDE, a standalone CLI, a desktop client, chat entry points, and cloud execution. Cursor, Kiro, Claude Code, Devin Desktop, and Warp Agent span more than one of those surfaces. Compare three independent questions before choosing a product: 1. **Interface**: CLI, TUI, IDE, desktop, web, or chat. 2. **Execution**: local, remote, or hybrid. 3. **Loop ownership**: does this product plan, act through tools, observe results, and decide the next step, or does it only host or coordinate another runtime? The [Agent Harness Landscape](./agent-harness-landscape.md#interface-execution-and-loop-ownership-are-separate) applies this taxonomy across the sourced catalog. The deeper [Warp Agent CLI profile](./agentic-tools.md#19-warp-agent-cli) shows why a product commonly described as an ADE may also belong in a terminal-agent comparison. ### Choose the Interface by Workflow | Need | Interface to test first | Examples, not rankings | |---|---|---| | Inline completion and edits beside code | IDE | Cursor, Cline, Devin Desktop | | Shell-heavy work and reproducible commands | CLI | Claude Code, Codex CLI, Warp Agent | | Interactive debuggers or full-screen terminal programs | TUI-capable CLI | Warp Agent, opencode, crush | | Asynchronous work and remote monitoring | Web | Jules, Devin, cloud-agent surfaces | | A dedicated native workspace | Desktop | Claude Code desktop, Devin Desktop, Kiro | | Start work from team communication or an issue | Chat | Products with Slack, Discord, or tracker entry points | An interface match is only a shortlist. Permission controls, repository isolation, execution location, recovery, model access, and accepted-task cost still require a representative trial. ### Hybrid Workflow **Morning session (strategic)**: ```bash claude "Review the auth module and suggest improvements" # Claude analyzes, suggests multi-file refactoring plan ``` **During coding (tactical)**: ``` # In Cursor/VS Code with Copilot # Quick autocomplete, inline suggestions # Small function implementations ``` **Before commit (validation)**: ```bash claude "Review my changes and suggest tests" # Claude reviews diff, generates comprehensive tests ``` ### Real-World Migration Path: Cursor → Windsurf → Claude Code > **Source**: [Zadig&Voltaire Engineering Blog](https://tech.zadig-et-voltaire.com/blog/migration-nuxt/), Benjamin Calef, Feb 2026 This is a dated adoption history, so the original product name is preserved. Windsurf was subsequently renamed [Devin Desktop](https://devin.ai/desktop); the name change does not alter what the team reported for 2025. A 6-person team at Zadig&Voltaire documented their sequential tool adoption during a 6-month e-commerce rebuild (July 2025 – January 2026): | Phase | Tool | Observation | |-------|------|-------------| | July 2025 | Cursor | Co-building workflow, inline suggestions | | Aug 2025 | Windsurf | Similar paradigm, slightly different UX | | Aug 2025 | **Claude Code** | Contextual understanding of entire codebase, pivot moment | | Nov 2025 | Claude Opus 4.5 | Model comprehension leap, reliable code generation | The team reported the pivot to Claude Code was driven by **codebase-level context** rather than file-level editing. They then integrated custom skills (`zv-commit`, `zv-code-review`, `zv-jira`, `zv-jira-qa`) and community skills from [skills.sh](https://skills.sh/) to standardize their workflows. **Caveat**: Performance gains reported (-33% LOC, -63% LCP) are primarily attributable to the Nuxt 3 migration itself, not the AI tooling. The tool migration path is the transferable insight. ### Cursor-Specific Integration Cursor's `.cursor/rules` can mirror your CLAUDE.md: ```markdown # .cursor/rules # Mirror from CLAUDE.md for consistency ## Conventions - Use TypeScript strict mode - Prefer named exports - Test files: *.test.ts ## Patterns - Services use dependency injection - Components use render props for flexibility ``` ### Multi-IDE Configuration Sync When your team uses multiple AI coding tools (Claude Code + Cursor + Copilot), maintaining consistent conventions across all tools becomes a challenge. #### The Problem | Tool | Config File | Format | |------|-------------|--------| | Claude Code | `CLAUDE.md` | Markdown + @imports | | Cursor | `.cursorrules` | Plain markdown | | Codex/ChatGPT | `AGENTS.md` | AGENTS.md standard | | Copilot | `.github/copilot-instructions.md` | GitHub-specific | **Without sync**: Each file drifts independently, producing inconsistent AI behavior across tools. #### Solution 1: Native @import (Recommended for Claude Code) Claude Code supports `@path/to/file.md` imports natively: ```markdown # CLAUDE.md @docs/conventions/coding-standards.md @docs/conventions/architecture.md ``` **Pros**: Native, no build step, maintained by Anthropic **Cons**: Cursor/.cursorrules doesn't support @import #### Solution 2: Script-Based Generation (Multi-IDE Teams) For teams needing **identical conventions across all IDEs**: ``` docs/ai-instructions/ # Source of truth ├── core.md # Shared conventions ├── claude-specific.md # Claude Code additions ├── cursor-specific.md # Cursor additions └── codex-specific.md # AGENTS.md additions ↓ sync script (bash/node) CLAUDE.md = core + claude-specific .cursorrules = core + cursor-specific AGENTS.md = core + codex-specific ``` **Example sync script** (bash): ```bash #!/bin/bash CORE="docs/ai-instructions/core.md" cat "$CORE" > CLAUDE.md echo -e "\n---\n" >> CLAUDE.md cat "docs/ai-instructions/claude-specific.md" >> CLAUDE.md cat "$CORE" > .cursorrules echo -e "\n---\n" >> .cursorrules cat "docs/ai-instructions/cursor-specific.md" >> .cursorrules ``` **When to use this approach**: - Team with mixed IDE preferences (Claude Code + Cursor + VS Code) - Need to enforce identical conventions across all tools - CI/CD validation of AI instructions #### ⚠️ AGENTS.md Support Status **Claude Code does NOT natively support AGENTS.md** ([GitHub issue #6235](https://github.com/anthropics/claude-code/issues/6235), 171 comments, still open as of Feb 2026). **Workaround**: Symlink `ln -s AGENTS.md .claude/CLAUDE.md` The AGENTS.md standard is supported by several coding tools. Because support changes by product and version, verify the current compatibility in the [AI Coding Agents Matrix](https://coding-agents-matrix.dev) before consolidating instruction files. ### Export from IDE to Claude When you need Claude's deeper analysis: 1. Select code in IDE 2. Copy with context (file path, line numbers) 3. Paste in Claude with: "Analyze this and suggest architectural improvements" --- ## 6.1 Google Antigravity (Agent-First IDE) > **Source**: [Google Codelabs](https://codelabs.developers.google.com/getting-started-google-antigravity), [Google Cloud Blog](https://cloud.google.com/blog/topics/developers-practitioners/choosing-antigravity-or-gemini-cli), community reviews (Feb 2026) Google Antigravity is an **agent-first IDE** (VS Code fork) launched late 2025. Unlike traditional IDE tools that add AI to an editor, Antigravity makes autonomous agents the primary interface. Developers supervise through a mission control-style UI rather than writing code directly. ### Claude Code vs Antigravity: Two Philosophies | Dimension | Claude Code | Google Antigravity | |-----------|-------------|-------------------| | **Paradigm** | Terminal-first, CLI-native | Agent-first, IDE-native | | **Developer control** | Explicit approval per edit | Higher agent autonomy | | **Context model** | Codebase-level via CLAUDE.md | Multi-surface (editor + browser + terminal) | | **Multi-agent** | Agent Teams (v2.1+) | Built-in multi-agent orchestration | | **CI/CD** | Native (headless, pipelines) | Not mature yet | | **Risk profile** | Predictable, conservative | Higher autonomy = higher overstep risk | | **Skills format** | `.claude/skills/` (YAML frontmatter) | Directory-based, different ecosystem | | **Models** | Claude (Anthropic) | Multi-model (Gemini, Claude, Liquid AI) | ### Bridge: antigravity-claude-proxy A community [npm package](https://www.npmjs.com/package/antigravity-claude-proxy) exposes an Anthropic-compatible API backed by Antigravity's Cloud Code service. This lets developers use Claude models through Antigravity's interface, or chain both tools in a single workflow. ### When to Consider Antigravity | Scenario | Recommendation | |----------|---------------| | Rapid prototyping ("vibe coding") | Antigravity (higher autonomy, visual feedback) | | Production code with CI/CD | Claude Code (predictable, headless, pipeline-native) | | Multi-model experimentation | Antigravity (~150 models via OpenRouter) | | Team standardization | Claude Code (CLAUDE.md, skills, hooks ecosystem) | | Non-CLI developers | Antigravity (IDE-native, less terminal friction) | ### Trade-offs to Know **Antigravity strengths**: Broader visual context (agents "see" browser + editor), parallel agent orchestration, lower barrier for non-CLI developers. **Antigravity weaknesses**: Higher cognitive overhead (monitoring multiple agents), less predictable behavior, CI/CD not mature, destructive operations risk when agents act autonomously. **Bottom line**: Claude Code optimizes for **predictability and integration with existing developer workflows**. Antigravity optimizes for **maximum agent autonomy with experimental trade-offs**. They serve different philosophies. Choose based on your risk tolerance and workflow preferences. --- ## 7. UI Prototypers (v0, Bolt, Lovable) ### When to Use Prototypers | Scenario | Use Prototyper | Use Claude Code | |----------|---------------|-----------------| | "Build a landing page" | ✅ v0 (visual) | ⚠️ No preview | | "Add form to existing app" | ⚠️ Context needed | ✅ Has context | | "Rapid UI iteration" | ✅ Live preview | ⚠️ Slower | | "Match design system" | ⚠️ Generic | ✅ Reads your tokens | ### Tool Comparison | Tool | Strengths | Stack | Best For | |------|-----------|-------|----------| | **v0.dev** | Shadcn/Tailwind | React | Component prototypes | | **Bolt.new** | Full app scaffold | Various | Quick MVPs | | **Lovable** | Design-to-code | React | Designer handoff | | **WebSim** | Experimental UI | Web | Creative exploration | ### Integration Workflow #### Pattern: Prototype → Production ``` ┌─────────────────────────────────────────────────────────┐ │ 1. V0.DEV │ │ Prompt: "A user profile card with avatar, │ │ stats, and action buttons" │ │ │ │ → Output: React + Shadcn component preview │ │ → Export: Copy code │ └───────────────────────────┬─────────────────────────────┘ ↓ Paste to clipboard ┌─────────────────────────────────────────────────────────┐ │ 2. CLAUDE CODE │ │ "Adapt this v0 component for our Next.js app: │ │ - Use our existing Button, Avatar components │ │ - Add TypeScript types matching User interface │ │ - Connect to getUserProfile API endpoint │ │ - Add loading and error states" │ │ │ │ → Output: Production-ready integrated component │ └─────────────────────────────────────────────────────────┘ ``` --- ## 7.1 Generative UI: Agent-Driven Interactive Output Formats ### Why This Category Exists UI prototypers (Section 7) generate a static app you paste into a codebase. A different problem is showing up in 2025-2026: an agent that needs to render an actual form, an approval gate, or a button *inside a single chat turn*, not as a separate artifact. Plain text can't collect structured input. A static screenshot can't dispatch an action. The response itself needs to be interactive, and it needs to come from a model call, often a small or fine-tuned one, not from a human writing JSX. Four approaches are competing to solve this, with genuinely different assumptions about who renders the output and what the model has to produce. | Approach | Vendor | What the model produces | Rendering | Portability | |----------|--------|--------------------------|-----------|-------------| | **A2UI** | Google | Structured UI description | Google ecosystem clients | Concept popularized by Google, not an independent standard | | **MCP Apps** (SEP-1865) | Anthropic + OpenAI + MCP-UI (co-authored) | HTML/iframe payload via MCP tool response | Claude Desktop, VS Code, ChatGPT, Goose | Open protocol extension, multi-vendor from day one | | **Vercel AI SDK generative UI** | Vercel | JSX / React components, streamed server-side (`streamUI`, `useObject`) | React only | Tied to the Vercel AI SDK and React | | **MDMA** | MobileReality (open-source) | Markdown with embedded YAML, validated against a Zod schema | `@mobile-reality/mdma-renderer-react` (React only, as of this writing) | Spec/parser/validator/runtime packages have zero Node-specific imports, run in any JS runtime; the renderer itself doesn't | These solve adjacent but distinct problems. MCP Apps is about a tool response carrying a UI. The Vercel AI SDK pattern is about the server choosing and streaming React components directly, so the client never parses an intermediate format. MDMA inverts that: the model produces validated YAML, and a client-side renderer interprets it, which trades some rendering flexibility for a format that's easier for a small or resource-constrained model to produce correctly. A third adjacent category is MCP Apps itself, already covered separately in this guide (`guide/core/architecture.md`, MCP Extensions section) since it's a protocol-level concern, not a rendering-format concern. ### Case Study: MDMA [MDMA](https://github.com/MobileReality/mdma) is an open-source project built around one core idea: producing a syntactically valid, schema-conformant YAML block is a lower bar for a small LLM (their target is models like Gemini Flash, and they fine-tuned their own 26B model) than producing correct JSX or hand-written HTML. The engineering behind that idea holds up under audit. The marketing claims layered on top of it mostly don't. **What holds up**: - A real deterministic validator/fixer pipeline: one pass, no extra LLM call, regex-based extraction tolerant of broken markdown, 19 validation rules, ordered fixers (field-type inference, YAML key typo correction, binding repair). - Standard parsing via remark/unified, with correct handling of streaming state (a plugin distinguishes a block still being generated from one that's actually malformed). - Honest, measured evals using promptfoo with custom assertions, explicitly framed in their own docs as "observations, not conclusions." The headline number: 41% success rate with a bare prompt versus 90.5% with the DSL plus validator, on their fine-tuned model (`evals/own-model/README.md`). - "Runs anywhere" is true for the core packages (spec, parser, validator, runtime): zero Node-specific imports (`fs`, `path`, `crypto`), verified by direct grep across those four packages. - CI with GitHub Actions pinned by commit SHA (a rare, good practice), changesets-based per-package versioning, and a real test suite (`turbo run test` across all packages, confirmed in `package.json`). **What's overstated or misleading**: - The implicit claim of guaranteed valid UI doesn't hold at the strict sense: 90.5% measured, not 100%. There's an unresolved contradiction in the repo itself: `evals/own-model/results.json` (`evals/own-model/results.json`) shows a 95/95 pass, 100%, run on 2026-06-30, while the README states 90.5% for the same eval track. Nothing in the repo reconciles the two numbers. - "Runs anywhere" doesn't extend to rendering. Exactly one renderer ships, `@mobile-reality/mdma-renderer-react`, 100% React. The default chart component isn't a chart: `ChartRenderer.tsx` parses CSV and renders an HTML ``, with a code comment admitting as much ("Renders chart data as a simple HTML table," `packages/renderer-react/src/components/ChartRenderer.tsx`). - Webhooks aren't wired to anything. `WebhookRenderer.tsx` dispatches a UI event, `INTEGRATION_CALLED`, that the host application has to handle itself (`packages/renderer-react/src/components/WebhookRenderer.tsx`). No HTTP call happens inside MDMA. To the project's credit, the corresponding webhook execution engine is listed as not-yet-built in their own roadmap docs, unlike the form validation gap below. - "On-device / small models" describes the size of the *generator* model (hosted on Modal, distributed via Hugging Face), not anything about the rendered output. The renderer's CSS ships with zero `@media` queries (confirmed by grepping every `.css` file in the React renderer package), so there's no responsive design story here either. - The demo site's "accessible by design" claim isn't backed by the code. The basics are there (native labels, native buttons, one `role="alert"` on the callout component), but there's no `aria-invalid` or `aria-live` anywhere in the renderer, and the PII-masking table cell is a clickable `` with no `role="button"` and no `tabIndex`, meaning keyboard users can't reveal or hide it (`packages/renderer-react/src/components/TableRenderer.tsx`, lines 4-15). **The functional bug two independent audits both found**: form validation is never enforced. `FormRenderer.tsx` wraps fields in a plain `
`, not a `
` element, and the submit control is `