Repository: CapSoftware/Cap

Stars: 18182

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides comprehensive guidance to Claude Code when working with code in this repository.

Project Overview Copy Chapter

Cap is the open source alternative to Loom. It's a Turborepo monorepo with a Tauri v2 desktop app (Rust + SolidStart) and a Next.js web app. The Next.js app at apps/web is the main web application for sharing and management; the desktop app at apps/desktop is the cross‑platform recorder/editor (macOS and Windows).

Product Context Copy Section

File Location Patterns & Key Directories Copy Chapter

Core Applications Copy Section

Shared Packages Copy Section

Rust Crates Copy Section

Important File Patterns Copy Section

Key Commands Copy Chapter

Development Copy Section

pnpm dev:web             # Start Next.js dev server (apps/web only)
pnpm run dev:desktop     # Start Tauri desktop dev (apps/desktop)
pnpm build               # Build all packages/apps via Turbo
pnpm lint                # Lint with Biome across the repo
pnpm format              # Format with Biome
pnpm typecheck           # TypeScript project references build

Database Operations Copy Section

pnpm db:generate         # Generate Drizzle migrations
pnpm db:push             # Push schema changes to MySQL
pnpm db:studio           # Open Drizzle Studio
pnpm --dir packages/database db:check  # Verify database schema

App-Specific Commands Copy Section

Web app (apps/web)

cd apps/web && pnpm dev          # Start Next.js dev server
Desktop (apps/desktop)

cd apps/desktop && pnpm dev      # Start SolidStart + Tauri dev
pnpm tauri:build                 # Build desktop app (release)

Development Environment Guidelines Copy Chapter

Server Management Copy Section

Auto-generated Bindings (Desktop) Copy Section

Common Development Pain Points Copy Section

Architecture Overview Copy Chapter

Monorepo Structure Copy Section

Technology Stack Copy Section

Critical Architectural Decisions Copy Section

#### Desktop event pattern
Rust (emit):

use specta::Type;
use tauri_specta::Event;
#[derive(Serialize, Type, tauri_specta::Event, Debug, Clone)]
pub struct UploadProgress {
    progress: f64,
    message: String,
}
UploadProgress { progress: 0.0, message: "Starting upload...".to_string() }
    .emit(&app)
    .ok();

Frontend (listen; generated bindings):

import { events } from "./tauri"; // auto-generated
await events.uploadProgress.listen((event) => {
  // update UI with event.payload
});

Development Workflow & Best Practices Copy Chapter

Code Organization Principles Copy Section

Key Implementation Patterns Copy Section

#### Server Actions (Web App)

"use server";
import { db } from "@cap/database";
import { getCurrentUser } from "@cap/database/auth/session";
export async function updateVideo(data: FormData) {
  const user = await getCurrentUser();
  if (!user?.id) throw new Error("Unauthorized");
  // Database operations with Drizzle
  return await db().update(videos).set({ ... }).where(eq(videos.id, id));
}

#### Desktop IPC Commands

// Rust side - emit events
UploadProgress { progress: 0.5, message: "Uploading...".to_string() }
  .emit(&app)
  .ok();

// Frontend side - listen to events (auto-generated)
import { events, commands } from "./tauri";
// Call commands
await commands.startRecording({ ... });
// Listen to events
await events.uploadProgress.listen((event) => {
  setProgress(event.payload.progress);
});

#### React Query Patterns

// Queries with Server Actions
const { data, isLoading } = useQuery({
  queryKey: ["videos", userId],
  queryFn: () => getUserVideos(),
  staleTime: 5  60  1000,
});
// Mutations with cache updates
const updateMutation = useMutation({
  mutationFn: updateVideo,
  onSuccess: (updated) => {
    queryClient.setQueryData(["video", updated.id], updated);
  },
});

Environment Variables Copy Chapter

Build/Client (selected) Copy Section

Server (selected) Copy Section

Testing & Build Optimization Copy Chapter

Testing Strategy Copy Section

Build Performance Copy Section

Performance Monitoring Copy Section

Troubleshooting Common Issues Copy Chapter

Build Failures Copy Section

Database Issues Copy Section

Desktop App Issues Copy Section

Web App Issues Copy Section

React/Next.js Coding Standards Copy Chapter

Data Fetching & Server State Copy Section

Basic query pattern:

import { useQuery } from "@tanstack/react-query";
function Example() {
  const { data, isLoading, error } = useQuery({
    queryKey: ["items"],
    queryFn: fetchItems,
    staleTime: 5  60  1000,
    gcTime: 10  60  1000,
  });
  if (isLoading) return <Skeleton />;
  if (error) return <ErrorState onRetry={() => { / refetch / }} />;
  return <List items={data} />;
}

Server Action mutation with targeted cache updates:

"use client";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { updateItem } from "@/actions/items"; // 'use server'
function useUpdateItem() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: updateItem,
    onSuccess: (updated) => {
      qc.setQueriesData({ queryKey: ["items"] }, (old: any[] | undefined) =>
        old?.map((it) => (it.id === updated.id ? { ...it, ...updated } : it))
      );
      qc.setQueryData(["item", updated.id], updated);
    },
  });
}

Minimize useEffect usage: compute during render, handle logic in event handlers, and ensure cleanups for any subscriptions/timers.

Next.js App Router Copy Section

UI/UX Guidelines Copy Section

Effect Patterns Copy Chapter

Managed Runtimes Copy Section

API Route Construction Copy Section

Server Components & Effects Copy Section

Client Integration Copy Section

Desktop (Solid + Tauri) Patterns Copy Chapter

Conventions Copy Chapter

Rust Clippy Rules (Workspace Lints) Copy Chapter

Rust compiler lints:
- unused_must_use = "deny" — Always handle Result/Option or types marked #[must_use]; never ignore them.

Clippy lints (all denied — code MUST NOT contain these patterns):
- dbg_macro — Never use dbg!() in code; use proper logging (tracing::debug!, etc.) instead.
- let_underscore_future — Never write let _ = async_fn() which silently drops futures; await or explicitly handle them.
- unchecked_time_subtraction — Use duration.saturating_sub(other) instead of duration - other to avoid panics on underflow.
- collapsible_if — Merge nested if statements: write if a && b { } instead of if a { if b { } }.
- clone_on_copy — Don't call .clone() on Copy types (integers, bools, etc.); just copy them directly.
- redundant_closure — Use function references directly: iter.map(foo) instead of iter.map(|x| foo(x)).
- ptr_arg — Accept &[T] or &str instead of &Vec<T> or &String in function parameters for flexibility.
- len_zero — Use .is_empty() instead of .len() == 0 or .len() > 0 / .len() != 0.
- let_unit_value — Don't assign () to a variable: write foo(); instead of let _ = foo(); or let x = foo(); when return is unit.
- unnecessary_lazy_evaluations — Use .unwrap_or(val) instead of .unwrap_or_else(|| val) when the default is a simple/cheap value.
- needless_range_loop — Use for item in &collection or for (i, item) in collection.iter().enumerate() instead of for i in 0..collection.len().
- manual_clamp — Use value.clamp(min, max) instead of manual if chains or .min(max).max(min) patterns.

Examples of violations to avoid:

dbg!(value);
let _ = some_async_function();
let duration = duration_a - duration_b;
if condition {
    if other_condition {
        do_something();
    }
}
let x = 5.clone();
vec.iter().map(|x| process(x))
fn example(v: &Vec<i32>) { }
if vec.len() == 0 { }
let _ = returns_unit();
option.unwrap_or_else(|| 42)
for i in 0..vec.len() { println!("{}", vec[i]); }
value.min(max).max(min)

Correct alternatives:

tracing::debug!(?value);
some_async_function().await;
let duration = duration_a.saturating_sub(duration_b);
if condition && other_condition {
    do_something();
}
let x = 5;
vec.iter().map(process)
fn example(v: &[i32]) { }
if vec.is_empty() { }
returns_unit();
option.unwrap_or(42)
for item in &vec { println!("{}", item); }
value.clamp(min, max)

Security & Privacy Considerations Copy Chapter

Data Handling Copy Section

Privacy Controls Copy Section

AI & Processing Pipeline Copy Chapter

AI Integration Points Copy Section

Media Processing Flow Copy Section

Desktop Recording → Local Files → Upload to S3 →
Background Processing (tasks service) →
Transcription/AI Enhancement → Database Storage

References & Documentation Copy Chapter

Core Technologies Copy Section

Cap-Specific Copy Section

Development Resources Copy Section

Code Formatting Copy Chapter

Always format code before completing work:
- TypeScript/JavaScript: Run pnpm format to format all code with Biome
- Rust: Run cargo fmt to format all Rust code with rustfmt

These commands should be run regularly during development and always at the end of a coding session to ensure consistent formatting across the codebase.

README.md Copy Chapter

<p align="center">
<p align="center">
<img width="150" height="150" src="https://github.com/CapSoftware/Cap/blob/main/apps/desktop/src-tauri/icons/Square310x310Logo.png" alt="Logo">
</p>
<h1 align="center"><b>Cap</b></h1>
<p align="center">
The open source Loom alternative.
<br />
<a href="https://cap.so"><strong>Cap.so »</strong></a>
<br />
<br />
<b>Downloads for </b>
<a href="https://cap.so/download">macOS & Windows</a>
<br />
</p>
</p>
<br/>


Cap is the open source alternative to Loom. It's a video messaging tool that allows you to record, edit and share videos in seconds.

<img src="https://raw.githubusercontent.com/CapSoftware/Cap/refs/heads/main/apps/web/public/landing-cover.png"/>

Self Hosting

Quick Start (One Command) Copy Section

git clone https://github.com/CapSoftware/Cap.git && cd Cap && docker compose up -d

Cap will be running at http://localhost:3000. That's it!

Note: Login links appear in the logs (docker compose logs cap-web) since email isn't configured by default.

Other Deployment Options Copy Section

| Method | Best For |
|--------|----------|
| Docker Compose | VPS, home servers, any Docker host |
| Railway | One-click managed hosting |
| Coolify | Self-hosted PaaS (use docker-compose.coolify.yml) |


Production Configuration Copy Section

For production, create a .env file:

CAP_URL=https://cap.yourdomain.com
S3_PUBLIC_URL=https://s3.yourdomain.com

See our self-hosting docs for full configuration options including email setup, AI features, and SSL.

Cap Desktop can connect to your self-hosted instance via Settings → Cap Server URL.

Monorepo App Architecture

We use a combination of Rust, React (Next.js), TypeScript, Tauri, Drizzle (ORM), MySQL, TailwindCSS throughout this Turborepo powered monorepo.

A note about database: The codebase is currently designed to work with MySQL only. MariaDB or other compatible databases might partially work but are not officially supported.

Apps: Copy Section

- desktop: A Tauri (Rust) app, using SolidStart on the frontend.
- web: A Next.js web app.

Packages: Copy Section

- ui: A React Shared component library.
- utils: A React Shared utility library.
- tsconfig: Shared tsconfig configurations used throughout the monorepo.
- database: A React and Drizzle ORM Shared database library.
- config: eslint configurations (includes eslint-config-next, eslint-config-prettier other configs used throughout the monorepo).

License: Copy Section

- All code residing in the cap-camera and scap- families of crates is licensed under the MIT License (see licenses/LICENSE-MIT).
- All third party components are licensed under the original license provided by the owner of the applicable component
- All other content not mentioned above is available under the AGPLv3 license as defined in LICENSE

Contributing

See CONTRIBUTING.md for more information. This guide is a work in progress, and is updated regularly as the app matures.

Analytics (Tinybird) Copy Chapter

Cap uses Tinybird to ingest viewer telemetry for dashboards. The Tinybird admin token (TINYBIRD_ADMIN_TOKEN or TINYBIRD_TOKEN) must be available in your environment. Once the token is present you can:

- Provision the required data sources and materialized views via pnpm analytics:setup. This command installs the Tinybird CLI (if needed), runs tb login when a .tinyb credential file is missing, copies that credential into scripts/analytics/tinybird, and finally executes tb deploy --allow-destructive-operations --wait from that directory. It synchronizes the Tinybird workspace to the resources defined in scripts/analytics/tinybird, removing any other datasources/pipes in that workspace.
- Validate that the schema and materialized views match what the app expects via pnpm analytics:check.

Both commands target the workspace pointed to by TINYBIRD_HOST (defaults to https://api.tinybird.co). Make sure you are comfortable with the destructive nature of the deploy step before running analytics:setup.