AGENTS.md

Project facts shared across all coding agents (Claude Code, Cursor, Codex, Gemini, Aider, …). Claude Code also reads CLAUDE.md for tool-specific preferences and the subagent registry.

What this is

Claw Installer — a cross-platform desktop installer (by Cylingo Group) that sets up the OpenClaw agent gateway and the Hermes browser-automation agent on a user's machine. A Tauri desktop GUI drives a pure-Bash installer pipeline; the same Bash logic also runs standalone on macOS/Linux and, via WSL, on Windows.

Tech stack

• Desktop app (gui/): Tauri 2 — Rust backend (gui/src-tauri) + web frontend.
• Frontend (gui/src): React 19 + TypeScript, Vite 6, Tailwind CSS 4, Zustand 5 (state), react-i18next (en + zh), Radix UI primitives.
• Installer logic (shell/): pure Bash (3.2-compatible) + a PowerShell bootstrap for Windows/WSL.
• Package manager: pnpm workspace (pnpm-workspace.yaml). Spec workflow: OpenSpec (openspec/).

Repository layout

gui/                  Tauri desktop app
  src/                React/TS frontend
    components/installer/   main UI (SettingsPanel, Sidebar, AgentCard, …)
    store/installer-store.ts  Zustand store — the GUI's source of truth
    api/installer.ts    typed wrappers over Tauri commands
    lib/                model-config-apply, provider-models, utils
    i18n/resources/     en.ts / zh.ts UI strings
    __tests__/          vitest suites
  src-tauri/          Rust backend
    src/commands.rs     #[tauri::command] handlers (incl. op-dispatch)
    src/steps.rs        @@step sentinel parsing + step labels
    src/lib.rs          handler registration
    Cargo.toml          ← single source of truth for the app version
    tauri.conf.json     Tauri config (omits version → inherits Cargo.toml)
shell/                installer pipeline (Bash)
  install.sh / uninstall.sh
  claw-op.sh           macOS/Linux op-dispatch entrypoint
  steps/<name>.sh       install steps (base-deps, fnm, node, pnpm, agentlink, …)
  agents/<agent>/       per-agent ops (openclaw/, hermes/): install.sh, pair-agentlink.sh, …
  lib/                  common.sh (run_steps, helpers), manifest.sh
  windows/bootstrap.ps1 Windows/WSL bootstrap + Invoke-OpDispatch
  docker/ vendor/
openspec/             specs/ + changes/ (OpenSpec)
tools/                build tooling (build-linux Docker image)
docs/                 research/ ued/ and design notes
Makefile              the command front door (see below)

Commands (the Makefile is the front door)

GUI-local equivalents: pnpm --filter gui {dev,build,test,typecheck}. The GUI build script runs tsc --noEmit -p tsconfig.app.json && vite build (typecheck is part of the build gate).

Versioning (single source of truth)

The app version lives only in gui/src-tauri/Cargo.toml ([package].version). To release a new version, bump that one line. Everything else derives from it:

• tauri.conf.json intentionally has no version key → Tauri falls back to Cargo.toml (drives mac/linux bundle filenames, e.g. Claw Installer_1.1.0_universal.dmg).
• The GUI sidebar reads it at runtime via @tauri-apps/api/app getVersion() (shows dev in stub mode).
• The Windows zip name embeds it via the Makefile's APP_VERSION (parsed from Cargo.toml).
• package.json / gui/package.json versions are inert (npm manifests, not used for bundling) — do not treat them as the source.

Architecture notes

• GUI ↔ Rust: the frontend calls #[tauri::command] handlers in gui/src-tauri/src/commands.rs via gui/src/api/installer.ts. UI state is a single Zustand store (installer-store.ts).
• Rust → shell (op-dispatch protocol): dispatch_op shells out to shell/claw-op.sh (macOS/Linux) or bootstrap.ps1 Invoke-OpDispatch (Windows). The op name is also the script filename: op pair-agentlink → shell/agents/<agent>/pair-agentlink.sh. The dispatch tables in claw-op.sh (_op_valid_agents) and bootstrap.ps1 ($OpAgentTable) must mirror each other, and the op string in commands.rs must match both.
• Install steps: ENV_STEPS=(…) in agents/<agent>/install.sh → run_steps (lib/common.sh) loads steps/<name>.sh and calls step_<name>. Steps emit @@step:<key>:<label> sentinels that Rust parses in steps.rs to drive the progress UI.
• i18n: strings in gui/src/i18n/resources/{en,zh}.ts; the chosen language is persisted to config.
• Persisted config: ~/.claw-installer/config.json (%APPDATA%\claw-installer\config.json on Windows) holds per-agent model credentials, channel, pairing timestamp, and UI language. Hydration in installer-store.ts tolerates older snapshots; there is no migration for renamed keys/values (treat config shape changes as greenfield unless told otherwise).

Conventions

• Language: durable artifacts (code, comments, commit messages, specs, these docs) are written in English. Human-facing chat/answers may be Chinese (see CLAUDE.md).
• Branching: dev is the primary working branch; main is protected and updated via merge request. Do not commit directly to main. Feature work follows the vcs-workflow convention (branch → dev → MR).
• Commits: do not commit/push unless asked. Branch first if on a protected branch.
• Bash 3.2 compatible: macOS ships bash 3.2 — no declare -A, no [[ -v ]] in shell/.
• Windows bootstrap.ps1 must keep its UTF-8 BOM (PowerShell 5.1 needs it to decode the Chinese strings); make build-windows hard-fails if the BOM is missing.

Known traps

• Op/step renames are not compiler-checked. An op or step name is a string spanning Rust (commands.rs), Bash (claw-op.sh), PowerShell (bootstrap.ps1), and a filename. A missed spot only fails at runtime ("unknown op"). Change all sites together and smoke-test pairing.
• gui/vite.config.js and gui/vite.config.ts are both tracked — Vite loads .js first, so it wins. Editing only .ts may have no effect. (Latent; clean up when convenient.)
• A tsc-clean + cargo check-clean change can still break the live op flow — only a real install/pairing run exercises the Rust↔shell↔ps1 string contract.

Domain glossary

• OpenClaw — open-source local agent runtime/gateway (~/.openclaw/).
• Hermes — Playwright-driven browser-automation agent; also Cylingo's hosted-model bridge.
• AgentLink — Cylingo's IM-side gateway; users pair it with a 4-digit code (agentlink pair, npm @xyagent/cli). The pairing channel id is agentlink.
• AgentLinkHub — hosted model hub (free-tier promo). Internal provider id is xinyuan; hidden this release (its card is gated off; not yet launched).
• Channels — wechat / feishu / dingtalk / agentlink.
• Model providers — deepseek (default) / kimi / kimi-coding / minimax / custom / xinyuan.</content>