From f3fb79fae4378f2698e289f9208bcd1599c1eae5 Mon Sep 17 00:00:00 2001 From: Logan Yang Date: Tue, 17 Jun 2025 12:55:59 -0700 Subject: [PATCH] Update claude md (#1556) --- .claude/settings.local.json | 6 ++ CLAUDE.md | 136 ++++++++++++++++++++++++++++++------ 2 files changed, 119 insertions(+), 23 deletions(-) create mode 100644 .claude/settings.local.json diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000..2991fd0a --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,6 @@ +{ + "permissions": { + "allow": ["Bash(npm run test:*)"], + "deny": [] + } +} diff --git a/CLAUDE.md b/CLAUDE.md index f1b39902..1c95ef07 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,31 +1,121 @@ -# CLAUDE.md - Copilot for Obsidian Plugin +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Overview + +Copilot for Obsidian is an AI-powered assistant plugin that integrates various LLM providers (OpenAI, Anthropic, Google, etc.) with Obsidian. It provides chat interfaces, autocomplete, semantic search, and various AI-powered commands for note-taking and knowledge management. ## Development Commands -- Build: `npm run build` -- Development: `npm run dev` -- Lint: `npm run lint` (fix: `npm run lint:fix`) -- Format: `npm run format` (check: `npm run format:check`) -- Test: `npm run test` (single test: `npm test -- -t "test name"`) -- Before PR: Run `npm run format && npm run lint` +### Build & Development + +- `npm run dev` - Start development server with hot reload (runs Tailwind CSS + esbuild in watch mode) +- `npm run build` - Production build (TypeScript check + minified output) + +### Code Quality + +- `npm run lint` - Run ESLint checks +- `npm run lint:fix` - Auto-fix ESLint issues +- `npm run format` - Format code with Prettier +- `npm run format:check` - Check formatting without changing files +- **Before PR:** Always run `npm run format && npm run lint` + +### Testing + +- `npm run test` - Run unit tests (excludes integration tests) +- `npm run test:integration` - Run integration tests (requires API keys) +- Run single test: `npm test -- -t "test name"` + +## High-Level Architecture + +### Core Systems + +1. **LLM Provider System** (`src/LLMProviders/`) + + - Provider implementations for OpenAI, Anthropic, Google, Azure, local models + - `LLMProviderManager` handles provider lifecycle and switching + - Stream-based responses with error handling and rate limiting + - Custom model configuration support + +2. **Chain Factory Pattern** (`src/chainFactory.ts`) + + - Different chain types for various AI operations (chat, copilot, adhoc prompts) + - LangChain integration for complex workflows + - Memory management for conversation context + - Tool integration (search, file operations, time queries) + +3. **Vector Store & Search** (`src/search/`) + + - `VectorStoreManager` manages embeddings and semantic search + - `ChunkedStorage` for efficient large document handling + - Event-driven index updates via `IndexManager` + - Multiple embedding providers support + +4. **UI Component System** (`src/components/`) + + - React functional components with Radix UI primitives + - Tailwind CSS with class variance authority (CVA) + - Modal system for user interactions + - Chat interface with streaming support + - Settings UI with versioned components + +5. **State Management** + + - Jotai for atomic state management + - React contexts for feature-specific state + - Shared state utilities in `src/sharedState.ts` + +6. **Plugin Integration** + - Main entry: `src/main.ts` extends Obsidian Plugin + - Command registration system + - Event handling for Obsidian lifecycle + - Settings persistence and migration + +### Key Patterns + +- **Error Handling**: Custom error types with detailed interfaces +- **Async Operations**: Consistent async/await pattern with proper error boundaries +- **Caching**: Multi-layer caching for files, PDFs, and API responses +- **Streaming**: Real-time streaming for LLM responses +- **Testing**: Unit tests adjacent to implementation, integration tests for API calls ## Code Style Guidelines -- TypeScript with strict null checks and no implicit any -- Use absolute imports with `@/` prefix (e.g., `import { ChainType } from "@/chainFactory"`) -- React functional components with hooks -- Error handling: Use detailed error objects with type interfaces -- Consistent naming: PascalCase for components/classes, camelCase for functions/variables -- Comment complex logic and functions with JSDoc format -- Use async/await for asynchronous operations -- Prefer const/let over var -- Organize imports: React first, then external, then internal -- Format with Prettier and ESLint before commits +### TypeScript -## Code Organization +- Strict mode enabled (no implicit any, strict null checks) +- Use absolute imports with `@/` prefix: `import { ChainType } from "@/chainFactory"` +- Prefer const assertions and type inference where appropriate +- Use interface for object shapes, type for unions/aliases -- UI components in src/components/ -- LLM providers in src/LLMProviders/ -- Utility functions in src/utils.ts -- Settings in src/settings/ -- Tests adjacent to implementation files +### React + +- Functional components only (no class components) +- Custom hooks for reusable logic +- Props interfaces defined above components +- Avoid inline styles, use Tailwind classes + +### General + +- File naming: PascalCase for components, camelCase for utilities +- Async/await over promises +- Early returns for error conditions +- JSDoc for complex functions +- Organize imports: React → external → internal + +## Testing Guidelines + +- Unit tests use Jest with TypeScript support +- Mock Obsidian API for plugin testing +- Integration tests require API keys in `.env.test` +- Test files adjacent to implementation (`.test.ts`) +- Use `@testing-library/react` for component testing + +## Important Notes + +- The plugin supports multiple LLM providers with custom endpoints +- Vector store requires rebuilding when switching embedding providers +- Settings are versioned - migrations may be needed +- Local model support available via Ollama/LM Studio +- Rate limiting is implemented for all API calls