obsidian-gemini-helper: 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 Google Gemini AI with Chat, Workflow Automation, and Semantic Search (RAG). Uses @google/genai SDK. API-only (no CLI backends or local LLM support).

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.

Releasing

After bumping, push master only — do NOT push the version tag manually:

git push origin master

The Release workflow (.github/workflows/release.yml) runs on push to master, creates the tag from manifest.json's version, builds, and opens a draft GitHub release with main.js/manifest.json/styles.css attached. The maintainer edits the notes and publishes the draft manually. If the tag already exists (e.g. it was pushed by hand), the workflow skips release creation entirely — delete the remote tag and re-run the workflow to recover.

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
  • messagesToHistory() - Converts Message[] to Gemini Content[] format
• fileSearch.ts - File Search RAG management
  • FileSearchManager - Handles store creation, file sync, deletion
  • smartSync() - Checksum-based incremental sync with parallel uploads
• tools.ts - Function calling tool definitions (13 tools for vault operations)
• mcpClient.ts - MCP (Model Context Protocol) client for external tool servers
  • Implements Streamable HTTP transport with JSON-RPC