Core concepts

This page explains the concepts that come up throughout Gonggong Space and how they relate. Reading it first will make the other pages much easier to follow.

Overview

Account (王磊 Wang Lei)
 ├─ Machine (wanglei-mbp) ── runs the daemon (gg run or the desktop app)
 │    └─ Bot 「后端助手」 (Backend Assistant) ── Agent: Claude Code / Codex
 │         └─ each group it joins → one workspace (group × Bot)
 └─ Group 「todo-app」 ── bound to repository todo-app (base branch main)
      ├─ Members: 王磊, 李娜, 陈晨
      ├─ Bots: 后端助手 (Wang Lei's), 前端助手 (Li Na's)
      └─ Message ──@Bot──→ run ──→ process / diff / approval / question / preview

Concept	Belongs to	In one sentence
Account	—	Your identity for signing in to the web app; the role is sysadmin or member
Machine	An account	A machine with the daemon installed and bound to that account
daemon	A machine	A background program on the machine that picks up tasks and invokes the local agent
Bot	An account (the owner)	An AI member you can @ in a group, pinned to one of its owner's machines
Group / direct chat	Group members	Where people and Bots work together; a direct chat has only you and your Bot
Workspace	A Bot in a group	The directory a Bot works in; one per "group × Bot"
Run	A Bot in a group	One turn of work triggered by @ing a Bot

Accounts and roles

• Sysadmin: can open the 「管理后台」 (admin console) to create accounts, manage all Bots and groups, configure system parameters, and so on. The admin account is created automatically the first time the server starts.
• Member: after signing in, binds their own machines, creates their own Bots, and creates groups.

Self-registration is off by default; the sysadmin creates accounts, and you must change the initial password on first sign-in. See Sign-in and accounts and Accounts and roles (admin console).

Within a group, members are either group admins (who manage group settings, members, and Bots) or regular members. In addition, each Bot's owner is called the Bot owner, and only they can approve that Bot's out-of-scope operations.

Machines and the daemon

A machine is the Mac, PC, or server a member uses to run Bots. Install the Gonggong Space daemon on it and bind it using the one-time connect link or bind command generated by 「绑定新机器」 (Bind new machine) in the web app; the machine then belongs to you.

The daemon comes in two forms with the same functionality:

• The gg CLI: after binding, run gg run to keep it running; see The gg CLI.
• The desktop app (macOS, Tauri): includes the daemon and keeps running in the menu bar after you close the window; see Desktop app.

The daemon reports the machine name, OS, CPU, memory, and the versions of Claude Code / Codex available locally to the server. When the daemon disconnects, the machine shows as 「离线」 (Offline), and tasks sent to Bots on it wait in a queue. See Bind a machine.

Bot

A Bot is an AI member you can @ in a group. It is defined by:

Attribute	Description
Owner	Who the Bot belongs to. Members can only create Bots for themselves; a sysadmin can create one for anyone, in which case the owner must confirm it in a notification before it can be triggered
Execution machine	One of the owner's machines; all of the Bot's work happens on it
Agent	Claude Code or Codex, using the CLI installed and signed in on the execution machine
Character	Avatar and persona: Gong (共字君) by default, plus 12 personality characters
System prompt	Tells the Bot its responsibilities; also shown as its description in groups
Trigger scope	Who can @ it to do work: any group member / a specified list / only me
Permission tier	Read-only / Workspace write / Full access
Command approval	How out-of-scope requests are handled: ask every time / auto-approve allowlist / auto-approve all. Only the Bot owner can change it
Concurrency limit	How many turns can run at once; extra ones queue on the machine

Bot statuses are: online idle, running, offline, agent missing (the selected agent wasn't detected on the machine), plus 「待绑定」 (Pending binding) and 「待确认」 (Pending confirmation) before setup is complete. See Create a Bot and Bot settings and permissions.

Groups and direct chats

• Group: where members and Bots work together. It can be bound to a git repository, or not.
• Direct chat: only you and your Bot—good for personal use.

A Bot is triggered only by @BotName request in a group; messages without an @ don't trigger it and are only passed to it as context. See Groups and direct chats and Directing Bots in a group.

Repositories, workspaces, and modes

• Repository: a group can be bound to a git repository URL and a base branch (default main). Each Bot clones it with its owner's own git credentials on the owner's machine; the server doesn't hold repository credentials for members.
• Workspace: the directory a Bot works in, one per "group × Bot," isolated from each other. There are two kinds:
  • Managed workspace: created and managed automatically by the daemon under ~/.gonggong/workspaces/ on the machine; in a group bound to a repository, it's a managed clone of that repository.
  • Local directory: the Bot owner can use /cd @Bot /absolute/path to have the Bot work directly in an existing directory of theirs, and /cd @Bot --reset to return to the managed workspace.
  • Groups without a repository and direct chats use the Bot's "default workspace" (optional when creating the Bot).
• Partition mode: the group's sync mode. Each Bot makes changes independently in its own workspace, and the Git bar at the top of the group shows each Bot's branch and sync status.

See Repositories and workspaces.

Runs

Each @ to a Bot starts a run (one turn), and a run card appears in the group. Run statuses:

Status	Meaning
「排队中」 (Queued)	This Bot's previous turn in this group hasn't finished, the workspace is still being prepared, or the Bot's concurrency limit is reached
「离线等待」 (Waiting for machine)	The Bot's machine is offline; waiting for it to come online (up to 30 minutes by default, adjustable in group settings)
「无权触发」 (Not allowed to trigger)	The requester isn't in this Bot's trigger scope
「运行中」 (Running)	The agent is working
「等待审批」 / 「等待回答」 (Awaiting approval / Awaiting answer)	Someone needs to handle an approval or answer a question
「已完成」 / 「已中断」 / 「已作废」 (Completed / Interrupted / Voided)	Final states; requests that time out before running are voided

While a run is in progress, you can send a follow-up message to interrupt and append new requirements, or use /stop to stop it. A Bot can hand off a task to another Bot in the group via the built-in 「交给其他 Bot」 (Hand off to another Bot) tool, forming a hand-off chain; writing @ in a Bot's reply is only a mention and doesn't trigger anything. See Runs and Command reference.

Approvals and questions

• Permission approval: when a Bot wants to do something beyond its permission tier (such as running a command), it's handled according to the Bot's command approval setting. When a human needs to decide, an approval card appears, and only the Bot owner can approve or deny it (not even group admins). By default it waits 30 minutes, and an unhandled request is treated as denied; the wait time is adjustable in group settings.
• Questions: when a Bot isn't sure, it asks group members a multiple-choice or open-ended question, which the requester or the Bot owner can answer.

See Approvals and questions.

Previews

A Bot can publish a web service it started, a static page, a desktop app's screen, or a mini program as a preview. A preview card appears in the group, and members open it directly in the browser; to show it to outsiders, you can generate a time-limited public link. Traffic is forwarded through a tunnel between the daemon and the server, and only published ports on the machine are reachable. See Previews and Public sharing.

Context

Each "group × Bot" maps to one persistent agent session, so the Bot remembers earlier conversation in that group. The Bot bar at the top of the group shows each Bot's context usage. When it's nearly full, you can:

• 「压缩上下文」 (Compact context): summarize the earlier conversation and keep the summary;
• 「开新对话」 (New conversation): stop carrying the earlier conversation (same as /new).

Related pages

• Architecture
• Quick start
• Glossary