Skip to content

Repository structure ​

This page explains what each directory in the repository is responsible for, and how work is divided among the server's domain modules, the web feature directories, the desktop app, and the daemon modules.

Top-level directories ​

DirectoryResponsibility
apps/webWeb client (React + Vite). src/ui/ holds the design system components, src/features/<domain>/ organizes pages and components by domain, src/app/ is the app shell (sidebar, layout, workbench), and src/i18n/ is i18n
apps/serverServer (Fastify + Drizzle + PostgreSQL). src/modules/<domain>/ organizes routes and services by domain; src/db/schema.ts is the single table definition, with migration files in drizzle/; src/daemon/ is the daemon WebSocket gateway, and src/realtime/ is the real-time channel to browsers; plugins/official/ holds the built-in plugins; install/ holds the install scripts for member machines and the 「发给你的 Agent」 (Send to your agent) connection instructions
apps/desktopDesktop app 「共工空间」 (Tauri). src/ is the React UI (which imports the web source and components directly), and src-tauri/ is the Rust shell, which depends on crates/gonggong to run the daemon in-process
crates/gonggongThe daemon and gg command line on member machines (binary name gg). presets/ holds built-in model provider presets, skills/ holds built-in Skills, and integration tests are in tests/
crates/gg-castThe live view streaming component gg-cast; not part of the Cargo workspace and built separately
packages/protocolAll wire contracts (zod): web ⇄ server APIs, daemon ⇄ server messages, preview tunnel frames, built-in MCP tools, the plugin manifest, and the i18n core. fixtures/*.json are shared samples of the daemon protocol that both TS and Rust must round-trip; cases/ holds other cross-language shared cases
tools/mock-agentA scriptable ACP Agent used instead of real Agents in daemon tests and some end-to-end tests; it decides what to do from the prompt (such as mock:echo, mock:slow, mock:crash)
tools/mcp-echoA minimal stdio MCP server (with a single echo tool) that tests use to verify MCP injection
examples/pluginsPlugin example (dashboard), demonstrating the gonggong-plugin.json manifest and a Skill bundled with a plugin
e2ePlaywright end-to-end tests: real server + web client + daemon + Agent
scriptsDevelopment and operations scripts: pg.sh (project-local PostgreSQL), check.sh (pre-push self-check), dev-cert.sh (self-signed dev certificate), backup.sh / restore.sh, release.sh and release/ (packaging and release), docker/ (nginx and startup scripts for the server image), gui-e2e.sh / linux-e2e.sh, and more
docker/daemonImage and Compose file for running a member machine (daemon) in a container
Dockerfile, docker-compose.ymlServer image and one-command deployment
videosSource projects for the promo and feature walkthrough videos (HTML animations rendered with hyperframes); each directory has its own instructions
websiteThis help manual (VitePress); scripts/ holds the screenshot scripts
docsRequirements, design, and release notes (release-notes/), for background reference; where they conflict with the code, the code wins

Server domain modules ​

Located in apps/server/src/modules/. Each directory usually contains routes.ts (HTTP/WS routes) and service.ts (business logic).

ModuleResponsibility
adminAdmin console: system parameters (params.ts), audit log, and more
agent-toolsBuilt-in MCP tools answered by the server (reading chat history, group info, run records, market, knowledge base, and so on); the daemon forwards calls using the run in progress as its credential
approvalsPermission approvals: creating, approving, rejecting, and voiding Agent requests that exceed its permissions
artifactsManaged artifacts and the multi-screen canvas: versions, annotations, sharing
attachmentsUploading, storing, and downloading message attachments
authSign-in, sessions, registration, and creating admin on first startup (bootstrap.ts)
avatarsAvatar upload (including using the Feishu avatar)
botsBot CRUD, assigned machine, permission tier, approval mode and Agent configuration, sharing
candidates@ suggestions in the input box: fetches the workspace file list from the Bot's daemon, using a cache when it's slow or offline
commandsParsing and executing group commands (/cd, stop, system commands, Agent commands)
conversation-statsConversation statistics
feishuFeishu apps, sign-in, group binding, cards, and message sync
gitGit management on the web (branches, log, commits, diffs, conflicts, and so on), forwarded to the Bot's machine for execution
git-accountsMembers' Git hosting accounts (tokens) used for repository access
group-tabsCustom tabs at the top of a group
groupsGroups and direct chats: members, Bots, settings, repositories
knowledgeGroup knowledge base entries and versions
liveLive views (LiveKit): watching, control, and gg-cast status
machinesMachine binding, connection confirmation, details, upgrades, Git access, network measurement, and Agent tools read and written live through the daemon
marketSkill market: listing, review, installs, and bans
mcpMCP server configuration at three levels (platform, team, group), injected when a session is created (the name gonggong is reserved for the built-in server)
messagesSending, quoting, and recalling messages, and appending during a run
notificationsNotification center and Web Push
pinsPinned group messages
pluginsPlugin upload, enabling, machine authorization, built-in plugins, and creation
previewsPreviews: tunnel, gateway proxy, hosted services, public share links
providersMachine model providers: only forwarded live to the daemon, never written to the database
questionsCards and answers for Bots asking group members questions
reactionsMessage emoji reactions
releasesClient releases: uploading daemon and desktop builds for auto-upgrade downloads
reposTeam repository history and repository accessibility probing
runsThe core of runs: triggering, scheduling, receiving daemon reports, redaction, stopping, reconciliation, and retention cleanup
saved「稍后处理」 (Later): saved messages and reminders
schedulesSchedules
searchGlobal search (messages, changed files)
secretsSecrets at four levels: platform, team, group, personal
sidebarCustom groupings in the conversation list
skillsTeam, group, repository, and personal Skills and their versions
syncForced sync: versions, file chunks, and conflict handling when several machines in a group share one workspace
team-sectionsTeam directory and join requests
teamsTeams and members
terminalsWeb terminal sessions
threadsThreads
usageUsage statistics
usersUser profile cards, disabling
workspacesThe workspace of each (group, Bot): preparation, /cd, file browsing, diff, and status

Web feature directories ​

Located in apps/web/src/features/. Each directory has its own English dictionary en.ts.

DirectoryContents
adminAdmin console layout and pages (accounts, teams, groups, machines, schedules, system parameters, client releases, audit)
artifactsArtifacts and the prototype canvas
attachmentsInput box attachments, message attachment display, and viewers (including the video player)
authSign-in, registration, password change, avatar menu
botsNew Bot, Bot settings, Agent configuration, Bot page, avatars
chatThe main group message view: message timeline, input box and suggestions, Git bar, context usage, new group
configAdmin console · configuration center
conversation-statsConversation statistics
diffDiff pane
feishuFeishu settings and binding
filesFile viewer
gitGit panel: commits, log, branches, conflict resolution, stash
group-tabsTabs at the top of a group
groupsGroup info, group announcement, group settings
knowledgeKnowledge base
machinesMy machines and Bots, bind new machine, machine details, Agent tools, providers, storage management
marketSkill market
notificationsNotification center and browser push
onboardingNew-user onboarding
pluginsPlugin management and the creation panel
previewsPreview cards, live views, share links, the admin public links page
reactionsEmoji reactions
reposRepository picker and repository access checks
richRich content in Bot replies (HTML pages, Mermaid diagrams, action buttons)
runsRun cards and run details: process, context, approvals, questions, interrupt and append
savedLater
schedulesSchedules
searchSearch overlay
secretsSecrets
settingsPersonal settings
syncForced-sync status bar, sync panel, and conflict handling
teamsTeams
terminalTerminal
usageUsage page
usersUser cards (hover profiles)
workbenchTabs of the right-hand workbench (runs, diff, files, web, mini program, live view, and more)
worksWorks library
workspacesWorkspace and directory picker

Desktop app ​

LocationContents
apps/desktop/src/pages/Pages: Overview, Agent, Bot, Workspaces, Online previews, Live views, Market, Logs & diagnostics, Settings, and run details
apps/desktop/src/onboarding/First-run setup (binding)
apps/desktop/src/shell/, providers/Window shell, provider editing
apps/desktop/src-tauri/src/commands/Tauri commands for each page, calling into crates/gonggong
apps/desktop/test/Desktop UI tests (Vitest, with IPC mocked by ipc-mock.ts)

Main daemon modules ​

Located in crates/gonggong/src/. main.rs is the gg command-line entry point, and lib.rs collects the modules for reuse by the desktop app.

ModuleResponsibility
daemon.rsThe overall daemon handle (shared by gg run and the desktop app): single-instance lock, service and engine, revocation cleanup, live status
service.rsThe WebSocket connection to the server: sending, receiving, and a byte-capped send buffer
engine.rsExecutes runs sent by the server; one ACP adapter process per (group, Bot); installs pinned versions of the Claude Code / Codex adapters
adapters.rsAdapters declared by the built-in Agent plugin manifests (Gemini CLI, CodeBuddy, pi, DeepSeek Harness, Antigravity CLI), with manifests compiled into the binary
session.rsA single (group, Bot) session: adapter process, ACP session, and turns
turn.rsPure per-turn logic: building prompts, mapping ACP updates to run events, permission tier policy
local/trust.rs, local/shell.rsThe rules 「帮我审批」 (Review for me) allows by, and the shell state of command-line parsing
ledger.rsEstimates what makes up a session's context (the 「上下文」 (Context) tab in run details)
web_call.rsRecognizes web searches and web fetches in a run
ask.rsThe built-in gonggong MCP server (local loopback, per-session URL): asking group members, forwarding server tools, answering daemon tools
mcp_call.rsParses MCP tool calls in ACP updates (each Agent uses a different format)
protocol/Wire types corresponding to packages/protocol
agents.rsDetects installed Agent CLIs and their versions
tools.rsManaged installs of Node.js and Agent CLIs (no sudo, no global npm changes)
manage.rsAnswers Agent tool, provider, and CC Switch requests from the server
providers.rs, provider_cli.rsLocal model provider storage (providers.json, always masked when sent out) and the gg provider subcommand
inject.rsInjects the run's provider into the adapter process (keys never go into command-line arguments or logs)
agent_settings.rs, claude_args.rsAgent settings, Claude Code command-line arguments
ccswitch.rsRead-only import of providers from the local CC Switch
skills.rs, plugins.rsPlaces the Skill and plugin versions a run uses on the local machine and hands them to the Agent
local.rsLocal settings (local.json): Agent CLI paths, command approval rules, model catalog
configure.rsThe gg agents and gg config subcommands
config.rsLocal state root (~/.gonggong, overridable with GONGGONG_HOME), binding info, and certificate trust
bind.rsBinding login, web-confirmed connection, the local machine info reported to the server, and the machine identifier
autostart.rsgg service: keeps the daemon running and starts it at login with launchd (macOS) or a systemd user unit (Linux)
bots.rsgg bots: lists Bots bound to this machine
workspace.rs, layout.rsThe workspace of each (group, Bot): managed clones, /cd binding, directory picking; managed workspaces live at ~/gonggong/workspaces/<group>/<Bot>/<repo>
janitor.rsBackground cleanup of state left by groups and Bots that no longer exist, long-unused plugin versions, and old runtimes
git.rs, git_ops.rs, git_write.rs, git_console.rsWorkspace Git status, read-only views, write operations started from the web, and their command log (using the local git)
git_access.rsMachine Git access managed from the web: SSH keys, HTTPS tokens, access tests
repo.rsRemote repository identity and access probing (ssh ⇄ https fallback)
sync.rs, sync/, replicas.rsForced sync: manifests, file chunk transfer, three-way merge, and catching up and committing before and after runs
artifacts.rsSyncing and committing managed artifacts on the local machine
files.rs, explorer.rs@ file suggestions, read-only workspace file browsing, and path validation
attachments.rsSaves attachments into the workspace's .gonggong/attachments/
terminal.rsPTY sessions for the web terminal
tunnel.rsPreview tunnel binary frames and forwarding
previews.rs, hosted.rs, static_site.rsLocal previews and hosted services (processes owned by the daemon that outlive a single turn), static sites
html_render.rs, snapshot.rsRenders HTML pages and preview first-screen screenshots with a local Chrome-family browser
cast.rs, wechatide.rsLive views (starting gg-cast streaming on demand), WeChat DevTools
open_apps.rsOpens the workspace with local apps
tls.rsHTTP(S)/WS(S) connections to the server: verifies certificates with system CAs, --ca-file, or --fingerprint; http:// is allowed only for local addresses
net.rsMeasures latency and bandwidth to the server
upgrade.rsSelf-upgrade: downloads the new version, verifies its sha256, replaces itself, and restarts when idle
revoke.rsCleans up managed workspaces and tokens after the machine is revoked
diag.rsgg doctor self-check and the redacted diagnostics bundle
logs.rsdaemon logs (daily rotation + in-memory ring buffer)
status.rsLive status for the UI: connection, heartbeat, latency, runs in progress
lock.rsAllows only one daemon per local directory (file lock)
proc.rsChild process spawning (no console window on Windows)
i18n.rs, i18n/en.rsi18n: the t! macro and the English dictionary

Released under the Apache License 2.0