openhuman/CONTRIBUTING-BEGINNERS.md

# 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`](CONTRIBUTING.md).

---

## Table of Contents

- [What is this project?](#what-is-this-project)
- [Step 1 — Install the required tools](#step-1--install-the-required-tools)
- [Step 2 — Fork and clone the repo](#step-2--fork-and-clone-the-repo)
- [Step 3 — Finish the local setup](#step-3--finish-the-local-setup)
- [Step 4 — Find an issue to work on](#step-4--find-an-issue-to-work-on)
- [Step 5 — Create your branch](#step-5--create-your-branch)
- [Step 6 — Make your change and verify it](#step-6--make-your-change-and-verify-it)
- [Step 7 — Push and open a Pull Request](#step-7--push-and-open-a-pull-request)
- [Optional — Let an AI coding agent guide you](#optional--let-an-ai-coding-agent-guide-you)
- [Keeping your fork up to date](#keeping-your-fork-up-to-date)
- [Troubleshooting common issues](#troubleshooting-common-issues)

---

## What is this project?

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

| Part             | Tech               | What it does                           |
| ---------------- | ------------------ | -------------------------------------- |
| `app/`           | React + TypeScript | The UI — what you see and click        |
| `app/src-tauri/` | Rust + Tauri       | Wraps the UI into a desktop app        |
| `src/`           | Rust               | The backend brain — logic, memory, RPC |

**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

<details>
<summary><strong>macOS setup</strong> (recommended for beginners)</summary>

Install [Homebrew](https://brew.sh) first if you don't have it:

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

Then install everything the project needs:

```bash
# 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
```

Verify everything is installed:

```bash
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
```

> **Node version warning**: The project requires Node 24+. If you see a warning like `Unsupported engine: wanted >=24.0.0 (current: v22.x.x)`, upgrade Node. Using `nvm`? Run `nvm install 24 && nvm use 24`.

</details>

<details>
<summary><strong>Windows setup</strong></summary>

Open PowerShell or Windows Terminal.

Install Node.js 24+ with `nvm-windows`:

```powershell
winget install CoreyButler.NVMforWindows
```

Close and reopen your terminal, then run:

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

Install pnpm:

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

Install Rust:

```powershell
winget install Rustlang.Rustup
```

Close and reopen your terminal, then run:

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

Install CMake:

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

Install Visual Studio Build Tools:

```powershell
winget install Microsoft.VisualStudio.2022.BuildTools
```

When the installer opens, select **Desktop development with C++**. Make sure it includes the Windows SDK and MSVC v143 build tools.

> **Node version warning**: The project requires Node 24+. If you see a warning like `Unsupported engine: wanted >=24.0.0 (current: v22.x.x)`, run `nvm install 24 && nvm use 24`.

</details>

<details>
<summary><strong>Linux (Arch) setup</strong></summary>

Install Node.js 24+, pnpm, Rust, and the native build dependencies:

```bash
# 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
```

For desktop (Tauri/CEF) builds, also install:

```bash
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
```

Verify everything is installed:

```bash
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
```

> **Node version warning**: The project requires Node 24+. If your Arch `nodejs` package is older, install `nvm` and run `nvm install 24 && nvm use 24`.

</details>

<details>
<summary><strong>Linux (Ubuntu/Debian) setup</strong></summary>

Install Node.js 24+ via [NodeSource](https://github.com/nodesource/distributions) or `nvm`:

```bash
# 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
```

Install Rust:

```bash
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
```

Install native build dependencies:

```bash
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
```

For desktop (Tauri/CEF) builds, also install:

```bash
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
```

Verify everything is installed:

```bash
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
```

> **Node version warning**: The project requires Node 24+. If you see `Unsupported engine: wanted >=24.0.0`, run `nvm install 24 && nvm use 24`.

</details>

---

## Step 2 — Fork and clone the repo

### 2a. Fork on GitHub

1. Go to [github.com/tinyhumansai/openhuman](https://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

```bash
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:

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

Verify both remotes exist:

```bash
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:

```bash
git submodule update --init --recursive
```

### 3b. Install dependencies

```bash
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

```bash
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

```bash
# 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](https://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

| Area                 | Where it lives                       | Skills needed     |
| -------------------- | ------------------------------------ | ----------------- |
| UI components        | `app/src/`                           | React, TypeScript |
| Styles / design      | `app/src/`, `app/tailwind.config.js` | CSS, Tailwind     |
| Documentation        | `*.md` files, `gitbooks/`            | Writing           |
| Bug fixes (frontend) | `app/src/`                           | React, TypeScript |

**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`.

```bash
# 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:

```bash
# 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

```bash
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:

```text
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:

```bash
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:

```bash
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:

```bash
git submodule update --init --recursive
```

### Node version warning during `pnpm install`

The project requires Node 24+. Upgrade:

```bash
# 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](https://discord.tinyhumans.ai/) and ask in the contributors channel
- Comment on the issue you're working on
- Check [`gitbooks/developing/getting-set-up.md`](gitbooks/developing/getting-set-up.md) for deeper setup docs

Thank you for contributing to OpenHuman!