{"owner":"enricoros","repo":"big-AGI","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nGuidance to Claude Code when working with code in this repository.\n\n\n## Architecture Overview\n\nBig-AGI is a Next.js 15 application with a sophisticated modular architecture built for professional AI interactions.\n\n### Development Commands\n\nDev servers may be already running on ports 3000, 3001, 3002, or 3003 (not always this app - other projects may occupy these ports). Never start or stop dev servers, let the user do it.\n\n```bash\n# Validate (~5s, safe while dev server runs, do NOT use `next build` ~45s for same checks)\ntsc --noEmit --pretty && npm run lint # Type check (~3.5s) + ESLint (~2s)\neslint src/path/to/file.ts           # Lint specific file\n\n# Full build (~60s+, only when suspecting runtime/bundle issues)\nnpm run build  # next build runs compile+lint+types but stops at first type-error file; tsc shows all at once\n\n# Database & External Services\n# npm run supabase:local-update-types   # Generate TypeScript types\n# npm run stripe:listen                 # Listen for Stripe webhooks\n```\n\nFor AI protocol development (model listing, live API requests/responses, parameter probing), real vendor API keys are in `.env.api-keys` if present (Anthropic, OpenAI, Gemini, etc., one VENDOR_API_KEY per line). Use them for empirical verification; never commit or echo the values.\n\n### Git/GitHub remotes\n\nThe `gh` command is available to interact with GitHub from the terminal, but **NEVER PUSH TO ANY BRANCH**. The user manages all 'write' git operations.\n- `opensource` -> `enricoros/big-AGI` (public, default branch: `main`, MIT) - community issues/PRs/releases\n- `private` -> `big-agi/big-agi-private` (private, default branch: `dev`) - main dev repo with `dev`->`staging`->`prod` pipeline\n- **Always use `git mv` instead of `mv`** when renaming or moving files - preserves git history tracking\n- **NEVER run `git stash`** - it causes work loss\n- **Commit subjects**: `Area: terse imperative` (e.g. `LLMs: OpenAI: ...`, `Build: ...`), single line, no body unless needed, and no `Co-Authored-By` trailer\n\n**Branch contents:**\n- `main` is the open-source build: local-first, BYO-keys, full AIX and provider coverage\n- `dev` extends `main` with the hosted/cloud layer: auth, Zync sync, Cloud Fabric, Stripe, multi-tenant, admin pages, it's the way to go for users, the best user experience of any multi-model chat application\n- Cloud/auth/sync code stays on `dev`; non-cloud improvements (UX, AIX, model support, bug fixes) can land on either branch\n\n**Branch workflow:**\n- `dev` is rebased on top of `main` (never merged) - `main` changes flow into `dev` on the next rebase, no manual forward-port needed\n- Never `git merge` between the two branches - breaks the linear topology\n- Backporting `dev` -> `main` is a re-implementation, never a cherry-pick - keep `main`-side edits minimal/additive so the existing `dev` version lands cleanly on rebase; split into small commits when natural\n- Rebasing `dev` onto `main`: work on a scratch branch (never `private/dev` directly); only files `main` changed since the merge-base can conflict - forecast with `git diff --name-only $(git merge-base private/dev opensource/main) opensource/main`\n- Resolve that rebase per-conflict: keep `dev` where it diverges, UNION where `main` only added (never blanket `-X theirs`/`-X ours` - they drop `main`'s additions). Check no `<<<<<<<` markers survive before each `--continue`\n\n### Core Directory Structure\n\nYou are started from the root of the repository (i.e. where the git folder is or scripts should be run from).\n**ISSUE ALL COMMANDS FROM THE ROOT, OMITTING 'cd' COMMANDS. DO NOT CHAIN CD AND OTHER COMMANDS**\n**NEVER RUN COMPOUND `cd` COMMANDS LIKE `cd some-folder && command` - ONLY RUN `command` FROM THE ROOT, ALWAYS.**\nThe directory structure is as follows:\n\n```\n/app/api/          # Next.js App Router (API routes only, mostly -> /src/server/)\n/pages/            # Next.js Pages Router (file-based, mostly -> /src/apps/)\n/src/\n├── apps/          # Feature applications (self-contained modules)\n├── modules/       # Reusable business logic and integrations\n├── common/        # Shared infrastructure and utilities\n└── server/        # Backend API layer with tRPC\n/kb/               # Knowledge base for modules, architectures\n```\n\n### Key Technologies\n\n- **Frontend**: Next.js 15, React 18, Material-UI Joy, Emotion (CSS-in-JS)\n- **State Management**: Zustand with localStorage/IndexedDB (single cell) persistence\n- **API Layer**: tRPC with TanStack React Query for type-safe communication\n- **Runtime**: Edge Runtime for AI operations, Node.js for data processing\n\n### \"Apps\" Architecture Pattern\n\nEach app in `/src/apps/` is a self-contained feature module:\n- Main component (`App*.tsx`)\n- Local state store (`store-app-*.ts`)\n- Feature-specific components and layouts\n- Runtime configurations\n\nExample apps: `chat/`, `call/`, `beam/`, `draw/`, `personas/`, `settings-modal/`\n\n### Modules Architecture Pattern\n\nModules in `/src/modules/` provide reusable business logic:\n- **`aix/`** - AI communication framework for real-time streaming\n- **`beam/`** - Multi-model AI reasoning system (scatter/gather pattern)\n- **`blocks/`** - Content rendering (markdown, code, images, etc.)\n- **`llms/`** - Language model abstraction supporting 20+ vendors\n\n### Key Subsystems & Their Patterns\n\n#### AIX - Real-time AI Communication\n**Location**: `/src/modules/aix/`\n**Pattern**: Client-server streaming architecture with provider abstraction\n\n- **Client** -> tRPC -> **Server** -> **AI Providers**\n- Handles streaming/non-streaming responses with batching and error recovery\n- Particle-based streaming: `AixWire_Particles` -> `ContentReassembler` -> `DMessage`\n- Provider-agnostic through adapter pattern (OpenAI, Anthropic, Gemini protocols)\n\n#### Beam - Multi-Model Reasoning\n**Location**: `/src/modules/beam/`\n**Pattern**: Scatter/Gather for parallel AI processing\n\n- **Scatter**: Multiple models (rays) process input in parallel\n- **Gather**: Fusion algorithms combine outputs\n- Real-time UI updates via vanilla Zustand stores\n- BeamStore per conversation via ConversationHandler\n\n#### Conversation Management\n**Location**: `/src/common/stores/chat/` and `/src/common/chat-overlay/`\n**Pattern**: Overlay architecture with handler per conversation\n\n- `ConversationHandler` orchestrates chat, beam, ephemerals\n- Per-chat stores: `PerChatOverlayStore` + `BeamStore`\n- Message structure: `DMessage` -> `DMessageFragment[]`\n- Supports multi-pane with independent conversation states\n\n#### Layout System (\"Optima\")\n\nThe Optima layout system provides:\n- **Responsive design** adapting desktop/mobile\n- **Drawer(left)/Toolbar/Panel(right)** composition\n- **Portal-based rendering** for flexible component placement\n\nLocated in `/src/common/layout/optima/`\n\n### Storage System\n\nBig-AGI uses a local-first architecture with Zustand + IndexedDB:\n- **Zustand** stores for in-memory state management\n- **localStorage** for persistent settings/all storage (via Zustand persist middleware)\n- **IndexedDB** for persistent chat-only storage (via Zustand persist middleware) on a single key-val cell\n- **Local-first** architecture with offline capability\n\nKey storage patterns:\n- Stores use `createIDBPersistStorage()` for IndexedDB persistence\n- Version-based migrations handle data structure changes\n- Partialize/merge functions control what gets persisted\n- Rehydration logic repairs and upgrades data on load\n\nLocated in `/src/common/stores/` with stores like:\n- `chat/store-chats.ts`: Conversations and messages\n- `llms/store-llms.ts`: Model configurations\n\n### State Management Patterns\n\n1. **Global Stores** (Zustand with IndexedDB persistence)\n   - `store-chats`: Conversations and messages\n   - `store-llms`: Model configurations\n   - `store-ux-labs`: UI preferences and labs features\n   - **Zustand pattern**: Always wrap multi-property selectors with `useShallow` from `zustand/react/shallow` to prevent re-renders on reference changes\n\n2. **Per-Instance Stores** (Vanilla Zustand)\n   - `store-beam_vanilla`: Beam scatter/gather state\n   - `store-perchat_vanilla`: Chat overlay state\n   - `store-attachment-drafts_vanilla`: Attachment drafts\n   - High-performance, no React integration\n\n3. **Module Stores**\n   - Feature-specific configuration and state\n   - Example: `store-module-beam`, `store-module-t2i`\n\n### User Flows & Interdependencies\n\n#### Chat Message Flow\n1. User input -> `Composer` -> `DMessage` creation\n2. `ConversationHandler.messageAppend()` -> Store update\n3. `_handleExecute()` / `ConversationHandler.executeChatMessages()` -> AIX client request\n4. AIX streaming -> `ContentReassembler` -> UI updates\n5. Zustand auto-persistence -> IndexedDB\n\n#### Beam Multi-Model Flow\n1. User triggers Beam -> `BeamStore.open()` state update\n2. Scatter: Parallel `aixChatGenerateContent()` to N models\n3. Real-time ray updates -> UI progress\n4. Gather: User selects fusion -> Combined output\n5. Result -> New message in conversation\n\n### Development Patterns\n\n#### TypeScript & Code Quality\n- Type-safe through strict TypeScript interfaces\n- Clear interface-first approach for modules and components\n- Use latest TypeScript 5.9+ features\n- Use forward-looking patterns to minimize future refactors (e.g., discriminated unions, `satisfies` operator, as const assertions)\n- Type guards and exhaustiveChecks for robustness\n- Type inference where possible\n- No unnecessary TS casts: prefer narrowing/inference; only `as` when the compiler genuinely can't know the type\n- Runtime validation with Zod schemas for API inputs/outputs (usually server-side, with the client importing as types the inferred types)\n\n#### Module Integration\n- Modules register with central registries (e.g., `vendors.registry.ts`)\n- Configuration objects define module behavior\n\n#### UI & Icons\n- Prefer `@mui/icons-material` icons/variants already imported elsewhere in the app over new ones (keeps the bundle lean); new icons only when depicting genuinely novel functionality\n\n#### API Patterns\n- **tRPC routers** for type-safe API endpoints\n- **Zod schemas** for runtime validation\n- **tRPC procedures middleware** for authorization and logging (authorization is on a httpOnly cookie)\n- **Edge functions** for performance-critical operations\n\n#### Security Considerations\n- API keys in environment variables only (server-side); on the client they're in localStorage for now, but we want to move away from this\n- XSS protection through proper content escaping\n\n#### Writing Style\n- **Never use emdashes (—).** Use normal dashes (-) instead, in all generated text, code comments, and documentation.\n- Register: sharp, terse, precise - in all prose (docs, UI copy, comments, commits, replies). No inflation, no sales tone, no clever headings (plain nouns). Cut sentences that carry no information.\n\n\n## Common Development Tasks\n\n### Testing & Quality\n- Run `npm run lint` before committing\n- Type-check with `tsc --noEmit`\n- Test critical user flows manually\n- Browser floor is lint-enforced: `no-restricted-syntax` bans ES2023 `toSorted/toReversed/toSpliced/with` + unguarded `Intl.Segmenter` (they crash Chrome 109 / Win7 holdouts). Use `[...x].sort()` etc.; don't lower `browserslist` to \"fix\" it - SWC won't polyfill prototype methods\n\n### Debugging Storage Issues\n- Check IndexedDB: DevTools -> Application -> IndexedDB -> `app-chats`\n- Monitor Zustand state: Use Zustand DevTools\n- Check migration logs in console during rehydration\n\n### Production errors (app.big-agi.com)\n- That host is the deployed build - triage runtime errors via the PostHog MCP (filter `url: app.big-agi.com`). Client noise filter (`before_send` / `shouldSuppressPostHogCapture`, matched on `$exception_list`) lives in `src/common/components/3rdparty/PostHogAnalytics.tsx`; `mechanism.handled:false` = an unhandled rejection via autocapture. Suppress only environmental/extension noise, never real bugs\n\n\n## Server Architecture\n\nThe server uses a split architecture with two tRPC routers:\n\n### Edge Network (`trpc.router-edge`)\nDistributed edge runtime for low-latency AI operations:\n- **AIX** [1] - AI streaming and communication\n- **LLM Routers** [1] - Vendor-specific operations such as list models (OpenAI, Anthropic, Gemini, Ollama)\n- **Speex** [1] - Unified TTS router (ElevenLabs, Inworld, and other TTS vendors)\n- **External Services** - Google Search, YouTube transcripts\n\n[1]: also supports client-side fetch (CSF) via client-side inclusion (rebundling with stubs),\nfor direct browser-to-API communication when possible (CORS), to reduce latency and network barriers\n\nLocated at `/src/server/trpc/trpc.router-edge.ts`\n\n### Cloud Network (`trpc.router-cloud`)\nCentralized server for data processing operations:\n- **Browse** - Web scraping and content extraction\n- **Trade** - Import/export functionality (ChatGPT, markdown, JSON)\n\nLocated at `/src/server/trpc/trpc.router-cloud.ts`\n\n**Key Pattern**: Edge runtime for AI (fast, distributed), Cloud runtime for data ops (centralized, Node.js)\n\n@kb/KB.md\n\n@kb/vision-inlined.md\n\nAs a side note, the product tiers (independent, non-VC-funded) are: **Open** (self-host, MIT) · **Free** (big-agi.com) · **Pro** (paid, includes Sync + backup). All tiers use the user's own API keys.\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nGuidance to Claude Code when working with code in this repository.\n\n\n## Architecture Overview\n\nBig-AGI is a Next.js 15 application with a sophisticated modular architecture built for professional AI interactions.\n\n### Development Commands\n\nDev servers may be already running on ports 3000, 3001, 3002, or 3003 (not always this app - other projects may occupy these ports). Never start or stop dev servers, let the user do it.\n\n```bash\n# Validate (~5s, safe while dev server runs, do NOT use `next build` ~45s for same checks)\ntsc --noEmit --pretty && npm run lint # Type check (~3.5s) + ESLint (~2s)\neslint src/path/to/file.ts           # Lint specific file\n\n# Full build (~60s+, only when suspecting runtime/bundle issues)\nnpm run build  # next build runs compile+lint+types but stops at first type-error file; tsc shows all at once\n\n# Database & External Services\n# npm run supabase:local-update-types   # Generate TypeScript types\n# npm run stripe:listen                 # Listen for Stripe webhooks\n```\n\nFor AI protocol development (model listing, live API requests/responses, parameter probing), real vendor API keys are in `.env.api-keys` if present (Anthropic, OpenAI, Gemini, etc., one VENDOR_API_KEY per line). Use them for empirical verification; never commit or echo the values.\n\n### Git/GitHub remotes\n\nThe `gh` command is available to interact with GitHub from the terminal, but **NEVER PUSH TO ANY BRANCH**. The user manages all 'write' git operations.\n- `opensource` -> `enricoros/big-AGI` (public, default branch: `main`, MIT) - community issues/PRs/releases\n- `private` -> `big-agi/big-agi-private` (private, default branch: `dev`) - main dev repo with `dev`->`staging`->`prod` pipeline\n- **Always use `git mv` instead of `mv`** when renaming or moving files - preserves git history tracking\n- **NEVER run `git stash`** - it causes work loss\n- **Commit subjects**: `Area: terse imperative` (e.g. `LLMs: OpenAI: ...`, `Build: ...`), single line, no body unless needed, and no `Co-Authored-By` trailer\n\n**Branch contents:**\n- `main` is the open-source build: local-first, BYO-keys, full AIX and provider coverage\n- `dev` extends `main` with the hosted/cloud layer: auth, Zync sync, Cloud Fabric, Stripe, multi-tenant, admin pages, it's the way to go for users, the best user experience of any multi-model chat application\n- Cloud/auth/sync code stays on `dev`; non-cloud improvements (UX, AIX, model support, bug fixes) can land on either branch\n\n**Branch workflow:**\n- `dev` is rebased on top of `main` (never merged) - `main` changes flow into `dev` on the next rebase, no manual forward-port needed\n- Never `git merge` between the two branches - breaks the linear topology\n- Backporting `dev` -> `main` is a re-implementation, never a cherry-pick - keep `main`-side edits minimal/additive so the existing `dev` version lands cleanly on rebase; split into small commits when natural\n- Rebasing `dev` onto `main`: work on a scratch branch (never `private/dev` directly); only files `main` changed since the merge-base can conflict - forecast with `git diff --name-only $(git merge-base private/dev opensource/main) opensource/main`\n- Resolve that rebase per-conflict: keep `dev` where it diverges, UNION where `main` only added (never blanket `-X theirs`/`-X ours` - they drop `main`'s additions). Check no `<<<<<<<` markers survive before each `--continue`\n\n### Core Directory Structure\n\nYou are started from the root of the repository (i.e. where the git folder is or scripts should be run from).\n**ISSUE ALL COMMANDS FROM THE ROOT, OMITTING 'cd' COMMANDS. DO NOT CHAIN CD AND OTHER COMMANDS**\n**NEVER RUN COMPOUND `cd` COMMANDS LIKE `cd some-folder && command` - ONLY RUN `command` FROM THE ROOT, ALWAYS.**\nThe directory structure is as follows:\n\n```\n/app/api/          # Next.js App Router (API routes only, mostly -> /src/server/)\n/pages/            # Next.js Pages Router (file-based, mostly -> /src/apps/)\n/src/\n├── apps/          # Feature applications (self-contained modules)\n├── modules/       # Reusable business logic and integrations\n├── common/        # Shared infrastructure and utilities\n└── server/        # Backend API layer with tRPC\n/kb/               # Knowledge base for modules, architectures\n```\n\n### Key Technologies\n\n- **Frontend**: Next.js 15, React 18, Material-UI Joy, Emotion (CSS-in-JS)\n- **State Management**: Zustand with localStorage/IndexedDB (single cell) persistence\n- **API Layer**: tRPC with TanStack React Query for type-safe communication\n- **Runtime**: Edge Runtime for AI operations, Node.js for data processing\n\n### \"Apps\" Architecture Pattern\n\nEach app in `/src/apps/` is a self-contained feature module:\n- Main component (`App*.tsx`)\n- Local state store (`store-app-*.ts`)\n- Feature-specific components and layouts\n- Runtime configurations\n\nExample apps: `chat/`, `call/`, `beam/`, `draw/`, `personas/`, `settings-modal/`\n\n### Modules Architecture Pattern\n\nModules in `/src/modules/` provide reusable business logic:\n- **`aix/`** - AI communication framework for real-time streaming\n- **`beam/`** - Multi-model AI reasoning system (scatter/gather pattern)\n- **`blocks/`** - Content rendering (markdown, code, images, etc.)\n- **`llms/`** - Language model abstraction supporting 20+ vendors\n\n### Key Subsystems & Their Patterns\n\n#### AIX - Real-time AI Communication\n**Location**: `/src/modules/aix/`\n**Pattern**: Client-server streaming architecture with provider abstraction\n\n- **Client** -> tRPC -> **Server** -> **AI Providers**\n- Handles streaming/non-streaming responses with batching and error recovery\n- Particle-based streaming: `AixWire_Particles` -> `ContentReassembler` -> `DMessage`\n- Provider-agnostic through adapter pattern (OpenAI, Anthropic, Gemini protocols)\n\n#### Beam - Multi-Model Reasoning\n**Location**: `/src/modules/beam/`\n**Pattern**: Scatter/Gather for parallel AI processing\n\n- **Scatter**: Multiple models (rays) process input in parallel\n- **Gather**: Fusion algorithms combine outputs\n- Real-time UI updates via vanilla Zustand stores\n- BeamStore per conversation via ConversationHandler\n\n#### Conversation Management\n**Location**: `/src/common/stores/chat/` and `/src/common/chat-overlay/`\n**Pattern**: Overlay architecture with handler per conversation\n\n- `ConversationHandler` orchestrates chat, beam, ephemerals\n- Per-chat stores: `PerChatOverlayStore` + `BeamStore`\n- Message structure: `DMessage` -> `DMessageFragment[]`\n- Supports multi-pane with independent conversation states\n\n#### Layout System (\"Optima\")\n\nThe Optima layout system provides:\n- **Responsive design** adapting desktop/mobile\n- **Drawer(left)/Toolbar/Panel(right)** composition\n- **Portal-based rendering** for flexible component placement\n\nLocated in `/src/common/layout/optima/`\n\n### Storage System\n\nBig-AGI uses a local-first architecture with Zustand + IndexedDB:\n- **Zustand** stores for in-memory state management\n- **localStorage** for persistent settings/all storage (via Zustand persist middleware)\n- **IndexedDB** for persistent chat-only storage (via Zustand persist middleware) on a single key-val cell\n- **Local-first** architecture with offline capability\n\nKey storage patterns:\n- Stores use `createIDBPersistStorage()` for IndexedDB persistence\n- Version-based migrations handle data structure changes\n- Partialize/merge functions control what gets persisted\n- Rehydration logic repairs and upgrades data on load\n\nLocated in `/src/common/stores/` with stores like:\n- `chat/store-chats.ts`: Conversations and messages\n- `llms/store-llms.ts`: Model configurations\n\n### State Management Patterns\n\n1. **Global Stores** (Zustand with IndexedDB persistence)\n   - `store-chats`: Conversations and messages\n   - `store-llms`: Model configurations\n   - `store-ux-labs`: UI preferences and labs features\n   - **Zustand pattern**: Always wrap multi-property selectors with `useShallow` from `zustand/react/shallow` to prevent re-renders on reference changes\n\n2. **Per-Instance Stores** (Vanilla Zustand)\n   - `store-beam_vanilla`: Beam scatter/gather state\n   - `store-perchat_vanilla`: Chat overlay state\n   - `store-attachment-drafts_vanilla`: Attachment drafts\n   - High-performance, no React integration\n\n3. **Module Stores**\n   - Feature-specific configuration and state\n   - Example: `store-module-beam`, `store-module-t2i`\n\n### User Flows & Interdependencies\n\n#### Chat Message Flow\n1. User input -> `Composer` -> `DMessage` creation\n2. `ConversationHandler.messageAppend()` -> Store update\n3. `_handleExecute()` / `ConversationHandler.executeChatMessages()` -> AIX client request\n4. AIX streaming -> `ContentReassembler` -> UI updates\n5. Zustand auto-persistence -> IndexedDB\n\n#### Beam Multi-Model Flow\n1. User triggers Beam -> `BeamStore.open()` state update\n2. Scatter: Parallel `aixChatGenerateContent()` to N models\n3. Real-time ray updates -> UI progress\n4. Gather: User selects fusion -> Combined output\n5. Result -> New message in conversation\n\n### Development Patterns\n\n#### TypeScript & Code Quality\n- Type-safe through strict TypeScript interfaces\n- Clear interface-first approach for modules and components\n- Use latest TypeScript 5.9+ features\n- Use forward-looking patterns to minimize future refactors (e.g., discriminated unions, `satisfies` operator, as const assertions)\n- Type guards and exhaustiveChecks for robustness\n- Type inference where possible\n- No unnecessary TS casts: prefer narrowing/inference; only `as` when the compiler genuinely can't know the type\n- Runtime validation with Zod schemas for API inputs/outputs (usually server-side, with the client importing as types the inferred types)\n\n#### Module Integration\n- Modules register with central registries (e.g., `vendors.registry.ts`)\n- Configuration objects define module behavior\n\n#### UI & Icons\n- Prefer `@mui/icons-material` icons/variants already imported elsewhere in the app over new ones (keeps the bundle lean); new icons only when depicting genuinely novel functionality\n\n#### API Patterns\n- **tRPC routers** for type-safe API endpoints\n- **Zod schemas** for runtime validation\n- **tRPC procedures middleware** for authorization and logging (authorization is on a httpOnly cookie)\n- **Edge functions** for performance-critical operations\n\n#### Security Considerations\n- API keys in environment variables only (server-side); on the client they're in localStorage for now, but we want to move away from this\n- XSS protection through proper content escaping\n\n#### Writing Style\n- **Never use emdashes (—).** Use normal dashes (-) instead, in all generated text, code comments, and documentation.\n- Register: sharp, terse, precise - in all prose (docs, UI copy, comments, commits, replies). No inflation, no sales tone, no clever headings (plain nouns). Cut sentences that carry no information.\n\n\n## Common Development Tasks\n\n### Testing & Quality\n- Run `npm run lint` before committing\n- Type-check with `tsc --noEmit`\n- Test critical user flows manually\n- Browser floor is lint-enforced: `no-restricted-syntax` bans ES2023 `toSorted/toReversed/toSpliced/with` + unguarded `Intl.Segmenter` (they crash Chrome 109 / Win7 holdouts). Use `[...x].sort()` etc.; don't lower `browserslist` to \"fix\" it - SWC won't polyfill prototype methods\n\n### Debugging Storage Issues\n- Check IndexedDB: DevTools -> Application -> IndexedDB -> `app-chats`\n- Monitor Zustand state: Use Zustand DevTools\n- Check migration logs in console during rehydration\n\n### Production errors (app.big-agi.com)\n- That host is the deployed build - triage runtime errors via the PostHog MCP (filter `url: app.big-agi.com`). Client noise filter (`before_send` / `shouldSuppressPostHogCapture`, matched on `$exception_list`) lives in `src/common/components/3rdparty/PostHogAnalytics.tsx`; `mechanism.handled:false` = an unhandled rejection via autocapture. Suppress only environmental/extension noise, never real bugs\n\n\n## Server Architecture\n\nThe server uses a split architecture with two tRPC routers:\n\n### Edge Network (`trpc.router-edge`)\nDistributed edge runtime for low-latency AI operations:\n- **AIX** [1] - AI streaming and communication\n- **LLM Routers** [1] - Vendor-specific operations such as list models (OpenAI, Anthropic, Gemini, Ollama)\n- **Speex** [1] - Unified TTS router (ElevenLabs, Inworld, and other TTS vendors)\n- **External Services** - Google Search, YouTube transcripts\n\n[1]: also supports client-side fetch (CSF) via client-side inclusion (rebundling with stubs),\nfor direct browser-to-API communication when possible (CORS), to reduce latency and network barriers\n\nLocated at `/src/server/trpc/trpc.router-edge.ts`\n\n### Cloud Network (`trpc.router-cloud`)\nCentralized server for data processing operations:\n- **Browse** - Web scraping and content extraction\n- **Trade** - Import/export functionality (ChatGPT, markdown, JSON)\n\nLocated at `/src/server/trpc/trpc.router-cloud.ts`\n\n**Key Pattern**: Edge runtime for AI (fast, distributed), Cloud runtime for data ops (centralized, Node.js)\n\n@kb/KB.md\n\n@kb/vision-inlined.md\n\nAs a side note, the product tiers (independent, non-VC-funded) are: **Open** (self-host, MIT) · **Free** (big-agi.com) · **Pro** (paid, includes Sync + backup). All tiers use the user's own API keys.\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nGuidance to Claude Code when working with code in this repository.\n\n\n## Architecture Overview\n\nBig-AGI is a Next.js 15 application with a sophisticated modular architecture built for professional AI interactions.\n\n### Development Commands\n\nDev servers may be already running on ports 3000, 3001, 3002, or 3003 (not always this app - other projects may occupy these ports). Never start or stop dev servers, let the user do it.\n\n```bash\n# Validate (~5s, safe while dev server runs, do NOT use `next build` ~45s for same checks)\ntsc --noEmit --pretty && npm run lint # Type check (~3.5s) + ESLint (~2s)\neslint src/path/to/file.ts           # Lint specific file\n\n# Full build (~60s+, only when suspecting runtime/bundle issues)\nnpm run build  # next build runs compile+lint+types but stops at first type-error file; tsc shows all at once\n\n# Database & External Services\n# npm run supabase:local-update-types   # Generate TypeScript types\n# npm run stripe:listen                 # Listen for Stripe webhooks\n```\n\nFor AI protocol development (model listing, live API requests/responses, parameter probing), real vendor API keys are in `.env.api-keys` if present (Anthropic, OpenAI, Gemini, etc., one VENDOR_API_KEY per line). Use them for empirical verification; never commit or echo the values.\n\n### Git/GitHub remotes\n\nThe `gh` command is available to interact with GitHub from the terminal, but **NEVER PUSH TO ANY BRANCH**. The user manages all 'write' git operations.\n- `opensource` -> `enricoros/big-AGI` (public, default branch: `main`, MIT) - community issues/PRs/releases\n- `private` -> `big-agi/big-agi-private` (private, default branch: `dev`) - main dev repo with `dev`->`staging`->`prod` pipeline\n- **Always use `git mv` instead of `mv`** when renaming or moving files - preserves git history tracking\n- **NEVER run `git stash`** - it causes work loss\n- **Commit subjects**: `Area: terse imperative` (e.g. `LLMs: OpenAI: ...`, `Build: ...`), single line, no body unless needed, and no `Co-Authored-By` trailer\n\n**Branch contents:**\n- `main` is the open-source build: local-first, BYO-keys, full AIX and provider coverage\n- `dev` extends `main` with the hosted/cloud layer: auth, Zync sync, Cloud Fabric, Stripe, multi-tenant, admin pages, it's the way to go for users, the best user experience of any multi-model chat application\n- Cloud/auth/sync code stays on `dev`; non-cloud improvements (UX, AIX, model support, bug fixes) can land on either branch\n\n**Branch workflow:**\n- `dev` is rebased on top of `main` (never merged) - `main` changes flow into `dev` on the next rebase, no manual forward-port needed\n- Never `git merge` between the two branches - breaks the linear topology\n- Backporting `dev` -> `main` is a re-implementation, never a cherry-pick - keep `main`-side edits minimal/additive so the existing `dev` version lands cleanly on rebase; split into small commits when natural\n- Rebasing `dev` onto `main`: work on a scratch branch (never `private/dev` directly); only files `main` changed since the merge-base can conflict - forecast with `git diff --name-only $(git merge-base private/dev opensource/main) opensource/main`\n- Resolve that rebase per-conflict: keep `dev` where it diverges, UNION where `main` only added (never blanket `-X theirs`/`-X ours` - they drop `main`'s additions). Check no `<<<<<<<` markers survive before each `--continue`\n\n### Core Directory Structure\n\nYou are started from the root of the repository (i.e. where the git folder is or scripts should be run from).\n**ISSUE ALL COMMANDS FROM THE ROOT, OMITTING 'cd' COMMANDS. DO NOT CHAIN CD AND OTHER COMMANDS**\n**NEVER RUN COMPOUND `cd` COMMANDS LIKE `cd some-folder && command` - ONLY RUN `command` FROM THE ROOT, ALWAYS.**\nThe directory structure is as follows:\n\n```\n/app/api/          # Next.js App Router (API routes only, mostly -> /src/server/)\n/pages/            # Next.js Pages Router (file-based, mostly -> /src/apps/)\n/src/\n├── apps/          # Feature applications (self-contained modules)\n├── modules/       # Reusable business logic and integrations\n├── common/        # Shared infrastructure and utilities\n└── server/        # Backend API layer with tRPC\n/kb/               # Knowledge base for modules, architectures\n```\n\n### Key Technologies\n\n- **Frontend**: Next.js 15, React 18, Material-UI Joy, Emotion (CSS-in-JS)\n- **State Management**: Zustand with localStorage/IndexedDB (single cell) persistence\n- **API Layer**: tRPC with TanStack React Query for type-safe communication\n- **Runtime**: Edge Runtime for AI operations, Node.js for data processing\n\n### \"Apps\" Architecture Pattern\n\nEach app in `/src/apps/` is a self-contained feature module:\n- Main component (`App*.tsx`)\n- Local state store (`store-app-*.ts`)\n- Feature-specific components and layouts\n- Runtime configurations\n\nExample apps: `chat/`, `call/`, `beam/`, `draw/`, `personas/`, `settings-modal/`\n\n### Modules Architecture Pattern\n\nModules in `/src/modules/` provide reusable business logic:\n- **`aix/`** - AI communication framework for real-time streaming\n- **`beam/`** - Multi-model AI reasoning system (scatter/gather pattern)\n- **`blocks/`** - Content rendering (markdown, code, images, etc.)\n- **`llms/`** - Language model abstraction supporting 20+ vendors\n\n### Key Subsystems & Their Patterns\n\n#### AIX - Real-time AI Communication\n**Location**: `/src/modules/aix/`\n**Pattern**: Client-server streaming architecture with provider abstraction\n\n- **Client** -> tRPC -> **Server** -> **AI Providers**\n- Handles streaming/non-streaming responses with batching and error recovery\n- Particle-based streaming: `AixWire_Particles` -> `ContentReassembler` -> `DMessage`\n- Provider-agnostic through adapter pattern (OpenAI, Anthropic, Gemini protocols)\n\n#### Beam - Multi-Model Reasoning\n**Location**: `/src/modules/beam/`\n**Pattern**: Scatter/Gather for parallel AI processing\n\n- **Scatter**: Multiple models (rays) process input in parallel\n- **Gather**: Fusion algorithms combine outputs\n- Real-time UI updates via vanilla Zustand stores\n- BeamStore per conversation via ConversationHandler\n\n#### Conversation Management\n**Location**: `/src/common/stores/chat/` and `/src/common/chat-overlay/`\n**Pattern**: Overlay architecture with handler per conversation\n\n- `ConversationHandler` orchestrates chat, beam, ephemerals\n- Per-chat stores: `PerChatOverlayStore` + `BeamStore`\n- Message structure: `DMessage` -> `DMessageFragment[]`\n- Supports multi-pane with independent conversation states\n\n#### Layout System (\"Optima\")\n\nThe Optima layout system provides:\n- **Responsive design** adapting desktop/mobile\n- **Drawer(left)/Toolbar/Panel(right)** composition\n- **Portal-based rendering** for flexible component placement\n\nLocated in `/src/common/layout/optima/`\n\n### Storage System\n\nBig-AGI uses a local-first architecture with Zustand + IndexedDB:\n- **Zustand** stores for in-memory state management\n- **localStorage** for persistent settings/all storage (via Zustand persist middleware)\n- **IndexedDB** for persistent chat-only storage (via Zustand persist middleware) on a single key-val cell\n- **Local-first** architecture with offline capability\n\nKey storage patterns:\n- Stores use `createIDBPersistStorage()` for IndexedDB persistence\n- Version-based migrations handle data structure changes\n- Partialize/merge functions control what gets persisted\n- Rehydration logic repairs and upgrades data on load\n\nLocated in `/src/common/stores/` with stores like:\n- `chat/store-chats.ts`: Conversations and messages\n- `llms/store-llms.ts`: Model configurations\n\n### State Management Patterns\n\n1. **Global Stores** (Zustand with IndexedDB persistence)\n   - `store-chats`: Conversations and messages\n   - `store-llms`: Model configurations\n   - `store-ux-labs`: UI preferences and labs features\n   - **Zustand pattern**: Always wrap multi-property selectors with `useShallow` from `zustand/react/shallow` to prevent re-renders on reference changes\n\n2. **Per-Instance Stores** (Vanilla Zustand)\n   - `store-beam_vanilla`: Beam scatter/gather state\n   - `store-perchat_vanilla`: Chat overlay state\n   - `store-attachment-drafts_vanilla`: Attachment drafts\n   - High-performance, no React integration\n\n3. **Module Stores**\n   - Feature-specific configuration and state\n   - Example: `store-module-beam`, `store-module-t2i`\n\n### User Flows & Interdependencies\n\n#### Chat Message Flow\n1. User input -> `Composer` -> `DMessage` creation\n2. `ConversationHandler.messageAppend()` -> Store update\n3. `_handleExecute()` / `ConversationHandler.executeChatMessages()` -> AIX client request\n4. AIX streaming -> `ContentReassembler` -> UI updates\n5. Zustand auto-persistence -> IndexedDB\n\n#### Beam Multi-Model Flow\n1. User triggers Beam -> `BeamStore.open()` state update\n2. Scatter: Parallel `aixChatGenerateContent()` to N models\n3. Real-time ray updates -> UI progress\n4. Gather: User selects fusion -> Combined output\n5. Result -> New message in conversation\n\n### Development Patterns\n\n#### TypeScript & Code Quality\n- Type-safe through strict TypeScript interfaces\n- Clear interface-first approach for modules and components\n- Use latest TypeScript 5.9+ features\n- Use forward-looking patterns to minimize future refactors (e.g., discriminated unions, `satisfies` operator, as const assertions)\n- Type guards and exhaustiveChecks for robustness\n- Type inference where possible\n- No unnecessary TS casts: prefer narrowing/inference; only `as` when the compiler genuinely can't know the type\n- Runtime validation with Zod schemas for API inputs/outputs (usually server-side, with the client importing as types the inferred types)\n\n#### Module Integration\n- Modules register with central registries (e.g., `vendors.registry.ts`)\n- Configuration objects define module behavior\n\n#### UI & Icons\n- Prefer `@mui/icons-material` icons/variants already imported elsewhere in the app over new ones (keeps the bundle lean); new icons only when depicting genuinely novel functionality\n\n#### API Patterns\n- **tRPC routers** for type-safe API endpoints\n- **Zod schemas** for runtime validation\n- **tRPC procedures middleware** for authorization and logging (authorization is on a httpOnly cookie)\n- **Edge functions** for performance-critical operations\n\n#### Security Considerations\n- API keys in environment variables only (server-side); on the client they're in localStorage for now, but we want to move away from this\n- XSS protection through proper content escaping\n\n#### Writing Style\n- **Never use emdashes (—).** Use normal dashes (-) instead, in all generated text, code comments, and documentation.\n- Register: sharp, terse, precise - in all prose (docs, UI copy, comments, commits, replies). No inflation, no sales tone, no clever headings (plain nouns). Cut sentences that carry no information.\n\n\n## Common Development Tasks\n\n### Testing & Quality\n- Run `npm run lint` before committing\n- Type-check with `tsc --noEmit`\n- Test critical user flows manually\n- Browser floor is lint-enforced: `no-restricted-syntax` bans ES2023 `toSorted/toReversed/toSpliced/with` + unguarded `Intl.Segmenter` (they crash Chrome 109 / Win7 holdouts). Use `[...x].sort()` etc.; don't lower `browserslist` to \"fix\" it - SWC won't polyfill prototype methods\n\n### Debugging Storage Issues\n- Check IndexedDB: DevTools -> Application -> IndexedDB -> `app-chats`\n- Monitor Zustand state: Use Zustand DevTools\n- Check migration logs in console during rehydration\n\n### Production errors (app.big-agi.com)\n- That host is the deployed build - triage runtime errors via the PostHog MCP (filter `url: app.big-agi.com`). Client noise filter (`before_send` / `shouldSuppressPostHogCapture`, matched on `$exception_list`) lives in `src/common/components/3rdparty/PostHogAnalytics.tsx`; `mechanism.handled:false` = an unhandled rejection via autocapture. Suppress only environmental/extension noise, never real bugs\n\n\n## Server Architecture\n\nThe server uses a split architecture with two tRPC routers:\n\n### Edge Network (`trpc.router-edge`)\nDistributed edge runtime for low-latency AI operations:\n- **AIX** [1] - AI streaming and communication\n- **LLM Routers** [1] - Vendor-specific operations such as list models (OpenAI, Anthropic, Gemini, Ollama)\n- **Speex** [1] - Unified TTS router (ElevenLabs, Inworld, and other TTS vendors)\n- **External Services** - Google Search, YouTube transcripts\n\n[1]: also supports client-side fetch (CSF) via client-side inclusion (rebundling with stubs),\nfor direct browser-to-API communication when possible (CORS), to reduce latency and network barriers\n\nLocated at `/src/server/trpc/trpc.router-edge.ts`\n\n### Cloud Network (`trpc.router-cloud`)\nCentralized server for data processing operations:\n- **Browse** - Web scraping and content extraction\n- **Trade** - Import/export functionality (ChatGPT, markdown, JSON)\n\nLocated at `/src/server/trpc/trpc.router-cloud.ts`\n\n**Key Pattern**: Edge runtime for AI (fast, distributed), Cloud runtime for data ops (centralized, Node.js)\n\n@kb/KB.md\n\n@kb/vision-inlined.md\n\nAs a side note, the product tiers (independent, non-VC-funded) are: **Open** (self-host, MIT) · **Free** (big-agi.com) · **Pro** (paid, includes Sync + backup). All tiers use the user's own API keys.\n","category":"root","tokens":3299}]}