Cursor rule

1---
2description: Global Rule. This rule should ALWAYS be loaded
3globs: *,**/*
4alwaysApply: true
5---
6vibe-tools is a CLI tool that allows you to interact with AI models and other tools.
7vibe-tools is installed on this machine and it is available to you to execute. You're encouraged to use it.
8 
9<vibe-tools Integration>
10# Instructions
11Use the following commands to get AI assistance:
12 
13**Direct Model Queries:**
14`vibe-tools ask "<your question>" --provider <provider> --model <model>` - Ask any model from any provider a direct question (e.g., `vibe-tools ask "What is the capital of France?" --provider openai --model o3-mini`). Note that this command is generally less useful than other commands like `repo` or `plan` because it does not include any context from your codebase or repository. In general you should not use the ask command because it does not include any context. The other commands like `web`, `doc`, `repo`, or `plan` are usually better. If you are using it, make sure to include in your question all the information and context that the model might need to answer usefully.
15 
16**Ask Command Options:**
17--provider=<provider>: AI provider to use (openai, anthropic, perplexity, gemini, modelbox, openrouter, xai, or groq)
18--model=<model>: Model to use (required for the ask command)
19--reasoning-effort=<low|medium|high>: Control the depth of reasoning for supported models (OpenAI o1/o3 models, Claude 4 Sonnet, and XAI Grok models). Higher values produce more thorough responses for complex questions.
20--with-doc=<doc_url>: Fetch content from one or more document URLs and include it as context. Can be specified multiple times (e.g., `--with-doc=<url1> --with-doc=<url2>`).
21 
22**Implementation Planning:**
23`vibe-tools plan "<query>"` - Generate a focused implementation plan using AI (e.g., `vibe-tools plan "Add user authentication to the login page"`)
24The plan command uses multiple AI models to:
251. Identify relevant files in your codebase (using Gemini by default)
262. Extract content from those files
273. Generate a detailed implementation plan (using OpenAI o3 by default)
28 
29**Plan Command Options:**
30--fileProvider=<provider>: Provider for file identification (gemini, openai, anthropic, perplexity, modelbox, openrouter, xai, or groq)
31--thinkingProvider=<provider>: Provider for plan generation (gemini, openai, anthropic, perplexity, modelbox, openrouter, xai, or groq)
32--fileModel=<model>: Model to use for file identification
33--thinkingModel=<model>: Model to use for plan generation
34--with-doc=<doc_url>: Fetch content from one or more document URLs and include it as context for both file identification and planning. Can be specified multiple times (e.g., `--with-doc=<url1> --with-doc=<url2>`).
35 
36**Web Search:**
37`vibe-tools web "<your question>"` - Get answers from the web using a provider that supports web search (e.g., Perplexity models, Gemini Models, and XAI Grok models either directly or from OpenRouter or ModelBox) (e.g., `vibe-tools web "latest shadcn/ui installation instructions"`)
38Note: web is a smart autonomous agent with access to the internet and an extensive up to date knowledge base. Web is NOT a web search engine. Always ask the agent for what you want using a proper sentence, do not just send it a list of keywords. In your question to web include the context and the goal that you're trying to acheive so that it can help you most effectively.
39when using web for complex queries suggest writing the output to a file somewhere like local-research/<query summary>.md.
40 
41**IMPORTANT: Do NOT use the `web` command for specific URLs.** If a user provides a specific URL (documentation link, GitHub repo, article, etc.), you should always use commands that support the `--with-doc` parameter instead, such as `repo`, `plan`, `doc`, or `ask`. Using `--with-doc` ensures the exact content of the URL is processed correctly and completely.
42 
43**Web Command Options:**
44--provider=<provider>: AI provider to use (perplexity, gemini, modelbox, openrouter, xai, or groq)
45 
46**Repository Context:**
47`vibe-tools repo "<your question>" [--subdir=<path>] [--from-github=<username/repo>] [--with-doc=<doc_url>...]` - Get context-aware answers about this repository using Google Gemini (e.g., `vibe-tools repo "explain authentication flow"`)
48Use the optional `--subdir` parameter to analyze a specific subdirectory instead of the entire repository (e.g., `vibe-tools repo "explain the code structure" --subdir=src/components`). Use the optional `--from-github` parameter to analyze a remote GitHub repository without cloning it locally (e.g., `vibe-tools repo "explain the authentication system" --from-github=username/repo-name`). Use the optional `--with-doc` parameter multiple times to include content from several URLs as additional context (e.g., `vibe-tools repo "summarize findings" --with-doc=https://example.com/spec1 --with-doc=https://example.com/spec2`).
49 
50**Documentation Generation:**
51`vibe-tools doc [options] [--with-doc=<doc_url>...]` - Generate comprehensive documentation for this repository (e.g., `vibe-tools doc --output docs.md`). Can incorporate document context from multiple URLs (e.g., `vibe-tools doc --with-doc=https://example.com/existing-docs --with-doc=https://example.com/new-spec`).
52 
53**YouTube Video Analysis:**
54`vibe-tools youtube "<youtube-url>" [question] [--type=<summary|transcript|plan|review|custom>]` - Analyze YouTube videos and generate detailed reports (e.g., `vibe-tools youtube "https://youtu.be/43c-Sm5GMbc" --type=summary`)
55Note: The YouTube command requires a `GEMINI_API_KEY` to be set in your environment or .vibe-tools.env file as the GEMINI API is the only interface that supports YouTube analysis.
56 
57**GitHub Information:**
58`vibe-tools github pr [number]` - Get the last 10 PRs, or a specific PR by number (e.g., `vibe-tools github pr 123`)
59`vibe-tools github issue [number]` - Get the last 10 issues, or a specific issue by number (e.g., `vibe-tools github issue 456`)
60 
61**ClickUp Information:**
62`vibe-tools clickup task <task_id>` - Get detailed information about a ClickUp task including description, comments, status, assignees, and metadata (e.g., `vibe-tools clickup task "task_id"`)
63 
64**Wait Command:**
65`vibe-tools wait <seconds>` - Pauses execution for the specified number of seconds (e.g., `vibe-tools wait 5` to wait for 5 seconds).
66 
67**Model Context Protocol (MCP) Commands:**
68Use the following commands to interact with MCP servers and their specialized tools:
69`vibe-tools mcp search "<query>"` - Search the MCP Marketplace and GitHub for available servers that match your needs (e.g., `vibe-tools mcp search "git repository management"`)
70`vibe-tools mcp run "<query>"` - Execute MCP server tools using natural language queries (e.g., `vibe-tools mcp run "list files in the current directory" --provider=openrouter`). The query must include sufficient information for vibe-tools to determine which server to use, provide plenty of context.
71 
72The `search` command helps you discover servers in the MCP Marketplace and on GitHub based on their capabilities and your requirements. The `run` command automatically selects and executes appropriate tools from these servers based on your natural language queries. If you want to use a specific server include the server name in your query. E.g. `vibe-tools mcp run "using the mcp-server-sqlite list files in directory --provider=openrouter"`
73 
74**Notes on MCP Commands:**
75- MCP commands require `ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY` to be set in your environment
76- By default the `mcp` command uses Anthropic, but takes a --provider argument that can be set to 'anthropic' or 'openrouter'
77- Results are streamed in real-time for immediate feedback
78- Tool calls are automatically cached to prevent redundant operations
79- Often the MCP server will not be able to run because environment variables are not set. If this happens ask the user to add the missing environment variables to the cursor tools env file at ~/.vibe-tools/.env
80 
81**Stagehand Browser Automation:**
82`vibe-tools browser open <url> [options]` - Open a URL and capture page content, console logs, and network activity (e.g., `vibe-tools browser open "https://example.com" --html`)
83`vibe-tools browser act "<instruction>" --url=<url | 'current'> [options]` - Execute actions on a webpage using natural language instructions (e.g., `vibe-tools browser act "Click Login" --url=https://example.com`)
84`vibe-tools browser observe "<instruction>" --url=<url> [options]` - Observe interactive elements on a webpage and suggest possible actions (e.g., `vibe-tools browser observe "interactive elements" --url=https://example.com`)
85`vibe-tools browser extract "<instruction>" --url=<url> [options]` - Extract data from a webpage based on natural language instructions (e.g., `vibe-tools browser extract "product names" --url=https://example.com/products`)
86`vibe-tools browser mac-chrome [options]` - Start a Chrome instance with remote debugging (macOS only) (e.g., `vibe-tools browser mac-chrome --debug`, `vibe-tools browser mac-chrome --lite`)
87 
88**Notes on Browser Commands:**
89- All browser commands are stateless unless --connect-to is used to connect to a long-lived interactive session. In disconnected mode each command starts with a fresh browser instance and closes it when done.
90- If you want to start a new long-lived session 
91- When using `--connect-to`, special URL values are supported:
92  - `current`: Use the existing page without reloading
93  - `reload-current`: Use the existing page and refresh it (useful in development)
94  - If working interactively with a user you should always use --url=current unless you specifically want to navigate to a different page. Setting the url to anything else will cause a page refresh loosing current state.
95- Multi step workflows involving state or combining multiple actions are supported in the `act` command using the pipe (|) separator (e.g., `vibe-tools browser act "Click Login | Type 'user@example.com' into email | Click Submit" --url=https://example.com`)
96- Video recording is available for all browser commands using the `--video=<directory>` option. This will save a video of the entire browser interaction at 1280x720 resolution. The video file will be saved in the specified directory with a timestamp.
97- DO NOT ask browser act to "wait" for anything, the wait command is currently disabled in Stagehand.
98 
99**Tool Recommendations:**
100- `vibe-tools web` is best for general web information not specific to the repository. Generally call this without additional arguments. Ask natural language questions when using this tool like "Describe OpenAI's Responses REST API for me, including examples of different request and response payloads" DO NOT use search keyword style queries like "OpenAI Responses REST API".
101- `vibe-tools repo` is ideal for repository-specific questions, planning, code review and debugging. E.g. `vibe-tools repo "Review recent changes to command error handling looking for mistakes, omissions and improvements"`. Generally call this without additional arguments.
102- `vibe-tools plan` is ideal for planning tasks. E.g. `vibe-tools plan "Adding authentication with social login using Google and Github"`. Generally call this without additional arguments.
103- `vibe-tools doc` generates documentation for local or remote repositories.
104- `vibe-tools youtube` analyzes YouTube videos to generate summaries, transcripts, implementation plans, or custom analyses
105- `vibe-tools browser` is useful for testing and debugging web apps and uses Stagehand
106- `vibe-tools mcp` enables interaction with specialized tools through MCP servers (e.g., for Git operations, file system tasks, or custom tools)
107- **URLS:** For any specific URL (documentation, article, reference, spec, GitHub repo, etc.), ALWAYS use a command with the `--with-doc=<url>` parameter rather than the `web` command. Examples: `vibe-tools repo "How should I implement this feature based on the spec?" --with-doc=https://example.com/spec.pdf` or `vibe-tools ask "What does this document say about authentication?" --with-doc=https://example.com/auth-doc.html`
108- When implementing features based on documentation, specifications, or any external content, always use the `--with-doc=<url>` flag instead of built-in web search. For example: `vibe-tools plan "Implement login page according to specs" --with-doc=https://example.com/specs.pdf` or `vibe-tools repo "How should I implement this feature?" --with-doc=https://example.com/feature-spec.md`.
109- When a user provides a specific URL for documentation or reference material, always use the `--with-doc=<url>` flag with that URL rather than attempting to search for or summarize the content independently. This ensures the exact document is used as context.
110 
111**Running Commands:**
1121. Use `vibe-tools <command>` to execute commands (make sure vibe-tools is installed globally using npm install -g vibe-tools so that it is in your PATH)
113 
114**General Command Options (Supported by all commands):**
115--provider=<provider>: AI provider to use (openai, anthropic, perplexity, gemini, openrouter, modelbox, xai, or groq). If provider is not specified, the default provider for that task will be used.
116--model=<model name>: Specify an alternative AI model to use. If model is not specified, the provider's default model for that task will be used.
117--max-tokens=<number>: Control response length
118--save-to=<file path>: Save command output to a file (in *addition* to displaying it)
119--debug: Show detailed logs and error information
120--web: Enable web search capabilities for supported models (Gemini models, XAI Grok models, Perplexity models, and ModelBox models) across all commands
121 
122**Repository Command Options:**
123--provider=<provider>: AI provider to use (gemini, openai, openrouter, perplexity, modelbox, anthropic, xai, or groq)
124--model=<model>: Model to use for repository analysis
125--max-tokens=<number>: Maximum tokens for response
126--from-github=<GitHub username>/<repository name>[@<branch>]: Analyze a remote GitHub repository without cloning it locally
127--subdir=<path>: Analyze a specific subdirectory instead of the entire repository
128--with-doc=<doc_url>: Fetch content from one or more document URLs and include it as context. Can be specified multiple times.
129 
130**Documentation Command Options:**
131--from-github=<GitHub username>/<repository name>[@<branch>]: Generate documentation for a remote GitHub repository
132--provider=<provider>: AI provider to use (gemini, openai, openrouter, perplexity, modelbox, anthropic, xai, or groq)
133--model=<model>: Model to use for documentation generation
134--max-tokens=<number>: Maximum tokens for response
135--with-doc=<doc_url>: Fetch content from one or more document URLs and include it as context. Can be specified multiple times.
136 
137**YouTube Command Options:**
138--type=<summary|transcript|plan|review|custom>: Type of analysis to perform (default: summary)
139 
140**GitHub Command Options:**
141--from-github=<GitHub username>/<repository name>[@<branch>]: Access PRs/issues from a specific GitHub repository
142 
143**Browser Command Options (for 'open', 'act', 'observe', 'extract'):**
144--console: Capture browser console logs (enabled by default, use --no-console to disable)
145--html: Capture page HTML content (disabled by default)
146--network: Capture network activity (enabled by default, use --no-network to disable)
147--screenshot=<file path>: Save a screenshot of the page
148--timeout=<milliseconds>: Set navigation timeout (default: 120000ms for Stagehand operations, 30000ms for navigation)
149--viewport=<width>x<height>: Set viewport size (e.g., 1280x720). When using --connect-to, viewport is only changed if this option is explicitly provided
150--headless: Run browser in headless mode (default: true)
151--no-headless: Show browser UI (non-headless mode) for debugging
152--connect-to=<port>: Connect to existing Chrome instance. Special values: 'current' (use existing page), 'reload-current' (refresh existing page)
153--wait=<time:duration or selector:css-selector>: Wait after page load (e.g., 'time:5s', 'selector:#element-id')
154--video=<directory>: Save a video recording (1280x720 resolution, timestamped subdirectory). Not available when using --connect-to
155--url=<url>: Required for `act`, `observe`, and `extract` commands. Url to navigate to before the main command or one of the special values 'current' (to stay on the current page without navigating or reloading) or 'reload-current' (to reload the current page)
156--evaluate=<string>: JavaScript code to execute in the browser before the main command
157 
158**Nicknames**
159Users can ask for these tools using nicknames
160Gemini is a nickname for vibe-tools repo
161Perplexity is a nickname for vibe-tools web
162Stagehand is a nickname for vibe-tools browser
163Grok (with a k) is a nickname for the xAI Grok model. If asked to use Grok, use the `--provider=xai` flag.
164If people say "ask Gemini" or "ask Perplexity" or "ask Stagehand" they mean to use the `vibe-tools` command with the `repo`, `web`, or `browser` commands respectively.
165 
166**Xcode Commands:**
167`vibe-tools xcode build [buildPath=<path>] [destination=<destination>]` - Build Xcode project and report errors.
168**Build Command Options:**
169--buildPath=<path>: (Optional) Specifies a custom directory for derived build data. Defaults to ./.build/DerivedData.
170--destination=<destination>: (Optional) Specifies the destination for building the app (e.g., 'platform=iOS Simulator,name=iPhone 16 Pro'). Defaults to 'platform=iOS Simulator,name=iPhone 16 Pro'.
171 
172`vibe-tools xcode run [destination=<destination>]` - Build and run the Xcode project on a simulator.
173**Run Command Options:**
174--destination=<destination>: (Optional) Specifies the destination simulator (e.g., 'platform=iOS Simulator,name=iPhone 16 Pro'). Defaults to 'platform=iOS Simulator,name=iPhone 16 Pro'.
175 
176`vibe-tools xcode lint` - Run static analysis on the Xcode project to find and fix issues.
177 
178**Additional Notes:**
179- For detailed information, see `node_modules/vibe-tools/README.md` (if installed locally).
180- Configuration is in `vibe-tools.config.json` (or `~/.vibe-tools/config.json`).
181- API keys are loaded from `.vibe-tools.env` (or `~/.vibe-tools/.env`).
182- ClickUp commands require a `CLICKUP_API_TOKEN` to be set in your `.vibe-tools.env` file.
183- Available models depend on your configured provider (OpenAI, Anthropic, xAI, Groq, etc.) in `vibe-tools.config.json`.
184- repo has a limit of 2M tokens of context. The context can be reduced by filtering out files in a .repomixignore file.
185- problems running browser commands may be because playwright is not installed. Recommend installing playwright globally.
186- MCP commands require `ANTHROPIC_API_KEY` or `OPENROUTER_API_KEY`
187- **Remember:** You're part of a team of superhuman expert AIs. Work together to solve complex problems.
188- **Repomix Configuration:** You can customize which files are included/excluded during repository analysis by creating a `repomix.config.json` file in your project root. This file will be automatically detected by `repo`, `plan`, and `doc` commands.
189 
190**Authentication and API Keys**: vibe-tools automatically loads API keys from ~/.vibe-tools/.env files, environment variables, and Doppler secrets when running in a folder that has a doppler project configured. Disable Doppler loading by adding `"disableDoppler": true` to `vibe-tools.config.json`. 
191 
192<!-- vibe-tools-version: 0.63.1 -->
193</vibe-tools Integration>