Skip to content

Contributing to development ​

This page introduces Gonggong Space's tech stack and where to start the first time you read the code.

Gonggong Space is a pnpm + Cargo monorepo: TypeScript for the server, the web client, and the desktop app UI; Rust for the daemon and gg command line on members' machines. Both sides share one protocol definition.

Tech stack at a glance ​

PartTechnologyVersion (the repository lockfiles are authoritative)
Web client apps/webReact + Vite, routing with react-router, state with zustand, syntax highlighting with shikiReact 19.3, Vite 8.3
Server apps/serverFastify + Drizzle ORM + PostgreSQL (driver postgres)Fastify 5.12, drizzle-orm 0.45, drizzle-kit 0.31
daemon and gg crates/gonggongRust (edition 2024), tokio, clap, agent-client-protocolagent-client-protocol 2.2
Desktop app apps/desktopTauri 2 + React, reusing crates/gonggong and the web componentsTauri 2.12
Protocol packages/protocolAll wire contracts defined with zodzod 4.6
TestsVitest (TS unit/integration), cargo test, Playwright (end-to-end)Vitest 5.0, Playwright 1.63
Code checksBiome (formatting + lint), TypeScriptBiome 2.5, TypeScript 5.9
Docs site websiteVitePress1.6

Prerequisites:

  • Node.js 24+. The pnpm version is pinned by the packageManager field in the root package.json (just run corepack enable).
  • Rust: the version is pinned by rust-toolchain.toml. Install it with rustup and make sure rustup's cargo comes before any other cargo on your PATH (such as Homebrew's rust); cargo --version should show the pinned version.
  • PostgreSQL: only the command-line tools are needed; the dev database is started by a repository script. See Local development and testing.

Where to start reading ​

  1. Read Architecture first to understand how the server, web client, daemon, and Agents relate.
  2. Look at Repository structure to learn where each piece of code lives.
  3. Follow Local development and testing to run the server, web client, and daemon on your machine, then create a Bot and try it end to end.
  4. Read packages/protocol/src/: it's the contract for every API and message. Once you understand it, you can trace the corresponding implementations in the server and daemon. See Protocol.
  5. Go deeper based on your interests:
    • How a run is scheduled: apps/server/src/modules/runs/
    • How the daemon drives Agents: crates/gonggong/src/engine.rs, session.rs, turn.rs, and the plugin-declared Agent adapters in adapters.rs
    • The UI: apps/web/src/features/chat/, apps/web/src/ui/
  6. Before you start coding, read the Contribution guide.

TIP

CLAUDE.md and AGENTS.md in the repository root are condensed versions of the development conventions (structure, commands, i18n, testing rules). AI coding tools read them automatically when you use them to contribute.

Released under the Apache License 2.0