Skip to content

Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.

docs: describe the Windows app and host

leepokai545c14d69e24
diff --git a/AGENTS.md b/AGENTS.md
index 7dd77865..3ae68449 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,7 +4,7 @@
- `host/`: Rust daemon, ACP integration, SQLite storage, HTTP/SSE API, and terminal UI; unit tests live alongside modules in `src/`.
- `apps/ios/`: iPhone app (SwiftUI); widgets live in `apps/ios/Widgets/`. `apps/ios/Kit/` is its Swift package: `CodyncKit` (models, clients, design primitives) and `CodyncUI` (screens and stores); tests in `apps/ios/Kit/Tests/CodyncKitTests/`.
-- `apps/desktop/`: desktop app for macOS and Linux (Electron, React, TypeScript): [docs/architecture/desktop-app.md](docs/architecture/desktop-app.md).
+- `apps/desktop/`: desktop app for macOS, Linux and Windows (Electron, React, TypeScript): [docs/architecture/desktop-app.md](docs/architecture/desktop-app.md).
- `apps/screen-macos` and `apps/screen-linux`: Remote screen helpers.
- `cloud/`: Cloudflare accounts, encrypted relay, Durable Objects and D1; tests live in `cloud/test/`.
- `relay/`: Cloudflare push worker and `test/`; `web/`: website (Next.js); `packaging/`: distribution templates; `docs/`: architecture and naming guidance.
@@ -30,7 +30,7 @@ Keep only the latest build: in this checkout, Apple builds go to `build/dd` only
## Versioning & releases
-- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → desktop app for macOS and Linux, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
+- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → desktop app for macOS, Linux and Windows, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
- Phone ↔ host compatibility: each side names the oldest version of the other it works with (`minApp` in the host's `hello`, `minHost` in each client). Additive changes need nothing; a rename/removal raises `minApp` in the same release, and hosts hold that release until the App Store has the iPhone app: [docs/reference/compatibility.md](docs/reference/compatibility.md)
- Pick the bump yourself: patch for fixes and small tweaks, minor for new features or protocol additions. Never bump major (stay on 2.x). One bump per merge into `main`: if `MARKETING_VERSION` is already ahead of the latest `v*` tag, leave it.
- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) and `apps/desktop/package.json` (+ `package-lock.json`) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
@@ -49,11 +49,11 @@ Name Swift files after their main `UpperCamelCase` type; use `snake_case.rs` and
## Cross-platform UI changes
-- Any UI change in any client must include the corresponding updates to the other clients in the same change: iOS (`apps/ios/`, `apps/ios/Kit/Sources/CodyncUI/`), desktop (`apps/desktop/src/renderer/`, macOS and Linux), and terminal UI (`host/src/tui/`). This applies in every direction.
+- Any UI change in any client must include the corresponding updates to the other clients in the same change: iOS (`apps/ios/`, `apps/ios/Kit/Sources/CodyncUI/`), desktop (`apps/desktop/src/renderer/`, macOS, Linux and Windows), and terminal UI (`host/src/tui/`). This applies in every direction.
- Keep shared features, actions, terminology, displayed information, and loading, empty, error, and permission states consistent. Adapt layout, controls, and input to each platform, including terminal keyboard interaction, while preserving the same user-facing behavior.
- Inspect every client's corresponding implementation before finishing a UI task. Implement applicable changes together; do not silently defer another client. For a platform-only change or an unsupported capability, document which clients are unaffected and the concrete reason in the change summary.
- Validate each affected client with its relevant build/tests and UI checks. Report any checks that could not run and why.
-- The desktop app is one codebase for macOS and Linux: platform differences go through `window.codync.platform` checks or the main process, never a fork of a view.
+- The desktop app is one codebase for macOS, Linux and Windows: platform differences go through `window.codync.platform` checks or the main process, never a fork of a view.
## Testing Guidelines
diff --git a/CLAUDE.md b/CLAUDE.md
index 397a791f..c1b6d8b2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,11 +19,11 @@ Bot-based remote for coding agents: persistent named bots on your computer, mess
## Architecture
-- Clients: iOS app (SwiftUI), desktop app for macOS and Linux (`apps/desktop/`, Electron: menu bar/tray + chat window; why and how: [docs/architecture/desktop-app.md](docs/architecture/desktop-app.md)), terminal UI (`codync-host tui`, `host/src/tui/`, ratatui; layout and state vocabulary modeled on herdr). All talk to the host API.
+- Clients: iOS app (SwiftUI), desktop app for macOS, Linux and Windows (`apps/desktop/`, Electron: menu bar/tray + chat window; why and how: [docs/architecture/desktop-app.md](docs/architecture/desktop-app.md)), terminal UI (`codync-host tui`, `host/src/tui/`, ratatui; layout and state vocabulary modeled on herdr). All talk to the host API.
- iPhone Swift package (`apps/ios/Kit/`, iOS only): `CodyncKit` (models, client, theme, avatars; also used by the widgets and the notification extension) + `CodyncUI` (`BotStore` + screens).
- UI principle: buttons an icon can express are icon-only (with tooltip / accessibility label); text only where an icon would be ambiguous (approval choices).
- UI controls default to the shared custom components. Explicit exception: iOS BotListView and ThreadView use native navigation/toolbar items and automatic back navigation for system Liquid Glass, as specified in `docs/design/ui-conventions.md`. **iOS menus are always the system ones**: tap menus through `DropdownMenu`/`ChoicePicker` (native `Menu`), long-press through `.contextActions` (native `contextMenu`). Never hand-build a dropdown on iOS: a custom overlay lands in the wrong place (sheets, scroll views, the composer's + menu). The desktop app's menu bar/tray menu is the system menu. Keep system authentication and widget containers native. On iOS `.codyncSheet` presents the system sheet (grabber, swipe down). Outside these exceptions, avoid: no `Menu`/`Picker`, `.switch` toggles, `Form`/`List` styling, `confirmationDialog`/`alert`, `ProgressView`, `.sheet`/`.popover`/`.fullScreenCover`, `.toolbar`/navigation bars, `TabView`, `ContentUnavailableView`. Use `apps/ios/Kit/Sources/CodyncUI/Controls.swift` + `Chrome.swift` (`.codyncSheet`, `ModalHeader`, `ScreenHeader`, `TabBar`, `.codyncDialog`, `ToggleStyle.codync`); on the desktop, `apps/desktop/src/renderer/components/` (`Sheet`, `Dialog`, `AnchoredMenu`, `ModalHeader`, `Controls.tsx`, `Icon` for SF Symbols). Every tap that shows/hides something animates (`Motion`). Anything with a background fill gets no border line.
-- `host/` — **codync-host** (Rust, macOS + Linux). Detects installed harnesses (`agent/backends.rs`: login-shell PATH + known dirs) and the ACP registry (`agent/registry.rs`, cached in `~/.codync/registry.json`, binaries under `~/.codync/agents`). Drives agents over **ACP** (JSON-RPC on stdio, hand-rolled in `agent/acp.rs`, updates kept as `serde_json::Value` so new adapter variants never break parsing). One actor per bot (`agent/bot/`) owns the agent process + session and maps `session/update` onto transcript entries.
+- `host/` — **codync-host** (Rust, macOS + Linux + Windows; platform differences in `service/` and `shell.rs`). Detects installed harnesses (`agent/backends.rs`: login-shell PATH + known dirs) and the ACP registry (`agent/registry.rs`, cached in `~/.codync/registry.json`, binaries under `~/.codync/agents`). Drives agents over **ACP** (JSON-RPC on stdio, hand-rolled in `agent/acp.rs`, updates kept as `serde_json::Value` so new adapter variants never break parsing). One actor per bot (`agent/bot/`) owns the agent process + session and maps `session/update` onto transcript entries.
- **Chat ≠ session**: a bot is one endless transcript (SQLite `entries`, ordered by `seq`); the ACP session underneath is resumed with `session/load` or replaced by *New session*.
- **Group chats and threads** are host features every client drives through the same methods (`send` with `threadId`, `thread`, `createBot {kind: group}`); clients never route, parse mentions or count replies themselves. A group is a roster row whose members answer in their own sessions (Grok Bot's room turns); a thread on a bot's message is a forked session: [docs/features/groups-and-threads.md](docs/features/groups-and-threads.md).
- Bot collaboration: built-in `team` MCP (`chat/team.rs`) lists visible bots and asks one for a reply through its actor queue. Requests are separate turns, cycle-checked and cancellable; native subagents stay with the harness. See [docs/features/bot-collaboration.md](docs/features/bot-collaboration.md).
@@ -42,11 +42,11 @@ Bot-based remote for coding agents: persistent named bots on your computer, mess
## Cross-platform UI changes
-- Any UI change in any client must include the corresponding updates to the other clients in the same change: iOS (`apps/ios/`, `apps/ios/Kit/Sources/CodyncUI/`), desktop (`apps/desktop/src/renderer/`, macOS and Linux), and terminal UI (`host/src/tui/`). This applies in every direction.
+- Any UI change in any client must include the corresponding updates to the other clients in the same change: iOS (`apps/ios/`, `apps/ios/Kit/Sources/CodyncUI/`), desktop (`apps/desktop/src/renderer/`, macOS, Linux and Windows), and terminal UI (`host/src/tui/`). This applies in every direction.
- Keep shared features, actions, terminology, displayed information, and loading, empty, error, and permission states consistent. Adapt layout, controls, and input to each platform, including terminal keyboard interaction, while preserving the same user-facing behavior.
- Inspect every client's corresponding implementation before finishing a UI task. Implement applicable changes together; do not silently defer another client. For a platform-only change or an unsupported capability, document which clients are unaffected and the concrete reason in the change summary.
- Validate each affected client with its relevant build/tests and UI checks. Report any checks that could not run and why.
-- The desktop app is one codebase for macOS and Linux: platform differences go through `window.codync.platform` checks or the main process, never a fork of a view.
+- The desktop app is one codebase for macOS, Linux and Windows: platform differences go through `window.codync.platform` checks or the main process, never a fork of a view.
## Codync 1.x does not exist for us
@@ -71,7 +71,7 @@ Keep only the latest build: in this checkout, Apple builds go to `build/dd` only
## Versioning
- Phone ↔ host compatibility: each side names the oldest version of the other it works with (`minApp` in the host's `hello`, `minHost` in each client). Additive changes need nothing; a rename/removal raises `minApp` in the same release, and hosts hold that release until the App Store has the iPhone app: [docs/reference/compatibility.md](docs/reference/compatibility.md)
-- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → desktop app for macOS and Linux, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
+- **Every source change ships as a release.** A version bump on `main` is the only release trigger (Auto Tag → desktop app for macOS, Linux and Windows, host, Homebrew, in-app update), so any change to shipped code (`apps/`, `host/`, `packaging/`) bumps the version before it reaches `main`, without being asked. Docs, `web/`, `cloud/`, `relay/` and CI-only changes don't bump.
- Pick the bump yourself: patch for fixes and small tweaks, minor for new features or protocol additions. Never bump major (stay on 2.x). One bump per merge into `main`: if `MARKETING_VERSION` is already ahead of the latest `v*` tag, leave it.
- How: set `MARKETING_VERSION` in `apps/project.yml` and `version` in `host/Cargo.toml` (+ its `Cargo.lock` entry) and `apps/desktop/package.json` (+ `package-lock.json`) to the same value, run `xcodegen generate --spec apps/project.yml`, commit as `build: bump version to X.Y.Z`. Never touch `CURRENT_PROJECT_VERSION` (Xcode Cloud sets the iOS build number). When the iOS app changes, also write that version's section in `apps/ios/WhatsNew.md` (zh-Hant + en-US, what iPhone users notice); it becomes the App Store "What's New".
diff --git a/docs/README.md b/docs/README.md
index 92dd1e99..1f136613 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,7 +9,7 @@ Source review, a passing build, local integration tests and production acceptanc
|---|---|
| Find a module or decide where a file belongs | [File structure](architecture/file-structure.md) |
| Understand clients, host, cloud and data ownership | [Architecture](architecture/overview.md) |
-| Work on the macOS and Linux desktop app (Electron) | [Desktop app](architecture/desktop-app.md) |
+| Work on the macOS, Linux and Windows desktop app (Electron) | [Desktop app](architecture/desktop-app.md) |
| Build, install, restart and run checks | [Development](guides/development.md) |
| Test a phone over Cloudflare instead of LAN | [Cloudflare testing](guides/cloudflare-testing.md) |
| Configure dev/main or deploy the services | [Environments and deployment](guides/environments-and-deployment.md) |
diff --git a/docs/architecture/desktop-app.md b/docs/architecture/desktop-app.md
index 58389b2c..fb7fe072 100644
--- a/docs/architecture/desktop-app.md
+++ b/docs/architecture/desktop-app.md
@@ -1,6 +1,6 @@
-# Desktop app (macOS and Linux)
+# Desktop app (macOS, Linux and Windows)
-Codync's computer-side app is one Electron app in `apps/desktop/` for macOS and Linux. It
+Codync's computer-side app is one Electron app in `apps/desktop/` for macOS, Linux and Windows. It
replaced the SwiftUI Mac app (`apps/macos/`) and the GTK 4 Linux app (`apps/linux/`) in 2.7.0.
The iPhone app stays native SwiftUI; its package moved from `kit/` into `apps/ios/Kit/`.
@@ -43,6 +43,17 @@ same way; the shared desktop behavior covers macOS and Linux.
- **On-device speech** is macOS only; Linux calls use OpenAI or Gemini on the user's key.
- **Host**: the Mac app bundles `codync-host` in `Contents/Resources`; Linux uses the installed
host (an AppImage's mount path changes on every launch, so a service can't point into it).
+- **Windows** (x64, per-user NSIS install, unsigned for now so SmartScreen warns once) bundles
+ `codync-host.exe` and `codync-hostw.exe` in `resources/`. `codync-host install` writes the
+ per-user Run key (`HKCU\…\Run\CodyncHost`), which starts `codync-hostw.exe` at sign-in: a
+ windowless launcher that runs the host with a hidden console (the agents share it, so none
+ opens a window) and restarts it when it exits. App updates stop the host first, as on macOS.
+ Agents start through `cmd /c` (`host/src/shell.rs`), setup terminals use ConPTY
+ (`portable-pty`), and the vault key lives in Credential Manager. Not on Windows yet: Remote
+ screen and the `computer` MCP (no screen helper), on-device speech, the Claude Code status
+ line hook (usage still comes from `claude -p /usage` and ACP), SSH tunnels to other
+ computers, and `curl | bash` installers (npm installs and Claude Code's PowerShell installer
+ work). The tray icon is the app icon; left-click opens the chat, right-click the menu.
- **Remote screen** on macOS registers `CodyncScreen.app` (built from the Xcode `Screen` target)
as an SMAppService agent; Linux starts its helper from the host, as before.
- **Other computers in the account** are reached through this computer's own host and SSH
@@ -73,6 +84,7 @@ Each packaging script names its environment:
npm run dist:mac:dev # dev cloud, Clerk development
npm run dist:mac:main # main: what the release workflow ships
npm run dist:linux:dev # / dist:linux:main
+npm run dist:win:dev # / dist:win:main, on Windows (builds the bundled host with rustup)
```
They write `resources/account-config.json` for that environment, and the Mac ones build the
diff --git a/docs/architecture/file-structure.md b/docs/architecture/file-structure.md
index 35040c14..89bee31c 100644
--- a/docs/architecture/file-structure.md
+++ b/docs/architecture/file-structure.md
@@ -43,7 +43,7 @@ Codync/
│ │ │ ├── Usage/
│ │ │ └── Resources/
│ │ └── Tests/ # CodyncKitTests and CodyncUITests
-│ ├── desktop/ # Electron app for macOS and Linux (see desktop-app.md)
+│ ├── desktop/ # Electron app for macOS, Linux and Windows (see desktop-app.md)
│ │ ├── src/main/ # Host service, tray, account, updates, SSH, screen, speech
│ │ ├── src/preload/ # window.codync bridge
│ │ ├── src/renderer/ # React UI: store/, components/, views/
@@ -67,7 +67,7 @@ Codync/
## Targets
-- `apps/desktop/` — desktop app for macOS and Linux (Electron; `npm run dev`, packaged by `.github/workflows/release-desktop.yml`)
+- `apps/desktop/` — desktop app for macOS, Linux and Windows (Electron; `npm run dev`, packaged by `.github/workflows/release-desktop.yml`)
- `iOS` (`apps/ios/`) — iOS app
- `Screen` (`apps/screen-macos/`) — Codync Screen: capture, input and WebRTC for Remote screen, embedded in the macOS desktop app (`Contents/Library/LoginItems`)
- `apps/screen-linux/` — `codync-screen` (Rust, GStreamer + xdg portals), the Linux Remote screen helper
diff --git a/docs/guides/development.md b/docs/guides/development.md
index 58f835a2..a15808a9 100644
--- a/docs/guides/development.md
+++ b/docs/guides/development.md
@@ -6,7 +6,7 @@ Run commands from the repository root unless a block changes directory. See [fil
## Desktop app
-The macOS and Linux app is the Electron app in `apps/desktop/`; setup, UI-check switches and packaging are in [desktop app](../architecture/desktop-app.md#development):
+The macOS, Linux and Windows app is the Electron app in `apps/desktop/`; setup, UI-check switches and packaging are in [desktop app](../architecture/desktop-app.md#development):
```sh
cd apps/desktop
diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md
index 468e003d..9e615426 100644
--- a/docs/reference/compatibility.md
+++ b/docs/reference/compatibility.md
@@ -1,6 +1,6 @@
# Client and host compatibility
-Clients (iPhone, desktop app on macOS and Linux, terminal client) and the host update on
+Clients (iPhone, desktop app on macOS, Linux and Windows, terminal client) and the host update on
different schedules: the iPhone app waits for App Review, the desktop app and standalone hosts
update when their owner (or the opt-in automatic updater) installs a release. Any client can
meet an older or a newer host.