* Fix Windows installation with smart caching installer
Fixes#52 - Windows users getting ERR_MODULE_NOT_FOUND for better-sqlite3
## Problem
Windows users (@adrianveen and others) were experiencing installation failures
with cryptic ERR_MODULE_NOT_FOUND errors. The root cause was:
1. npm install running on EVERY SessionStart (slow, wasteful)
2. Silent logging hiding actual installation errors
3. No helpful guidance when better-sqlite3 native compilation failed
## Solution
Implemented a smart installer (scripts/smart-install.js) that:
- Caches installation state with version marker (.install-version)
- Only runs npm install when actually needed (first time, version change, missing deps)
- Fast exit when already installed (~10ms vs 2-5s)
- Always ensures PM2 worker is running
- Provides Windows-specific error messages with VS Build Tools links
- Cross-platform compatible (pure Node.js)
## Changes
- Added: scripts/smart-install.js - Smart caching installer with PM2 worker management
- Modified: plugin/hooks/hooks.json - Use smart-install.js instead of raw npm install
- Modified: .gitignore - Added .install-version cache file
- Modified: CLAUDE.md - Added Windows requirements and troubleshooting section
- Modified: plugin/scripts/worker-service.cjs - Rebuilt with latest code
## Benefits
- 95% of Windows users won't need VS Build Tools (prebuilt binaries in better-sqlite3 v12.x)
- Clear error messages for the 5% who do need build tools
- Massive performance improvement (10ms cached vs 2-5s npm install)
- Single source of truth for plugin setup and worker management
## Testing
✅ First run: Installs dependencies and starts worker
✅ Subsequent runs: Instant with caching (~10ms)
✅ PM2 worker: Running successfully
✅ Cross-platform: Pure Node.js, no shell scripts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
* Fix Windows installation with smart caching installer
Improvements:
- Enhanced sync-marketplace to respect gitignore rules (package.json)
- Added dynamic Python version detection in Windows help text (scripts/smart-install.js)
- Fixed hardcoded Python version message to show actual installed version
Technical changes:
- Modified package.json sync-marketplace script to use --filter=':- .gitignore' --exclude=.git
- Added runtime Python version detection in getWindowsErrorHelp function
- Improved user experience by showing actual Python installation status
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
---------
Co-authored-by: Claude <noreply@anthropic.com>
- Updated new-hook.js, save-hook.js, and summary-hook.js to enhance logging and session handling.
- Simplified session auto-creation logic in worker-service.ts to prioritize observation data preservation.
- Added a blocking wait in ensureWorkerRunning function to prevent race conditions during worker startup.
- Improved error handling and logging consistency across hooks.
- Refactored logging functionality in summary-hook.js to improve clarity and consistency.
- Added checks in worker-utils.ts to prevent unnecessary restarts of the worker service, ensuring it only starts if not already running.
- Updated `save-hook.js`, `summary-hook.js`, `context-hook.ts`, `new-hook.ts`, and `save-hook.ts` to include a call to `ensureWorkerRunning()` at the beginning of their main functions. This ensures that the worker is active before any operations are performed.
- Cleaned up import statements in the affected files to include the new utility function from `worker-utils.js`.
- Minor adjustments to logging and error handling to improve robustness and clarity.
- Removed ensureWorkerRunning calls from multiple hooks (cleanup, context, new, save, summary) to streamline code and avoid unnecessary checks.
- Introduced fixed port usage for worker communication across hooks.
- Enhanced error handling in newHook, saveHook, and summaryHook to provide clearer messages for worker connection issues.
- Updated worker service to start without health checks, relying on PM2 for management.
- Cached Claude executable path to optimize repeated calls.
- Improved logging for better traceability of worker actions and errors.
- Changed user prompt formatting to use full text instead of truncated version.
- Updated date filtering logic to use milliseconds instead of seconds for 90-day cutoff.
- Renamed doc_type values in ChromaSync to ensure consistency and prevent deduplication issues.
- Improved documentation for concept tags in input schema.
- Updated the StdioClientTransport configuration in search-server.ts to include 'stderr: ignore' for the Chroma client.
- Modified the ChromaSync class in ChromaSync.ts to also set 'stderr: ignore' when initializing the Chroma client.
- Implemented a new tool to search for observations using natural language and retrieve timeline context around the best match.
- Introduced two modes: "auto" for automatic timeline anchor selection and "interactive" for user selection of top matches.
- Added input schema validation using zod for query parameters including depth before/after, limit, and project filtering.
- Integrated hybrid semantic search with fallback to FTS5 for observation retrieval.
- Enhanced response formatting for both modes, including detailed timeline context and observation summaries.
- Added `getObservationById` method to retrieve observations by ID in SessionStore.
- Introduced `getSessionSummariesByIds` and `getUserPromptsByIds` methods for fetching session summaries and user prompts by IDs.
- Developed `getTimelineAroundTimestamp` and `getTimelineAroundObservation` methods to provide a unified timeline of observations, sessions, and prompts around a specified anchor point.
- Enhanced ChromaSync to format and sync user prompts, including a new `syncUserPrompt` method.
- Updated WorkerService to sync the latest user prompt to Chroma after updating the worker port.
- Created tests for timeline querying and MCP handler logic to ensure functionality.
- Documented the implementation plan for user prompts and timeline context tool in the Chroma search completion plan.
Changes:
- Updated legend to show only observation types (bugfix, feature, refactor, change, discovery, decision)
- Mapped each type to a color dot emoji (🔴 bugfix, 🟢 feature, 🔵 refactor, ⚪ change, 🟡 discovery, 🟤 decision)
- Removed concept-based filtering and icon selection
- Simplified progressive disclosure instructions to reference types instead of concepts
- All observations now shown in timeline (no concept filtering)
Technical details:
- Modified: src/hooks/context-hook.ts:203-207 (legend)
- Modified: src/hooks/context-hook.ts:210-223 (progressive disclosure text)
- Modified: src/hooks/context-hook.ts:344-369 (icon mapping switched from concepts to types)
- Modified: src/hooks/context-hook.ts:168-173 (removed concept filtering)
- Rebuilt: plugin/scripts/context-hook.js
Rationale: Types are mutually exclusive and core to categorization, while concepts are multi-select metadata better accessed through MCP search tools. This simplifies the display and reduces visual noise.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Features:
- New UsageLogger utility that writes usage metrics to daily JSONL files
- Captures token counts, costs, timing, and cache metrics from SDK result messages
- Usage logs stored in ~/.claude-mem/usage-logs/ (one file per day)
- Added analyze-usage.js script for analyzing usage patterns
Usage data captured:
- Token counts (input, output, cache creation, cache read)
- Total cost in USD per API call
- Duration metrics (total and API time)
- Number of turns per session
- Session and project attribution
Analysis script features:
- Aggregates totals by project and model
- Shows cache hit rates and savings
- Displays cost breakdowns and averages
- npm scripts: usage:analyze and usage:today
Files:
- src/utils/usage-logger.ts (new)
- src/services/worker-service.ts (modified - captures SDK result messages)
- scripts/analyze-usage.js (new)
- package.json (added usage:* npm scripts)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Built search-server.mjs successfully (55KB)
- Configured with packages: 'external' to use node_modules dependencies
- MCP config points to ${CLAUDE_PLUGIN_ROOT}/scripts/search-server.mjs
- Ready for deployment to plugin directory
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Changes:
- Renamed src/hooks/stderr-test-hook.ts to user-message-hook.ts
- Updated user-message-hook with production-ready messaging
- Updated scripts/build-hooks.js to build user-message-hook
- Updated plugin/hooks/hooks.json to reference user-message-hook.js
- Cleaned up old stderr-test-hook.js files
- Built and deployed user-message-hook.js to plugin directory
This hook displays context information to users via stderr, which is
currently the only way to show messages in Claude Code UI. It runs in
parallel with context-hook during SessionStart.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed bin/hooks/ wrapper layer
- Moved all hook logic into consolidated hooks/*-hook.ts files
- Each hook now handles its own stdin/stdout/JSON wrapping
- Removed ALL try-catch blocks from context-hook (let errors surface)
- Updated build script to reference new src/hooks/ paths
- Reduced from 12+ files to 6 hook files
This simplifies the architecture and makes debugging actually possible.
- Wrap stdin event handler in try/catch to catch async errors
- Output errors to stdout so Claude can see them
- Show input preview and stack trace for debugging
- Remove outer try/catch that wasn't catching async errors
- Updated logic to retrieve recent summaries and observations, focusing on the last 4 summaries for better context.
- Simplified the extraction of unique session IDs from the recent summaries.
- Enhanced the timeline rendering to include both observations and summaries, grouped by day and file.
- Removed redundant queries for recent summaries and observations, streamlining the data retrieval process.
- Improved output formatting for better readability, including color-coded sections and clearer headers.
- Added detailed display of the most recent session's completed status and next steps.
- Introduced new helper functions for parsing JSON, formatting dates, and estimating token counts.
- Implemented retrieval of recent session IDs and observations from the database.
- Added filtering of observations based on key concepts for a more relevant timeline.
- Enhanced output formatting to include a chronological timeline of recent activities grouped by day and file.
- Included a legend for better understanding of the timeline icons.
- Displayed recent session summaries with improved formatting and details.
- Added footer instructions for accessing records via MCP search.
Critical bugfix for NOT NULL constraint violation.
Problem:
- Worker service calls getSessionById(sessionDbId) to fetch session data
- Worker then uses dbSession.claude_session_id to create ActiveSession
- But getSessionById was NOT selecting claude_session_id from database
- Result: claudeSessionId = undefined in worker
- Caused: "NOT NULL constraint failed: sdk_sessions.claude_session_id" errors
- Impact: Observations and summaries couldn't be stored
Root cause:
- SessionStore.getSessionById() SQL query missing claude_session_id column
- Line 710-713: "SELECT id, sdk_session_id, project, user_prompt"
- Should be: "SELECT id, claude_session_id, sdk_session_id, project, user_prompt"
Fix:
- Added claude_session_id to SELECT query in getSessionById
- Updated return type to include claude_session_id: string
- Now worker correctly receives claude_session_id from database
- Session ID from hook flows properly through entire system
Files changed:
- src/services/sqlite/SessionStore.ts (getSessionById method)
Testing:
- Build succeeded
- Ready for PM2 restart and live testing
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Updated session initialization to retrieve claude_session_id instead of sdk_session_id.
- Removed redundant comments and code related to sdk_session_id handling.
- Simplified session creation logic by directly using values from the database.
- Cleaned up message handling logic to focus on assistant messages and removed unnecessary checks for system init messages.
- Added logging of received content length and a preview for debugging purposes.
- Introduced detailed logging for summary parsing, including flags for summary components.
- Improved warning logging when no summary tags are found, including a content sample.
- Updated success message for stored summaries to be more descriptive.
Improvements:
- Enhanced null handling for empty/whitespace fields
- Ensures clean null values in database instead of empty strings
- Improves query efficiency and data consistency
Testing:
- Added comprehensive regression test suite (49 tests)
- Tests v4.2.5 summary fixes and v4.2.6 observation fixes
- Tests edge cases: missing fields, empty fields, whitespace
- New test script: npm run test:parser
- All tests passing with 100% coverage
Code Quality:
- Removed unused extractFileArray() function
- Improved function documentation
- TypeScript diagnostics clean
Technical Details:
- Updated src/sdk/parser.ts extractField function
- Created src/sdk/parser.test.ts regression test suite
- Updated package.json to v4.2.7
- Updated CLAUDE.md with version history
- All changes backward compatible
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Critical Bugfix:
- Fixed overly defensive observation validation blocking observations from being saved
- Parser now NEVER skips observations - always saves them
- Invalid or missing type defaults to "change" (generic catch-all type)
- Removed validation requiring title, subtitle, and narrative fields
- Prevents critical data loss - partial observations better than no observations
Impact:
- Before: Missing title, subtitle, OR narrative caused entire observation to be discarded
- After: ALL observations preserved regardless of field completeness
- Even partial observations contain valuable data: concepts, files_read, files_modified, facts
- LLMs make mistakes - system must be resilient and save everything
- Consistent with v4.2.5 summary fix
Technical changes:
- Updated src/sdk/parser.ts:52-67 to never skip observations
- Uses "change" as fallback type for invalid/missing types (no schema change)
- Updated ParsedObservation interface to allow null for title, subtitle, narrative
- Updated SessionStore.storeObservation signature to accept nullable fields
- Updated built worker-service.cjs
- Bumped version to 4.2.6 in all metadata files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Removed validation for required fields in parseSummary function.
- Added a note emphasizing the importance of saving the summary even if some fields are missing.
Improvements:
- Removed optional skip_summary functionality (summaries now always generated)
- Clarified that summaries are mid-session checkpoints, not session endings
- Improved request field instructions to better form descriptive titles
- Changed wording from "discovered" to "learned" for consistency
Technical changes:
- Updated src/sdk/prompts.ts summary prompt
- Removed "WHEN NOT TO SUMMARIZE" section
- Added clarifying footer text about ongoing sessions
- Updated built worker-service.cjs
- Bumped version to 4.2.4 in all metadata files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Alex Newman