|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Roo Code is an AI-powered VS Code extension that acts as a development assistant. It's built as a monorepo using pnpm workspaces and TypeScript with Turbo for build orchestration. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +### Monorepo Structure |
| 12 | +- **Root**: Main extension code in `src/` |
| 13 | +- **Packages/**: Shared workspace packages: |
| 14 | + - `@roo-code/types`: Shared TypeScript types and interfaces |
| 15 | + - `@roo-code/config-eslint`: ESLint configuration |
| 16 | + - `@roo-code/config-typescript`: TypeScript configuration |
| 17 | + - `@roo-code/build`: Build utilities |
| 18 | + - `@roo-code/ipc`: Inter-process communication |
| 19 | + - `@roo-code/cloud`: Cloud services integration |
| 20 | + - `@roo-code/telemetry`: Telemetry and analytics |
| 21 | + - `@roo-code/evals`: Evaluation framework |
| 22 | + |
| 23 | +### Core Extension Architecture |
| 24 | +- **Entry Point**: `src/extension.ts` - Main extension activation |
| 25 | +- **Core**: `src/core/` - Core functionality including prompts, tools, and webview management |
| 26 | +- **API**: `src/api/` - Provider integrations for various AI models (40+ providers including OpenAI, Claude, Gemini, local models, etc.) |
| 27 | +- **Services**: `src/services/` - Core services (MCP server management, code indexing, checkpoints) |
| 28 | +- **Integrations**: `src/integrations/` - VS Code editor integrations, terminal handling, theme support |
| 29 | +- **Webview**: `webview-ui/` - React-based UI for the extension's chat interface |
| 30 | + |
| 31 | +### Key Components |
| 32 | +- **Provider System**: Modular AI provider architecture in `src/api/providers/` with base classes and OpenAI-compatible implementations |
| 33 | +- **Tool System**: Extensible tool framework in `src/core/prompts/tools/` for file operations, browser automation, MCP integration |
| 34 | +- **MCP Integration**: Model Context Protocol server management for external tool integration |
| 35 | +- **Code Indexing**: Tree-sitter based code analysis and indexing system |
| 36 | +- **Terminal Integration**: Advanced terminal process management with shell integration |
| 37 | +- **I18n Support**: Full internationalization with 20+ language locales |
| 38 | + |
| 39 | +## Development Commands |
| 40 | + |
| 41 | +### Package Management |
| 42 | +```bash |
| 43 | +# Install all dependencies and bootstrap workspace |
| 44 | +pnpm install |
| 45 | + |
| 46 | +# Clean all build artifacts |
| 47 | +pnpm clean |
| 48 | +``` |
| 49 | + |
| 50 | +### Development & Testing |
| 51 | +```bash |
| 52 | +# Run extension in development mode (F5 in VSCode) |
| 53 | +# Builds and opens new VSCode instance with extension loaded |
| 54 | + |
| 55 | +# Lint all code |
| 56 | +pnpm lint |
| 57 | + |
| 58 | +# Type checking |
| 59 | +pnpm check-types |
| 60 | + |
| 61 | +# Run tests |
| 62 | +pnpm test |
| 63 | + |
| 64 | +# Format code |
| 65 | +pnpm format |
| 66 | +``` |
| 67 | + |
| 68 | +### Building & Distribution |
| 69 | +```bash |
| 70 | +# Build extension |
| 71 | +pnpm build |
| 72 | + |
| 73 | +# Create VSIX package for manual installation |
| 74 | +pnpm vsix |
| 75 | + |
| 76 | +# Build and install VSIX directly to VSCode |
| 77 | +pnpm install:vsix [options] |
| 78 | +# Options: -y (skip confirmations), --editor=<command> (code/cursor/code-insiders) |
| 79 | + |
| 80 | +# Nightly builds |
| 81 | +pnpm bundle:nightly |
| 82 | +pnpm vsix:nightly |
| 83 | +``` |
| 84 | + |
| 85 | +### Package-Specific Operations |
| 86 | +```bash |
| 87 | +# Build types package |
| 88 | +pnpm --filter @roo-code/types build |
| 89 | + |
| 90 | +# Watch types package during development |
| 91 | +pnpm --filter @roo-code/types build:watch |
| 92 | + |
| 93 | +# Publish types to npm |
| 94 | +pnpm npm:publish:types |
| 95 | +``` |
| 96 | + |
| 97 | +## Development Workflow |
| 98 | + |
| 99 | +### Testing Individual Components |
| 100 | +- Use VSCode's built-in debugging (F5) for extension development |
| 101 | +- Extension hot-reloads automatically for most changes |
| 102 | +- Webview changes appear immediately in debug instance |
| 103 | +- Use `pnpm test` for unit tests, `pnpm lint` for code quality |
| 104 | + |
| 105 | +### Adding New AI Providers |
| 106 | +1. Create provider in `src/api/providers/` extending `BaseProvider` or `BaseOpenAICompatibleProvider` |
| 107 | +2. Add provider to `src/api/providers/index.ts` |
| 108 | +3. Add types to `packages/types/src/providers/` |
| 109 | +4. Create React component in `webview-ui/src/components/settings/providers/` |
| 110 | +5. Add to webview provider index and constants |
| 111 | + |
| 112 | +### Adding New Tools |
| 113 | +1. Define tool in `src/core/prompts/tools/` following existing patterns |
| 114 | +2. Implement tool execution logic |
| 115 | +3. Add to tools registry in prompt sections |
| 116 | +4. Test tool functionality through extension |
| 117 | + |
| 118 | +### MCP Server Integration |
| 119 | +- MCP servers managed through `McpServerManager` in `src/services/mcp/` |
| 120 | +- Configuration through extension settings |
| 121 | +- Tools auto-discovered and made available to AI models |
| 122 | + |
| 123 | +## Important Notes |
| 124 | + |
| 125 | +- **Node Version**: Requires Node.js 20.19.2 |
| 126 | +- **Package Manager**: Uses pnpm 10.8.1 (enforced by only-allow) |
| 127 | +- **Build System**: Turbo for workspace orchestration |
| 128 | +- **Testing**: Vitest for unit tests, extension testing through VSCode debugger |
| 129 | +- **Code Quality**: ESLint + Prettier, pre-commit hooks via Husky |
| 130 | +- **Type Safety**: Strict TypeScript with shared types package |
| 131 | + |
| 132 | +### Git Workflow |
| 133 | +- Main development branch: `1696` |
| 134 | +- Uses changesets for version management |
| 135 | +- Pre-commit hooks run lint-staged for code formatting |
| 136 | + |
| 137 | +### Environment Configuration |
| 138 | +- Environment variables loaded from `.env` in project root |
| 139 | +- Handles environment loading gracefully for development |
0 commit comments