claude-brain 0.5.0 → 0.8.0

package/packs/frontend/react.json

@@ -0,0 +1,254 @@
+{
+  "id": "frontend/react",
+  "name": "React Patterns & Pitfalls",
+  "version": "1.0.0",
+  "stack": ["react", "next.js", "remix", "gatsby"],
+  "description": "Hooks pitfalls, state management decisions, performance optimization, and component patterns",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Avoid infinite loops with useEffect dependencies",
+      "content": "Objects, arrays, and functions created during render are new references each time. Including them in useEffect deps causes infinite re-renders. Use useMemo/useCallback to stabilize references, or restructure to use primitive deps.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "useEffect", "performance"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Hooks",
+      "title": "Don't use useEffect for derived state",
+      "content": "Don't use useEffect to sync state derived from other state or props. Calculate it during render instead. useEffect for derived state adds unnecessary re-renders and complexity.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "useEffect", "state"],
+      "example": "// Bad: useEffect(() => setFullName(first + last), [first, last])\n// Good: const fullName = first + ' ' + last"
+    },
+    {
+      "type": "best-practice",
+      "category": "State Management",
+      "title": "Lift state up only as far as needed",
+      "content": "Keep state as close to where it's used as possible. Only lift state to a common parent when multiple siblings need it. Over-lifting state to the top causes unnecessary re-renders.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "architecture"]
+    },
+    {
+      "type": "pattern",
+      "category": "State Management",
+      "title": "Use useReducer for complex state logic",
+      "content": "When state updates depend on previous state or involve multiple related values, useReducer provides clearer intent and easier testing than multiple useState calls.",
+      "confidence": 0.85,
+      "tags": ["react", "hooks", "useReducer", "state"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Stale closures in event handlers and effects",
+      "content": "Event handlers and effects capture the state/props from the render they were created in. Use refs for values that need to be always-current in callbacks, or ensure proper dependency arrays.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "closures", "stale-state"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Use React.memo sparingly and with profiling",
+      "content": "React.memo prevents re-renders when props haven't changed, but adds comparison overhead. Only use it when profiling shows a component re-renders frequently with the same props.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "memo"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Use key prop correctly for list rendering",
+      "content": "Always use stable, unique keys for list items. Never use array index as key if the list can be reordered, filtered, or items inserted. Bad keys cause incorrect DOM reuse and state bugs.",
+      "confidence": 0.95,
+      "tags": ["react", "performance", "keys", "lists"]
+    },
+    {
+      "type": "pattern",
+      "category": "Components",
+      "title": "Composition over prop drilling",
+      "content": "Use component composition (children, render props, compound components) to avoid passing props through multiple intermediate layers. This keeps components focused and reduces coupling.",
+      "confidence": 0.9,
+      "tags": ["react", "composition", "patterns"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Components",
+      "title": "Avoid defining components inside other components",
+      "content": "Never define a component inside another component's render. This creates a new component type each render, causing full unmount/remount and losing all state. Define components at module scope.",
+      "confidence": 0.95,
+      "tags": ["react", "components", "performance"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Hooks",
+      "title": "Extract custom hooks for reusable logic",
+      "content": "Extract shared stateful logic into custom hooks (useXyz). Custom hooks compose well, are independently testable, and keep components focused on rendering.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "custom-hooks", "reuse"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Follow the Rules of Hooks",
+      "content": "Hooks must be called at the top level (not inside conditions, loops, or nested functions) and only from React function components or custom hooks. Violating this causes incorrect hook state association.",
+      "confidence": 0.95,
+      "tags": ["react", "hooks", "rules"]
+    },
+    {
+      "type": "pattern",
+      "category": "Data Fetching",
+      "title": "Use a data fetching library over raw useEffect",
+      "content": "Use React Query (TanStack Query), SWR, or your framework's data fetching solution instead of raw useEffect + fetch. These handle caching, deduplication, race conditions, and background refetching.",
+      "confidence": 0.9,
+      "tags": ["react", "data-fetching", "react-query", "swr"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "State Management",
+      "title": "Avoid mirroring props in state",
+      "content": "Don't copy props into state with useState. The state won't update when props change unless you add a useEffect to sync them. Use props directly, or derive values during render.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "props", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Performance",
+      "title": "Lazy load routes and heavy components",
+      "content": "Use React.lazy() and Suspense for code splitting. Lazy load routes and heavy components (charts, editors, modals) to reduce initial bundle size and improve time-to-interactive.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "lazy-loading", "code-splitting"]
+    },
+    {
+      "type": "pattern",
+      "category": "Error Handling",
+      "title": "Use Error Boundaries for resilient UI",
+      "content": "Wrap sections of your UI with Error Boundaries to catch rendering errors and show fallback UI instead of crashing the entire app. Place boundaries at route level and around risky components.",
+      "confidence": 0.9,
+      "tags": ["react", "error-handling", "error-boundary"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Hooks",
+      "title": "Use useCallback for stable event handlers",
+      "content": "Wrap event handler functions in useCallback when passing them to memoized children or using them in effect dependency arrays. This prevents unnecessary re-renders of child components.",
+      "confidence": 0.85,
+      "tags": ["react", "hooks", "useCallback", "performance"]
+    },
+    {
+      "type": "common-issue",
+      "category": "State Management",
+      "title": "Batching state updates",
+      "content": "React 18+ automatically batches state updates in event handlers, timeouts, promises, and native events. Multiple setState calls in one function only trigger one re-render.",
+      "confidence": 0.85,
+      "tags": ["react", "state", "batching", "react-18"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "State Management",
+      "title": "Avoid excessive global state",
+      "content": "Don't put everything in global state (Redux/Context). Server data belongs in a cache layer (React Query). UI state should be local. Only truly global state (auth, theme) needs a global store.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "redux", "context"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Components",
+      "title": "Keep components small and focused",
+      "content": "Each component should do one thing well. If a component file exceeds 200 lines, it likely handles too many concerns. Extract sub-components, custom hooks, or utility functions.",
+      "confidence": 0.85,
+      "tags": ["react", "components", "architecture"]
+    },
+    {
+      "type": "pattern",
+      "category": "Forms",
+      "title": "Use controlled components for forms",
+      "content": "Prefer controlled components (state-driven) for forms. Use a form library (React Hook Form, Formik) for complex forms with validation, arrays, and dynamic fields.",
+      "confidence": 0.85,
+      "tags": ["react", "forms", "controlled-components"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Accessibility",
+      "title": "Use semantic HTML and ARIA attributes",
+      "content": "Use semantic HTML elements (button, nav, main, article) over generic divs. Add ARIA labels for interactive elements. Ensure keyboard navigation works for all interactive components.",
+      "confidence": 0.9,
+      "tags": ["react", "accessibility", "a11y", "html"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Hooks",
+      "title": "Clean up effects to prevent memory leaks",
+      "content": "Always return a cleanup function from useEffect when subscribing to events, setting up intervals, or creating observers. Forgetting cleanup causes memory leaks and stale callbacks.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "useEffect", "cleanup"],
+      "example": "useEffect(() => { const id = setInterval(fn, 1000); return () => clearInterval(id); }, [])"
+    },
+    {
+      "type": "pattern",
+      "category": "Performance",
+      "title": "Virtualize long lists",
+      "content": "For lists with hundreds or thousands of items, use virtualization (react-window, react-virtuoso, TanStack Virtual) to render only visible items. This dramatically improves scroll performance.",
+      "confidence": 0.9,
+      "tags": ["react", "performance", "virtualization", "lists"]
+    },
+    {
+      "type": "best-practice",
+      "category": "State Management",
+      "title": "Use server state libraries for API data",
+      "content": "Treat server data as a cache, not as state. Libraries like TanStack Query manage caching, invalidation, background updates, and optimistic updates. This removes most useState/useEffect for data fetching.",
+      "confidence": 0.9,
+      "tags": ["react", "state", "server-state", "caching"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Hooks",
+      "title": "Avoid useEffect as an event handler",
+      "content": "Don't use useEffect to respond to user events (clicks, form submissions). Handle events directly in event handlers. useEffect is for synchronizing with external systems, not for responding to events.",
+      "confidence": 0.9,
+      "tags": ["react", "hooks", "useEffect", "events"]
+    },
+    {
+      "type": "pattern",
+      "category": "Components",
+      "title": "Use compound components for flexible APIs",
+      "content": "For complex UI components (tabs, dropdowns, accordions), use the compound component pattern with React Context. This gives consumers flexible control over rendering while keeping logic encapsulated.",
+      "confidence": 0.85,
+      "tags": ["react", "components", "compound-components", "patterns"],
+      "example": "<Tabs>\n  <Tabs.List>\n    <Tabs.Tab>One</Tabs.Tab>\n  </Tabs.List>\n  <Tabs.Panel>Content</Tabs.Panel>\n</Tabs>"
+    },
+    {
+      "type": "best-practice",
+      "category": "TypeScript",
+      "title": "Type component props with interfaces",
+      "content": "Define component props as interfaces or types. Use React.FC sparingly (it adds implicit children). Prefer explicit prop typing with destructuring in the function signature.",
+      "confidence": 0.85,
+      "tags": ["react", "typescript", "props", "typing"],
+      "example": "interface ButtonProps { label: string; onClick: () => void }\nfunction Button({ label, onClick }: ButtonProps) { ... }"
+    },
+    {
+      "type": "common-issue",
+      "category": "Performance",
+      "title": "Avoid creating new objects in JSX props",
+      "content": "Inline objects and arrays in JSX (`style={{ color: 'red' }}`, `data={[1,2,3]}`) create new references each render. Move static values outside the component or use useMemo for dynamic ones.",
+      "confidence": 0.85,
+      "tags": ["react", "performance", "rendering"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Testing",
+      "title": "Test behavior, not implementation",
+      "content": "Test what the user sees and interacts with, not component internals. Use React Testing Library to query by role, text, and labels. Avoid testing state values or implementation details directly.",
+      "confidence": 0.9,
+      "tags": ["react", "testing", "react-testing-library"]
+    },
+    {
+      "type": "pattern",
+      "category": "Hooks",
+      "title": "Use useId for accessibility IDs",
+      "content": "Use React.useId() to generate stable, unique IDs for accessibility attributes (htmlFor, aria-describedby). This works correctly with server-side rendering unlike random ID generation.",
+      "confidence": 0.8,
+      "tags": ["react", "hooks", "accessibility", "ssr"]
+    }
+  ]
+}

package/packs/meta/testing.json

@@ -0,0 +1,172 @@
+{
+  "id": "meta/testing",
+  "name": "Testing Best Practices",
+  "version": "1.0.0",
+  "stack": ["jest", "vitest", "mocha", "bun:test", "testing"],
+  "description": "Test pyramid, mocking strategies, anti-patterns, arrange-act-assert, and testing philosophy",
+  "author": "claude-brain",
+  "entries": [
+    {
+      "type": "best-practice",
+      "category": "Test Structure",
+      "title": "Follow Arrange-Act-Assert pattern",
+      "content": "Structure every test in three clear phases: Arrange (set up data and dependencies), Act (call the code under test), Assert (verify the result). This makes tests readable and consistent.",
+      "confidence": 0.95,
+      "tags": ["testing", "aaa", "structure"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Strategy",
+      "title": "Follow the testing pyramid",
+      "content": "Write many fast unit tests, fewer integration tests, and minimal E2E tests. Unit tests catch logic bugs cheaply. Integration tests verify component interaction. E2E tests validate critical user journeys.",
+      "confidence": 0.95,
+      "tags": ["testing", "pyramid", "strategy"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Test Design",
+      "title": "Avoid testing implementation details",
+      "content": "Test behavior and outcomes, not internal implementation. Tests that verify private methods, internal state, or specific function calls break when refactoring even if behavior is unchanged.",
+      "confidence": 0.95,
+      "tags": ["testing", "behavior", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Design",
+      "title": "Each test should test one thing",
+      "content": "Keep tests focused on a single behavior or scenario. Multiple assertions are fine if they verify aspects of the same behavior. Avoid testing multiple unrelated behaviors in one test.",
+      "confidence": 0.9,
+      "tags": ["testing", "single-responsibility", "design"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Mocking",
+      "title": "Don't over-mock",
+      "content": "Only mock external dependencies (APIs, databases, file system). Don't mock the code under test or internal modules. Over-mocking makes tests pass even when the real code is broken.",
+      "confidence": 0.9,
+      "tags": ["testing", "mocking", "integration"]
+    },
+    {
+      "type": "pattern",
+      "category": "Mocking",
+      "title": "Use dependency injection for mockable code",
+      "content": "Pass dependencies as parameters instead of importing them directly. This makes functions testable without module-level mocking, which is fragile and order-dependent.",
+      "confidence": 0.9,
+      "tags": ["testing", "mocking", "dependency-injection"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Design",
+      "title": "Write descriptive test names",
+      "content": "Test names should describe the scenario and expected outcome: 'should return 404 when user does not exist' is better than 'test getUser'. Good names serve as documentation.",
+      "confidence": 0.9,
+      "tags": ["testing", "naming", "documentation"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Test Design",
+      "title": "Avoid test interdependence",
+      "content": "Each test must be independent and able to run in isolation. Never rely on test execution order or shared mutable state between tests. Use beforeEach to reset state.",
+      "confidence": 0.95,
+      "tags": ["testing", "isolation", "anti-pattern"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Async Testing",
+      "title": "Always await async assertions",
+      "content": "Forgetting to await async operations in tests causes false positives — the test passes before assertions run. Always return or await promises, and use the test framework's async utilities.",
+      "confidence": 0.9,
+      "tags": ["testing", "async", "promises"]
+    },
+    {
+      "type": "pattern",
+      "category": "Test Data",
+      "title": "Use factories for test data",
+      "content": "Create factory functions that generate test data with sensible defaults and overrides. This reduces boilerplate, keeps tests focused on what's relevant, and makes it easy to create variations.",
+      "confidence": 0.85,
+      "tags": ["testing", "data", "factories"],
+      "example": "function createUser(overrides = {}) { return { name: 'Test', email: 'test@test.com', ...overrides } }"
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Maintenance",
+      "title": "Keep tests fast",
+      "content": "Fast tests get run often. Avoid real network calls, file I/O, and sleeps in unit tests. Use in-memory alternatives and mock external services. A slow test suite leads to developers skipping tests.",
+      "confidence": 0.9,
+      "tags": ["testing", "performance", "speed"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Test Design",
+      "title": "Avoid snapshot overuse",
+      "content": "Snapshot tests are easy to write but hard to maintain. Large snapshots are never reviewed when updated. Use snapshots sparingly for stable output (serialized data, error messages), not for entire component trees.",
+      "confidence": 0.85,
+      "tags": ["testing", "snapshots", "anti-pattern"]
+    },
+    {
+      "type": "pattern",
+      "category": "Error Testing",
+      "title": "Test error cases and edge cases",
+      "content": "Don't only test the happy path. Test invalid input, empty data, null values, boundary conditions, and error responses. Error handling code has bugs too — verify it works correctly.",
+      "confidence": 0.9,
+      "tags": ["testing", "error-cases", "edge-cases"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Strategy",
+      "title": "Use integration tests for API endpoints",
+      "content": "Test API endpoints with real HTTP requests against the actual server (with mocked external services). This verifies routing, middleware, validation, and response formatting together.",
+      "confidence": 0.85,
+      "tags": ["testing", "integration", "api"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Mocking",
+      "title": "Reset mocks between tests",
+      "content": "Always clear mock state between tests using beforeEach, afterEach, or the framework's auto-clear feature. Leftover mock state from previous tests causes intermittent failures.",
+      "confidence": 0.9,
+      "tags": ["testing", "mocking", "cleanup"]
+    },
+    {
+      "type": "anti-pattern",
+      "category": "Test Design",
+      "title": "Avoid conditional logic in tests",
+      "content": "Tests should not contain if/else, loops, or try/catch. Each test should follow a straight-line path. If you need different scenarios, write separate tests for each.",
+      "confidence": 0.9,
+      "tags": ["testing", "simplicity", "anti-pattern"]
+    },
+    {
+      "type": "best-practice",
+      "category": "Coverage",
+      "title": "Use coverage as a guide, not a goal",
+      "content": "Code coverage measures lines executed, not quality of assertions. 100% coverage with weak assertions is worse than 80% coverage with thorough behavior tests. Focus on testing critical paths well.",
+      "confidence": 0.9,
+      "tags": ["testing", "coverage", "quality"]
+    },
+    {
+      "type": "pattern",
+      "category": "Test Organization",
+      "title": "Group tests by behavior with describe blocks",
+      "content": "Use nested describe blocks to group related tests: by function/method, then by scenario. This creates readable test output and makes it easy to find and run specific test groups.",
+      "confidence": 0.85,
+      "tags": ["testing", "organization", "describe"],
+      "example": "describe('UserService', () => {\n  describe('createUser', () => {\n    it('should create with valid data', ...)\n    it('should reject duplicate email', ...)\n  })\n})"
+    },
+    {
+      "type": "best-practice",
+      "category": "Test Design",
+      "title": "Assert on the most specific thing",
+      "content": "Use the most specific assertion available. `toBe(3)` is better than `toBeGreaterThan(0)`. `toEqual({name: 'test'})` is better than `toBeTruthy()`. Specific assertions catch bugs that general ones miss.",
+      "confidence": 0.85,
+      "tags": ["testing", "assertions", "specificity"]
+    },
+    {
+      "type": "common-issue",
+      "category": "Flaky Tests",
+      "title": "Eliminate time-dependent tests",
+      "content": "Tests that depend on wall clock time, setTimeout delays, or Date.now() are inherently flaky. Use fake timers (jest.useFakeTimers, vi.useFakeTimers) to control time in tests.",
+      "confidence": 0.9,
+      "tags": ["testing", "flaky", "timers"]
+    }
+  ]
+}

package/src/cli/bin.ts

@@ -33,6 +33,8 @@ function printHelp() {
     ['uninstall', 'Remove MCP server from Claude Code'],
     ['update', 'Update package and refresh CLAUDE.md'],
     ['chroma', 'Manage ChromaDB server (start/stop/status)'],
+    ['hooks', 'Manage passive learning hooks (install/uninstall/status)'],
+    ['pack', 'Manage knowledge packs (list/status/reload)'],
     ['health', 'Run health checks'],
     ['diagnose', 'Run diagnostics'],
     ['version', 'Show version'],
@@ -116,6 +118,18 @@ async function main() {
       break
     }
 
+    case 'hooks': {
+      const { runHooks } = await import('./commands/hooks')
+      await runHooks()
+      break
+    }
+
+    case 'pack': {
+      const { runPack } = await import('./commands/pack')
+      await runPack()
+      break
+    }
+
     case 'health': {
       const { runHealthCheck } = await import('@/health')
       await runHealthCheck()

package/src/cli/commands/chroma.ts

@@ -29,25 +29,53 @@ function getChromaDataPath(): string {
  * Find the chroma binary - checks PATH first, then common pip install locations
  */
 function findChromaBinary(): string | null {
+  const isWindows = process.platform === 'win32'
+  const chromaName = isWindows ? 'chroma.exe' : 'chroma'
+
   // Try bare 'chroma' first (on PATH)
   try {
     execSync('chroma --version', { stdio: 'pipe', timeout: 5000 })
     return 'chroma'
   } catch {}
 
-  // Search common pip install locations
   const { homedir } = require('os')
   const home = homedir()
-  const candidates = [
-    join(home, 'Library', 'Python', '3.9', 'bin', 'chroma'),
-    join(home, 'Library', 'Python', '3.10', 'bin', 'chroma'),
-    join(home, 'Library', 'Python', '3.11', 'bin', 'chroma'),
-    join(home, 'Library', 'Python', '3.12', 'bin', 'chroma'),
-    join(home, 'Library', 'Python', '3.13', 'bin', 'chroma'),
-    join(home, '.local', 'bin', 'chroma'),
-    '/usr/local/bin/chroma',
-    '/opt/homebrew/bin/chroma',
-  ]
+
+  // Platform-specific search paths
+  const candidates: string[] = isWindows
+    ? [
+        // Windows pip install locations
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Local', 'Programs', 'Python', 'Python313', 'Scripts', chromaName),
+        // Windows user pip install (pip install --user)
+        join(home, 'AppData', 'Roaming', 'Python', 'Python39', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python310', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python311', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python312', 'Scripts', chromaName),
+        join(home, 'AppData', 'Roaming', 'Python', 'Python313', 'Scripts', chromaName),
+        // Scoop / Chocolatey / winget
+        join(home, 'scoop', 'shims', chromaName),
+        'C:\\Python39\\Scripts\\' + chromaName,
+        'C:\\Python310\\Scripts\\' + chromaName,
+        'C:\\Python311\\Scripts\\' + chromaName,
+        'C:\\Python312\\Scripts\\' + chromaName,
+        'C:\\Python313\\Scripts\\' + chromaName,
+      ]
+    : [
+        // macOS pip install locations
+        join(home, 'Library', 'Python', '3.9', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.10', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.11', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.12', 'bin', chromaName),
+        join(home, 'Library', 'Python', '3.13', 'bin', chromaName),
+        // Linux pip install locations
+        join(home, '.local', 'bin', chromaName),
+        '/usr/local/bin/' + chromaName,
+        '/opt/homebrew/bin/' + chromaName,
+      ]
 
   for (const candidate of candidates) {
     try {
@@ -58,15 +86,23 @@ function findChromaBinary(): string | null {
     } catch {}
   }
 
-  // Try finding via python -m site
+  // Try finding via python -m site (works on all platforms)
+  const pythonCmd = isWindows ? 'python' : 'python3'
   try {
-    const sitePackages = execSync('python3 -c "import site; print(site.getusersitepackages())"', {
+    const sitePackages = execSync(`${pythonCmd} -c "import site; print(site.getusersitepackages())"`, {
       encoding: 'utf-8', stdio: 'pipe', timeout: 5000
     }).trim()
-    // User site-packages is like /Users/x/Library/Python/3.9/lib/python/site-packages
-    // The bin is at the same level as lib
-    const binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
-    const chromaPath = join(binDir, 'chroma')
+
+    let binDir: string
+    if (isWindows) {
+      // Windows: C:\Users\x\AppData\Roaming\Python\Python311\site-packages → Scripts
+      binDir = sitePackages.replace(/[\\\/]site-packages$/, '\\Scripts')
+    } else {
+      // Unix: /Users/x/Library/Python/3.9/lib/python/site-packages → bin
+      binDir = sitePackages.replace(/\/lib\/.*/, '/bin')
+    }
+
+    const chromaPath = join(binDir, chromaName)
     if (existsSync(chromaPath)) {
       execSync(`"${chromaPath}" --version`, { stdio: 'pipe', timeout: 5000 })
       return chromaPath