Claudette

Claude's missing better half — a companion tool for Claude Code usage.

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), LM Studio (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.rs                 # SQLite database (rusqlite)
  git.rs                # Async git operations
  diff.rs               # Diff parsing
  agent.rs              # Claude CLI subprocess + streaming
  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

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

A batch manifest declares one repository, optional defaults, and a list of workspaces with prompts:

repository: my-repo
defaults:
  model: sonnet
workspaces:
  - name: builtins-tsx
    prompt_file: ./prompts/43-builtins.md
  - name: shell-rs
    prompt: |
      Implement issue #42 ...
    model: opus

Most CLI operations require the desktop app to be running — IPC-backed commands flow through the GUI's own command core, so tray icons, notifications, and the workspace list update live as the CLI works. Two exceptions: claudette completion <shell> is purely local (clap_complete output, no IPC) and claudette version prints the CLI version unconditionally and only notes if the GUI isn't reachable. Run claudette --help for the full subcommand list. The full reference (with every flag) lives at docs/features/cli-client.

Main-agent orchestration uses the same IPC surface: claudette chat show returns session metadata, recent transcript messages, completed tool activity, attachment metadata, and pending AskUserQuestion / ExitPlanMode controls. Use claudette chat answer <session-id> <tool-use-id> --answers-json '{"Question?":"Answer"}', claudette chat approve-plan, or claudette chat deny-plan to resolve pending controls from a terminal or another agent.

Drive from a Claude Code agent

The repo ships a Claude Code skill at .claude/skills/claudette/SKILL.md that pre-grants an agent permission to invoke claudette and provides a curated playbook of common workflows. Use it from a Claudette checkout (auto-loaded as a project skill), or symlink it into ~/.claude/skills/claudette/ to use it from any project. See docs/features/cli-client for setup details.

Remote access

Claudette can connect to workspaces on another machine over an encrypted WebSocket connection. The local app discovers or connects to a remote server and displays remote repos, agents, and terminals alongside local ones.

Sharing from the desktop app

Click Share this machine in the sidebar. The server starts automatically as a subprocess and displays a connection string to share. No separate installation required — the server is embedded in the Claudette binary (gated behind the default-enabled server feature).

On startup the server prints a connection string:

claudette-server v0.8.0 listening on wss://0.0.0.0:7683
Name: Work Laptop

Connection string (paste into Claudette):
  claudette://work-laptop.local:7683/aBcDeFgH1234...

Headless server (standalone)

For headless machines without a GUI, the standalone server binary is still available:

# Build and install the standalone server binary
cargo install --path src-server

# Start it (generates a TLS certificate and pairing token on first run)
claudette-server

Connecting from the local app

Automatic (LAN): If both machines are on the same network, the server appears automatically in the sidebar under Nearby. Click Connect and enter the pairing token when prompted.

Manual: Click + Add remote in the sidebar footer and paste the full connection string. Claudette authenticates, stores a session token, and reconnects automatically on future launches.

Server management

# Regenerate the pairing token (revokes all existing sessions)
claudette-server regenerate-token

# Print the current connection string
claudette-server show-connection-string

# Bind to a specific interface or port
claudette-server --bind 192.168.1.50 --port 9000

# Disable mDNS advertisement
claudette-server --no-mdns

All traffic is encrypted with TLS. The local app pins the server's certificate fingerprint on first connection (trust-on-first-use), similar to SSH's known_hosts.

Community

Join us on Discord to ask questions, share feedback, and connect with other Claudette users.

Contributing

Contributions are welcome! Please read our Contributing Guide to get started. All participants are expected to follow our Code of Conduct.

Translations

Claudette currently ships in English and Spanish, and we'd love help adding more languages. Translations live as JSON files under src/ui/src/locales/<lang>/ (frontend) and src/locales/<lang>/ (tray menu, notifications, and quit dialog) — most of the work is editing key/value pairs and requires no Rust or TypeScript experience. See Translating Claudette in the Contributing Guide for the step-by-step recipe.

Development notes

• The project uses Rust edition 2024 and Bun as the frontend package manager.
• The backend (src/) is a library crate consumed by the Tauri binary (src-tauri/).
• See CLAUDE.md for detailed architecture and contribution guidelines.

Relationship to Anthropic

Claudette is an independent, community-built tool. It is not affiliated with, endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude Code" are trademarks of Anthropic, PBC; their use here is descriptive — Claudette orchestrates the official Claude Code CLI — and does not imply any partnership.

How Claudette uses your Claude account

Claudette does not authenticate to Anthropic on your behalf. It spawns the official claude CLI you have installed locally as a subprocess; the CLI authenticates itself using the credentials you have configured for it. Claudette never reads, copies, or forwards your Claude OAuth tokens, and explicitly strips any inherited subscription tokens from spawned subprocesses so they are never passed through.

Pro/Max plan usage and parallel agents

Per the Claude Code legal and compliance page:

Advertised usage limits for Pro and Max plans assume ordinary, individual usage of Claude Code and the Agent SDK.

Claudette can run multiple agents in parallel git worktrees. We recommend keeping default parallelism low (1–3 simultaneous agents) and treating heavier use as something you explicitly opt into. Whether running N parallel agents counts as "ordinary, individual usage" under your plan is a judgment Anthropic reserves for itself; Claudette is the affordance, but the responsibility for staying within your plan's terms is yours.

If you need higher throughput, the supported path is API-key authentication via Claude Console, which is governed by Anthropic's Commercial Terms.

Plugin secrets storage

Claude Code plugins may require their own secrets (API keys, tokens). Claudette stores these in the same secure-storage object Claude Code itself uses — the macOS Keychain entry Claude Code-credentials, or ~/.claude/.credentials.json on Linux — but only under its own pluginSecrets namespace. Your Claude OAuth tokens (claudeAiOauth.*) are never read or written by Claudette's plugin code.

License

This project is licensed under the MIT License.