obsidian-llm-hub: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Obsidian plugin for multi-provider LLM Chat, Workflow Automation, and Semantic Search (RAG). Supports Gemini, OpenAI, Anthropic, OpenRouter, Grok via API, plus CLI backends (Gemini CLI, Claude CLI, Codex CLI) and local LLM servers (Ollama, LM Studio, vLLM).

Build Commands

npm run build    # Production build (tsc + esbuild) -> outputs main.js
npm run dev      # Development build with watch mode
npm run lint     # ESLint check

After building, reload the plugin in Obsidian to test changes.

Version Bumping

Use npm's built-in version command which automatically updates all version files:

npm version patch   # 1.2.3 -> 1.2.4
npm version minor   # 1.2.3 -> 1.3.0
npm version major   # 1.2.3 -> 2.0.0

This runs version-bump.mjs which updates package.json, manifest.json, and versions.json together.

Architecture

Core Layer (src/core/)

• gemini.ts - Gemini API client wrapper
  • GeminiClient class with streaming chat, function calling, and RAG integration
  • chatWithToolsStream() - Main method for chat with tools and optional RAG
  • messagesToContents() - Converts Message[] to Gemini Content[] format (private)
• localRagStore.ts - Local RAG store with cosine-similarity search
  • LocalRagStore - Manages in-memory index/vectors, sync, and search
  • searchLocalRag() - Entry point for RAG context injection
  • Supports external pre-built index via externalIndexPath
• localRagStorage.ts - Persistence for local RAG index (index.json + vectors.bin)
• embeddingProvider.ts - Embedding generation via OpenAI-compatible API
  • generateEmbeddings() - Batch embedding generation
  • fetchEmbeddingModels() - Fetches available models (Ollama /api/tags or /v1/models)
• openaiProvider.ts - OpenAI-compatible API provider (chat, image generation)
• anthropicProvider.ts - Anthropic API provider (chat with tools)
• tools.ts - Function calling tool definitions (15 tools for vault operations)
• cliProvider.ts - CLI backend abstraction for Gemini/Claude/Codex CLIs
  • CliProviderManager - Manages CLI provider instances
  • Prefers child_process.spawn with shell: false everywhere. On Windows, auto-detects the npm-global .js script (via findWindowsNpmScript) and runs it through node, or the standalone claude.exe. Only falls back to shell: true + command name when no .js/.exe is found, so .cmd wrappers from PATH still work (with the documented cmd.exe-metacharacter caveat for user prompts).
  • findNodeBinary() - Resolves node path from version managers (nodenv, nvm, volta, fnm, asdf, mise)
  • Custom CLI paths dispatch by extension on Windows (.js → node, .exe → direct, .cmd/.bat → shell). On macOS/Linux always run via node <path>.
• mcpClient.ts - MCP (Model Context Protocol) client for external tool servers
  • Implements Streamable HTTP transport with JSON-RPC