# How to Contribute to the OpenHuman Project: A Complete Developer Guide

> Learn how to contribute to the OpenHuman project. Fork the repo, initialize submodules, install dependencies, and follow the Git workflow. Achieve 80% line coverage for your contributions.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: how-to-guide
- Published: 2026-06-11

---

**To contribute to the openhuman project, fork the repository, initialize Tauri submodules with `git submodule update --init --recursive`, install dependencies via `pnpm install`, and follow the Git workflow defined in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md) while maintaining 80% line coverage.**

OpenHuman is a Rust-powered, Tauri-based desktop assistant that combines a React frontend with a native Rust core. To contribute to the openhuman project effectively, you must understand its monorepo layout and the specific toolchain requirements that bridge TypeScript and Rust. This guide provides the exact commands, file paths, and architectural context needed to set up a development environment and submit a valid pull request.

## Repository Structure and Architecture

### Monorepo Layout

The repository organizes code into distinct directories that separate concerns between the frontend shell and the native backend. According to the source code in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md), the layout follows this structure:

- `app/` – The pnpm workspace containing the **openhuman-app** package with the React UI (`app/src/`), Tauri shell (`app/src-tauri/`), and Vitest tests.
- `src/` – The Rust core crate (`openhuman-core`) and the CLI binary.
- `docs/` – Internal design documentation including architecture, security, and iOS client specs.
- `gitbooks/developing/` – Authoritative developer documentation for architecture and setup procedures.
- [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md) and [`CLAUDE.md`](https://github.com/tinyhumansai/openhuman/blob/main/CLAUDE.md) – Repository-specific coding agent rules.
- [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md) – The fast-track guide for bootstrapping and PR workflows.
- [`CONTRIBUTING-BEGINNERS.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING-BEGINNERS.md) – Step-by-step onboarding for first-time contributors.

The full project layout is visualized in the **Project Layout** section of [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md).

### High-Level Architecture

OpenHuman operates as a three-layer system:

1. **React Frontend** – Uses Redux Toolkit for state management, Socket.io for real-time communication, and MCP (Model Context Protocol) for transport.
2. **Tauri IPC Bridge** – Exposes shell commands like `core_rpc_relay` and forwards JSON-RPC calls to the Rust core.
3. **Rust Core** – Hosts business logic, a persistent WebSocket manager, tool registry, security sandbox, and SQLite storage. The core runs either as an embedded child process in the desktop app or as a standalone server via `cargo run --bin openhuman-core`.

The architecture overview in [`gitbooks/developing/architecture.md`](https://github.com/tinyhumansai/openhuman/blob/main/gitbooks/developing/architecture.md) defines the runtime scope and communication boundaries between these layers.

## Development Environment Setup

### Prerequisites

Before cloning, ensure your system meets the toolchain requirements specified in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md):

- Node.js ≥ 24
- pnpm 10.10.0
- Rust 1.93
- CMake and Ninja
- ripgrep
- Vendored Tauri sources (installed via submodules)

### Installation and Configuration

Clone your fork and initialize the repository with these exact steps:

```bash

# Clone your fork and add upstream

git clone git@github.com:YOUR_USERNAME/openhuman.git
cd openhuman
git remote add upstream git@github.com:tinyhumansai/openhuman.git

# Initialize submodules for Tauri and notification plugins

git submodule update --init --recursive

# Install Node dependencies (pnpm enforces the lockfile)

pnpm install

```

After installation, copy the environment templates before running any code:

```bash
cp .env.example .env               # Root Rust core settings

cp app/.env.example app/.env.local # Frontend VITE_* variables

```

These steps are documented in the "Configure for development" section of [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md).

## Building and Testing

### Frontend Development

For web-only development without the desktop shell:

```bash
pnpm dev

```

For the full desktop experience with the Tauri backend:

```bash
pnpm --filter openhuman-app dev:app

```

This command boots Tauri with the vendored CEF toolchain and hot-reloads both the React frontend and Rust glue code.

### Rust Core Development

To work on the core logic independently of the UI, run the standalone JSON-RPC server:

```bash
cargo run --bin openhuman-core

```

This is useful when testing RPC methods or debugging the WebSocket manager and tool registry implemented in `src/openhuman/`.

### Verification Commands

Before submitting changes, run the complete verification suite:

```bash

# TypeScript type checking

pnpm typecheck

# Linting and formatting

pnpm lint
pnpm format:check

# Frontend unit tests

pnpm test

# Rust checks

cargo check
cargo test
pnpm test:rust

# Desktop E2E tests

pnpm test:e2e

```

All commands are listed under "Bootstrap commands" in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md).

## Git Workflow and Submission Process

### Syncing and Branching

Keep your fork synchronized with the upstream repository:

```bash
git fetch upstream
git checkout main
git pull --ff-only upstream main

```

Create focused branches following the naming conventions in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md):

```bash
git checkout -b feat/your-feature

```

### CI Requirements and Coverage

All pull requests must pass the CI suite which includes typecheck, lint, format, and Rust checks. The project enforces a **80% changed-line coverage** minimum via `diff-cover` in CI. Additionally, tool execution is gated by the security sandbox defined in [`src/openhuman/security/policy.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/security/policy.rs).

When ready to submit:

```bash
git push origin feat/your-feature

# Open PR against tinyhumansai/openhuman:main and fill the PR template

```

For AI-authored contributions, also follow the Codex checklist in [`docs/agent-workflows/codex-pr-checklist.md`](https://github.com/tinyhumansai/openhuman/blob/main/docs/agent-workflows/codex-pr-checklist.md).

## Coding Standards and Conventions

### Logging and Security

Follow the logging conventions in [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md): prefix logs with domain tags like `[socket]` or `[rpc]`, and never print sensitive credentials. All persistent data must live in the Rust core or OS keychain, not `localStorage`. The security sandbox supports backends including Docker and bubblewrap, configured via the policy engine.

### Documentation

Keep the GitBook documentation in `gitbooks/developing/` as the source of truth. Use ESLint and Prettier for TypeScript, and `cargo fmt` with `clippy` for Rust. Prefer Redux Toolkit over ad-hoc state management in the frontend.

## Summary

- **OpenHuman** uses a monorepo structure separating the React/Tauri frontend (`app/`) from the Rust core (`src/`).
- **Setup requires** Node ≥ 24, pnpm 10.10.0, Rust 1.93, and initialized git submodules for Tauri dependencies.
- **Development commands** include `pnpm --filter openhuman-app dev:app` for the full stack and `cargo run --bin openhuman-core` for core-only work.
- **Quality gates** enforce 80% diff coverage, ESLint/Prettier formatting, and `cargo fmt` compliance.
- **Key files** include [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md) for workflow, [`AGENTS.md`](https://github.com/tinyhumansai/openhuman/blob/main/AGENTS.md) for logging rules, and [`src/openhuman/security/policy.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/security/policy.rs) for sandbox configuration.

## Frequently Asked Questions

### What are the minimum system requirements to contribute to the OpenHuman project?

You need Node.js version 24 or higher, pnpm 10.10.0, Rust 1.93, and build tools including CMake and Ninja. The repository also requires ripgrep for certain development scripts. All dependencies are enforced via the lockfiles in [`pnpm-workspace.yaml`](https://github.com/tinyhumansai/openhuman/blob/main/pnpm-workspace.yaml) and [`Cargo.toml`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml).

### How do I run just the Rust backend without the desktop UI?

Execute `cargo run --bin openhuman-core` from the repository root. This starts the JSON-RPC server and WebSocket manager as a standalone process, allowing you to test core logic and tool execution without launching the Tauri frontend.

### Why does the initial clone require submodule initialization?

OpenHuman vendors the Tauri source tree and notification plugins as submodules to maintain compatibility with specific CEF toolchain versions. You must run `git submodule update --init --recursive` after cloning to download these dependencies, or the desktop build will fail.

### What is the coverage requirement for pull requests?

All PRs must maintain at least 80% coverage on changed lines, enforced by `diff-cover` in the CI pipeline. You should run `pnpm test` and `cargo test` locally before pushing, and ensure the PR template is fully completed according to the standards in [`CONTRIBUTING.md`](https://github.com/tinyhumansai/openhuman/blob/main/CONTRIBUTING.md).