Thank you for your interest in contributing to OpenHuman. This guide is the fast path for getting a fresh checkout running locally, validating changes, and opening a pull request without having to piece together setup notes from multiple files.

New to open source or coding? Start with CONTRIBUTING-BEGINNERS.md — it walks you through every step from installing tools to opening your first PR.

For deeper architecture and subsystem references, use the GitBook under gitbooks/developing/. For coding-agent and repository-specific implementation rules, see AGENTS.md and CLAUDE.md.

• Code of Conduct
• Getting Started
• Development Setup
• Project Layout
• Git Workflow
• Making Changes
• Submitting Changes
• Project Conventions

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

• Read the README for product context.
• Use gitbooks/developing/architecture.md for the current system architecture.
• Check open issues and discussions before starting work.
• For security issues, follow SECURITY.md and do not file public issues.

Windows requires several additional tools that are not needed on macOS or Linux. Install them in the order listed below, restarting your terminal after each step so PATH changes take effect.

1. Visual Studio C++ Build Tools

Rust's cargo needs a linker on Windows. The easiest way to get one is during rustup-init: select option 1 (Default installation) when prompted, which includes MSVC v143 and the Windows 11 SDK. This is the full Visual Studio installer, not the VS Code lightweight editor — it lives only on C: and consumes ~5.4 GB.

2. LLVM / Clang

whisper-rs-sys depends on libclang. Download the Windows x86_64 release from github.com/llvm/llvm-project/releases (~822 MB). During install, check "Add LLVM to system PATH for all users". If you see a "PATH too long" warning, skip the PATH step and set the environment variable manually:

LIBCLANG_PATH=C:\Program Files\LLVM\bin

3. CMake

whisper.cpp requires CMake. Install via winget:

winget install Kitware.CMake

4. Node.js and pnpm

Install Node.js 24+ and [email protected] as usual.

Recommended install order

1. VS Build Tools → restart terminal
2. Rust (rustup) → restart terminal
3. LLVM → restart terminal
4. CMake → restart terminal
5. Node.js + pnpm

Quick dependency check

# Verify all required tools are reachable
rustc --version
cargo --version
clang --version
cmake --version
node --version
pnpm --version

# Verify libclang is accessible (needed by whisper-rs-sys)
$env:LIBCLANG_PATH = "C:\Program Files\LLVM\bin"
clang -v

• Web-only development needs Node, pnpm, and the Rust toolchain present in the repo. You can usually ignore desktop-only system packages.
• Desktop development needs the vendored Tauri/CEF setup. The preferred entrypoint is pnpm --filter openhuman-app dev:app, which ensures the vendored Tauri CLI is installed and configures CEF_PATH.
• Linux desktop builds require extra system packages beyond Node/Rust. Follow the distro-specific Tauri dependency list before running desktop commands, then use the OpenHuman scripts below. For deeper platform troubleshooting, see gitbooks/developing/getting-set-up.md.
• Windows 10 WSL + classic X11 forwarding is unsupported for the desktop app. The Tauri/CEF stack can hang, render blank windows, or crash before useful app logs are available. Use native Windows development, or Windows 11 WSLg if you need a Linux GUI workflow. OpenHuman logs a startup warning when it detects WSL with DISPLAY set but no WAYLAND_DISPLAY/WSLg markers.
• Windows desktop builds additionally require Visual Studio C++ Build Tools (MSVC v143), LLVM/Clang, and CMake. See Windows-specific setup for the full list and install order.
• Skills development happens in the separate tinyhumansai/openhuman-skills repository. This repo consumes built skill bundles from GitHub or a local override path; it does not vendor the skills source as a submodule.

Example macOS bootstrap with Homebrew:

brew install node@24 pnpm rustup-init cmake
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

Fork the upstream repository on GitHub first if you plan to submit changes, then clone your fork:

git clone [email protected]:YOUR_USERNAME/openhuman.git
cd openhuman
git remote add upstream [email protected]:tinyhumansai/openhuman.git
git submodule update --init --recursive
pnpm install

Why submodules matter here:

• app/src-tauri/vendor/tauri-cef
• app/src-tauri/vendor/tauri-plugin-notification

Those vendored trees are part of the current desktop toolchain. If they are missing, desktop builds and Tauri CLI setup will fail.

OpenHuman uses two environment templates:

• Root .env.example: Rust core, Tauri shell, shared runtime settings.
• app/.env.example: frontend VITE_* variables for the web app.

Copy them to local-only files before editing:

cp .env.example .env
cp app/.env.example app/.env.local

Minimal configuration guidance:

• Web UI / frontend work: the defaults in app/.env.local are usually enough for local startup. Set VITE_BACKEND_URL only if you need a non-production backend in web mode.
• Desktop work: leave OPENHUMAN_CORE_TOKEN blank for local child-mode development unless you are intentionally wiring an external core. The shell manages the embedded core token flow.
• Core RPC / standalone core work: OPENHUMAN_CORE_PORT=7788 and OPENHUMAN_CORE_RPC_URL=http://127.0.0.1:7788/rpc are already documented in the root template and are the normal local defaults.
• Skills development: use SKILLS_REGISTRY_URL or SKILLS_LOCAL_DIR from the root template when pointing the app at a local built skills checkout.

Never commit .env, app/.env.local, tokens, or other secrets.

These commands cover the most common local workflows from the repository root:

# Install workspace dependencies
pnpm install

# Web-only development (Vite dev server)
pnpm dev

# Preferred desktop development path (sets up vendored Tauri CLI + CEF env)
pnpm --filter openhuman-app dev:app

# Lower-level Tauri command entrypoint
pnpm tauri dev

# Standalone Rust core
cargo run --manifest-path Cargo.toml --bin openhuman-core

Which mode to choose:

• pnpm dev: frontend-only iteration in the browser.
• pnpm --filter openhuman-app dev:app: full desktop app flow with Tauri + CEF.
• cargo run --bin openhuman-core: core/RPC work when you want the Rust server without the desktop shell.

If setup is correct, these commands should all succeed:

pnpm typecheck
pnpm lint
pnpm format:check
cargo check --manifest-path Cargo.toml
cargo check --manifest-path app/src-tauri/Cargo.toml

If you only changed docs in a normal local workflow, pnpm format:check is usually the only validation you need. AI-authored or remote-agent PRs must still follow docs/agent-workflows/codex-pr-checklist.md and report any blocked commands with the exact command and error.

Merge-gate context:

• PRs must meet the checks enforced by CI and keep changed-line coverage at or above 80%.
• For code changes, run the smallest relevant local checks before you push.
• For AI-authored or remote-agent PRs, also follow docs/agent-workflows/codex-pr-checklist.md.

Useful local paths during development:

• ~/.openhuman/: default workspace for the Rust core and local app data.
• ~/.openhuman-staging/: staging workspace when OPENHUMAN_APP_ENV=staging.
• app/.env.local: browser-facing VITE_* overrides.
• .env: Rust core, Tauri shell, and shared runtime overrides.

Most contributor-visible configuration and state flows are documented in:

• gitbooks/developing/getting-set-up.md
• gitbooks/developing/architecture/frontend.md
• gitbooks/developing/architecture/tauri-shell.md

openhuman/
├── app/                    # React app, Tauri shell, Vitest tests
│   ├── src/
│   ├── src-tauri/
│   └── test/
├── src/                    # Rust core crate and openhuman-core binary
├── docs/                   # Internal and workflow docs
├── gitbooks/developing/    # Contributor-facing architecture and setup guides
├── scripts/                # Dev, test, debug, and automation scripts
├── AGENTS.md               # Coding-agent repo rules
└── CLAUDE.md               # Additional contributor and workflow guidance

Short version:

• app/ is the UI and desktop shell.
• Root src/ is the Rust core and JSON-RPC surface.
• gitbooks/developing/ is the canonical place for deeper subsystem docs.

• Fork tinyhumansai/openhuman and push branches to your fork.
• Pull requests target the upstream main branch.
• Do not push directly to upstream unless you are explicitly authorized to do so.

Use a short descriptive branch name, for example:

• fix/socket-reconnect
• feat/settings-shortcuts
• docs/contributing-setup

git fetch upstream
git checkout main
git pull --ff-only upstream main
git checkout -b docs/your-change

1. Start from main and create a focused branch.
2. Keep the diff small and scoped to the issue you are solving.
3. Run the smallest relevant checks locally before pushing.
4. Update docs with code whenever behavior, commands, or contributor workflow changes.

• Verify the command you are documenting exists in the current repo.
• Prefer source-of-truth files such as package.json, app/package.json, Cargo.toml, rust-toolchain.toml, and the env templates over older prose docs.
• Link to GitBook chapters for deeper architecture instead of duplicating large internal explanations.

1. Push your branch to your fork.
2. Open a pull request against tinyhumansai/openhuman:main.
3. Fill in .github/PULL_REQUEST_TEMPLATE.md completely.
4. Link the issue using a closing keyword such as Closes #1441.
5. Call out any blocked validation commands with the exact command and error.

If you are contributing through a coding agent or remote environment, include the metadata required by the PR template and the Codex PR checklist.

Maintainers can reward eligible contributors through the automated workflow in docs/CONTRIBUTOR-REWARDS.md. First merged pull requests are handled automatically, and maintainers can apply the reward user label to manually start the same Discord and merch invite flow.

• Use Redux and existing app state patterns instead of adding new ad hoc browser storage.
• Treat Rust core logic as the source of truth; avoid re-implementing business rules in the Tauri shell.
• Use the controller registry and domain module structure described in AGENTS.md for new Rust functionality.
• Keep logs grep-friendly and avoid logging secrets, tokens, or full PII.
• Follow ESLint, Prettier, and Rust formatting output as authoritative.

Thank you for contributing to OpenHuman.