1+ .roorules
2+
3+ This file provides guidance to Roo Code (or other AI coding assistants) when working with code in this repository.
4+
5+ ## Project Overview
6+
7+ **Roo Code** is a VSCode extension that provides an AI-powered autonomous coding agent. Built as a monorepo using TypeScript, React, and VSCode Extension API, it enables natural language code generation, refactoring, and intelligent assistance directly within the editor.
8+
9+ **Tech Stack:**
10+ - **Core:** TypeScript, VSCode Extension API, Node.js 20.19.2
11+ - **Frontend:** React 18, Vite, Tailwind CSS, Radix UI
12+ - **Build:** pnpm workspaces, Turbo, ESBuild, Vite
13+ - **Testing:** Vitest
14+ - **State Management:** VSCode Extension Context, React Context
15+ - **Communication:** Webview API, IPC
16+
17+ ## Essential Commands
18+
19+ ```bash
20+ # Installation & Setup
21+ pnpm install # Install all dependencies (uses pnpm 10.8.1)
22+
23+ # Development
24+ pnpm lint # Run ESLint across all workspaces
25+ pnpm check-types # TypeScript type checking
26+ pnpm test # Run all tests
27+ pnpm format # Format with Prettier
28+ pnpm build # Build all packages
29+ pnpm clean # Clean build artifacts
30+
31+ # Extension Development
32+ cd src && pnpm bundle # Bundle extension code
33+ pnpm vsix # Create VSIX package for distribution
34+ pnpm install:vsix # Build and install extension locally
35+ Press F5 in VSCode # Launch extension in debug mode
36+
37+ # Testing (CRITICAL - Must run from correct directory!)
38+ cd src && npx vitest run tests/user.test.ts # Backend tests
39+ cd webview-ui && npx vitest run src/test.ts # UI tests
40+ # NEVER run tests from project root - causes "vitest: command not found"
41+ ```
42+
43+ ## Architecture Overview
44+
45+ ```
46+ User Input → VSCode Extension → Webview UI
47+ ↓ ↓
48+ ClineProvider ←→ WebviewMessageHandler
49+ ↓
50+ Task Engine
51+ ↓
52+ Tool Execution System
53+ ↙ ↓ ↘
54+ Files Terminal Browser
55+ ```
56+
57+ ### Core Components
58+
59+ 1. **Extension Entry** ([`src/extension.ts`](src/extension.ts))
60+ - Activates on VSCode startup
61+ - Initializes services (Cloud, Telemetry, MDM, MCP)
62+ - Registers commands and providers
63+
64+ 2. **ClineProvider** ([`src/core/webview/ClineProvider.ts`](src/core/webview/ClineProvider.ts))
65+ - Central orchestrator for all interactions
66+ - Manages webview lifecycle
67+ - Handles task stack and state persistence
68+
69+ 3. **Task System** ([`src/core/task/Task.ts`](src/core/task/Task.ts))
70+ - Executes AI agent workflows
71+ - Manages tool usage and message flow
72+ - Handles checkpoints and recovery
73+
74+ 4. **Webview UI** ([`webview-ui/`](webview-ui/))
75+ - React-based chat interface
76+ - Communicates via postMessage API
77+ - Styled with Tailwind + VSCode theme variables
78+
79+ ## Development Guides
80+
81+ ### Adding a New AI Provider
82+
83+ 1. Create provider class in [`src/api/providers/`](src/api/providers/)
84+ 2. Extend `BaseProvider` or `BaseOpenAICompatibleProvider`
85+ 3. Implement required methods: `createMessage()`, `getModel()`
86+ 4. Register in [`src/api/index.ts`](src/api/index.ts)
87+ 5. Add UI configuration in webview settings
88+
89+ ### Creating a Custom Mode
90+
91+ 1. Add mode definition to [`.roomodes/`](.roomodes/)
92+ 2. Include mode metadata (name, slug, model preferences)
93+ 3. Define system prompt and tool restrictions
94+ 4. Register in [`CustomModesManager`](src/core/config/CustomModesManager.ts)
95+
96+ ### Adding a New Tool
97+
98+ 1. Create tool file in [`src/core/tools/`](src/core/tools/)
99+ 2. Implement tool interface with `execute()` method
100+ 3. Add tool to system prompt in [`src/core/prompts/tools/`](src/core/prompts/tools/)
101+ 4. Handle tool response in Task execution flow
102+
103+ ### Modifying the Webview UI
104+
105+ 1. Components live in [`webview-ui/src/components/`](webview-ui/src/components/)
106+ 2. Use Tailwind classes, not inline styles
107+ 3. VSCode CSS variables must be added to [`webview-ui/src/index.css`](webview-ui/src/index.css)
108+ 4. Test with both light and dark themes
109+
110+ ## Project-Specific Patterns
111+
112+ ### State Management
113+ - Extension state: VSCode `globalState` and `secrets` APIs via `ContextProxy`
114+ - Webview state: React Context + message passing
115+ - Task persistence: JSON files in global storage directory
116+
117+ ### Message Flow
118+ ```typescript
119+ // Webview → Extension
120+ vscode.postMessage({ type: "newTask", text: "..." })
121+
122+ // Extension → Webview
123+ provider.postMessageToWebview({ type: "taskUpdated", ... })
124+ ```
125+
126+ ### Error Handling
127+ - All async operations wrapped in try-catch
128+ - Errors logged to output channel
129+ - User-facing errors shown via `vscode.window.showErrorMessage`
130+
131+ ### File Operations
132+ - Always use VSCode workspace APIs for file access
133+ - Respect `.rooignore` patterns
134+ - Use `FileContextTracker` for monitoring file changes
135+
136+ ## Code Style
137+
138+ ```typescript
139+ // Formatting (from .prettierrc.json)
140+ - Tabs (width: 4)
141+ - No semicolons
142+ - Print width: 120 chars
143+ - Brackets on same line
144+
145+ // TypeScript
146+ - Strict mode enabled
147+ - No implicit any (currently disabled in ESLint)
148+ - Use type imports: import type { ... }
149+
150+ // Naming Conventions
151+ - Files: camelCase.ts or PascalCase.ts for classes
152+ - Interfaces: IPrefixed or suffixed with Interface
153+ - Types: PascalCase
154+ - Constants: UPPER_SNAKE_CASE
155+ ```
156+
157+ ## Testing Guidelines
158+
159+ ### Test Structure
160+ ```typescript
161+ // Tests use Vitest with globals (vi, describe, test, it)
162+ describe("ComponentName", () => {
163+ test("should do something", async () => {
164+ // Arrange
165+ const mock = vi.fn()
166+
167+ // Act
168+ await doSomething()
169+
170+ // Assert
171+ expect(mock).toHaveBeenCalled()
172+ })
173+ })
174+ ```
175+
176+ ### Running Tests
177+ ```bash
178+ # CRITICAL: Tests must run from workspace directory!
179+ cd src && npx vitest run path/to/test.ts # Backend
180+ cd webview-ui && npx vitest run src/... # Frontend
181+
182+ # Watch mode for development
183+ cd src && npx vitest watch
184+ ```
185+
186+ ### Mocking VSCode APIs
187+ - Mock modules in [`src/__mocks__/vscode.ts`](src/__mocks__/vscode.ts)
188+ - Use `vi.mock("vscode")` in test files
189+ - Mock extension context for provider tests
190+
191+ ## Security Considerations
192+
193+ - **API Keys:** Stored in VSCode secrets, never in code
194+ - **File Access:** Respect workspace boundaries and .rooignore
195+ - **Command Execution:** User approval required for terminal commands
196+ - **Protected Files:** RooProtectedController prevents accidental overwrites
197+
198+ ## Performance Optimization
199+
200+ - **Lazy Loading:** MCP servers and code indexing initialize on-demand
201+ - **Debouncing:** File watchers and UI updates are debounced
202+ - **Caching:** Model lists and API responses cached with TTL
203+ - **Streaming:** LLM responses streamed for better UX
204+
205+ ## Critical Rules
206+
207+ 1. **Never disable lint rules** without explicit user approval
208+ 2. **Always ensure test coverage** before attempting completion
209+ 3. **Use Tailwind CSS** for new UI components, not inline styles
210+ 4. **Run tests from correct directory** - see Testing Guidelines
211+ 5. **Respect file restrictions** - some modes can only edit specific file types
212+ 6. **Wait for tool confirmation** - never assume tool success without user response
213+
214+ ## Troubleshooting
215+
216+ ### Common Issues
217+
218+ **"vitest: command not found"**
219+ - You're running tests from the wrong directory
220+ - Solution: `cd src` or `cd webview-ui` first
221+
222+ **Extension not loading**
223+ - Check output channel for errors
224+ - Verify all dependencies installed: `pnpm install`
225+ - Try clean rebuild: `pnpm clean && pnpm build`
226+
227+ **Webview not updating**
228+ - In dev mode (F5), changes should hot-reload
229+ - For VSIX installation, rebuild and reinstall
230+
231+ **MCP server connection failed**
232+ - Check server configuration in settings
233+ - Verify server binary is executable
234+ - Check logs in output channel
235+
236+ ## Development Workflow
237+
238+ 1. **Branch naming:** `feature/description` or `fix/issue-number`
239+ 2. **Commits:** Descriptive messages referencing issues
240+ 3. **Testing:** Run tests before pushing
241+ 4. **Code review:** All PRs require approval
242+ 5. **Deployment:** Automated via GitHub Actions on merge to main
0 commit comments