Rakit UI AI

--- description: "Complete Cursor 2.2 native tools reference: search, edit, run, and advanced features for agentic workflows" alwaysApply: true --- # Cursor 2.2 Tools Mastery Complete reference for all Cursor IDE tools. Use these tools effectively to accomplish tasks efficiently. ## CRITICAL: Agentic-First Tool Usage ### The Golden Rule: Verify Before You Act Every action follows this pattern: 1. **CHECK** - What exists? What's the current state? 2. **VERIFY** - What versions? What's available? 3. **ACT** - Make the change using proper tools 4. **VALIDATE** - Did it work? Any errors? ### Pre-Action Verification Protocol Before ANY significant action: ``` BEFORE CREATING PROJECT: 1. Check if CLI tool exists: run_terminal_cmd("which flutter") 2. Check CLI version: run_terminal_cmd("flutter --version") 3. Web search for current version: web_search("Flutter stable December 2024") 4. Check if project already exists: list_dir("./") BEFORE INSTALLING PACKAGES: 1. Check package.json/pubspec.yaml exists: read_file("package.json") 2. Check if already installed: read_file("package-lock.json") 3. Verify package name/version: web_search("lodash npm latest version") BEFORE EDITING CODE: 1. Read the file first: read_file("src/component.tsx") 2. Understand context and dependencies 3. Check for related files that might need updating ``` ### Proactive Web Search Usage **ALWAYS use web_search for:** - Package versions before installing - Framework syntax when unsure - Error messages you encounter - API documentation verification - Current best practices **Search Pattern:** ``` web_search("[package/framework] [specific feature] [current year/month]") ``` Examples: - `web_search("Next.js 15 App Router server actions December 2024")` - `web_search("React 19 useFormStatus hook syntax")` - `web_search("shadcn ui button component installation")` --- ## Search Tools ### `read_file` **Purpose**: Read file contents with line numbers **When to Use**: - Examining specific files - Understanding code structure - Reviewing implementations - Checking configurations **Best Practices**: - Read whole files unless very large (>1000 lines) - Use `offset` and `limit` for large files - Batch multiple file reads in parallel - Check imports and dependencies **Example Usage**: ``` Read the main entry point to understand the application structure → read_file("src/index.ts") ``` --- ### `list_dir` **Purpose**: List directory contents **When to Use**: - Exploring project structure - Finding files in a directory - Understanding folder organization - Discovering available modules **Best Practices**: - Start at project root for orientation - Use `ignore_globs` to filter noise (node_modules, etc.) - Navigate progressively deeper **Example Usage**: ``` Explore the project structure → list_dir(".", ignore_globs=["node_modules", ".git"]) ``` --- ### `codebase_search` **Purpose**: Semantic search - finds code by meaning, not exact text **When to Use**: - Finding implementations by concept - Locating where behavior is defined - Understanding how features work - Exploring unfamiliar codebases **When NOT to Use**: - Exact text matches (use `grep`) - Simple symbol lookups (use `grep`) - Finding files by name (use `glob_file_search`) **Best Practices**: - Ask complete questions: "Where is user authentication handled?" - One question per search (don't combine multiple queries) - Start broad, then narrow to specific directories - Use for "how/where/what" questions **Example Usage**: ``` Find where API routes are defined → codebase_search("Where are the API routes defined?", target_directories=["src/"]) ``` --- ### `grep` **Purpose**: Regex-based text search (powered by ripgrep) **When to Use**: - Exact symbol/string searches - Finding function calls - Locating imports/exports - Counting occurrences **Parameters**: - `pattern`: Regex pattern to search - `path`: Directory or file to search - `type`: File type filter (js, py, rs, go, etc.) - `glob`: Custom glob pattern - `-C`, `-A`, `-B`: Context lines - `output_mode`: "content", "files_with_matches", or "count" **Best Practices**: - Escape special regex characters: `functionCall\(` - Use `output_mode: "files_with_matches"` to find all relevant files - Add context with `-C 3` to understand surrounding code **Example Usage**: ``` Find all uses of a specific function → grep("useAuth\\(", path="src/", type="ts") Find files containing a pattern → grep("TODO:", output_mode="files_with_matches") ``` --- ### `glob_file_search` **Purpose**: Find files by name pattern **When to Use**: - Locating files by extension - Finding configuration files - Discovering test files - Matching naming conventions **Best Practices**: - Patterns auto-prepend `**/` for recursive search - Use for file discovery, not content search **Example Usage**: ``` Find all test files → glob_file_search("*.test.ts") Find configuration files → glob_file_search("*.config.*") ``` --- ### `web_search` **Purpose**: Search the internet for real-time information **When to Use**: - Current documentation - Recent solutions - Security advisories - Version-specific information **Best Practices**: - Include version numbers if relevant - Add dates for time-sensitive queries - Use specific keywords **Proactive Usage**: Don't wait for "Ask" mode - use `web_search` proactively in Agent mode when: - You need current information about libraries or APIs - Error messages suggest version-specific issues - User asks about recent features or changes --- ## Browser Tools Cursor provides built-in browser tools for testing and interacting with web applications. ### `browser_navigate` **Purpose**: Navigate to a URL **When to Use**: - Testing web application features - Verifying UI implementations - Checking deployed changes ### `browser_snapshot` **Purpose**: Capture accessibility snapshot of current page **When to Use**: - Understanding page structure - Finding elements to interact with - Better than screenshots for element identification **Best Practices**: - Call snapshot BEFORE clicking/typing to get element refs - Use returned refs for subsequent interactions ### `browser_click` **Purpose**: Click on web page elements **Parameters**: - `element`: Human-readable element description - `ref`: Exact target element reference from snapshot - `button`: Button to click (defaults to left) - `doubleClick`: Whether to double-click ### `browser_type` **Purpose**: Type text into editable elements **Parameters**: - `element`: Human-readable element description - `ref`: Exact target element reference from snapshot - `text`: Text to type - `submit`: Whether to press Enter after typing - `slowly`: Type one character at a time (for key handlers) ### `browser_hover` **Purpose**: Hover over elements (for tooltips, dropdowns) ### `browser_select_option` **Purpose**: Select options in dropdowns ### `browser_press_key` **Purpose**: Press keyboard keys (e.g., ArrowLeft, Enter, Escape) ### `browser_wait_for` **Purpose**: Wait for conditions **Parameters**: - `text`: Wait for text to appear - `textGone`: Wait for text to disappear - `time`: Wait for specified seconds ### `browser_navigate_back` **Purpose**: Go back to previous page ### `browser_resize` **Purpose**: Resize browser window for responsive testing ### `browser_console_messages` **Purpose**: Get all console messages (errors, warnings, logs) **When to Use**: - Debugging JavaScript errors - Checking for runtime issues - Verifying console output ### `browser_network_requests` **Purpose**: Get all network requests since page load **When to Use**: - Debugging API calls - Verifying request/response data - Checking for failed requests ### Browser Testing Workflow ``` 1. Navigate to the page → browser_navigate(url="http://localhost:3000") 2. Snapshot to get elements → browser_snapshot() 3. Interact using refs from snapshot → browser_click(element="Submit button", ref="btn-submit") 4. Wait for changes if needed → browser_wait_for(text="Success") 5. Snapshot again to verify → browser_snapshot() 6. Check console/network for issues → browser_console_messages() → browser_network_requests() ``` ### Proactive Browser Usage Don't wait for explicit requests - use browser tools proactively when: - You've implemented a UI feature → test it immediately - User reports a visual bug → navigate and inspect - You need to verify API integrations → check network requests - You're debugging frontend issues → check console messages --- ## Edit Tools ### `search_replace` **Purpose**: Exact string replacement in files **When to Use**: - Modifying existing code - Updating function implementations - Fixing bugs in specific locations - Renaming with `replace_all: true` **CRITICAL Rules**: - `old_string` must be UNIQUE in the file - Include enough context (3-5 lines before/after) - Match exact whitespace and indentation - Preserve original indentation style **Best Practices**: - Read the file first to ensure accurate matching - Include surrounding context for uniqueness - Use `replace_all: true` for renaming operations - Make atomic, focused changes **Example Usage**: ``` Update a function implementation → search_replace( file_path="src/utils.ts", old_string="function oldImpl() {\n return 1;\n}", new_string="function oldImpl() {\n return 2;\n}" ) ``` --- ### `write` **Purpose**: Create or overwrite entire files **When to Use**: - Creating new files - Complete file rewrites - Generating new modules - Writing configuration files **Best Practices**: - ALWAYS read existing files before overwriting - Prefer `search_replace` for modifications - Include all necessary imports - Follow project conventions --- ### `delete_file` **Purpose**: Remove files from the project **When to Use**: - Cleanup during refactoring - Removing deprecated code - Deleting generated files --- ### `edit_notebook` **Purpose**: Edit Jupyter notebook cells **When to Use**: - Data science notebooks - Interactive Python development - Documentation notebooks **Best Practices**: - Set `is_new_cell` correctly - Use 0-based cell indices - Provide unique `old_string` for edits --- ## Run Tools ### `run_terminal_cmd` **Purpose**: Execute shell commands **When to Use**: - Building projects - Running tests - Installing dependencies - Executing scripts - Git operations (with `git_write` permission) **Permissions**: - `network`: For package installs, API calls, servers - `git_write`: For commits, checkouts, git modifications - `all`: Full system access (use sparingly) **Best Practices**: - Use `is_background: true` for long-running processes - Check existing terminals before starting servers - Use non-interactive flags (`--yes`, `-y`, etc.) - Request only necessary permissions **Example Usage**: ``` Install dependencies → run_terminal_cmd("npm install", required_permissions=["network"]) Run tests → run_terminal_cmd("npm test") Start dev server in background → run_terminal_cmd("npm run dev", is_background=true, required_permissions=["network"]) ``` --- ### `read_lints` **Purpose**: Read linter errors from workspace **When to Use**: - After making edits - Before committing changes - Debugging type errors - Checking code quality **Best Practices**: - Only call on files you've edited - Fix errors before proceeding - Don't call with wide scope --- ## MCP Tools ### `call_mcp_tool` **Purpose**: Invoke MCP server tools **When to Use**: - External service integration - Specialized functionality - MiniMax tools (web_search, understand_image) **CRITICAL**: Always check tool schema before calling --- ## Tool Selection Decision Tree ``` Need to find code? ├─ By meaning/concept → codebase_search ├─ Exact text/symbol → grep └─ By filename → glob_file_search Need to read? ├─ File contents → read_file ├─ Directory structure → list_dir └─ Linter errors → read_lints Need to edit? ├─ Modify existing → search_replace ├─ Create new file → write ├─ Remove file → delete_file └─ Jupyter notebook → edit_notebook Need to execute? ├─ Shell command → run_terminal_cmd └─ MCP tool → call_mcp_tool Need external info? ├─ Real-time data → web_search (Cursor native) ├─ MiniMax search → call_mcp_tool (MiniMax web_search) └─ Image analysis → call_mcp_tool (MiniMax understand_image) Need to test web UI? ├─ Navigate to page → browser_navigate ├─ Get page structure → browser_snapshot ├─ Interact with elements → browser_click / browser_type ├─ Check for errors → browser_console_messages └─ Debug API calls → browser_network_requests ``` ## Parallel vs Sequential Tool Calls ### Use Parallel Calls When: - Reading multiple independent files - Searching different directories - Making independent edits - Gathering unrelated information ### Use Sequential Calls When: - Results inform next parameters - Order matters (create before edit) - Dependencies between operations - Validation needed before proceeding ### Example Parallel Pattern: ``` Reading multiple files simultaneously: → read_file("src/index.ts") → read_file("src/config.ts") → read_file("package.json") [All called in single batch] ``` ## Cursor 2.2 Advanced Features ### Debug Mode - Instruments apps with runtime logs - Helps reproduce complex bugs - Works across stacks and languages ### Browser Layout Editor - Real-time CSS/layout editing - Component tree visualization - Integrated with codebase ### Plan Mode + Mermaid - Visual planning with diagrams - Send to-dos to new agents - Structured task management ### Multi-Agent Judging - Run parallel agents - Best solution selection - Automated comparison ### Pinned Chats - Quick access to important threads - Persistent conversation references --- ## CRITICAL: What NEVER To Do ### Never Manually Create These Files These files are generated by CLIs and should NEVER be created manually: | File Type | Use CLI Instead | |-----------|----------------| | `package.json` | `npm init` or `pnpm init` | | `package-lock.json` | Generated by `npm install` | | `go.mod` | `go mod init` | | `Cargo.toml` | `cargo new` or `cargo init` | | `pubspec.yaml` | `flutter create` | | `*.xcodeproj/*` | Xcode or `swift package init` | | `project.pbxproj` | **NEVER TOUCH** - Xcode only | | `.csproj` | `dotnet new` | | `pom.xml` | `mvn archetype:generate` | ### Never Skip These Steps ``` ❌ DON'T: Create project files manually ✅ DO: Use framework CLI (npx create-next-app, flutter create, cargo new) ❌ DON'T: Assume packages are installed ✅ DO: Run npm install / flutter pub get / cargo build after setup ❌ DON'T: Guess CLI availability ✅ DO: Check with --version first ❌ DON'T: Write code without reading existing files ✅ DO: Always read_file before editing ❌ DON'T: Skip dependency installation ✅ DO: npm install, pip install, cargo build after adding deps ❌ DON'T: Forget post-edit verification ✅ DO: Run linters, tests, builds after changes ``` ### Always Verify After Actions ```bash # After creating web project npm install && npm run dev # Verify it starts # After adding shadcn component npx shadcn@latest add button # Use CLI, don't copy files! # After Flutter changes flutter pub get && flutter analyze # After Rust changes cargo check && cargo clippy # After Go changes go build ./... && go vet ./... # After Python changes pip install -e . && pytest ```