Cline rules

1This file is the secret sauce for working effectively in this codebase. It captures tribal knowledge—the nuanced, non-obvious patterns that make the difference between a quick fix and hours of back-and-forth & human intervention.
2 
3**When to add to this file:**
4- User had to intervene, correct, or hand-hold
5- Multiple back-and-forth attempts were needed to get something working
6- You discovered something that required reading many files to understand
7- A change touched files you wouldn't have guessed
8- Something worked differently than you expected
9- User explicitly asks to "add this to CLAUDE.md"
10 
11**Proactively suggest additions** when any of the above happen—don't wait to be asked.
12 
13**What NOT to add:** Stuff you can figure out from reading a few files, obvious patterns, or standard practices. This file should be high-signal, not comprehensive.
14 
15## Miscellaneous
16- This is a VS Code extension—check `package.json` for available scripts before trying to verify builds (e.g., `npm run compile`, not `npm run build`).
17- When creating PRs, if the change is user-facing and significant enough to warrant a changelog entry, run `npm run changeset` and create a patch changeset. Never create minor or major version bumps. Skip changesets for trivial fixes, internal refactors, or minor UI tweaks that users wouldn't notice.
18- When adding new feature flags, see this PR as a reference https://github.com/cline/cline/pull/7566
19- Additional instructions about making requests: @.clinerules/network.md
20 
21## gRPC/Protobuf Communication
22The extension and webview communicate via gRPC-like protocol over VS Code message passing.
23 
24**Proto files live in `proto/`** (e.g., `proto/cline/task.proto`, `proto/cline/ui.proto`)
25- Each feature domain has its own `.proto` file
26- For simple data, use shared types in `proto/cline/common.proto` (`StringRequest`, `Empty`, `Int64Request`)
27- For complex data, define custom messages in the feature's `.proto` file
28- Naming: Services `PascalCaseService`, RPCs `camelCase`, Messages `PascalCase`
29- For streaming responses, use `stream` keyword (see `subscribeToAuthCallback` in `account.proto`)
30 
31**Run `npm run protos`** after any proto changes—generates types in:
32- `src/shared/proto/` - Shared type definitions
33- `src/generated/grpc-js/` - Service implementations
34- `src/generated/nice-grpc/` - Promise-based clients
35- `src/generated/hosts/` - Generated handlers
36 
37**Adding new enum values** (like a new `ClineSay` type) requires updating conversion mappings in `src/shared/proto-conversions/cline-message.ts`
38 
39**Adding new RPC methods** requires:
40- Handler in `src/core/controller/<domain>/`
41- Call from webview via generated client: `UiServiceClient.scrollToSettings(StringRequest.create({ value: "browser" }))`
42 
43**Example—the `explain-changes` feature touched:**
44- `proto/cline/task.proto` - Added `ExplainChangesRequest` message and `explainChanges` RPC
45- `proto/cline/ui.proto` - Added `GENERATE_EXPLANATION = 29` to `ClineSay` enum
46- `src/shared/ExtensionMessage.ts` - Added `ClineSayGenerateExplanation` type
47- `src/shared/proto-conversions/cline-message.ts` - Added mapping for new say type
48- `src/core/controller/task/explainChanges.ts` - Handler implementation
49- `webview-ui/src/components/chat/ChatRow.tsx` - UI rendering
50 
51## Adding a New API Provider
52When adding a new provider (e.g., "openai-codex"), you must update the proto conversion layer in THREE places or the provider will silently reset to Anthropic:
53 
541. `proto/cline/models.proto` - Add to the `ApiProvider` enum (e.g., `OPENAI_CODEX = 40;`)
552. `convertApiProviderToProto()` in `src/shared/proto-conversions/models/api-configuration-conversion.ts` - Add case mapping string to proto enum
563. `convertProtoToApiProvider()` in the same file - Add case mapping proto enum back to string
57 
58**Why this matters:** Without these, the provider string hits the `default` case and returns `ANTHROPIC`. The webview, provider list, and handler all work fine, but the state silently resets when it round-trips through proto serialization. No error is thrown.
59 
60**Other files to update when adding a provider:**
61- `src/shared/api.ts` - Add to `ApiProvider` union type, define models
62- `src/shared/providers/providers.json` - Add to provider list for dropdown
63- `src/core/api/index.ts` - Register handler in `createHandlerForProvider()`
64- `webview-ui/src/components/settings/utils/providerUtils.ts` - Add cases in `getModelsForProvider()` and `normalizeApiConfiguration()`
65- `webview-ui/src/utils/validate.ts` - Add validation case
66- `webview-ui/src/components/settings/ApiOptions.tsx` - Render provider component
67 
68## Responses API Providers (OpenAI Codex, OpenAI Native)
69Providers using OpenAI's Responses API require native tool calling. XML tools don't work with the Responses API.
70 
71**Symptoms of broken native tool calling:**
72- Tools get called multiple times (e.g., `ask_followup_question` asks the same question twice)
73- Tool arguments get duplicated or malformed
74- The model responds but tools aren't recognized
75 
76**Root causes to check:**
771. **Provider missing from `isNextGenModelProvider()`** in `src/utils/model-utils.ts`. The native variant matchers (e.g., `native-gpt-5/config.ts`) call this function. If your provider isn't in the list, the matcher returns false and falls back to XML tools.
78 
792. **Model missing `apiFormat: ApiFormat.OPENAI_RESPONSES`** in its model info (`src/shared/api.ts`). This property signals that the model requires native tool calling. The task runner in `src/core/task/index.ts` checks this and forces `enableNativeToolCalls: true` regardless of user settings.
80 
81**When adding a new Responses API provider:**
821. Add provider to `isNextGenModelProvider()` list in `src/utils/model-utils.ts`
832. Set `apiFormat: ApiFormat.OPENAI_RESPONSES` on all models that use the Responses API
843. The variant matcher and task runner will handle the rest automatically
85 
86## Adding Tools to System Prompt
87This is tricky—multiple prompt variants and configs. **Always search for existing similar tools first and follow their pattern.** Look at the full chain from prompt definition → variant configs → handler → UI before implementing.
88 
891. **Add to `ClineDefaultTool` enum** in `src/shared/tools.ts`
902. **Tool definition** in `src/core/prompts/system-prompt/tools/` (create file like `generate_explanation.ts`)
91   - Define variants for each `ModelFamily` (generic, next-gen, xs, etc.)
92   - Export variants array (e.g., `export const my_tool_variants = [GENERIC, NATIVE_NEXT_GEN, XS]`)
93   - **Fallback behavior**: If a variant isn't defined for a model family, `ClineToolSet.getToolByNameWithFallback()` automatically falls back to GENERIC. So you only need to export `[GENERIC]` unless the tool needs model-specific behavior.
943. **Register in `src/core/prompts/system-prompt/tools/init.ts`** - Import and spread into `allToolVariants`
954. **Add to variant configs** - Each model family has its own config in `src/core/prompts/system-prompt/variants/*/config.ts`. Add your tool's enum to the `.tools()` list:
96   - `generic/config.ts`, `next-gen/config.ts`, `gpt-5/config.ts`, `native-gpt-5/config.ts`, `native-gpt-5-1/config.ts`, `native-next-gen/config.ts`, `gemini-3/config.ts`, `glm/config.ts`, `hermes/config.ts`, `xs/config.ts`
97   - **Important**: If you add to a variant's config, make sure the tool spec exports a variant for that ModelFamily (or relies on GENERIC fallback)
985. **Create handler** in `src/core/task/tools/handlers/`
996. **Wire up in `ToolExecutor.ts`** if needed for execution flow
1007. **Add to tool parsing** in `src/core/assistant-message/index.ts` if needed
1018. **If tool has UI feedback**: add `ClineSay` enum in proto, update `src/shared/ExtensionMessage.ts`, update `src/shared/proto-conversions/cline-message.ts`, update `webview-ui/src/components/chat/ChatRow.tsx`
102 
103## Modifying System Prompt
104**Read these first:** `src/core/prompts/system-prompt/README.md`, `tools/README.md`, `__tests__/README.md`
105 
106System prompt is modular: **components** (reusable sections) + **variants** (model-specific configs) + **templates** (with `{{PLACEHOLDER}}` resolution).
107 
108**Key directories:**
109- `components/` - Shared sections: `rules.ts`, `capabilities.ts`, `editing_files.ts`, etc.
110- `variants/` - Model-specific: `generic/`, `next-gen/`, `xs/`, `gpt-5/`, `gemini-3/`, `hermes/`, `glm/`, etc.
111- `templates/` - Template engine and placeholder definitions
112 
113**Variant tiers (ask user which to modify):**
114- **Next-gen** (Claude 4, GPT-5, Gemini 2.5): `next-gen/`, `native-next-gen/`, `native-gpt-5/`, `native-gpt-5-1/`, `gemini-3/`, `gpt-5/`
115- **Standard** (default fallback): `generic/`
116- **Local/small models**: `xs/`, `hermes/`, `glm/`
117 
118**How overrides work:** Variants can override components via `componentOverrides` in their `config.ts`, or provide a custom template in `template.ts` (e.g., `next-gen/template.ts` exports `rules_template`). If no override, the shared component from `components/` is used.
119 
120**Example: Adding a rule to RULES section**
1211. Check if variant overrides rules: look for `rules_template` in `variants/*/template.ts` or `componentOverrides.RULES` in `config.ts`
1222. If shared: modify `components/rules.ts`
1233. If overridden: modify that variant's template
1244. XS variant is special—has heavily condensed inline content in `template.ts`
125 
126**After any changes, regenerate snapshots:**
127```bash
128UPDATE_SNAPSHOTS=true npm run test:unit
129```
130Snapshots live in `__tests__/__snapshots__/`. Tests validate across model families and context variations (browser, MCP, focus chain).
131 
132## Modifying Default Slash Commands
133Three places need updates:
134- `src/core/slash-commands/index.ts` - Command definitions
135- `src/core/prompts/commands.ts` - System prompt integration
136- `webview-ui/src/utils/slash-commands.ts` - Webview autocomplete
137 
138## Adding New Global State Keys
139Adding a new key to global state requires updates in multiple places. Missing any step causes silent failures.
140 
141Required steps:
1421. Type definition in `src/shared/storage/state-keys.ts` - Add to `GlobalState` or `Settings` interface
1432. Read from globalState in `src/core/storage/utils/state-helpers.ts`:
144   - Add `const myKey = context.globalState.get<GlobalStateAndSettings["myKey"]>("myKey")` in `readGlobalStateFromDisk()`
145   - Add to the return object: `myKey: myKey ?? defaultValue,`
1463. StateManager handles read/write via `setGlobalState()`/`getGlobalStateKey()` after initialization
147 
148Common mistake: Adding only the return value without the `context.globalState.get()` call. This compiles but the value is always `undefined` on load.
149 
150## StateManager Cache vs Direct globalState Access
151StateManager uses an in-memory cache populated during `StateManager.initialize(context)` in `common.ts`. For most state, use `controller.stateManager.setGlobalState()`/`getGlobalStateKey()`.
152 
153Exception: State needed immediately at extension startup (before cache is ready)
154 
155When Window A sets state and immediately opens Window B, the new window's StateManager cache is populated from `context.globalState` during initialization. If you need to read state in Window B right at startup (e.g., in `common.ts` during `initialize()`), read directly from `context.globalState.get()` instead of StateManager's cache.
156 
157Example pattern (see `lastShownAnnouncementId` and `worktreeAutoOpenPath`):
158```typescript
159// Writing (normal pattern)
160controller.stateManager.setGlobalState("myKey", value)
161 
162// Reading at startup in common.ts (bypass cache)
163const value = context.globalState.get<string>("myKey")
164```
165 
166This is only needed for cross-window state read during the brief startup window before StateManager cache is fully usable. Normal state access after initialization should use StateManager.
167 
168## ChatRow Cancelled/Interrupted States
169When a ChatRow displays a loading/in-progress state (spinner), you must handle what happens when the task is cancelled. This is non-obvious because cancellation doesn't update the message content—you have to infer it from context.
170 
171**The pattern:**
1721. A message has a `status` field (e.g., `"generating"`, `"complete"`, `"error"`) stored in `message.text` as JSON
1732. When cancelled mid-operation, the status stays `"generating"` forever—no one updates it
1743. To detect cancellation, check TWO conditions:
175   - `!isLast` — if this message is no longer the last message, something else happened after it (interrupted)
176   - `lastModifiedMessage?.ask === "resume_task" || "resume_completed_task"` — task was just cancelled and is waiting to resume
177 
178**Example from `generate_explanation`:**
179```tsx
180const wasCancelled =
181    explanationInfo.status === "generating" &&
182    (!isLast ||
183        lastModifiedMessage?.ask === "resume_task" ||
184        lastModifiedMessage?.ask === "resume_completed_task")
185const isGenerating = explanationInfo.status === "generating" && !wasCancelled
186```
187 
188**Why both checks?**
189- `!isLast` catches: cancelled → resumed → did other stuff → this old message is stale
190- `lastModifiedMessage?.ask === "resume_task"` catches: just cancelled, hasn't resumed yet, this message is still technically "last"
191 
192**See also:** `BrowserSessionRow.tsx` uses similar pattern with `isLastApiReqInterrupted` and `isLastMessageResume`.
193 
194**Backend side:** When streaming is cancelled, clean up properly (close tabs, clear comments, etc.) by checking `taskState.abort` after the streaming function returns.
195