Imported from hamza-paracha/aya-copilot (apps/librechat/AGENTS.md). Install upstream with npx skills add hamza-paracha/aya-copilot --skill librechat. Copyright stays with the author.

LibreChat

Project Overview

LibreChat is a monorepo with the following key workspaces:

The source code for @librechat/agents (major backend dependency, same team) is at /home/danny/agentus.

Workspace Boundaries

• All new backend code must be TypeScript in /packages/api.
• Keep /api changes 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.

Code Style

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/reduce over 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/Set for lookups instead of Array.find/Array.includes).
• Avoid unnecessary object creation; consider space-time tradeoffs.
• Prevent memory leaks: careful with closures, dispose resources/event listeners, no circular references.

Type Safety

• Never use any. Explicit types for all parameters, return values, and variables.
• Limit unknown — avoid unknown, Record<string, unknown>, and as unknown as T assertions. A Record<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:

1. Package imports — sorted shortest to longest line length (react always first).
2. import type imports — sorted longest to shortest (package types first, then local types; length resets between sub-groups).
3. 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...of for simple array iteration.
• for...in only 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.

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.

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 encodeURIComponent for 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.

Development Commands

• Node.js: v20.19.0+ or ^22.12.0 or >= 23.0.0
• Database: MongoDB
• Backend runs on http://localhost:3080/; frontend dev server on http://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; use test/layout-test-utils for rendering.
• Cover loading, success, and error states for UI/data flows.

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-server for a real in-memory MongoDB instance. Test actual queries and schema validation, not mocked DB calls.
• MCP: use real @modelcontextprotocol/sdk exports 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.