agentleFS
different-ai-studiodifferent-ai-studio/teamclaw/CLAUDE.md

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

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
  1. Distinctive:

    Never push directly to main: All changes go through a feature branch and a Pull Request:

    line 15
  2. Very specific:

    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 …

    line 19
  3. Distinctive:

    Do not merge or push to main directly, even for small fixes.

    line 24
  4. Very specific:

    If SDLC.md exists at the repo root of this checkout, read it before starting any change.

    line 26
  5. Very specific:

    Add the route handler in services/fc/lib/business-api.mjs.

    line 155
  6. Very specific:

    Add tests in services/fc/test/ (route, repository, contract).

    line 157
  7. Distinctive:

    Do not bypass the Cloud API and call Supabase directly from client code.

    line 160
  8. Very specific:

    Never: write to msg.content during streaming

    line 168
  9. Distinctive:

    Never: use "longest content" strategy on completion

    line 169
  10. Distinctive:

    When the streamed text and the daemon's final content are the *same text after whitespace normalization*, that helper keeps the longer one, …

    line 175
  11. Distinctive:

    Commit, push to main

    line 224
  12. Distinctive:

    Commit and push to main

    line 242
  13. Distinctive:

    Do not collapse the two environments or share proxy certificate files between them.

    line 263
  14. Distinctive:

    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:

    line 328
  15. Distinctive:

    Only when you actually work in it.

    line 349

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 in apps/ios/.
  • Web / desktop (packages/app/): AGENTS.md at 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:

  1. Work on a task-scoped branch, never on main.
  2. 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 "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.
  3. Do not merge or push to main directly, 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 packages
  • services/supabase/ — Supabase migrations, seed, and database tests
  • services/fc/ — Cloud API service (Node.js 20). Deploys as a container to the self-host Compose stack and Belayo Dokploy
  • crates/ — 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, one CronInstance per workspace. Global jobs are stored under dirs::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.db mirroring Cloud API rows (actors, sessions, participants, messages, ideas, claims, submissions, outbox, watermarks) for offline reads. Commands are local_cache_*, all gated on the current team.
  • Introspect API — commands/introspect_api.rs: a loopback HTTP server on 127.0.0.1:13144 that the teamclu-introspect MCP 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; see introspect_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/): CloudApiProvider in packages/app/src/lib/backend/provider.ts
  • Expo (apps/expo/): createCloudSessionsApi in apps/expo/src/features/sessions/cloud-api.ts
  • iOS (apps/ios/): CloudAPIClient / CloudAPIRepositories in apps/ios/Packages/AMUXCore/Sources/AMUXCore/CloudAPI/
  • daemon (apps/daemon/): cloud_api backend module in apps/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:

  1. Define the endpoint in docs/openapi/teamclu-api.v1.yaml first.
  2. Implement the repository contract in services/fc/lib/repository-contract.mjs.
  3. Add the route handler in services/fc/lib/business-api.mjs.
  4. Implement the Supabase passthrough in services/fc/lib/supabase-repo.mjs.
  5. Add tests in services/fc/test/ (route, repository, contract).
  6. 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 v1 useStreamingStore is gone
  • Completed phase: display from message.content (built from message.parts[])
  • Never write to msg.content during 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:

  1. Bump desktop version in all 5 places above
  2. Commit, push to main
  3. git tag v<desktop-version> && git push origin v<desktop-version>
  4. 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:

  1. Bump MARKETING_VERSION if the user-facing version changes; CURRENT_PROJECT_VERSION is cosmetic (see above) but keep it moving so the checked-in value stays honest
  2. Commit and push to main
  3. 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
  4. Tag push triggers .github/workflows/testflight.yml (runs fastlane beta on 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 the fc: service's environment: 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.cc via Cloudflare and Traefik. Its names-only environment contract is deploy/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:

URLWhat
https://api.teamclu-dev.ucar.ccCloud API (/v1) — what clients call
https://supabase.teamclu-dev.ucar.ccSupabase gateway (PostgREST / GoTrue / Storage)
https://studio.teamclu-dev.ucar.ccSupabase Studio (behind Kong basic-auth — DASHBOARD_* in the box's .env)
https://emqx.teamclu-dev.ucar.ccEMQX dashboard
wss://mqtt.teamclu-dev.ucar.cc/mqttMQTT 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 at GET /v1/teams/:id/workspace-defaults (PUT path is unchanged). A team with no stored llm_base_url is served the deployment's own gateway (<request origin>/ai/v1/teams/:id + the three tiers) whenever FC has AI_GATEWAY_INTERNAL_URL/AI_GATEWAY_SERVICE_TOKEN; a stored baseUrl always wins, and enabled=false with 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 option

Give 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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.