* 📐 docs: Record Who Owns Which Piece of Client State * 🔌 refactor: Give the Subagent Surface a Host Seam and Its Own Jotai State The subagent chat surface reached up into seven application atoms and could not be lifted anywhere, and the six atoms it owns were still Recoil while its sibling stores had already moved to Jotai. Feature-owned state converts to Jotai and stays where it is: the selection, per-task control receipts, live progress and the parent-stream fence. The control atom keeps its session-storage retry — restored per store rather than per family member, so a reload still sees what the last one persisted. App-global state now arrives through one `ChatSurface` value the host supplies: `enterToSend`, `maximizeChatSpace`, `showScrollButton`, the reader's composer bindings, a `claimForeground` command for the slot the panel and the artifacts panel share, and `handOffComposerText` for a continuation's unsent words. Two hosts mount the same adapter — the conversation view and the shared-link view. Opening the panel was three copies of "clear the artifacts slot, then select"; that is now `useOpenSubagentPanel`, and the three call sites say what they mean. Nothing under `Chat/Subagents/**` imports `~/store` or `recoil` any more, and its whole suite runs with no `RecoilRoot` at all. * 🧹 refactor: Move Subagent State Into the Feature and Free Its Drained Atoms Two review findings, both fair. The selection atom still lived in `~/store`, which handed the supposedly liftable surface an implicit dependency on the application store alongside its declared host interface — and contradicted the ownership rule this branch added to CLAUDE.md two commits ago. The module moves to `components/Chat/Subagents/state.ts`; the hosts that write it (the SSE step handler, the message renderers) now import from the feature, which is the direction that survives an extraction. The conversation-switch drain blanked its two atom-family members but left them cached. Every invocation key is unique, so a long-lived tab accumulated two atom configurations per subagent call it ever saw — exactly what the comment at that boundary says it exists to prevent. `removeSubagentProgressAtoms` releases them after the values are cleared, mirroring `removeUsageAtoms`. The new test fails without the release. * 🔎 fix: Let a Subagent Card Render Where There Is No Panel to Open Search results render the same card through `Part`, and that route is not beneath either chat surface — so a search hit containing a subagent tool call threw on `useChatSurface()` before it could render at all. Rendering the card and opening a panel are different requirements. The host stays required for the panel, the activity view and the event group, all of which only ever mount inside one. `useOpenSubagentPanel` reads the context optionally instead and answers `null` where there is no host, which is also the honest answer for search: there is no panel on that route to open, so the card renders with its details control disabled. The new test renders the card with no surface at all, and throws with the reported error when the hook is put back the way it was. * 🧮 fix: Enrol Read-Created Progress Atoms in the Drain Registry The read is what creates a family member, and only the streaming paths were registering their keys. A card rendering a conversation that finished streaming long ago — or a search result that never streams at all — created one the navigation drain could not see, so browsing history accumulated an atom configuration per card for the life of the tab. `useSubagentProgress` does both halves: it reads the invocation's progress and enrols its key, so every route into the family shares the one cleanup boundary. The panel and the parent card both read through it now. * 🧽 fix: Free a Read-Created Progress Atom at Its Own Card's Unmount Enrolling read-created keys in the drain registry only helps where something runs the drain, and `/search` is a standalone route that never mounts the chat event handlers. Scrolling a virtualised result list therefore kept minting members nothing would ever free. `useSubagentProgress` cleans up after itself instead: on unmount it frees the family members when the read is the only reason they exist. Two guards keep that from taking live history with it — a key the stream registered belongs to the drain, and a member holding folded activity is the record of what the child did, so reopening its card still shows it. * 🔗 fix: Free a Progress Atom Only After Its Last Reader Lets Go Opening a foreground panel before the first event gives one still-empty member two readers: the card that spawned the child and the panel showing it. Closing the panel freed it while the card was still subscribed — and a subscriber does not re-render just because its atom left the family, so the first SSE update landed on the replacement member and the card's ticker stayed dead. `useSubagentProgress` counts its mounted readers and frees only when the last one lets go, alongside the two claims that already blocked it: a key the stream registered, and a member holding folded activity.
15 KiB
LibreChat
Project Overview
LibreChat is a monorepo with the following key workspaces:
| Workspace | Language | Side | Dependency | Purpose |
|---|---|---|---|---|
/api |
JS (legacy) | Backend | packages/api, packages/data-schemas, packages/data-provider, @librechat/agents |
Express server — minimize changes here |
/packages/api |
TypeScript | Backend | packages/data-schemas, packages/data-provider |
New backend code lives here (TS only, consumed by /api) |
/packages/data-schemas |
TypeScript | Backend | packages/data-provider |
Database models/schemas, shareable across backend projects |
/packages/data-provider |
TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend |
/client |
TypeScript/React | Frontend | packages/data-provider, packages/client |
Frontend SPA |
/packages/client |
TypeScript | Frontend | packages/data-provider |
Shared frontend utilities |
The source code for @librechat/agents (major backend dependency, same team) lives at
https://github.com/danny-avila/agents.
Workspace Boundaries
- All new backend code must be TypeScript in
/packages/api. - Keep
/apichanges to the absolute minimum (thin JS wrappers calling into/packages/api). - Database-specific shared logic goes in
/packages/data-schemas. - Frontend/backend shared API logic (endpoints, types, data-service) goes in
/packages/data-provider. - Build data-provider from project root:
npm run build:data-provider.
Branching and Pull Requests
- Branch off
dev, and targetdevwith every pull request. All work lands ondevfirst. mainis the released branch. It is kept as a fast-forward ofdevand synced as-is, so it is always an ancestor ofdev— equal to it right after a sync, behind it otherwise. It never carries a commit thatdevdoes not have.- Never open a backport pull request to
main. Anything merged todevreachesmainat the next sync; a second pull request for the same change is redundant. - The repository's default branch is
main, sogh pr createand the GitHub UI target it unless told otherwise — always pass--base devexplicitly. - Pull requests opened against
mainare retargeted todevautomatically by.github/workflows/pr-retarget-dev.yml. Thetarget: mainlabel exempts one, as do release-bound upstream branches (dev,release/*,hotfix/*). Backport branches are deliberately not exempt — a backport merged straight tomainis what breaks the fast-forward invariant. Fixes #Ndoes not close the issue. GitHub honors closing keywords only when a pull request merges into the default branch (main). Merging todevdoes not close anything, and the later fast-forward ofmainis not a merge event either — close linked issues by hand.- Git worktrees share one stash stack.
refs/stashlives in the common.gitdirectory, so a baregit stash popin one worktree can take work stashed in another. Prefer a throwaway WIP commit; if you must stash,git stash push -m <tag>andapplythat specific entry.
Code Style
Naming and File Organization
- Single-word file names whenever possible (e.g.,
permissions.ts,capabilities.ts,service.ts). - When multiple words are needed, prefer grouping related modules under a single-word directory rather than using multi-word file names (e.g.,
admin/capabilities.tsnotadminCapabilities.ts). - The directory already provides context —
app/service.tsnotapp/appConfigService.ts.
Structure and Clarity
- Never-nesting: early returns, flat code, minimal indentation. Break complex operations into well-named helpers.
- Functional first: pure functions, immutable data,
map/filter/reduceover imperative loops. Only reach for OOP when it clearly improves domain modeling or state encapsulation. - No dynamic imports unless absolutely necessary.
DRY
- Extract repeated logic into utility functions.
- Reusable hooks / higher-order components for UI patterns.
- Parameterized helpers instead of near-duplicate functions.
- Constants for repeated values; configuration objects over duplicated init code.
- Shared validators, centralized error handling, single source of truth for business rules.
- Shared typing system with interfaces/types extending common base definitions.
- Abstraction layers for external API interactions.
Iteration and Performance
- Minimize looping — especially over shared data structures like message arrays, which are iterated frequently throughout the codebase. Every additional pass adds up at scale.
- Consolidate sequential O(n) operations into a single pass whenever possible; never loop over the same collection twice if the work can be combined.
- Choose data structures that reduce the need to iterate (e.g.,
Map/Setfor lookups instead ofArray.find/Array.includes). - Avoid unnecessary object creation; consider space-time tradeoffs.
- Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references.
Backend Database Performance
- On request startup and first page load paths, watch for serial database reads. Multiple round trips to MongoDB can add significant latency when the database is far from the app server.
- Prefer passing already-loaded request/user/config data through helper functions instead of re-reading the same user, role, tenant, or principal data.
- When two reads are independent, start them in parallel and gate the response on the authorization or validation result before returning data.
- Keep authorization, permission, and tenant checks semantically identical when parallelizing reads. Speculative reads must remain scoped to the authenticated user or tenant and must not write to the response before validation succeeds.
Type Safety
- Never use
any. Explicit types for all parameters, return values, and variables. - Limit
unknown— avoidunknown,Record<string, unknown>, andas unknown as Tassertions. ARecord<string, unknown>almost always signals a missing explicit type definition. - Don't duplicate types — before defining a new type, check whether it already exists in the project (especially
packages/data-provider). Reuse and extend existing types rather than creating redundant definitions. - Use union types, generics, and interfaces appropriately.
- All TypeScript and ESLint warnings/errors must be addressed — do not leave unresolved diagnostics.
Comments and Documentation
- Write self-documenting code; no inline comments narrating what code does.
- JSDoc only for complex/non-obvious logic or intellisense on public APIs.
- Single-line JSDoc for brief docs, multi-line for complex cases.
- Avoid standalone
//comments unless absolutely necessary.
Import Order
Imports are organized into three sections:
- Package imports — sorted shortest to longest line length (
reactalways first). import typeimports — sorted longest to shortest (package types first, then local types; length resets between sub-groups).- Local/project imports — sorted longest to shortest.
Multi-line imports count total character length across all lines. Consolidate value imports from the same module. Always use standalone import type { ... } — never inline type inside value imports.
JS/TS Loop Preferences
- Limit looping as much as possible. Prefer single-pass transformations and avoid re-iterating the same data.
for (let i = 0; ...)for performance-critical or index-dependent operations.for...offor simple array iteration.for...inonly for object property enumeration.
Frontend Rules (client/src/**/*)
Localization
- All user-facing text must use
useLocalize(). - Only update English keys in
client/src/locales/en/translation.json(other languages are automated externally). - Semantic key prefixes:
com_ui_,com_assistants_, etc.
Components
- TypeScript for all React components with proper type imports.
- Semantic HTML with ARIA labels (
role,aria-label) for accessibility. - Group related components in feature directories (e.g.,
SidePanel/Memories/). - Use index files for clean exports.
Theming and styling
- Compose before styling. Search
@librechat/clientfor an existing primitive, semantic variant, or composition before adding feature-local classes or CSS. - Use semantic roles. Colors and shared appearance values must come from the semantic Tailwind/theme roles. Do not add raw palette utilities, hard-coded hex/RGB/HSL colors, or light/dark-specific values in feature components.
- Deepen the system when the need is reusable. Add a focused variant to a shared primitive or extend the canonical, versioned theme-token registry when multiple screens should share the same design decision. Do not create shallow local wrappers that merely relocate class strings.
- Themes are data, not arbitrary CSS. Theme definitions may select semantic colors and shared appearance roles. They must not contain selectors, arbitrary CSS, application behavior, or alternate feature layouts. Preserve existing environment and stored-theme compatibility when changing the theme engine.
- Keep layout and behavior local. Feature structure, responsive layout, state-driven transitions, and specialized visualization may remain feature-owned. Expose a theme role only when it represents a stable, reusable appearance decision; do not turn every measurement into a global token.
- Treat custom CSS as an exception. Use it only when shared primitives and semantic utilities cannot express the requirement. Keep it narrowly scoped, consume theme variables where applicable, support light/dark and reduced motion, and add a brief code or PR explanation of why the exception is necessary.
- Preserve defaults and prove variability. New theme-aware variants must reproduce the current default appearance unless a redesign is explicitly requested. Test semantic-token use and, when extending theme capabilities, include a deliberately different reference theme to prove that components adapt without feature-specific overrides.
Data Management
- Feature hooks:
client/src/data-provider/[Feature]/queries.ts→[Feature]/index.ts→client/src/data-provider/index.ts. - React Query (
@tanstack/react-query) for all API interactions; proper query invalidation on mutations. - QueryKeys and MutationKeys in
packages/data-provider/src/keys.ts.
Client State Ownership
The client is migrating from Recoil to Jotai. Convert the areas you touch rather than migrating wholesale, and split the work by who owns the state:
- Feature-owned state — atoms a single feature both writes and reads. Convert these to Jotai as you touch them, and keep them inside the feature.
- App-global state — preferences and shell state a feature merely consumes
(
maximizeChatSpace,showScrollButton,enterToSend, artifact visibility). A feature that could plausibly be extracted must not reach into~/storefor these; accept them through props or a small context the host supplies.
Passing app-global state in — rather than reaching for it — is what lets a feature move to its own workspace later without a rewrite, and it keeps the Jotai conversion scoped to the state a feature actually owns instead of dragging the global migration forward early.
Data-Provider Integration
- Endpoints:
packages/data-provider/src/api-endpoints.ts - Data service:
packages/data-provider/src/data-service.ts - Types:
packages/data-provider/src/types/queries.ts - Use
encodeURIComponentfor dynamic URL parameters.
Performance
- Prioritize memory and speed efficiency at scale.
- Cursor pagination for large datasets.
- Proper dependency arrays to avoid unnecessary re-renders.
- Leverage React Query caching and background refetching.
Backend Rules (api/**, packages/api/**)
Auth cache invalidation
When adding or changing code that mutates user documents, invalidate the auth user document cache
for the affected users. This covers single-user updates as well as bulk role and user mutations.
Without it, OpenID JWT request burst caching can serve a stale req.user until its TTL expires.
Development Commands
| Command | Purpose |
|---|---|
npm run smart-reinstall |
Install deps (if lockfile changed) + build via Turborepo |
npm run reinstall |
Clean install — wipe node_modules and reinstall from scratch |
npm run backend |
Start the backend server |
npm run backend:dev |
Start backend with file watching (development) |
npm run build |
Build all compiled code via Turborepo (parallel, cached) |
npm run frontend |
Build all compiled code sequentially (legacy fallback) |
npm run frontend:dev |
Start frontend dev server with HMR (port 3090, requires backend running) |
npm run build:data-provider |
Rebuild packages/data-provider after changes |
- Node.js: v24.16.0
- Database: MongoDB
- Backend runs on
http://localhost:3080/; frontend dev server onhttp://localhost:3090/
Testing
- Framework: Jest, run per-workspace.
- Run tests from their workspace directory:
cd api && npx jest <pattern>,cd packages/api && npx jest <pattern>, etc. - Frontend tests:
__tests__directories alongside components; usetest/layout-test-utilsfor rendering. - Cover loading, success, and error states for UI/data flows.
Typechecking
- A green build is not a typecheck.
packages/api,packages/clientandpackages/data-schemasbuild withtsdownalone, which emits without checking types. Onlypackages/data-providerrunstscas part of its build. - Run
npx tsc --noEmitin the workspace you changed before calling it done.clientalso exposes it asnpm run typecheck. packages/client/tsconfig.jsonexcludes*.spec.ts(x)and*.test.ts(x), so test files there are never typechecked — a type error in a spec surfaces only when the test runs.npm run static-checksruns the Static Checks CI job locally against your staged files;npm run static-checks -- --against origin/devreproduces what CI sees for a pull request, andnpm run static-checks:fulladds the slow gates (TypeScript, config migration tests, unused i18n keys, unused npm packages).
Philosophy
- Real logic over mocks. Exercise actual code paths with real dependencies. Mocking is a last resort.
- Spies over mocks. Assert that real functions are called with expected arguments and frequency without replacing underlying logic.
- MongoDB: use
mongodb-memory-serverfor a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls. - MCP: use real
@modelcontextprotocol/sdkexports for servers, transports, and tool definitions. Mirror real scenarios, don't stub SDK internals. - Only mock what you cannot control: external HTTP APIs, rate-limited services, non-deterministic system calls.
- Heavy mocking is a code smell, not a testing strategy.
Formatting
Fix all formatting lint errors (trailing spaces, tabs, newlines, indentation) using auto-fix when available. All TypeScript/ESLint warnings and errors must be resolved.
npm run sort-imports with no arguments rewrites every file under api/, client/src and the four
packages/*/src roots — far beyond what you touched. Always pass explicit paths:
npm run sort-imports -- path/to/file.ts.