obsidian-todo-tracker/CLAUDE.md

CLAUDE.md

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

Project Type

This is an Obsidian community plugin written in TypeScript and bundled to JavaScript using esbuild.

Build Commands

# Install dependencies
npm install

# Development mode (watch mode, auto-recompiles on changes)
npm run dev

# Production build (type checks, then bundles with minification)
npm run build

# Lint code
npm run lint

Architecture

Entry Points & Build Process

• Source code lives in src/
• Main entry point: src/main.ts (plugin lifecycle management)
• Build target: main.js (bundled output at root)
• Bundler: esbuild (configured in esbuild.config.mjs)
• Required release artifacts: main.js, manifest.json, styles.css (if present)

Code Organization Pattern

• Keep main.ts minimal: Only plugin lifecycle (onload, onunload, command registration)
• Delegate feature logic to separate modules
• Settings are defined in src/settings.ts
• Organize larger features into subdirectories:
  • commands/ for command implementations
  • ui/ for modals, views, and UI components
  • utils/ for helper functions

Plugin Architecture

• Extends Plugin class from obsidian package
• Settings are loaded/saved using this.loadData() / this.saveData()
• All event listeners, intervals, and DOM events must use this.register*() helpers for proper cleanup
• Commands are registered via this.addCommand() with stable IDs

Key Constraints

Obsidian-Specific

• Bundle everything: No external runtime dependencies (except obsidian, electron, CodeMirror packages)
• External packages: Listed in esbuild.config.mjs external array; never bundle these
• Mobile compatibility: Avoid Node/Electron APIs unless isDesktopOnly: true in manifest
• Network requests: Default to offline; require explicit user consent for any external calls
• No remote code execution: Never fetch/eval scripts or auto-update outside normal releases

Manifest (manifest.json)

• Never change id after initial release
• Use semantic versioning for version
• Keep minAppVersion accurate when using newer Obsidian APIs
• Update both manifest.json and versions.json when bumping versions

Development Workflow

Testing Locally

1. Build the plugin: npm run dev or npm run build
2. Copy main.js, manifest.json, styles.css to:

   <Vault>/.obsidian/plugins/<plugin-id>/
   

3. Reload Obsidian and enable plugin in Settings → Community plugins

Type Checking

• TypeScript strict mode enabled in tsconfig.json
• Build command runs tsc -noEmit -skipLibCheck before bundling
• Fix type errors before considering build successful

Important Files

• src/main.ts - Plugin class and lifecycle
• src/settings.ts - Settings interface, defaults, and settings tab UI
• manifest.json - Plugin metadata (never commit with wrong version)
• esbuild.config.mjs - Build configuration
• eslint.config.mts - ESLint configuration with Obsidian-specific rules
• styles.css - Optional plugin styles

Code Quality Guidelines

From AGENTS.md and Obsidian best practices:

• Split files when they exceed ~200-300 lines
• Use clear module boundaries (single responsibility per file)
• Prefer async/await over promise chains
• Register all cleanup via this.register*() helpers to prevent memory leaks
• Keep startup lightweight; defer heavy work until needed
• Use stable command IDs (don't rename after release)
• Provide sensible defaults for all settings