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.
- 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
- Keeping your fork up to date
- Troubleshooting common issues
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.
Install Homebrew first if you don't have it:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Then install everything the project needs:
# 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 --installnode --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 versionNode 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. Usingnvm? Runnvm install 24 && nvm use 24.
- Go to github.com/tinyhumansai/openhuman
- Click Fork (top right)
- This creates your own copy at
github.com/YOUR_USERNAME/openhuman
git clone https://github.com/YOUR_USERNAME/openhuman.git
cd openhumanThis links your local copy to the original repo so you can pull in updates later:
git remote add upstream https://github.com/tinyhumansai/openhuman.gitVerify both remotes exist:
git remote -v
# origin https://github.com/YOUR_USERNAME/openhuman.git ← your fork
# upstream https://github.com/tinyhumansai/openhuman.git ← the originalThe 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 --recursivepnpm installpnpm not found? If your shell can't find
pnpmafter installing it, runexport PATH="$PATH:$(npm root -g)/.bin"and try again. Add that line to your~/.zshrcor~/.bashrcto make it permanent.
cp .env.example .env
cp app/.env.example app/.env.localThe defaults work for web-only development. You don't need to change anything to get started.
# Web UI only (easiest — runs in your browser)
pnpm dev
# Full desktop app (needs Rust + Tauri built first)
pnpm --filter openhuman-app dev:appFor your first contribution, pnpm dev is all you need.
- Go to github.com/tinyhumansai/openhuman/issues
- Filter by label — look for
good first issue,documentation, or frontend-related labels - Read the issue fully before starting
- Leave a comment saying you'd like to work on it — this avoids two people solving the same issue
| 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.
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-nameAfter 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 formatIf you only changed documentation (.md files), pnpm format:check is the only check you need to run.
git add .
git commit -m "your short description of what you changed"
git push -u origin your-branch-name- Go to your fork on GitHub:
github.com/YOUR_USERNAME/openhuman - You'll see a "Compare & pull request" banner — click it
- Make sure the PR targets
tinyhumansai/openhuman:main(not your fork) - Fill in the PR template completely
- Link the issue with
Closes #ISSUE_NUMBERin the description - Submit
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 mainpnpm 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.
You skipped the submodule step. Run:
git submodule update --init --recursiveThe project requires Node 24+. Upgrade:
# If using nvm
nvm install 24
nvm use 24
# If using Homebrew
brew install node@24These may be pre-existing issues on main unrelated to your change. Note them in your PR description and proceed.
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.
- Join the Discord and ask in the contributors channel
- Comment on the issue you're working on
- Check
gitbooks/developing/getting-set-up.mdfor deeper setup docs
Thank you for contributing to OpenHuman!