Codebase file structure and descriptions.
| File | Description |
|---|---|
index.html |
Vite entry point HTML file |
package.json |
Dependencies and scripts |
vite.config.ts |
Vite bundler configuration |
tsconfig.json |
TypeScript configuration |
tsconfig.node.json |
TypeScript config for Node tooling |
tailwind.config.js |
Tailwind CSS configuration |
postcss.config.js |
PostCSS configuration |
netlify.toml |
Netlify deployment config with SPA redirect rules |
vercel.json |
Vercel deployment config with SPA rewrite rules for one-click deploy |
ONE-CLICK-DEPLOY.md |
Post-deploy checklist for users who one-click deployed to Vercel or Netlify |
README.md |
Project documentation with Ecosystem table (official + community plugins including codex-sync) |
install.md |
AI agent installation instructions following install.md spec for self-hosting setup |
Backend functions and schema.
| File | Description |
|---|---|
schema.ts |
Database schema: users (with enabledAgents for CLI tool preferences, deletion tracking fields: deletionStatus, deletionStartedAt, deletionCompletedAt, deletionError, deletionProgress), sessions (with eval fields: evalReady, reviewedAt, evalNotes, evalTags, evalStatus (golden/correct/incorrect/needs_review), expectedOutput, detectedLanguage; indexes: by_user_eval_status), messages, parts, sessionEmbeddings, messageEmbeddings, apiLogs, dailyWrapped (for Daily Sync Wrapped feature with 24h expiry) |
auth.config.ts |
WorkOS JWT validation configuration |
convex.config.ts |
Convex app configuration |
users.ts |
User queries/mutations: getOrCreate, me (returns enabledAgents with cursor->cursor-sync normalization, deletionStatus/deletionProgress for reactive UI), stats, API key management, updateEnabledAgents (normalizes cursor->cursor-sync), deleteAllData (initiates batch deletion via orchestrateBatchDeletion), deleteAccount (initiates batch deletion then deletes WorkOS account), clearDeletionStatus. Batch deletion system: orchestrateBatchDeletion (internalAction orchestrator), updateDeletionStatus, deletePartsBatch, deleteMessagesBatch, deleteSessionsBatch, deleteSessionEmbeddingsBatch, deleteMessageEmbeddingsBatch, deleteDailyWrappedBatch, deleteApiLogsBatch, deleteUserRecord, initiateDeletion. All batch mutations use BATCH_SIZE=200 to stay under 4096 read limit. |
sessions.ts |
Session CRUD: list, get, getPublic, setVisibility, remove, getMarkdown, upsert (with 10s dedup window, idempotency, cursor->cursor-sync normalization, optional createdAt for timestamp preservation), batchUpsert (with source normalization), listExternalIds, exportAllDataCSV |
messages.ts |
Message mutations: upsert (with 5s dedup, combined session patch, parallel parts ops, cursor->cursor-sync normalization, optional createdAt for timestamp preservation), batchUpsert for bulk sync (with source normalization). Message handlers only update messageCount and searchableText on sessions; token values (promptTokens, completionTokens, totalTokens) are set exclusively by session-level sync to avoid double-counting (fixes #32). |
analytics.ts |
Analytics queries with source filtering: dailyStats, modelStats, projectStats, providerStats, summaryStats, sessionsWithDetails, sourceStats, publicPlatformStats (no auth, for homepage leaderboard, limited to last 1000 sessions with null-safe token handling), publicMessageCount (no auth, uses async iteration for large datasets), publicMessageGrowth (no auth, daily growth with cumulative totals, uses async iteration to avoid 16MB read limit). Includes inferProvider helper with OAuth provider normalization (antigravity-oauth to google, anthropic-oauth to anthropic) and model-based provider detection (including Codex models mapped to openai) |
search.ts |
Full-text and semantic search: searchSessions, searchSessionsPaginated, searchMessages, searchMessagesPaginated, semanticSearch, hybridSearch, semanticSearchMessages, hybridSearchMessages |
embeddings.ts |
Vector embedding generation with idempotency checks and replace pattern for session-level and message-level semantic search |
evals.ts |
Eval management: setEvalReady, updateEvalStatus, updateExpectedOutput, bulkUpdateEvalStatus, bulkAddTags, listEvalSessions (enhanced filtering: source, tags, model, date range, minTokens, project, evalStatus), getEvalTags, getEvalModels, previewExport (validation + stats), generateEvalExport (DeepEval JSON, OpenAI JSONL, Promptfoo JSONL, Filesystem formats with multi-turn modes: full/per_turn/final_only, tool message skipping for proper user-assistant pair extraction) |
api.ts |
Internal API functions: listSessions, getSession, fullTextSearch, exportSession, getStats, semanticSearch, hybridSearch, getContext |
http.ts |
HTTP endpoints: /sync/_ (session, message with createdAt passthrough for timestamp preservation, batch using batchUpsert mutations, sessions/list), /api/_ including /api/export/evals (GET with format, tool, model, date_from, date_to, tags, min_tokens, status filters), /health |
rag.ts |
RAG retrieval functions for context engineering |
wrapped.ts |
Daily Wrapped queries and mutations: getTodayWrapped, getWrappedStats, get24HourStats, getCountdownInfo queries; createWrapped, deleteExpired, getActiveUsers mutations |
wrappedActions.ts |
Daily Wrapped Node.js actions: generateWrappedImage (Google Imagen API), generateForUser, generateAllWrapped |
crons.ts |
Scheduled jobs: daily wrapped generation at 9:30 AM PT, cleanup every 6 hours |
README.md |
Convex backend documentation |
React frontend application.
| File | Description |
|---|---|
main.tsx |
App entry point with providers (Convex, AuthKit, Router), devMode=true for localStorage tokens (avoids third-party cookie blocking in production) |
App.tsx |
Route definitions: public routes (/, /login, /stats, /updates, /s/:slug), protected routes (/dashboard, /profile, /settings, /evals, /context). /docs, /docs/*, and /docs-legacy all redirect to docs.opensync.dev (Mintlify). ProtectedRoute with delayed spinner (500ms) and Safari timeout (5s), CallbackHandler for OAuth code exchange, return-to URL preservation |
index.css |
Global styles, Tailwind imports, dark theme tokens, chart utilities, scrollbar-hide utility, mobile touch scrolling improvements (dvh, touch-action, webkit-overflow-scrolling) |
vite-env.d.ts |
Vite client type declarations for import.meta.env |
| File | Description |
|---|---|
Login.tsx |
Public homepage with WorkOS AuthKit integration. Shows "Go to Dashboard" button when logged in (no auto-redirect), "Sign in" when logged out. Loading spinner only during OAuth callback (not for cold page loads), includes privacy messaging, "Syncs with" section showing supported CLI tools (OpenCode, Claude Code, Droid, Codex CLI, Cursor, Pi), getting started section with plugin links including codex-sync and pi-opensync-plugin (mobile-visible), tan mode theme support with footer (theme switcher, Terms/Privacy/Updates links), footer icons (GitHub, Discord, Support, Discussions), updated mockup with view tabs and OC/CC source badges (desktop-only), feature list with Sync/Search/Private/Tag/Export/Delete keywords and eval datasets tagline, Watch the demo link, trust message with cloud/local deployment info, real-time Platform Stats leaderboard (Top Models, Top CLI, shows last 1000 sessions) above Open Source footer link |
Stats.tsx |
Public stats page (/stats) disabled to reduce Convex reads. Route exists but shows placeholder "Stats page is currently disabled" message. Original code with MessageMilestoneCounter and GrowthChart was removed to simplify the file. |
Dashboard.tsx |
Main dashboard with custom themed source filter dropdown (filters by user's enabled agents from Settings, dark/tan mode support, click-outside close, escape key close), source badges (CC/OC/FD), eval toggle button, Context link with search icon, Updates link with Bell icon, setup banner for new users with plugin cards (OpenCode, Claude Code, Factory Droid, Pi), mobile-optimized header/filters/session rows with iOS scroll fixes (overscroll-contain, touch-pan-y, WebkitOverflowScrolling, absolute positioning on mobile for full-screen detail view), URL param support for deep linking from Context search (?session=id), Cmd/Ctrl+K shortcut to open Context search, MessageBubble with content normalization helpers (getPartTextContent, getToolName) for multi-plugin format support, flash-free session transitions using lastValidSessionRef cache (shows cached content until new data loads, subtle corner spinner), sessions pagination (40 initial, load more 20 at a time), eval selection mode (checkbox toggle, select all, batch mark for evals), CompactDropdown component for themed filter dropdowns, and five views: Overview (responsive stat grids), Sessions (mobile-friendly list with stacked layout, pagination, eval selection), Evals (CRM-style compact list with hidden scrollbars, flex layout, 50 items + load more, truncated names, wider model column, CompactDropdown filters), Analytics (responsive breakdowns with CompactDropdown filters), Wrapped (Daily Sync Wrapped visualization) |
Settings.tsx |
Tabbed settings: API Access (two-column layout with Plugin Setup and AI Coding Agents sections, keys, endpoints with plugin links including codex-sync), Profile (collapsible section for privacy, account info, Legal section with Terms/Privacy links, Danger Zone with delete data/account options and real-time deletion progress tracking). AI Coding Agents section lets users enable/disable CLI tools for the source filter dropdown (OpenCode, Claude Code, Factory Droid, Codex CLI with supported status, Cursor, Continue, Amp, Aider, Goose, Mentat, Cline, Kilo Code). Danger Zone shows deletion progress with counts per table type, success/error messages, and disables buttons during deletion. Back link navigates to /dashboard |
Docs.tsx |
Removed. Documentation migrated to Mintlify at docs.opensync.dev. All /docs routes redirect externally via DocsRedirect component in App.tsx. |
PublicSession.tsx |
Public session viewer for shared sessions (/s/:slug) with dark/tan theme toggle, content normalization for multi-plugin support, textContent fallback for empty parts |
Evals.tsx |
Compact CRM-style evals page with hidden scrollbars, pagination (50 items + load more), truncated session names, eval-ready session list, stats row, export modal (DeepEval JSON, OpenAI JSONL, Promptfoo JSONL, Filesystem formats with multi-turn modes), enhanced filtering (source, model, date range, status, tags), inline status dropdown for annotation (golden/correct/incorrect/needs_review), bulk status updates, export preview with validation warnings |
Context.tsx |
Dedicated context search page (/context) with paginated full-text search for sessions and messages, slide-over panel for viewing session details without navigation, message highlighting for search results, source badges using centralized utilities, no OpenAI key required |
Updates.tsx |
Public GitHub activity page (/updates) with two-column layout showing open issues and discussions from waynesutton/opensync repo. Client-side GitHub API fetching, refresh button, dark/tan theme support, fallback card for discussions (REST API requires auth). No login required. |
| File | Description |
|---|---|
Header.tsx |
Top navigation with search input and user menu |
Sidebar.tsx |
Session list sidebar with search results |
SessionViewer.tsx |
Session detail view with messages and actions |
Charts.tsx |
Reusable chart components: BarChart, AreaChart, DonutChart, Sparkline, ProgressBar, StatCard, DataTable, FilterPill, StackedBarChart, UsageCreditBar, ConsumptionBreakdown, ChartDropdown (themed dropdown for Usage Overview filters) |
ConfirmModal.tsx |
Custom confirmation modal with theme support, replaces browser confirm() dialogs |
LegalModal.tsx |
Dark mode modal for displaying Terms of Service and Privacy Policy with markdown rendering, ESC/X to close |
WrappedView.tsx |
Daily Wrapped component with countdown timer, download PNG (675x1200 9:16 portrait) using hidden off-screen export container for clean captures (rotate design button commented out for production) |
WrappedTemplates.tsx |
10 CSS template designs for wrapped (9:16 portrait 675x1200px) showing tokens, messages, sessions (not cost), with large readable fonts |
SetupIncompleteBanner.tsx |
Yellow warning banner shown when VITE_CONVEX_URL or VITE_WORKOS_CLIENT_ID env vars are missing, links to ONE-CLICK-DEPLOY.md checklist |
| File | Description |
|---|---|
auth.tsx |
Auth wrapper for WorkOS AuthKit with useAuth hook, session rehydration, and token refresh handling |
utils.ts |
Utility functions (cn for classnames) |
theme.tsx |
Theme context with page-specific defaults (PAGE_THEME_DEFAULTS config), useTheme and usePageTheme hooks, dark/tan mode toggle with localStorage persistence. getThemeClasses returns bgPrimary, bgSecondary, bgCard, bgHover (no bare bg property) |
source.ts |
Source utilities: getSourceLabel (OC/CC/FD/CX/CR/PI labels, handles cursor alias), getSourceColorClass (themed badge colors for OpenCode/Claude Code/Factory Droid/Codex CLI/Cursor/Pi with purple for codex-cli, violet for cursor-sync/cursor, orange #f97316 for pi) |
MDX documentation pages served by Mintlify.
| File | Description |
|---|---|
docs.json |
Mintlify configuration: theme, navigation groups, anchors, colors, footer socials |
index.mdx |
Landing page with CardGroup links to all major sections, supported tools table |
getting-started/hosted.mdx |
Hosted version setup: features, supported tools, step-by-step guide, what gets synced, privacy |
getting-started/requirements.mdx |
Self-hosting requirements: cloud vs local deployment, Convex/WorkOS roles, architecture overview |
getting-started/quick-start.mdx |
5-minute deploy guide with one-click buttons for Convex, Netlify, Vercel |
dashboard/overview.mdx |
Dashboard overview: summary cards, session list fields, filters, real-time updates, schema mapping |
dashboard/sessions.mdx |
Sessions view: data model, filtering, sorting, detail view, message parts, bulk actions |
dashboard/evals.mdx |
Evals: workflow, labels, metadata fields, export formats (DeepEval/OpenAI/text), API export |
dashboard/analytics.mdx |
Analytics: summary metrics, cost calculation with pricing table, token breakdown, trend charts |
dashboard/context.mdx |
Context search: embeddings, full-text vs semantic, dashboard usage, API examples, RAG use cases |
plugins/opencode-sync.mdx |
OpenCode plugin: setup, commands, syncing internals, schema mapping, troubleshooting |
plugins/claude-code-sync.mdx |
Claude Code plugin: setup, commands, syncing internals, session data mapping, troubleshooting |
plugins/codex-sync.mdx |
Codex CLI plugin: setup, commands, supported models with pricing, troubleshooting |
plugins/cursor-sync.mdx |
Cursor plugin: setup, commands, supported models, what gets synced, privacy notes |
api/authentication.mdx |
API authentication: key generation, usage, rate limits, revocation |
api/endpoints.mdx |
Full API reference: sync, query, search, export, context, health endpoints with request/response |
api/errors.mdx |
Error handling: response format, HTTP status codes, retry strategy with code examples |
search/fulltext.mdx |
Full-text search: indexing, syntax, ranking, API usage, comparison with semantic |
search/semantic.mdx |
Semantic search: embedding model, storage schema, examples, requirements, comparison |
search/hybrid.mdx |
Hybrid search: scoring formula, use cases, RAG pipeline example, comparison table |
auth/workos.mdx |
WorkOS AuthKit: auth flow, user provisioning, redirect URIs, CORS, troubleshooting |
auth/api-keys.mdx |
API key management: generation, format, storage, revocation, security practices |
hosting/convex.mdx |
Convex backend: deploy, schema tables, indexes, HTTP endpoints, monitoring, scaling |
hosting/netlify.mdx |
Frontend hosting: Netlify/Vercel deploy with build settings and environment variables |
hosting/env.mdx |
Environment variable reference: required/optional vars, setting per platform |
fork/guide.mdx |
Fork guide: clone, setup, local dev, deploy, syncing upstream updates |
fork/customize.mdx |
Customization: branding, colors, adding sources, custom fields, API extensions |
fork/contribute.mdx |
Contributing: bug reports, PRs, code style, commit conventions |
troubleshooting/common-issues.mdx |
Common issues: auth, sync, search, deployment, performance troubleshooting |
troubleshooting/faq.mdx |
FAQ: supported tools, data storage, migration, cost calculation, deletion, contributing |
| File | Description |
|---|---|
OPENSYNC-SETUP.md |
Full deployment and configuration guide with cloud and 100% local self-hosting options |
API.md |
API endpoint reference with examples |
OPENCODE-PLUGIN.md |
OpenCode plugin installation and usage (API Key auth) |
CLAUDE-CODE-PLUGIN.md |
Claude Code plugin installation and hooks (API Key auth) |
PLUGIN-AUTH-PRD.md |
Plugin authentication specification (API Key vs WorkOS OAuth) |
PRD-FEATURES.md |
Product requirements: Eval Suite, Marketplace, Context Library, Analytics |
SYNC-FOR-EVALS-PRD.md |
Detailed PRD for eval export system with DeepEval/OpenAI Evals support |
workosfix.md |
WorkOS troubleshooting notes |
add-package-to-home-prompt.md |
Reusable prompt template for adding CLI/npm packages to homepage Getting Started section |
ADD-NEW-PLUGIN-TEMPLATE.md |
Comprehensive prompt template for adding new sync plugins to OpenSync (10 file locations, testing checklist, color/status options) |
setup-codex-sync.md |
Complete guide to building, publishing, and integrating codex-sync with OpenSync |
WORKOS-AUTH.md |
WorkOS AuthKit integration architecture and security model |
NETLIFY-WORKOS-DEPLOYMENT.md |
Deployment guide for Netlify, WorkOS, and Convex integration |
fix-blank-sessions.md |
Tracking document for empty session messages fix (Issues #7, #8) |
PLUGIN-DEVELOPMENT-GUIDE.md |
Comprehensive guide for building OpenSync sync plugins: API endpoints, database schema (with tool role), CLI commands reference, hook-based vs file-based sync patterns, token data availability matrix, code examples with debug logging, eval export compatibility, README/package.json templates, testing checklist |
cursor-sync-plugin-fix-09.md |
PRD documenting all fixes made to cursor-sync plugin for OpenSync API compatibility |
cursor-sync-discussion.md |
Announcement post for cursor-opensync-plugin with feature comparison to other sync plugins |
Static assets.
| File | Description |
|---|---|
_redirects |
Netlify SPA fallback rules for client-side routing |
favicon.png |
PNG favicon |
favicon.svg |
SVG favicon |
convex.svg |
Convex logo |
workos.svg |
WorkOS logo |
netlify-logo.svg |
Netlify logo |
opencode-dark.svg |
OpenCode logo for dark theme |
opencode-light.svg |
OpenCode logo for light theme |
claude.svg |
Claude Code logo (uses currentColor) |
factory-droid.svg |
Factory Droid logo (uses currentColor) |
llms.txt |
AI assistant documentation file with project overview, features, API reference, and setup instructions |
Cursor IDE rules for AI assistance.
| File | Description |
|---|---|
dev2.mdc |
Main development guidelines |
help.mdc |
Problem-solving workflow |
write.mdc |
Writing style guide |
convex2.mdc |
Convex best practices |
rulesforconvex.mdc |
Additional Convex guidelines |
convex-write-conflicts.mdc |
Write conflict prevention patterns with OpenSync-specific sync patterns (dedup windows, batch mutations, replace pattern) |
changelog.mdc |
Changelog format rules for GitHub Releases automation |
gitruels.mdc |
Git safety rules |
sec-check.mdc |
Security checklist |
task.mdc |
Task management guidelines |
Claude AI skill files.
| File | Description |
|---|---|
convex-*.md |
Various Convex development skills |