Beginner's Guide to Contributing to OpenHuman

New to open source or coding? This guide walks you through everything from zero to your first pull request — based on real setup pain points that new contributors hit.

For the full contributor reference, see CONTRIBUTING.md.

Table of Contents

• What is this project?
• Step 1 — Install the required tools
• Step 2 — Fork and clone the repo
• Step 3 — Finish the local setup
• Step 4 — Find an issue to work on
• Step 5 — Create your branch
• Step 6 — Make your change and verify it
• Step 7 — Push and open a Pull Request
• Optional — Let an AI coding agent guide you
• Keeping your fork up to date
• Troubleshooting common issues

What is this project?

OpenHuman is a desktop AI assistant app. The codebase has three main parts:

As a beginner, focus on app/src/ (React/TypeScript). You don't need to touch Rust to make meaningful contributions.

Step 1 — Install the required tools

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js 24+ and pnpm (JavaScript package manager)
brew install node@24
npm install -g pnpm@10.10.0

# Rust (the backend language)
brew install rustup-init
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

# CMake (required by Rust dependencies)
brew install cmake

# Xcode Command Line Tools (macOS build tools)
xcode-select --install

node --version     # should be v24.x.x or higher
pnpm --version     # should be 10.10.0
rustc --version    # should be 1.93.0
cmake --version    # any recent version

winget install CoreyButler.NVMforWindows

nvm install 24
nvm use 24
node --version     # should be v24.x.x or higher

npm install -g pnpm@10.10.0
pnpm --version     # should be 10.10.0

winget install Rustlang.Rustup

rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0
rustc --version    # should be 1.93.0

winget install Kitware.CMake
cmake --version    # any recent version

winget install Microsoft.VisualStudio.2022.BuildTools

# Node.js and npm (Arch ships current Node)
sudo pacman -S --needed nodejs npm

# pnpm (JavaScript package manager)
npm install -g pnpm@10.10.0

# Rust via rustup
sudo pacman -S --needed rustup
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

# Build tools required by native Rust crates (whisper-rs, cpal, enigo, etc.)
sudo pacman -S --needed base-devel cmake pkgconf clang openssl \
  alsa-lib xdotool libxtst libxi libevdev

sudo pacman -S --needed gtk3 webkit2gtk-4.1 libayatana-appindicator \
  librsvg patchelf nss nspr at-spi2-core libcups libdrm \
  libxkbcommon libxcomposite libxdamage libxfixes libxrandr \
  mesa pango cairo libxshmfence

node --version     # should be v24.x.x or higher
pnpm --version     # should be 10.10.0
rustc --version    # should be 1.93.0
cmake --version    # any recent version

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"

nvm install 24
nvm use 24

# pnpm
npm install -g pnpm@10.10.0

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install 1.93.0 --profile minimal
rustup component add rustfmt clippy --toolchain 1.93.0

sudo apt-get update
sudo apt-get install -y \
  build-essential cmake pkg-config clang libssl-dev libclang-dev \
  libasound2-dev libxi-dev libxtst-dev libxdo-dev libudev-dev \
  libstdc++-14-dev

sudo apt-get install -y \
  libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev \
  patchelf libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
  libgbm1 libpango-1.0-0 libcairo2 libatspi2.0-0 libxshmfence1 libu2f-udev

node --version     # should be v24.x.x or higher
pnpm --version     # should be 10.10.0
rustc --version    # should be 1.93.0
cmake --version    # any recent version

Step 2 — Fork and clone the repo

2a. Fork on GitHub

1. Go to github.com/tinyhumansai/openhuman
2. Click Fork (top right)
3. This creates your own copy at github.com/YOUR_USERNAME/openhuman

2b. Clone your fork locally

git clone https://github.com/YOUR_USERNAME/openhuman.git
cd openhuman

2c. Add the upstream remote

This links your local copy to the original repo so you can pull in updates later:

git remote add upstream https://github.com/tinyhumansai/openhuman.git

Verify both remotes exist:

git remote -v
# origin    https://github.com/YOUR_USERNAME/openhuman.git  ← your fork
# upstream  https://github.com/tinyhumansai/openhuman.git   ← the original

Step 3 — Finish the local setup

3a. Initialize submodules

The project includes vendored Tauri and CEF code as git submodules. You must do this before installing dependencies or desktop builds will fail:

git submodule update --init --recursive

3b. Install dependencies

pnpm install

pnpm not found? If your shell can't find pnpm after installing it, run export PATH="$PATH:$(npm root -g)/.bin" and try again. Add that line to your ~/.zshrc or ~/.bashrc to make it permanent.

3c. Set up environment files

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

The defaults work for web-only development. You don't need to change anything to get started.

3d. Start the app

# Web UI only (easiest — runs in your browser)
pnpm dev

# Full desktop app (needs Rust + Tauri built first)
pnpm --filter openhuman-app dev:app

For your first contribution, pnpm dev is all you need.

Step 4 — Find an issue to work on

1. Go to github.com/tinyhumansai/openhuman/issues
2. Filter by label — look for good first issue, documentation, or frontend-related labels
3. Read the issue fully before starting
4. Leave a comment saying you'd like to work on it — this avoids two people solving the same issue

Recommended first areas for beginners

Avoid for now: anything in src/ (Rust core) or app/src-tauri/ (Tauri shell) until you're comfortable with the codebase.

Step 5 — Create your branch

Always create a new branch for each issue. Never work directly on main.

# Make sure your main is up to date first
git fetch upstream
git checkout main
git pull --ff-only upstream main

# Create a branch named after what you're doing
git checkout -b fix/your-issue-description
# or
git checkout -b docs/your-doc-change
# or
git checkout -b feat/your-feature-name

Step 6 — Make your change and verify it

After making your changes, run the relevant checks:

# For any change — check formatting
pnpm format:check

# For frontend code changes
pnpm typecheck   # TypeScript errors
pnpm lint        # Code style issues

# Auto-fix formatting issues
pnpm format

If you only changed documentation (.md files), pnpm format:check is the only check you need to run.

Step 7 — Push and open a Pull Request

Push your branch

git add .
git commit -m "your short description of what you changed"
git push -u origin your-branch-name

Open the PR

1. Go to your fork on GitHub: github.com/YOUR_USERNAME/openhuman
2. You'll see a "Compare & pull request" banner — click it
3. Make sure the PR targets tinyhumansai/openhuman:main (not your fork)
4. Fill in the PR template completely
5. Link the issue with Closes #ISSUE_NUMBER in the description
6. Submit

Optional — Let an AI coding agent guide you

If you use Claude Code, Cursor, AmpCode, Codex, or another coding agent, you can paste this prompt after cloning the repo:

I want to make my first contribution to OpenHuman. First read these upstream docs:

CONTRIBUTING.md: https://raw.githubusercontent.com/tinyhumansai/openhuman/main/CONTRIBUTING.md
AGENTS.md: https://raw.githubusercontent.com/tinyhumansai/openhuman/main/AGENTS.md
CLAUDE.md: https://raw.githubusercontent.com/tinyhumansai/openhuman/main/CLAUDE.md

If you can see the cloned repo locally, also read those files directly from the repo. Then guide me step by step: verify my tools, install dependencies, initialize submodules, create a branch, make the smallest safe change for my issue, run the right checks, and prepare a PR. Do not skip failed checks; explain any blocked command with the exact command and error.

The agent should still ask before destructive actions like deleting files, resetting branches, or force-pushing. You are responsible for reviewing the final diff before opening a PR.

Keeping your fork up to date

Before starting any new work, sync your fork with the latest upstream changes:

git fetch upstream
git checkout main
git pull --ff-only upstream main
git push origin main

Troubleshooting common issues

pnpm: command not found

pnpm was installed but your shell can't find it. Fix:

export PATH="$PATH:$(npm root -g)/.bin"

Make it permanent by adding that line to ~/.zshrc.

submodule errors or missing Tauri vendor files

You skipped the submodule step. Run:

git submodule update --init --recursive

Node version warning during pnpm install

The project requires Node 24+. Upgrade:

# If using nvm
nvm install 24
nvm use 24

# If using Homebrew
brew install node@24

pnpm typecheck or pnpm lint errors on unchanged files

These may be pre-existing issues on main unrelated to your change. Note them in your PR description and proceed.

Desktop build fails (pnpm --filter openhuman-app dev:app)

The desktop build requires the full Rust toolchain and vendored Tauri setup. For your first contributions, stick to pnpm dev (web mode) and skip the desktop build entirely.

Still stuck?

• Join the Discord and ask in the contributors channel
• Comment on the issue you're working on
• Check gitbooks/developing/getting-set-up.md for deeper setup docs

Thank you for contributing to OpenHuman!