Skip to content

CLAUDE.md

Latest commit

 

History

History
96 lines (72 loc) · 4.02 KB

CLAUDE.md

File metadata and controls

96 lines (72 loc) · 4.02 KB
Raw

Claude Code Instructions for openadapt-desktop

MANDATORY: Branches and Pull Requests

NEVER push directly to main. ALWAYS use feature branches and pull requests.

  1. Create a feature branch: git checkout -b feat/description or fix/description
  2. Make commits on the branch
  3. Push the branch: git push -u origin branch-name
  4. Create a PR: gh pr create --title "..." --body "..."
  5. Only merge via PR (never git push origin main)

PR Titles MUST Use Conventional Commit Format

fix: short description          -> patch bump (0.0.x)
feat: short description         -> minor bump (0.x.0)
fix(scope): short description   -> patch bump with scope
feat!: breaking change          -> major bump (x.0.0)

Types: feat, fix, docs, style, refactor, perf, test, chore, ci

Overview

Cross-platform desktop app for continuous screen recording and AI training data collection. Built with Tauri 2.x (Rust shell) + Python sidecar (recording engine).

Quick Start

uv sync --extra dev
uv run pytest tests/ -v
uv run ruff check engine/ tests/

Architecture

Two-process model:

  • Tauri shell (Rust + WebView): system tray, native window, IPC dispatch
  • Python engine (sidecar): recording, scrubbing, storage, upload

Communication via JSON-over-stdin/stdout IPC protocol (see DESIGN.md Appendix B).

Key Design Decisions

  1. Raw-then-review scrubbing: Recordings saved raw to disk. Scrubbing is a separate user-reviewed step. check_egress_allowed() gates ALL outbound paths.
  2. Build-time trust: Tauri Cargo.toml feature flags physically exclude upload code. Enterprise binary verifiable with strings.
  3. Multiple storage backends: StorageBackend protocol in engine/backends/protocol.py. All backends conform to the same interface.
  4. Network audit logging: Every outbound request logged to audit.jsonl (JSONL format).

File Map

File Purpose
engine/controller.py Recording lifecycle (start/stop/pause)
engine/review.py Upload review state machine (the egress gate)
engine/scrubber.py PII scrubbing orchestration
engine/config.py Settings (pydantic-settings, OPENADAPT_ prefix)
engine/audit.py Network audit logger
engine/backends/protocol.py StorageBackend protocol definition
engine/backends/s3.py S3/R2/MinIO backend
src-tauri/src/commands.rs IPC commands (13 endpoints)
src-tauri/src/main.rs Tauri entry point
DESIGN.md Comprehensive design document (v2.0, 1800 lines)

Running Tests

uv run pytest tests/ -v              # all tests
uv run ruff check engine/ tests/     # lint

Hosted loop modules (engine rewire)

File Purpose
engine/auth/provider.py AuthProvider Protocol + Credential TypedDict (shared contract)
engine/auth/store.py Keychain store (keyring, service ai.openadapt.desktop) + auth_header()
engine/auth/paste.py PasteTokenProvider (token paste / headless env)
engine/auth/browser_pkce.py BrowserPkceProvider (system browser + loopback PKCE)
engine/backends/hosted_ingest.py HostedIngestBackend -> POST /api/ingest (bearer)
engine/hosted.py push (zip -> ingest) + report_break (/api/runs/ingest-report)
engine/flow_bridge.py Wraps the openadapt-flow CLI (record/compile/replay/run/teach)
engine/dispatch.py Shared command dispatcher (frontend engine.ts CMD names -> engine actions) used by BOTH local wires
engine/ipc.py Tauri stdin/stdout JSON-lines wire -> EngineDispatcher
engine/socket_server.py Tray loopback TCP server + ~/.openadapt/desktop_ipc.json discovery file (spec 3d)

Dependencies

  • Python: openadapt-capture (recording), openadapt-privacy (scrubbing), pydantic-settings, httpx (hosted ingest), keyring (credential store)
  • Rust: tauri, tauri-plugin-shell, tauri-plugin-notification, tauri-plugin-updater
  • Optional: boto3 (S3, BYOC customer-owned storage)
  • Loop engine: openadapt-flow (wrapped, not vendored)