Skip to content

CLAUDE.md

Latest commit

 

History

History
100 lines (70 loc) · 4.38 KB

CLAUDE.md

File metadata and controls

100 lines (70 loc) · 4.38 KB

CLAUDE.md

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

Project Overview

Xcho is a Chrome extension that generates AI-powered reply suggestions for X (Twitter). It uses Google Gemini API to create personalized, authentic-sounding comments based on selected tweets.

Build Commands

npm install          # Install dependencies
npm run dev          # Development mode with hot reload
npm run build        # Production build (outputs to dist/)

After building, load the extension in Chrome:

  1. Navigate to chrome://extensions/
  2. Enable "Developer mode"
  3. Click "Load unpacked" and select the dist folder

Test Commands

npm test             # Run all tests once
npm run test:watch   # Watch mode during development

Test Architecture

  • Framework: Vitest with jsdom environment
  • Setup: tests/setup.ts provides global Chrome API mocks
  • Mocks: tests/mocks/chrome.ts (storage mock factory), tests/mocks/gemini.ts (Gemini SDK mock)
  • Tests: tests/utils/ contains tests for gemini.ts, storage.ts, persona.ts

Documentation

Architecture

Chrome Extension Structure (Manifest V3)

The extension uses three interconnected components that communicate via Chrome's messaging API:

  1. Content Script (src/content/index.ts)

    • Injected into x.com/twitter.com pages
    • Detects tweet clicks and extracts tweet data using DOM selectors ([data-testid="tweetText"], [data-testid="User-Name"])
    • Handles both timeline view (article elements) and detail page (direct extraction)
    • Uses MutationObserver to detect SPA navigation (URL changes)

  2. Background Service Worker (src/background/index.ts)

    • Manages side panel lifecycle
    • Caches tweet data per tab (Map<tabId, TweetData>) to handle timing issues between content script and side panel
    • Cleans up cache when tabs close

  3. Side Panel UI (src/sidepanel/App.tsx)

    • React-based UI for comment generation
    • Requests cached tweet data from background on mount (handles race conditions)
    • Settings modal for API key and persona configuration

Message Flow

User clicks tweet → Content Script extracts data → sends TWEET_CLICKED message
→ Background caches data + opens side panel → Side panel requests GET_CURRENT_TWEET
→ Background returns cached data → UI displays tweet + generation options

Caching Strategy

  • Per-tab tweet cache: Background stores latest tweet per tab in chrome.storage.session (keyed by tabId, cleaned on tab close)
  • Per-tweet results cache: Side panel caches generated comments per tweet in chrome.storage.session (LRU eviction at 10 entries, keyed by first 200 chars of tweet text)
  • Translation cache: In-memory Map via React useRef (keyed by first 100 chars of tweet text, lives for session duration)
  • Session state: Side panel state persisted to chrome.storage.session for survival across panel close/reopen

Key Utilities

  • src/utils/gemini.ts: LLM integration with structured prompting (role/goal/context/constraints pattern), token tracking, and cost calculation
  • src/utils/persona.ts: Writing style analysis from uploaded documents, extracts formality/directness/humor traits
  • src/utils/storage.ts: Typed wrapper around chrome.storage.local

Type Definitions

All shared types are in src/types/index.ts including TweetData, PersonaData, MessagePayload, and token/cost tracking interfaces.

Extension Debugging

See DEBUGGING.md for step-by-step debugging guide. Key debugging points:

  • Content script: Check X.com page console for emoji-prefixed logs
  • Background worker: Click "service worker" link in chrome://extensions/
  • Side panel: Right-click inside panel → Inspect

Configuration

  • Gemini API key stored in chrome.storage.local
  • Default model: gemini-3-flash-preview (configurable via UI, defined in gemini.ts)
  • Model pricing defined in MODEL_PRICING constant for cost tracking