CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

This project uses pnpm as the package manager and Turbo for build orchestration:

• pnpm install - Install all dependencies
• pnpm build - Build all packages using Turbo
• pnpm dev - Start development mode for all packages
• pnpm test - Run all unit tests
• pnpm e2e - Run end-to-end tests
• pnpm lint - Run ESLint across all packages
• pnpm type-check - Run TypeScript type checking across workspace
• pnpm format - Check code formatting with Prettier
• pnpm format:write - Auto-fix formatting issues
• pnpm circular-check - Check for circular dependencies using madge

For individual package development:

• turbo run build --filter="@llamaindex/core" - Build specific package
• turbo run test --filter="@llamaindex/core" - Test specific package
• Navigate to specific package directory and run pnpm test for focused testing
• pnpm clean - Remove all build artifacts and node_modules across workspace

Architecture Overview

LlamaIndex.TS is a TypeScript data framework for LLM applications organized as a pnpm monorepo with multiple runtime environment support (Node.js, Deno, Bun, Vercel Edge, Cloudflare Workers).

Package Structure

Core Packages:

• packages/core/ - Abstract base classes and interfaces for all runtime environments
• packages/llamaindex/ - Main package that aggregates core functionality
• packages/env/ - Environment-specific compatibility layers for different JS runtimes

Provider Packages (packages/providers/):

• LLM providers: openai/, anthropic/, ollama/, google/, groq/, etc.
• Vector stores: storage/pinecone/, storage/chroma/, storage/qdrant/, etc.
• Embeddings: Various embedding providers integrated within LLM packages
• Readers: assemblyai/, discord/, notion/ for data ingestion

Specialized Packages:

• packages/cloud/ - LlamaCloud integration for managed services
• packages/tools/ - Function calling tools and utilities
• packages/workflow/ - Agent workflow orchestration
• packages/readers/ - File format readers (PDF, DOCX, etc.)

Key Architectural Patterns

Runtime Abstraction: Core functionality is runtime-agnostic, with environment-specific implementations in separate entry points (index.ts, index.edge.ts, index.workerd.ts).

Provider Pattern: LLMs, embeddings, and vector stores implement common interfaces from @llamaindex/core, allowing easy swapping between providers.

Modular Design: Each provider is a separate package to minimize bundle size - users install only what they need.

Data Flow: Document → NodeParser → Embedding → VectorStore → Retriever → QueryEngine → Response

Core Components

• Agents and Workflows: Abstractions for building agentic workflows and agents in packages/workflow
• Chat Engines: Conversational interfaces in core/chat-engine/
• Query Engines: Document querying with retrieval in core/query-engine/
• Indices: VectorStoreIndex, SummaryIndex, KeywordTable in llamaindex/indices/
• Node Parsers: Text splitting and chunking in core/node-parser/
• Ingestion Pipeline: Document processing workflows in llamaindex/ingestion/
• Storage: Chat stores, document stores, index stores, and KV stores in core/storage/

Deprecated Components

• Agents: ReAct and function calling agents in core/agent/ and llamaindex/agent/

Testing Structure

• Unit tests in each package's tests/ directory
• E2E tests in e2e/ directory with runtime-specific examples
• Tests depend on build artifacts, so always run pnpm build before testing

Multi-Runtime Support

The codebase supports multiple JavaScript runtimes through conditional exports and separate entry points. When making changes, consider compatibility across Node.js, Deno, Bun, and edge runtimes.

Development Notes

• The project uses Husky for git hooks with lint-staged for pre-commit formatting and linting
• All packages use bunchee for building with dual CJS/ESM support
• Core package exports are organized as sub-modules (e.g., @llamaindex/core/llms, @llamaindex/core/embeddings)
• Always run pnpm build before running tests, as tests depend on build artifacts