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

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 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, 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 and CLAUDE.md – Repository-specific coding agent rules.
• CONTRIBUTING.md – The fast-track guide for bootstrapping and PR workflows.
• 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.

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

• 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:

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

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.

Building and Testing

Frontend Development

For web-only development without the desktop shell:

pnpm dev

For the full desktop experience with the Tauri backend:

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:

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:

# 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.

Git Workflow and Submission Process

Syncing and Branching

Keep your fork synchronized with the upstream repository:

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

Create focused branches following the naming conventions in CONTRIBUTING.md:

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.

When ready to submit:

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.

Coding Standards and Conventions

Logging and Security

Follow the logging conventions in 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 for workflow, AGENTS.md for logging rules, and 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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}