Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (54 loc) · 3.32 KB

CLAUDE.md

File metadata and controls

73 lines (54 loc) · 3.32 KB

CLAUDE.md

Project overview

screenpipe-ui is a community-built, open-source UI for screenpipe (AI screen & audio memory tool). Three interfaces share one TypeScript/Bun codebase: CLI commands, interactive TUI, and a web SPA.

Architecture

packages/
  core/      Framework-agnostic: REST client, Zustand vanilla stores, formatters
  react/     React hooks bridging core stores via useSyncExternalStore
  cli/       Commander.js commands — no React, calls core directly
  tui/       Ink (React for terminals) interactive app
  web/       Vite + React + Tailwind SPA

Key design: Zustand vanilla stores (createStore(), not create()) are framework-agnostic. CLI uses .getState() imperatively. TUI and Web subscribe reactively via shared React hooks.

Commands

bun install          # install all dependencies
bun run build        # build all packages (tsup + vite)
bun test --recursive # run all tests (60+ tests across 6 files)
bun cli <command>    # run CLI commands (search, health, activity)
bun tui              # launch interactive TUI
bun web              # start web dev server

Code conventions

  • Runtime: Bun for all commands (install, test, build, dev)
  • Module format: ESM only ("type": "module" everywhere)
  • Imports: Use import type for type-only imports
  • Stores: Use createStore() from zustand/vanilla, not create() — stores must work without React
  • Store actions: Take client: ScreenpipeUIClient as parameter, don't store it in state
  • Client: Custom ScreenpipeUIClient with raw fetch (the published @screenpipe/js SDK is designed for pipes/plugins, not external apps)
  • Build tool: tsup for libraries (core, react, cli, tui), Vite for web
  • Testing: bun test with bun:test built-in runner; happy-dom for React hook tests
  • Web resolves workspace packages via Vite aliases to source (not dist) for HMR

Testing requirements

All changes must include tests. Before claiming work is complete, run bun test --recursive and ensure all tests pass.

  • New behavior: Add tests that cover the new logic. Place tests next to source (e.g. __tests__/*.test.ts) or in package test directories.
  • Bug fixes: Add or extend a test that reproduces the bug and asserts the fix.
  • Refactors: Update existing tests if behavior changes; add tests for any newly exposed behavior.
  • Packages: Tests live per package — core, react, cli, etc. each have their own __tests__ or *.test.ts files.
  • Verification: Never claim tests pass without running bun test --recursive and confirming success in the output.

Key types

  • ContentItem — union type: OCR | Audio | UI (no "Input" type in published SDK)
  • ScreenpipeQueryParams — search parameters from @screenpipe/js
  • ScreenpipeResponse — search response with data: ContentItem[] and pagination
  • HealthCheckResponse — health status with status, frame_status, audio_status

Package dependencies

cli  → core
tui  → core, react
web  → core, react
react → core

Publishing

Packages publish to npm under @screenpipe-ui/* org. Publish in dependency order: core → react → cli, tui. Web is private: true (not published).

Workspace dependencies (workspace:*) are resolved to actual versions at publish time.