Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The Crisp development environment is designed to support the creation of a native macOS application and its accompanying marketing website. The project is structured as a monorepo utilizing a specialized architecture where the Swift/SwiftUI desktop application drives a Python-based processing engine. The development setup ensures that all necessary local dependencies, including media processing tools and machine learning models, are correctly configured to allow for side-by-side execution of different release channels.
Sources: CLAUDE.md:4-10, README.md:38-42, package.json:1-10
Environment Requirements
To build and run Crisp, developers must use a Mac with Apple Silicon. Intel-based Macs are explicitly not supported for new builds.
System Prerequisites
- Operating System: macOS 14+ is required.
- Hardware: Apple Silicon (arm64 architecture).
- Development Tools:
- Xcode (with macOS SDK).
- Swift Toolchain.
- Homebrew (for dependency management).
- Bun (for web application and monorepo management).
- Python 3 (stdlib-only for the engine).
- CMake (to build bundled components).
Sources: setup.sh:18-35, README.md:16-18, apps/desktop/build.sh:44-45, CLAUDE.md:126-128
Initial Repository Initialization
The project uses a setup.sh script to automate the installation of runtime tools and the retrieval of external assets that are not committed to the repository.
The diagram above illustrates the sequential checks and installations performed by the setup script.
Setup Execution
- Tool Installation: Installs
ffmpegfor media energy detection andwhisper-cppfor transcription. - Speech Model: Downloads the
ggml-base.en.binmodel (~148 MB) from Hugging Face intoapps/desktop/Resources/engine/models/. - Build Tools: Verifies the presence of
cmake(used for vendoringwhisper-cli) and the Swift compiler.
Sources: setup.sh:1-46, README.md:20-22
Desktop Application Development
Crisp supports three distinct release channels that can be installed side-by-side on a developer's machine. Each channel has a unique bundle identifier, name, and data directory.
| Channel | Bundle ID | App Name | Purpose |
|---|---|---|---|
| Stable | com.syntaxlabtechnology.crisp | Crisp | Default production build. |
| Nightly | ...crisp.nightly | Crisp Nightly | Integration/staging builds. |
| Dev | ...crisp.dev | Crisp Dev | Local development and testing. |
Sources: apps/desktop/build.sh:5-30, CLAUDE.md:99-110
Local Development Flow
For active development, the ./dev.sh script is used. This script builds and launches the "Crisp Dev" application. It ensures that the development version does not interfere with the stable version of the app.
# From apps/desktop
./dev.sh
Sources: apps/desktop/dev.sh, CLAUDE.md:113-114
The Build Process
The build.sh script handles the complexity of assembling the native app, including:
- Arch: Compiling a single
arm64slice. - Vendoring: Invoking
Scripts/vendor.shto download and sign binaries likeffmpeg,ffprobe, andwhisper-cli. - Engine Bundling: Copying the Python
crisppackage andclean_video.pyinto the app bundle. - Signing: Performing inside-out signing of all bundled Mach-O binaries followed by the outer app seal.
Sources: apps/desktop/build.sh:44-70, apps/desktop/build.sh:169-183
Web Development
The marketing site is a separate Vite/React application located in apps/web. It uses Tailwind CSS v4 and Framer Motion for animations.
Web Setup and Scripts
The project uses bun as the package manager and turbo for task orchestration across the monorepo.
- Install Dependencies:
bun install(from root). - Local Dev Server:
bun run dev. - Production Build:
bun run build.
Sources: apps/web/README.md:20-35, package.json:9-12
Testing and Verification
Development is gated by several test suites that must pass before promotion between branches.
- Swift Tests:
swift test(unit tests for the macOS app logic). - Engine Tests:
python3 -m unittest discover -s Resources/engine/tests(verified in a stdlib-only environment). - UI Verification: Changes must be verified visually against the "Crisp Dev" app.
- Linting:
swiftlintfor Swift andbun run lint(tsc) for the web app.
Sources: CLAUDE.md:88-91, CLAUDE.md:120-125, apps/web/README.md:34
Summary
The Crisp development setup is optimized for Apple Silicon and utilizes a monorepo structure to manage both the macOS application and its marketing presence. By employing a localized setup script (setup.sh) and channel-specific build scripts (dev.sh, build.sh), developers can safely iterate on the product without disrupting stable installations. The architecture emphasizes local processing, requiring the manual retrieval of large assets like the whisper speech model while vendoring essential media tools directly into the application bundle.