alexopus-ComfyUI-Notes-Sidebar/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a ComfyUI extension that adds a server-side notes sidebar for managing markdown notes. The extension provides a complete notes management system with both backend API endpoints and a frontend JavaScript interface.

Architecture

Backend (Python)

• Main Module: __init__.py - Core extension entry point
• NotesManager Class: Handles all note operations (CRUD) with file system storage
• API Endpoints: RESTful endpoints using aiohttp web framework integrated with ComfyUI's PromptServer
• File Storage: Notes stored as .md files in the notes/ directory

Frontend (JavaScript)

• Extension Module: js/extension.js - ComfyUI extension integration
• NotesStore Class: Event-driven state management using EventTarget pattern
• NotesSidebar Class: Main UI component managing tabs, content area, and user interactions
• Styling: js/notes-sidebar.css - Complete UI styling for dark theme integration

Key Components

1. Server Integration: Uses ComfyUI's PromptServer.instance.routes for API endpoints
2. File Management: Notes stored as markdown files with automatic directory creation
3. UI Architecture: Tab-based interface with content area and action buttons
4. Extension Registration: Properly registers with ComfyUI's extension manager as a sidebar tab
5. State Management: Centralized state using NotesStore class with EventTarget pattern:
   • noteContent: Current content for each note (including unsaved)
   • savedContent: Last saved content from server
   • unsavedChanges: Boolean flag for each note's modification state
   • Event-driven updates automatically sync UI components

API Endpoints

The extension exposes these REST endpoints:

• GET /notes_sidebar/list - List all notes
• GET /notes_sidebar/note/{note_name} - Get specific note content
• POST /notes_sidebar/note/{note_name} - Save/create note
• DELETE /notes_sidebar/note/{note_name} - Delete note

Development Notes

Extension Structure

• Must export NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS, and WEB_DIRECTORY for ComfyUI compatibility
• JavaScript extension uses ComfyUI's app.registerExtension() pattern
• Sidebar integration uses app.extensionManager.registerSidebarTab()

File Operations

• Notes are automatically saved as .md files in the notes/ directory
• File names are URL-encoded for safe handling
• Directory creation is handled automatically on initialization

UI State Management

• Active note tracking with tab highlighting
• Content persistence across sidebar open/close cycles
• Real-time tab rendering on note operations
• Button layout: Save/Rename on left, Refresh/Delete on right
• Unsaved Changes Tracking: Visual indicators (*) for modified notes
• Content Preservation: Tab switching preserves unsaved content
• Change Detection: Automatic tracking of modifications vs saved state

Unsaved Changes Behavior

• Notes with modifications show asterisk (*) in tab name
• Switching tabs preserves unsaved content in inactive notes
• onTextAreaChange() method tracks real-time content changes
• Save operation clears unsaved state and updates saved content reference
• Delete/rename operations properly clean up tracking maps

Key Architectural Patterns

• State Management: Uses EventTarget pattern for reactive state updates
• File I/O: Synchronous file operations in Python with proper error handling
• API Design: RESTful endpoints with JSON responses and consistent error handling
• UI Updates: Event-driven architecture prevents manual DOM manipulation
• Extension Integration: Follows ComfyUI's extension patterns (NODE_CLASS_MAPPINGS, registerExtension)

Development Commands

Installation & Setup

• No build process required - extension loads directly in ComfyUI
• Place extension folder in ComfyUI's custom_nodes/ directory
• Restart ComfyUI to load the extension

Testing the Extension

No automated tests defined. Manual testing workflow:

1. Load extension in ComfyUI
2. Verify sidebar tab appears with "Notes" label and book icon
3. Test CRUD operations: create, edit, save, rename, delete notes
4. Verify tab switching and content persistence

Development Workflow

1. Modify Python code in __init__.py for backend changes
2. Modify JavaScript in js/extension.js for frontend changes
3. Update CSS in js/notes-sidebar.css for styling changes
4. Python changes: Restart ComfyUI completely to reload the extension
5. JavaScript/CSS changes: Browser refresh is sufficient

File Structure

• notes/ - Storage directory for markdown notes (auto-created)
• js/ - Frontend assets loaded by ComfyUI
• __init__.py - Main extension code
• pyproject.toml - Project metadata