teamclaw
CLAUDE.md128 starsChanged 2 months agoMITView on GitHub
For UI / visual design work, source-of-truth depends on the platform: - iOS (apps/ios/): apps/ios/DESIGN.md — the Hai 灰 palette, wabi-sabi language, and SwiftUI implementation conventions (tokens, Hai sheets, iOS 26 toolbar rules). Read this before touching anything in apps/ios/. - Web / desktop (packages/app/): AGENTS.md at the repo root — the Editorial Calm direction (paper neutrals, coral accent, Chinese-first type). Never push directly to main. All changes go through a feature branch and a Pull Request: 1. Work on…
- Reads credentials
- Installs packages
- Commits and pushes
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- sentry-fixSkill
- sentry-monitorSkill
- image-genSkill
The file
Show its rules and text
We split this CLAUDE.md into the rules it gives an agent
15 rules. About 0 are common, 10 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 15
Never push directly to
main: All changes go through a feature branch and a Pull Request: - Very specific: line 19
Wait for the user to explicitly ask you to open the PR: Do not git push or run gh pr create on your own initiative, even if the work looks …
- Distinctive: line 24
Do not merge or push to main directly, even for small fixes.
- Very specific: line 26
If SDLC.md exists at the repo root of this checkout, read it before starting any change.
- Very specific: line 155
Add the route handler in services/fc/lib/business-api.mjs.
- Very specific: line 157
Add tests in services/fc/test/ (route, repository, contract).
- Distinctive: line 160
Do not bypass the Cloud API and call Supabase directly from client code.
- Very specific: line 168
Never: write to msg.content during streaming
- Distinctive: line 169
Never: use "longest content" strategy on completion
- Distinctive: line 175
When the streamed text and the daemon's final content are the *same text after whitespace normalization*, that helper keeps the longer one, …
- Distinctive: line 224
Commit, push to main
- Distinctive: line 242
Commit and push to main
- Distinctive: line 263
Do not collapse the two environments or share proxy certificate files between them.
- Distinctive: line 328
When you finish a turn and can anticipate the user's likely next steps, end your reply with one final plain-text line formatted exactly as:
- Distinctive: line 349
Only when you actually work in it.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
For UI / visual design work, source-of-truth depends on the platform:
- iOS (
apps/ios/):apps/ios/DESIGN.md— the Hai 灰 palette, wabi-sabi language, and SwiftUI implementation conventions (tokens, Hai sheets, iOS 26 toolbar rules). Read this before touching anything inapps/ios/. - Web / desktop (
packages/app/):AGENTS.mdat the repo root — the Editorial Calm direction (paper neutrals, coral accent, Chinese-first type).
Git Workflow
Never push directly to main. All changes go through a feature branch and a
Pull Request:
- Work on a task-scoped branch, never on
main. - Wait for the user to explicitly ask you to open the PR. Do not
git pushor rungh pr createon your own initiative, even if the work looks "done" and tests pass. An explicit "open the PR", "ship it", "提 PR", or "可以提 PR 了" is the trigger; absent that, stop after committing and report back. - Do not merge or push to
maindirectly, even for small fixes.
If SDLC.md exists at the repo root of this checkout, read it before starting
any change.
It is a local, git-ignored SDLC override that can layer additional personal
workflow (e.g. worktree + preview-integration conventions) on top of the rules
above. It is intentionally not checked in, so it only affects the workspace that
has it.
Project Overview
TeamClu is an AI Agent Desktop Platform built with Tauri 2.0 + React 19. Three-column layout chat/collaboration tool with local AI agents, team sync (Git / OSS, owned by the amuxd daemon), and multi-channel gateways.
Commands
# Install
pnpm install
# Dev
pnpm dev # Frontend only (Vite)
pnpm tauri:dev # Full Tauri desktop app
pnpm tauri:dev -- --skip-setup --skip-daemon-onboarding # Dev: skip first-run wizards
pnpm rust:check # Fast Rust compile check with shared .cargo-target
pnpm rust:build # Rust build with shared .cargo-target
# Always go through these wrappers rather than bare cargo. `binaries/` is fully
# gitignored, but tauri.conf.json globs binaries/{cursor,claude}-bridge/**/* as
# bundle resources — on a fresh checkout that glob matches nothing and
# tauri-build fails before any crate compiles. The wrappers stage the bridge
# trees for real builds and drop the globs for analysis-only runs.
pnpm daemon:run # Run amuxd from apps/daemon
pnpm ios:run # Build, install, and launch iOS app on booted Simulator
# Build
pnpm tauri:build # Production build
pnpm tauri:build:debug # Debug build
pnpm tauri:build:mac:all # macOS dual-arch (ARM64 + Intel)
pnpm daemon:build # Build daemon
pnpm ios:build # Build iOS simulator app
# Lint & Typecheck
pnpm lint # ESLint (frontend)
pnpm typecheck # TypeScript strict
cargo fmt --check --manifest-path apps/desktop/Cargo.toml
pnpm rust:clippy # clippy -D warnings; use this over bare `cargo clippy`,
# which fails on a fresh checkout (see rust:check below)
# Test
pnpm test:unit # Vitest unit tests
pnpm test:e2e # E2E (requires built app + tauri-mcp)
pnpm test:smoke # Smoke subset
pnpm daemon:test # Daemon tests
pnpm ios:test:core # AMUXCore SwiftPM tests
pnpm ios:test # iOS UI tests
# Deploy — self-host: nightly at 00:00 Asia/Shanghai (self-host-deploy.yml
# schedule) or manual workflow_dispatch. No longer on push to main. Belayo is
# a separate path.Architecture
Monorepo layout:
packages/app/— React 19 frontend (TypeScript, Tailwind 4, Zustand, Vite)apps/desktop/— Rust/Tauri backend (Tauri IPC commands, amuxd supervisor)apps/daemon/— amuxd daemon (pi runtime, MQTT/Supabase bridge)apps/ios/— iOS app, Xcode project, and Swift packagesservices/supabase/— Supabase migrations, seed, and database testsservices/fc/— Cloud API service (Node.js 20). Deploys as a container to the self-host Compose stack and Belayo Dokploycrates/— shared Rust crates (teamclu-proto,teamclu-types,teamclu-transport)tests/— E2E tests (tauri-mcp): smoke, regression, performance, functional
Frontend key paths:
packages/app/src/stores/— Zustand stores (50+ files, global state)packages/app/src/components/— React components (editors, chat, diff)packages/app/src/lib/— Utilities (backend client, skills, sync, MQTT)packages/app/src/hooks/— React hooks
Rust backend key paths:
apps/desktop/src/commands/— Tauri IPC commands (oss_sync/, team_share/, gateway/, cron/, etc.)apps/desktop/binaries/— sidecar binaries (teamclu-introspect, etc.)
Desktop-owned surfaces (they live in the Tauri process and are documented nowhere else; this describes what exists, it decides nothing):
- Cron —
apps/desktop/src/commands/cron/: the scheduler runs inside the desktop process, oneCronInstanceper workspace. Global jobs are stored underdirs::config_dir()/<brand storage dir>/cron-global, workspace jobs are keyed by workspace path. The daemon only executes the turns a job triggers, so a headless daemon has no cron. - Local cache —
apps/desktop/src/local_cache/: a libsql (SQLite) file at<brand home>/local-cache.dbmirroring Cloud API rows (actors, sessions, participants, messages, ideas, claims, submissions, outbox, watermarks) for offline reads. Commands arelocal_cache_*, all gated on the current team. - Introspect API —
commands/introspect_api.rs: a loopback HTTP server on127.0.0.1:13144that theteamclu-introspectMCP sidecar calls for WeCom sends, cron runs, team sync, env vars, workspace MCP config, and session archive / participants / export. Requests carry a per-launch bearer token; the module header documents the token file and the rejection rules. Calls that change state must also come from an agent host amuxd spawned (checked against/internal/runtime-context/verify; seeintrospect_api/caller.rs). Publishing or deleting an app, changing who can reach it, or replacing MCP servers waits for a native approval dialog that times out when nobody is at this machine (introspect_api/confirm.rs).
Editor system: Markdown (Tiptap) / HTML (Tiptap + sandbox preview) / Code (CodeMirror 6 + Shiki)
Agent runtime: the amuxd daemon drives pi exclusively (ADR-0014) over
stdio JSONL host processes — one pi child per (isolation domain, env revision,
worktree), multiple sessions per host. Legacy opencode / cursor / claude backends
have been removed. See docs/architecture/pi-agent-backend.md.
Backend Access Boundary — Cloud API is the only client backend
cloud_api is the only backend kind for clients. The supabase and pocketbase backend kinds have been removed from packages/app/. Direct @supabase/supabase-js usage in client code is forbidden and enforced by a guardrail test (packages/app/src/lib/backend/__tests__/no-supabase-import.test.ts).
The API contract is defined in docs/openapi/teamclu-api.v1.yaml. All business data operations must go through the TeamClu Cloud API (/v1) rather than direct Supabase client calls.
The Cloud API facade (services/fc/lib/business-api.mjs) is the canonical entry point for teams, sessions, messages, and invite operations. Clients (Tauri, Expo, iOS, daemon) should use their respective Cloud API providers:
- Web/Desktop (
packages/app/):CloudApiProviderinpackages/app/src/lib/backend/provider.ts - Expo (
apps/expo/):createCloudSessionsApiinapps/expo/src/features/sessions/cloud-api.ts - iOS (
apps/ios/):CloudAPIClient/CloudAPIRepositoriesinapps/ios/Packages/AMUXCore/Sources/AMUXCore/CloudAPI/ - daemon (
apps/daemon/):cloud_apibackend module inapps/daemon/src/backend/cloud_api.rs
Direct Supabase client usage (e.g. supabase.from('sessions').select()) is reserved for internal FC repository implementation only (services/fc/lib/supabase-repo.mjs). The FC facade forwards caller bearer tokens to Supabase, preserving RLS and auth semantics.
When adding new business endpoints:
- Define the endpoint in
docs/openapi/teamclu-api.v1.yamlfirst. - Implement the repository contract in
services/fc/lib/repository-contract.mjs. - Add the route handler in
services/fc/lib/business-api.mjs. - Implement the Supabase passthrough in
services/fc/lib/supabase-repo.mjs. - Add tests in
services/fc/test/(route, repository, contract). - Wire the endpoint into client Cloud API providers.
Do not bypass the Cloud API and call Supabase directly from client code. The facade exists so future backend replacements (MySQL, other storage) happen inside FC without client rewrites.
Streaming Architecture (Critical)
Single source of truth principle — never mix content sources:
- Streaming phase: display from the v2 stream entry (
useV2StreamingStore, built from the delta buffer); the v1useStreamingStoreis gone - Completed phase: display from
message.content(built frommessage.parts[]) - Never write to
msg.contentduring streaming - Never use "longest content" strategy on completion
The one exception, and where it lives. Completed content is reconciled in
exactly one place: deriveAgentReplyContent in
packages/app/src/lib/agent/agent-reply-transcript.ts, and the finalize path in
stores/v2-stream-parts.ts goes through its reconcileEquivalentAgentReplyText.
When the streamed text and the daemon's final content are the same text after
whitespace normalization, that helper keeps the longer one, because MQTT QoS0
can drop post-tool deltas and the daemon final carries the tail. Texts that
differ are never merged by length. pickCanonicalAgentReplyText may be imported
only by that module; lib/__tests__/agent-reply-single-reconciliation.test.ts
fails the build on a second importer.
Team Collaboration
Team sync is owned by the amuxd daemon (OSS engine). The legacy iroh-based P2P
mode has been removed, and so has git share — team sync never invokes git.
(The only git left in the product is the per-app Gitea checkout in
apps/daemon/src/sync/app_git.rs, which has nothing to do with team share.)
There is no share-mode switch any more. It was a one-shot cloud flag with no
producer left in the product — nothing shipped a call that set it — so every team
created since read as "off", and everything branching on it silently did nothing
(the sync button, the status poll, the daemon's sync, and a link sweep that
removed the team links it exists to create). The only remaining precondition
is the auto-sync toggle checked where the sync runs (sync::dispatch::run_once):
off and not forced → skipped; otherwise → sync. The team secret is fetched,
not required: knowledge content is uploaded as plaintext (see ADR-0008),
and the secret is only derived to decrypt blobs written before that switch and
to seal the local state/secrets.enc. A team without a secret syncs fine.
The teams.share_mode column and its Postgres enum are still there (in-use enum
values cannot be dropped, and dropping the column is a one-way door on
production data), but no code reads or writes them. Do not reintroduce a branch
on them.
Shared: the sync content root is ~/.amuxd/teams/<id>/shared/team-sync/, and
global_team_store::SHARED_PREFIXES is the whole of it — knowledge/ and
documents/, surfaced in a workspace as the team-knowledge and
team-documents symlinks. skills moved to the skills registry; .mcp and
_secrets moved to the Cloud API. The teamclu-team workspace link still
exists but is daemon-owned and sits outside the synced tree.
Versioning & Release
Version numbers — Desktop version must match across five places: package.json,
apps/desktop/Cargo.toml, apps/desktop/tauri.conf.json, apps/daemon/Cargo.toml
(bundled amuxd sidecar), and Cargo.lock (the teamclu and amuxd entries).
Cargo.lock is not optional: CI builds the daemon with --locked
(cargo test/check/build -p amuxd --locked), which fails outright when the lockfile
disagrees with the manifests. Verify with cargo metadata --locked before tagging.
Release process:
- Bump desktop version in all 5 places above
- Commit, push to main
git tag v<desktop-version> && git push origin v<desktop-version>- Tag push triggers
release.yml(macOS desktop)
iOS TestFlight Release
Version file: apps/ios/project.yml — MARKETING_VERSION (e.g. 1.2) +
CURRENT_PROJECT_VERSION.
CURRENT_PROJECT_VERSION does NOT decide what TestFlight receives. fastlane asks
App Store Connect for the latest build number and increments that at build time, so
the uploaded build comes from ASC. This field governs local builds only. The two
drift far apart — on the 1.2 release the file said 25 while ASC was already at 52,
so the upload went out as 53. Setting it by hand cannot fix a rejected upload.
Release process:
- Bump
MARKETING_VERSIONif the user-facing version changes;CURRENT_PROJECT_VERSIONis cosmetic (see above) but keep it moving so the checked-in value stays honest - Commit and push to main
git tag ios-v<version>-<build> && git push origin ios-v<version>-<build>- Example:
git tag ios-v1.2-25 && git push origin ios-v1.2-25
- Example:
- Tag push triggers
.github/workflows/testflight.yml(runsfastlane betaon CI)
Tag format must be ios-v* — other formats (e.g. ios-1.1.5-4) do not trigger the workflow.
testflight.yml also runs on pushes to main touching apps/ios/**, so the normal
release flow (merge, then tag) fires it twice for the same commit. A guard job
handles that: after the debounce it checks whether HEAD carries an ios-v* tag and
stands down if so, leaving the tag's run to publish. A main push with no tag behind
it still releases as before.
Deployment — two environments, two Cloud API targets
There are two environments:
- self-host is the Docker Compose test environment and stays on Caddy;
- Belayo is the hosted environment. Its production Cloud API runs on Dokploy, and its HTTP ingress is owned by Traefik.
Do not collapse the two environments or share proxy certificate files between them. Align their application contract instead: environment keys, internal ports, URL behaviour, health checks, immutable images, and smoke tests.
services/fc/ is the Cloud API service, and it supports two deploy targets
from the same source:
- self-host test — built as a container by
deploy/self-host/docker-compose.yml(build: context: ../../services/fc). Env comes from thefc:service'senvironment:map, which is an explicit allowlist: a var absent from it never reaches the container. - Belayo Dokploy — immutable container image on the main Swarm, exposed
through
teamclaw-api.ucar.ccvia Cloudflare and Traefik. Its names-only environment contract isdeploy/belayo/cloud-api.env.keys.
Both targets must keep working. When adding a Cloud API env var, update the
Compose environment: map and the Belayo keys manifest unless the difference
is explicitly documented and enforced by
services/fc/test/deploy-env-parity.test.ts.
Self-host test host: 47.112.210.217 (ECS
i-wz90nb0me448q3k22fxt). Every self-host subdomain below resolves to it:
| URL | What |
https://api.teamclu-dev.ucar.cc | Cloud API (/v1) — what clients call |
https://supabase.teamclu-dev.ucar.cc | Supabase gateway (PostgREST / GoTrue / Storage) |
https://studio.teamclu-dev.ucar.cc | Supabase Studio (behind Kong basic-auth — DASHBOARD_* in the box's .env) |
https://emqx.teamclu-dev.ucar.cc | EMQX dashboard |
wss://mqtt.teamclu-dev.ucar.cc/mqtt | MQTT over WSS (JWT access_token as password) |
The -dev hostnames identify the self-host test environment. Belayo's current
topology and migration state are tracked in
docs/specs/2026-09-11-belayo-dokploy-target-architecture.md.
Self-host deploys on a nightly schedule, not on every merge.
.github/workflows/self-host-deploy.yml runs at 00:00 Asia/Shanghai (cron:
0 16 * * * UTC) and on workflow_dispatch. It SSHes to the box, git pulls,
docker compose build fc ai-gateway, docker compose up -d, waits for both to
report healthy, then runs run-e2e.sh.
belayo does not ride that workflow. Self-host builds the gateway from
source in compose; belayo's Dokploy app is sourceType: docker, so it pulls a
pre-built image from Alibaba ACR and a source change reaches it only when
someone builds and pushes that image. .github/workflows/belayo-ai-gateway.yml
still triggers on push to main under services/ai-gateway/** (and on
workflow_dispatch). Database migrations are applied by the migrate
compose service (deploy/self-host/init/apply-migrations.sh, tracked in
_selfhost.schema_migrations, idempotent, lexical order).
Credentials (SSH, Postgres, service-role key, dashboard logins) live in the
box's .env and GitHub Actions secrets — never in this repo.
Cloud API endpoints: see docs/openapi/teamclu-api.v1.yaml (the contract) —
/v1/teams, /v1/sessions, /v1/messages, /v1/invites, plus /ai/*.
Team share onboarding endpoints (see docs/openapi/teamclu-api.v1.yaml):
GET /v1/teams/:id/workspace-config— merged shape{ syncMode, llm }. The legacy{ defaultWorkspaceId, pinnedWorkspaceIds }shape now lives atGET /v1/teams/:id/workspace-defaults(PUT path is unchanged). A team with no storedllm_base_urlis served the deployment's own gateway (<request origin>/ai/v1/teams/:id+ the three tiers) whenever FC hasAI_GATEWAY_INTERNAL_URL/AI_GATEWAY_SERVICE_TOKEN; a stored baseUrl always wins, andenabled=falsewith a baseUrl is how a team opts out (services/fc/src/lib/team-llm-defaults.ts).PUT /v1/teams/:id/llm-config— sets the team's AI gateway ({ enabled, baseUrl, models }). FC no longer provisions LiteLLM; the gateway is configured, not minted.
<!-- seahelm:suggest:start -->Quick options for the user (seahelm)
When you finish a turn and can anticipate the user's likely next steps, end your reply with one final plain-text line formatted exactly as:
::seahelm-suggest:: first option | second optionGive 2-5 short imperative phrases separated by |. seahelm turns that line into
clickable buttons for the user. Make it the LAST line of your message; do NOT run
a tool or shell command to produce it.
<!-- seahelm:suggest:end --><!-- seahelm:worktree:start -->Moving into another worktree (seahelm)
seahelm draws one card per git worktree, and your pane is filed under the one it started in. If you move into a different worktree and start working there, say so:
seahelm pane move "$SEAHELM_PANE_ID" <absolute-worktree-path>Your pane — and everything running in it — moves to that worktree's card, instead of a stray empty pane appearing there while you keep reporting under the old one.
Only when you actually work in it. Creating a worktree you do not move into needs nothing. seahelm often notices on its own; saying it means it is never missed.
<!-- seahelm:worktree:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

