Skip to content

Getting Started

Clone the Repository

git clone https://github.com/mayocream/koharu.git
cd koharu

Prerequisites

  • Rust 1.92 or later
  • Bun 1.0 or later

Windows

macOS

  • Xcode Command Line Tools (xcode-select --install)

Linux

  • A working C/C++ toolchain (build-essential or the equivalent for your distro)
  • LLVM 15 or later for GPU-accelerated builds

Install Dependencies

bun install

Rust toolchain components are resolved automatically from rust-toolchain.toml on first build.

Run Koharu Locally

bun run dev

This launches the Tauri app in development mode against the bundled UI.

Build a Release

bun run build

The built binaries land in target/release-with-debug/ or target/release/ depending on the profile.

Daily Commands

Always go through bun cargo for Rust commands so platform feature flags (CUDA, Metal, Vulkan) are wired up correctly.

bun cargo check                         # type-check the workspace
bun cargo clippy -- -D warnings         # lint
bun cargo fmt -- --check                # format check
bun cargo test --workspace --tests      # unit and integration tests

UI and config formatting use oxfmt:

bun run format
bun run format:check

UI unit tests:

bun run test:ui

ML Work

When iterating on koharu-ml or koharu-llm locally, enable the backend that matches your machine:

# Windows / Linux with NVIDIA
bun cargo test -p koharu-ml --features=cuda

# macOS (Apple Silicon)
bun cargo test -p koharu-ml --features=metal

See Acceleration and Runtime for details on how backends are selected.

Docs

Docs live under docs/en-US/, docs/ja-JP/, docs/zh-CN/, and docs/pt-BR/. Build each locale you touched:

zensical build -f docs/zensical.toml -c
zensical build -f docs/zensical.ja-JP.toml
zensical build -f docs/zensical.zh-CN.toml
zensical build -f docs/zensical.pt-BR.toml

If you add a new page, register it in the matching zensical*.toml nav.

Before Opening a PR

Run the checks that match what you changed. You do not need to run everything on every PR.

  • Rust changes — bun cargo fmt -- --check, bun cargo check, bun cargo clippy -- -D warnings, bun cargo test --workspace --tests
  • UI changes — bun run format and bun run test:ui
  • Desktop integration — bun run build
  • Docs — build every locale you edited

Pull Request Expectations

  • One goal per PR. Bug fix or refactor or new feature, not all three.
  • Follow existing patterns. If the file already has a convention, match it instead of introducing a new one.
  • Describe what changed and how you verified it. Screenshots or short clips for UI work; before/after for pipeline work.
  • No backwards-compat shims. Replace old code in place — no v2/ folders, no deprecated aliases.
  • No drive-by refactors. If you spot unrelated cleanup, open a separate PR.

Small, focused PRs get reviewed faster than large, mixed ones.