CLAUDE.md · vastsa/PI-Desktop

Sections

1. Interaction language
2. Hard rules (do not negotiate)
3. Read before you change
4. Repo map
5. Validation commands
6. Claude Code session checklist
7. Issue and PR intake
8. Quick “where do I put this?”

First lines (shown under the repo's LGPL-3.0 license)

# CLAUDE.md

Policy-Sync: 2026-09-26.1

Instructions for Claude Code CLI and Claude Cowork on PI-Desktop.

**Authoritative policy:** [`AGENTS.md`](AGENTS.md). Read it before any non-trivial change. If this file and `AGENTS.md` disagree, follow `AGENTS.md`. Domain specs under `docs/spec/` remain authoritative for product behavior, protocols, and security boundaries.

**Mirror sync:** This file condenses `AGENTS.md` for Claude Code. When policy changes, update both files, keep the shared non-negotiables aligned, and set the same `Policy-Sync:` token in both. Enforced by `pnpm check:agent-policy` (`scripts/check-agent-policy-sync.mjs`).

PI-Desktop is released software with real users. Treat every change as production maintenance, not prototype work.

Priority order when deciding what to do:

1. Correctness and user data safety
2. Security and backward compatibility
3. Architectural integrity
4. Testability and maintainability
5. Delivery speed

Optimize for changing the system safely, not merely changing it quickly.

---

## Interaction language

Reply to the user in the language they used (Chinese request → Chinese answer, kept terse). Keep code, identifiers, comments, commit messages, specs, ADRs, log strings, and repository docs in English. GitHub issue / PR discussion follows the original author's language.

---

## Hard rules (do not negotiate)

### Worktree isolation

Every request uses:

```text
1 request = 1 branch + 1 dedicated worktree
```

- Never develop on `main` or in the primary checkout.
- Never merge unvalidated task code into local `main`.
- Never reuse, modify, or delete another agent's branch or worktree.
- Never discard unrelated work in the primary checkout.
- Resolve conflicts only inside your own task worktree.

Create the worktree from current remote `main`:

```bash
git fetch origin main
git worktree add \
  -b <type>/<short-description> \
  <worktree-path> \
  origin/main
cd <worktree-path>
```

Suggested worktree path: `../PI-Desktop-worktrees/<short-description>`.

Branch names: `feat/...`, `fix/...`, `docs/...`, `refactor/...`, `chore/...`.

### Delivery order (code-bearing changes)

```text
1. branch + worktree from origin/main
2. implement in the worktree
3. targeted static/unit/integration checks
4. review the full diff
5. commit
6. fetch + rebase/refresh against latest origin/main (private branch)
7. resolve conflicts in the worktree
8. task-candidate E2E in the same worktree
9. push branch
10. open/update PR
11. PR integration validation
12. merge into remote main through repository gates
13. synchronize local main
14. remove your worktree and merged local branch
```

Do **not** insert `merge task → local main` between refresh and task-candidate E2E. The task branch itself is the local integration candidate after incorporating latest `origin/main`. Do not open or update a PR that is behind `origin/main`. Run `pnpm check:pr-base` before opening or updating a PR.

Record E2E evidence:

```text
Task candidate:
Base main:
E2E suites:
Result:
Environment:
```

If a required suite cannot run, report `NOT RUN` with reason, alternative validation, and remaining risk. Never report a skipped command as passing.

### E2E environment reuse

Task-candidate E2E uses the host development environment already provisioned
in the primary checkout. Reuse its Node/pnpm toolchain, compatible
`node_modules`, Electron, Rust/Cargo targets, stores, caches, and ignored
configuration by reference or link when needed.

Never run `pnpm install` or `npm install`, or create a second dependency or
runtime environment, solely for E2E. Keep temporary profiles, data, sockets,
ports, logs, and artifacts isolated. Install or rebuild only for missing or
incompatible host dependencies, and record the reason; clean CI/release
runners may install from lockfiles.

### Architecture (frozen)

```text
Renderer → Preload IPC → Electron Main → Rust Host Core / Node Agent Runtime → pi-ai / pi-agent-core
```

Ownership:

```text
Renderer       = UI and interaction
Electron Main  = thin orchestrator
Rust Host Core = persistence and authoritative host/native state
Agent Runtime  = agent execution
Plugin SDK     = extension contract
Shared         = cross-boundary contracts and schemas
```

Boundaries you must not break:

- Renderer never touches SQLite or Electron Main internals.
- SQLite is owned exclusively by Rust `host-core`.
- Agent execution does not move into the renderer.
- Electron Main stays a thin orchestrator.
- Shared packages do not depend on desktop implementation code.
- Plugin permissions and sandbox boundaries are never bypassed.

Changing a frozen architecture, public interface, data ownership model, or security boundary requires an ADR under `docs/adr/`.

### Behavior and data safety

Unless the task explicitly requires a behavior change, do not:

- remove functionality or change user-visible defaults
- change persisted data semantics without migration
- change IPC/RPC or Plugin SDK contracts
- weaken security, permissions, sandbox, or URL/filesystem checks
- hide behavior changes inside a `refactor` commit

Database / schema changes need migration, schema version bump, upgrade compatibility, tests, and spec updates. Never assume an empty database.

### Architecture ratchet

Do not pile new logic into God Modules. Prefer shrink-or-stay-stable for:

```text
apps/desktop/electron/main/index.ts
apps/desktop/src/stores/app-store.ts
apps/desktop/src/components/ChatTranscript.tsx
apps/desktop/src/components/Composer.tsx
crates/host-core/src/plugins.rs
crates/host-core/src/db.rs
crates/host-core/src/providers.rs
crates/host-core/src/plans.rs