claudette

<p align="center"> <img src="assets/logo.png" alt="Claudette" width="128" /> </p> <h1 align="center">Claudette</h1> <p align="center">Claude's missing better half — a companion tool for Claude Code usage.</p> <p align="center"> <a href="https://utensils.github.io/claudette/"><img src="https://img.shields.io/badge/docs-utensils.github.io%2Fclaudette-7c3aed" alt="Documentation"/></a> <a href="https://codecov.io/gh/utensils/claudette"><img src="https://codecov.io/gh/utensils/claudette/graph/badge.svg" alt="codecov"/></a> <a href="https://discord.gg/JQdfT3Z67F"><img src="https://img.shields.io/discord/1491165880820699398?logo=discord&label=Discord" alt="Discord"/></a> <a href="https://www.reddit.com/r/ClaudetteApp"><img src="https://img.shields.io/reddit/subreddit-subscribers/ClaudetteApp?style=social" alt="Reddit"/></a> </p>

Highlights

• Parallel agents in isolated git worktrees — run multiple Claude Code agents simultaneously, each on its own branch with no merge conflicts.
• Plan mode and AskUserQuestion handling — let the agent draft a plan or pause for input, then approve, deny with feedback, or answer from the GUI or the CLI.
• Checkpoints and workspace forking — roll any session back to an earlier turn, or fork a workspace from a checkpoint to explore alternates without losing the original.
• CLI client + Claude Code skill — script every workspace operation from the terminal; install the bundled skill and a "main" agent can drive Claudette to fan out work across N workspaces.
• Remote workspaces over encrypted WebSocket — connect to another machine and work with its repos, agents, and terminals as if they were local. Auto-discovers on LAN via mDNS.
• SCM providers (GitHub, GitLab, extensible) — pull request status, CI checks, and one-click merge without leaving the app, powered by sandboxed Lua plugins.
• MCP supervision and env-providers — per-repo MCP server config with health monitoring, plus a pluggable env stack (direnv, mise, dotenv, nix-devshell).
• Voice input — push-to-talk dictation with Apple Speech (macOS) or bundled Whisper, all on-device.
• Agent providers — choose Claude Code, Ollama (local), the OpenAI API, or Codex as first-class agent backends. Gateway and app-server paths adapt chat controls to whichever provider is active.

Full documentation lives at utensils.github.io/claudette.

About

Claudette is a cross-platform desktop application built with Tauri 2 (Rust backend) and React/TypeScript (frontend). It provides a lightweight interface for managing and orchestrating Claude Code sessions, similar in spirit to Conductor.build but with a focused feature set. Unlike most similar tools, Claudette runs natively on macOS (Apple Silicon + Intel), Linux (x86_64 + aarch64, Wayland + X11), and Windows (x86_64 + ARM64).

Prerequisites

• Rust (stable toolchain, edition 2024)
• Bun (JavaScript runtime and package manager)
• Tauri CLI: cargo install tauri-cli --version "^2"
• Platform dependencies for Tauri:

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

  • Linux: System libraries for WebKitGTK and (when building with the default voice feature) ALSA. On Debian/Ubuntu:

    sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
      libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev \
      libasound2-dev
    

    Equivalents on other distros: alsa-lib-devel (Fedora/RHEL), alsa-lib (Arch). Nix users get this automatically via flake.nix.

    Headless or sandboxed Linux environments that lack ALSA can build without voice support:

    cargo tauri build --no-default-features --features tauri/custom-protocol,server
    

  • Windows: Visual Studio C++ Build Tools with the Desktop development with C++ workload (or full Visual Studio 2022). Building ring on ARM64 also requires Clang/LLVM on PATH — scoop install llvm is the easiest path. WebView2 ships with Windows 11 and recent Windows 10. Voice support is off by default on Windows; see Run in development mode for the opt-in.

Getting started

# Install frontend dependencies
cd src/ui && bun install && cd ../..

Run in development mode

Pick the launcher that matches your platform — --new, --clean, and -h/--help work on both. --clone (rsync mirror of your real setup into a stable sandbox dir; re-runs sync incrementally) is macOS/Linux only for now; on Windows the PowerShell launcher silently treats it as an unknown passthrough to cargo run.

# macOS / Linux — shell launcher
./scripts/dev.sh                 # full-feature dev (required for macOS voice)
./scripts/dev.sh --new           # fresh-user sandbox under TMPDIR
./scripts/dev.sh --clone         # rsync mirror of your real setup; incremental on re-run
./scripts/dev.sh --clean         # nuke /tmp/claudette-dev/ and exit
cargo tauri dev                  # quick path; no voice, no port probing

# Windows — PowerShell launcher
.\scripts\dev.ps1                # equivalent of dev.sh, ARM64 + x64
.\scripts\dev.ps1 --new          # fresh-user sandbox under $env:TEMP
.\scripts\dev.ps1 --clean        # nuke $env:TEMP\claudette-dev\ and exit
.\scripts\dev.ps1 --help         # full flag/env reference

To get the bare dev command (matching the Nix devshell), add this to your PowerShell profile ($PROFILE):

function dev {
    $repo = "<absolute path to your claudette clone>"
    & "$repo\scripts\dev.ps1" @args
}

Both launchers do a few things cargo tauri dev doesn't:

• macOS only: wraps the binary in a signed Claudette Dev.app bundle (with the right Info.plist usage strings and Entitlements.plist) and launches it via Launch Services. This is required because macOS's privacy system (TCC) refuses to grant Microphone or Speech Recognition permissions to a bare Mach-O binary and aborts the process when the prompt appears.
• Probes free Vite + debug-eval ports and exports them so multiple dev instances can run side by side.
• Stages the claudette-cli sidecar binary so the in-app CLI install path works in dev.
• Writes a per-PID discovery file at ${TMPDIR:-/tmp}/claudette-dev/<pid>.json (or $env:TEMP\claudette-dev\<pid>.json on Windows) consumed by the /claudette-debug skill.

Windows-only details the dev.ps1 launcher takes care of so you don't have to:

• Forces Vite's bind to 127.0.0.1 (IPv4). Vite's default localhost resolves to ::1 on Windows, but WebView2 navigates IPv4-first — mismatch surfaces as a blank webview with HRESULT 0x80070057.
• Defaults to the same feature set as scripts/dev.sh — devtools,server,voice,alternative-backends. On aarch64-pc-windows-msvc the launcher appends -C target-feature=+fullfp16 to $env:RUSTFLAGS so the gemm-f16 ARMv8.2 inline asm in the voice feature compiles. Existing RUSTFLAGS are kept (rustc concatenates -C target-feature directives), so any flags you already set continue to apply. Override the feature set with $env:CARGO_TAURI_FEATURES to drop voice or add other features.
• Skips tauri/custom-protocol. With it on, import.meta.env.DEV is false in the webview, which leaves window.__CLAUDETTE_INVOKE__ unset and breaks the /claudette-debug TCP eval server.
• Stages the claudette-cli sidecar at the path Tauri's bundle.externalBin expects — necessary because tauri.conf.json's beforeDevCommand shell script can't run on Windows.

Build, test, lint

# Build optimized release binary
cargo tauri build

# Run backend tests
cargo test --all-features

# Lint
cargo clippy --workspace --all-targets

# Check frontend types
cd src/ui && bunx tsc --noEmit

Project structure

Cargo.toml              # Workspace root + claudette lib crate
src/
  lib.rs                # Backend library entry point
  db/                   # SQLite database (rusqlite)
  git.rs                # Async git operations
  diff.rs               # Diff parsing
  agent/                # Claude CLI subprocess + streaming, alternative backends
  model/                # Data types
  names/                # Random workspace name generator
  ui/                   # React/Vite frontend
    src/
      components/       # UI components (sidebar, chat, diff, terminal, modals)
      hooks/            # Tauri event listeners
      stores/           # Zustand state management
      services/         # Typed Tauri IPC wrappers
      types/            # TypeScript types matching Rust models
src-tauri/
  Cargo.toml            # Tauri binary crate
  tauri.conf.json       # Tauri configuration
  src/
    main.rs             # Tauri entry point
    commands/           # #[tauri::command] handlers
    state.rs            # Managed application state
    pty.rs              # Terminal PTY management
    transport/          # Remote transport trait + WebSocket client
    remote.rs           # Remote connection manager
    mdns.rs             # mDNS service browser
src-server/
  Cargo.toml            # Server library + standalone binary crate
  src/
    lib.rs              # Server library (shared by Tauri binary and standalone CLI)
    main.rs             # Standalone CLI entry point (clap)
    ws.rs               # WebSocket accept loop + per-connection handler
    handler.rs          # JSON-RPC command dispatcher
    tls.rs              # Self-signed TLS certificate management
    auth.rs             # Pairing token + session token auth
    mdns.rs             # mDNS service advertisement
src-cli/
  Cargo.toml            # Command-line client crate (`claudette` binary)
src-mobile/
  Cargo.toml            # Tauri iOS / Android remote-control client crate

Command-line client

The claudette CLI drives the running desktop app over a local IPC socket. Use it to script workspace creation, send prompts to chat sessions, or fan out a phase-of-work plan across many workspaces at once.

# Discover what's available
claudette capabilities

# List repos and workspaces
claudette repo list
claudette workspace list

# Create a workspace and dispatch a prompt
claudette workspace create <repo-id> my-task
claudette chat send <session-id> @./prompts/task.md

# Inspect and orchestrate active chat sessions
claudette chat list <workspace-id>
claudette chat show <session-id> --limit 50
claudette chat turns <session-id>
claudette chat send <other-session-id> "Can you review this approach?"
claudette chat stop <session-id>

# Fan out N workspaces from a YAML manifest
claudette batch validate plan.yaml
claudette batch run plan.yaml

# Pull-request shortcuts (resolves the active SCM provider per workspace)
claudette pr list --workspace <workspace-id>
claudette pr show <number> --workspace <workspace-id>

# Generic plugin invocation (escape hatch when no first-class subcommand exists)
claudette plugin list
claudette plugin invoke github list_pull_requests --workspace <workspace-id> '{}'

# Install shell completion
claudette completion zsh > ~/.zsh/completions/_claudette
`