Cline rules

1# Storage Architecture
2 
3Global settings, secrets and workspace state are stored in **file-backed JSON stores** under `~/.cline/data/`. This is the shared storage layer used by VSCode, CLI, and JetBrains.
4 
5## Key Abstractions
6 
7### `StorageContext` (src/shared/storage/storage-context.ts)
8The entry point. Created via `createStorageContext()` and passed to `StateManager.initialize()`. Contains three `ClineFileStorage` instances:
9- `globalState` → `~/.cline/data/globalState.json`
10- `secrets` → `~/.cline/data/secrets.json` (mode 0o600)
11- `workspaceState` → `~/.cline/data/workspaces/<hash>/workspaceState.json`
12 
13### `ClineFileStorage` (src/shared/storage/ClineFileStorage.ts)
14Synchronous JSON key-value store backed by a single file. Supports `get()`, `set()`, `setBatch()`, `delete()`. Writes are atomic (write-then-rename).
15 
16### `StateManager` (src/core/storage/StateManager.ts)
17In-memory cache on top of `StorageContext`. All runtime reads hit the cache; writes update cache immediately and debounce-flush to disk.
18 
19## ⚠️ Do NOT Use VSCode's ExtensionContext for Storage
20 
21**Do not** read from or write to `context.globalState`, `context.workspaceState`, or `context.secrets` for persistent data. These are VSCode-specific and not available on CLI or JetBrains.
22 
23Instead, use:
24```typescript
25// Reading state
26StateManager.get().getGlobalStateKey("myKey")
27StateManager.get().getSecretKey("mySecretKey")
28StateManager.get().getWorkspaceStateKey("myWsKey")
29 
30// Writing state
31StateManager.get().setGlobalState("myKey", value)
32StateManager.get().setSecret("mySecretKey", value)
33StateManager.get().setWorkspaceState("myWsKey", value)
34```
35 
36Remember that your data may be read by a different client than the one that wrote it. For example, a value written by Cline in JetBrains may be read by Cline CLI.
37 
38## VSCode Migration (src/hosts/vscode/vscode-to-file-migration.ts)
39 
40On VSCode startup, a migration copies data from VSCode's `ExtensionContext` storage into the file-backed stores. This runs in `src/common.ts` before `StateManager.initialize()`.
41 
42- **Sentinel**: `__vscodeMigrationVersion` key in global state and workspace state — prevents re-migration.
43- **Merge strategy**: File store wins. Existing values are never overwritten.
44- **Safe downgrade**: VSCode storage is NOT cleared, so older extension versions still work.
45 
46## Adding New Storage Keys
47 
481. Add to `src/shared/storage/state-keys.ts` (see existing patterns)
492. Read/write via `StateManager` (NOT via `context.globalState`)
503. If adding a secret, add to `SecretKeys` array in `state-keys.ts`
51 
52## File Layout
53 
54```
55~/.cline/
56  data/
57    globalState.json          # Global settings & state
58    secrets.json              # API keys (mode 0o600)
59    tasks/
60      taskHistory.json        # Task history (separate file)
61    workspaces/
62      <hash>/
63        workspaceState.json   # Per-workspace toggles
64```
65