GatherThread

English | 简体中文

One room, many minds.

GatherThread is an open-source, self-hostable workspace for real-time online collaboration among people using their own local AI coding agents. Codex Desktop and DeepSeek Harness connect to the same ordered project history and shared context: conversations are attributable, replayable, and delivered live across role-based Solo and Multi sessions. Each person keeps their local Agent and credentials; Git-backed code checkpoints are a separate, opt-in feature. The collaboration layer remains harness-neutral rather than requiring everyone to use one Agent or model.

Alpha 8 adds a bilingual first-use guide and isolated practice project, quotes and member mentions, clearer conversation navigation, runtime-advertised model choices, optional Windows/macOS Codex Launcher prototypes, batch test-access issuance, and self-service account deletion. See the Alpha 8 notes for limits and verification gates.

Invitation-only Alpha. gatherthread.cn is running a small hosted Alpha. Public registration and the public Beta are not open. Each tester needs a one-use test qualification to activate an account; a project invitation alone grants access only to that project. The local, LAN, and Tailscale self-hosting options remain available.

Git tag, npm package, and GitHub Release details are recorded in the release index.

Request Alpha test access

Open an Alpha access Issue to request a test qualification. The source repository is public, but hosted account activation still requires maintainer approval and a one-use qualification; the Issue is the only application channel, with no separate application form or server-side applicant profile. The public template lets applicants optionally describe why they want to join, what they want to test, and how they heard about GatherThread. Email is optional and recommended only if you are comfortable sharing it publicly for private code delivery. If you prefer not to publish your email, after approval you may privately email the Issue link to [email protected]. Issues are public; never post qualification codes, device access tokens, passwords, keys, or private source code.

A maintainer replies on the public Issue with the review result and next steps. Qualification codes are one-use secrets and must never be published in an Issue. On receiving a code, open the hosted login page, enter your display and device names, and activate it under First-time activation. Save the separately issued device token privately for later sign-ins. Existing qualified users can invite guests into individual projects without granting them account-wide project creation.

For questions, bug reports, and non-sensitive feedback, open a GitHub Issue. Send security reports privately to [email protected], without including credentials or raw private transcripts.

• solo: its creator publishes a complete canonical session stream; every other project member, including the project owner when someone else created it, follows it read-only.
• multi: people share one ordered project conversation. A human chat message is shared without invoking an agent. An agent request is claimed only by the sender's local runtime, and the response is labelled with username, harness, provider, model, and capture fidelity; local device and native-session identifiers are not exposed to non-owner collaborators reading another user's activity.

The server persists an append-only canonical event log in SQLite WAL, assigns authoritative per-session sequence numbers, enforces role-based access, and provides durable replay plus WebSocket live delivery. Codex and DeepSeek Harness keep separate native projections of that same history, recover from durable cursors and outboxes, and route each Agent request only to the runtime the user selected.

The bilingual Web workspace is responsive and resizable. Project-scoped settings control the default Agent model, reasoning effort, and context-injection ceiling; accessible custom controls, default high contrast, and theme-aware ambient lighting keep the interface legible without competing with the conversation.

Web Agent turns mirror Codex Desktop's reading hierarchy: public work updates arrive live, then collapse into an optional work log when the final response appears. Final responses and work updates render safe GitHub-flavored Markdown with bundled KaTeX for inline and display math, while hidden reasoning is never uploaded or displayed.

Project and role model

A project is the collaboration and invitation boundary. The project owner can rename the project, creates multi sessions, can switch their own sessions between solo and multi, and may change any other member between participant and viewer later. Owners and participants may each create personal solo sessions; only that Solo's creator may write or rename it, while every other project member reads it. A participant can also write and run their own agent in every multi session. A viewer is read-only across the entire project, and local tasks created by a viewer never create cloud sessions. A session creator or the project owner may permanently delete that session's cloud copy; only the project owner may delete the whole cloud project. Cloud deletion stops synchronization and removes shared server history, but never deletes local workspaces, files, Codex tasks, or Agent conversations.

What “complete context” means

The project records three explicit fidelity levels:

1. canonical_history: the complete shared event history visible to that member.
2. harness_transcript: content observed in an authorized local harness transcript.
3. provider_request: the exact request observed by an explicit harness hook or authorized provider proxy.

An MCP server cannot independently read an entire host conversation. Therefore reconstructed history is never labelled provider_request, and exact provider request uploads are disabled unless the local bridge is explicitly authorized and confirms an exact observation. Compaction remains local; the shared canonical log stays durable.

Repository layout

Requirements and verification

Node.js 24 or newer is required because the server uses node:sqlite.

npm install
npm run verify

verify runs strict TypeScript checks, server/protocol/adapter/bridge/MCP tests, Web tests and build, a real server-to-bridge agent turn, collaboration contract tests, reference/license checks, a secret scan, and an npm vulnerability audit. The secret scan covers every Git-visible file while excluding the ignored local .env; a force-tracked .env is still scanned and rejected.

Local end-to-end run

On first initialization, a missing .env or blank pepper is filled automatically with a stable random value in a private 0600 file. Create the first owner directly on the host, then start the same-origin Web/API/WebSocket service:

npm run connection:local
npm run owner-host:init -- --display-name "Alice" --device-name "Alice laptop"
npm run owner-host

To customize ports or paths, copy .env.example before initialization. owner-host:init fills only a blank pepper and preserves every other setting. owner-host builds the current source automatically on every start.

Open http://127.0.0.1:18787 to see the product home, then choose Get Started to enter the same-origin application at /app/. Enter the one-time displayed device credential there. The application exchanges it for an opaque HttpOnly; SameSite=Strict browser session cookie and immediately clears the credential from JavaScript memory. Reloading restores the signed-in workspace without storing a device token in localStorage or sessionStorage. The default session has a 24-hour absolute server-side lifetime and a non-persistent Cookie. Choosing Remember this device creates a 30-day persistent session and a separate HttpOnly remembered-account credential. That account appears in the same browser profile's sign-in chooser with its last display and device names, both editable before sign-in. Signing out revokes the active session but leaves that account available for one-click sign-in until its 30-day expiry, Forget this account, or device revocation/rotation. Do not choose Remember on a shared browser profile. HTTPS deployments add Secure and the __Host- cookie prefix. WebSockets still use a separate 30-second, one-use, session-scoped ticket, and no credential is placed in a URL. The higher default reduces collisions with commonly occupied low ports on Windows. Existing installations that explicitly set GATHERTHREAD_SERVER_PORT=8787 continue to use that value; 18787 is only the new default.

For UI-only development, npm --workspace apps/web run dev starts the loopback preview and proxies the local API. The product home is at http://127.0.0.1:4173/; explicit workspace mock mode is available only at http://127.0.0.1:4173/app/?mock=1 with demo-token.

Hosted Alpha and other connection modes

For the current hosted Alpha, use https://gatherthread.cn and enter the same-origin workspace at /app/. The owner-operated ECS service terminates HTTPS at Caddy while the application remains on loopback; it does not open anonymous account registration or public Git transport. Connect your own Codex or DeepSeek Harness from your device after joining a project. No server SSH account is needed for ordinary product testing.

For an independent self-hosted deployment, three modes work without an Alibaba Cloud account and preserve that deployment's own private .env, database, credential pepper, users, and history:

LAN mode keeps the application on loopback and runs a dedicated Caddy HTTPS proxy bound only to the selected private interface. Client devices must explicitly trust the dedicated local CA; never bypass a certificate warning or expose the port through the router. A campus network is usually institution-managed LAN infrastructure, but peer access is not guaranteed: use LAN mode only when school policy permits it and the devices can reach each other. If client isolation or VLAN separation blocks direct access, use the hosted Alpha if qualified, or a private Tailscale deployment. See the bilingual connection-mode guide and the detailed owner-hosting guide.

Connect a local Codex agent

The Web dialog uses one short, three-step flow:

1. Install the fixed 共序 / GatherThread Codex plugin once.
2. Copy the generated macOS/Linux or PowerShell connector command. The command includes --plugin-hooks, but no credential.
3. Restart Codex Desktop, review and enable the plugin Hooks, then keep the connector terminal open.

One-time plugin install:

If codex --version is unavailable or Terminal reports codex: command not found, first install or update the official Codex CLI with npm install -g @openai/codex. Reopen Terminal and confirm codex plugin --help works before continuing.

codex plugin marketplace add https://github.com/TH060419/gatherthread.git --ref v0.1.0-alpha.8 --sparse .agents/plugins --sparse plugins/gatherthread
codex plugin add gatherthread@gatherthread

The connector asks for the device token in a hidden terminal prompt, creates or reuses the local project, opens Codex Desktop, and discovers later sessions automatically. Editable GatherThread sessions become Codex tasks; Web Agent requests run in an isolated background projection, while trusted Hooks return direct Desktop turns to the same canonical history. The workspace provides a per-conversation Auto-upload local turns to cloud switch and Upload local turns to cloud now recovery action; the Codex plugin exposes the same controls. Manual upload scans completed turns when a Hook was missed or failed without turning automation back on. By default, each session imports one verified, readable native-history snapshot the first time it is established locally; Settings can disable that initial import. Import Codex history always creates a new verified local task, retains public text within a separate snapshot resource limit and uses Codex's native compaction when needed, and switches future Hook and context delivery to it. GatherThread neither overwrites nor archives the previous local task; review and archive it yourself. Continuing that previous task stays local and cannot create a replacement binding or cloud session. Realtime context injection remains active regardless of the visible-history setting or manual imports. A genuinely new local task creates a personal Solo only after its first completed turn; viewer tasks remain local.

The fixed Alpha commands are documented in the Codex connection guide. Verify the matching v0.1.0-alpha.8 Git ref and npm package before installing; the source-checkout path is also documented there.

Connect DeepSeek Harness

DeepSeek Harness uses the same four-step shape:

1. Install @gatherthread/dsh-host into the verified DSH Web profile.
2. Start @deepseek-ai/[email protected] web and keep it running.
3. Open Settings → GatherThread / 共序, enter the current server, and approve the one-use pairing code in the already signed-in browser.
4. In the same panel, choose a DSH provider and model and connect the projects this identity can access. Pairing alone registers no runtime, so the GatherThread workspace cannot discover this DSH before this step.

One explicit pairing connects every active Project visible to that identity and discovers new access later. Writable GatherThread sessions appear as editable native DSH conversations; completed DSH turns upload once, and canonical server history projects back in order. DSH Settings exposes a per-conversation automatic-upload switch and manual upload action. A successful first turn in a new DSH conversation creates a creator-owned cloud Solo; empty, failed, and viewer conversations remain local. When the connected DSH route exposes DeepSeek model metadata, the GatherThread workspace can choose any advertised model and reasoning effort for each Agent request. The temporary choice applies only to that GatherThread-driven turn, so model selection inside DSH remains independent. Older or non-advertising routes keep their fixed model. Only the explicitly selected runtime handles an Agent request, with no Codex fallback.

Enter the current server URL in DSH Settings. Approved testers can use https://gatherthread.cn; local, LAN, and Tailscale origins also work. See the DSH connection guide for package and source-checkout paths.

Security and current limits

Optional code collaboration and shared summaries

Unreleased source preview: direct GitHub synchronization. GitHub is the recommended storage option for longer-term collaboration and larger source trees within the preview limits; the existing GatherThread cloud checkpoints remain suitable for small projects and trials. Each authorized device connects directly to GitHub using its own local GitHub CLI login, uploads only to its stable personal branch, and keeps GitHub source and credentials off the GatherThread server. GitHub permissions, Actions and remote deletion remain separately managed. This does not claim availability in published packages or the hosted service. See the bilingual GitHub setup and limits and ADR-0035.

Alpha 7 introduced opt-in Git-backed project code checkpoints: a separate branch per member, manual/idle automatic upload, clean download, new-directory recovery, change review and owner-only merge. Codex requires explicit --code-sync authorization; DSH exposes project code consent and controls in its plugin settings. Existing conversation uploads and context injection remain independent. Cloud Git is used only to synchronize code with members of the same project, never for GatherThread product development or unrelated purposes. This does not alter your original Git branch/index or provide a public git push endpoint. All project readers can read code branches, including branches associated with Solo work. Project members can disable cloud code synchronization, at the cost of cloud code-collaboration features. See the bilingual setup, limitations and acceptance checklist.

The Alpha 7 source added a 128 MiB per-user active cloud-code quota and Settings cleanup. Members may clear their own cloud branch; project owners may clear their own branch or the entire project's cloud Git data. A branch cleanup does not undo changes already merged into shared main. These operations do not touch anyone's local Git or Agent files. They revoke cloud access and release logical quota, but physical Git objects and backup copies remain until separate operator retention cleanup. See the current code-sync guide before using deletion.

Native context accounting no longer applies application-side clipping to accepted incoming history. Codex prioritizes its reported model capacity; DSH keeps native model/compaction settings. Native summaries are not lossless or unlimited, and exceptional recovery limits still apply; see Codex context management and DSH guidance.

Alpha 7 also lets a session writer select completed public messages and ask their own connected local Agent for a shared manual summary. The new version is attributed and visible to project members; no original event is deleted. Summaries can be selected again as source text for a later summary, and the Web UI can switch between the compact view, original messages, and earlier versions. A per-user project setting chooses summarized context by default or original text for future Web-triggered Agent requests and explicit derived-context reads; it does not retroactively rewrite a native Codex/DSH conversation. Writers can customize/reset the summary instructions. Viewers can read and switch views but cannot generate summaries. This is separate from each harness's native compaction and from local-turn upload consent. See ADR-0027.

The first release includes peppered device credentials, HMAC-protected and revocable browser sessions, strict Cookie-write Origin checks, single-use invitations and device authorization, device-bound runtime provenance, immediate session/socket/authorization invalidation on device or membership revocation, solo/multi ACL, event redaction, session-scoped idempotency validation, single-runtime request serialization, one-use realtime tickets, strict production WebSocket Origin checks, bounded JSON complexity and byte-paged replay, per-device rate limits, per-user/project/deployment session-count limits, event and snapshot-job storage quotas, reconnect replay, and SQLite backup/restore scripts. A newly invited user sees the new device credential once and must save it before dismissing the dialog.

The hosted gatherthread.cn Alpha is open only to approved testers; public registration and public Beta remain closed. Local-only, private LAN HTTPS, and private Tailscale Serve are also available. The Alibaba Cloud ECS profile documents the live deployment pattern. Every mode keeps the application on loopback; only the documented Caddy edge may accept public traffic.

Not yet implemented: automatic host failover, multi-process WebSocket fan-out, token-by-token agent streaming, attachment blob storage, general conversation-retention workers, offline Web outbox, conversation search and production-signed native installers. Alpha 8 adds account deletion and ECS backup, cloud-Git, and journal retention jobs; those guarantees apply to a host only after the updated units and every off-host copy policy are deployed and verified. See the privacy notice and operations guide. Current progress delivery is item-level public commentary rather than token streaming.

See the documentation index, 0.1.0-alpha.8 notes, product specification, architecture, connection modes, Codex guide, DSH guide, owner hosting, security model, and operations.

Contributing and release governance

Human contributors and development Agents should start with AGENTS.md and CONTRIBUTING.md. Public and internal integration boundaries are mapped in docs/INTERFACE_CONTRACTS.md.

Every version update is reviewed through a pull request by the project lead / designated release maintainer, currently @TH060419, before it is merged or released. Contributors and Agents must not publish npm packages, create or move release tags, create GitHub Releases, deploy servers, or delete another contributor's branch without explicit project-lead authorization. CODEOWNERS requests this review; repository administrators must also enable the documented main branch-protection settings to enforce it on GitHub.

License

Licensed under the Apache License 2.0. Copyright 2026 Yuhan He and contributors.