Give Cursor Agent an AI team and advanced skills

Table of Contents

- The AI Team
- New Skills
- How to Use
- Example: Using Perplexity
- Example: Using Gemini
- What is cursor-tools
- Installation
- Requirements
- Tips
- Additional Examples
- GitHub Skills
- Gemini Code Review
- Detailed Cursor Usage
- Tool Recommendations
- Command Nicknames
- Web Search
- Repository Search
- Documentation Generation
- GitHub Integration
- Browser Automation
- Browser Agent
- Direct Model Queries
- Authentication and API Keys
- AI Team Features
- Perplexity: Web Search & Research
- Gemini 2.0: Repository Context & Planning
- Stagehand: Browser Automation
- Browser Command Options
- Video Recording
- Browser Agent
- Console and Network Logging
- Complex Actions
- Troubleshooting Browser Commands
- Skills
- GitHub Integration
- Xcode Tools
- Documentation Generation
- Configuration
- cursor-tools.config.json
- GitHub Authentication
- Repomix Configuration
- Model Selection
- Cursor Configuration
- Cursor Agent Configuration
- cursor-tools cli
- Command Options
- Execution Methods
- Troubleshooting
- Examples
- Web Search Examples
- Repository Context Examples
- Documentation Examples
- GitHub Integration Examples
- Xcode Command Examples
- Browser Command Examples
- open subcommand examples
- act, extract, observe subcommands examples
- Node Package Manager
- Contributing
- Sponsors
- License

$3

- Perplexity to search the web and perform deep research
- Gemini 2.0 for huge whole-codebase context window, search grounding and reasoning
- Stagehand for browser operation to test and debug web apps (uses Anthropic or OpenAI models)
- OpenRouter for access to a variety of models through a unified API (for MCP commands)

$3

- Work with GitHub Issues and Pull Requests
- Generate local agent-accessible documentation for external dependencies
- Autonomous browser interaction with the new browser agent command for complex multi-step tasks

cursor-tools is optimized for Cursor Composer Agent but it can be used by any coding agent that can execute commands

$3

After installation, to see AI teamwork in action just ask Cursor Composer to use Perplexity or Gemini.
Here are two examples:

Asking Perplexity to carry out web research

see what happens next...

see what happens next...

see what happens next...

see the spec composer and perplexity produced together:
pac-man-spec.md (link out to the example repo)

Asking Gemini for a plan

see what happens next...

see what happens next...

see what happens next...

see the spec composer and perplexity produced together:
pac-man-plan.md (link out to the example repo)

What is cursor-tools

cursor-tools provides a CLI that your AI agent can use to expand its capabilities. cursor-tools is designed to be installed globally, providing system-wide access to its powerful features. When you run cursor-tools install we automatically add a prompt section to your Cursor project rules. During installation, you can choose between:
- The new .cursor/rules/cursor-tools.mdc file (recommended)
- The legacy .cursorrules file (for backward compatibility)

You can also control this using the USE_LEGACY_CURSORRULES environment variable:
- USE_LEGACY_CURSORRULES=true - Use legacy .cursorrules file
- USE_LEGACY_CURSORRULES=false - Use new .cursor/rules/cursor-tools.mdc file
- If not set, defaults to legacy mode for backward compatibility

cursor-tools requires a Perplexity API key and a Google AI API key.

cursor-tools is a node package that should be installed globally.

Installation

Install cursor-tools globally:
``bash
npm install -g cursor-tools
`

Then run the interactive setup:
`bash
cursor-tools install .
`

This command will:
1. Guide you through API key configuration
2. Update your Cursor project rules for Cursor integration (using .cursor/rules/cursor-tools.mdc or existing .cursorrules)

Requirements

- Node.js 18 or later
- Perplexity API key
- Google Gemini API key
- For browser commands:
- Playwright (npm install --global playwright)
- OpenAI API key or Anthropic API key (for act, extract, observe, and agent commands)

cursor-tools uses Gemini-2.0 because it is the only good LLM with a context window that goes up to 2 million tokens - enough to handle and entire codebase in one shot. Gemini 2.0 experimental models that we use by default are currently free to use on Google and you need a Google Cloud project to create an API key.

cursor-tools uses Perplexity because Perplexity has the best web search api and indexes and it does not hallucinate. Perplexity Pro users can get an API key with their pro account and recieve $5/month of free credits (at time of writing). Support for Google search grounding is coming soon but so far testing has shown it still frequently hallucinates things like APIs and libraries that don't exist.

Tips:

- Ask Cursor Agent to have Gemini review its work
- Ask Cursor Agent to generate documentation for external dependencies and write it to a local-docs/ folder

If you do something cool with cursor-tools please let me know on twitter or make a PR to add to this section!

Additional Examples

$3

To see cursor-tools GitHub and Perplexity skills: Check out this example issue that was solved using Cursor agent and cursor-tools

$3

See cursor get approximately 5x more work done per-prompt with Gemini code review:

Detailed Cursor Usage

Use Cursor Composer in agent mode with command execution (not sure what this means, see section below on Cursor Agent configuration). If you have installed the cursor-tools prompt to your .cursorrules (or equivalent) just ask your AI coding agent/assistant to use "cursor-tools" to do things.

$3

-

Note: The ask command requires both --provider and --model parameters to be specified. 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.

Authentication and API Keys

1. Interactive Setup: Run cursor-tools install and follow the prompts
2. Manual Setup: Create ~/.cursor-tools/.env in your home directory or .cursor-tools.env in your project root:
`env
PERPLEXITY_API_KEY="your-perplexity-api-key"
GEMINI_API_KEY="your-gemini-api-key"
OPENAI_API_KEY="your-openai-api-key" # Optional, for Stagehand
ANTHROPIC_API_KEY="your-anthropic-api-key" # Optional, for Stagehand and MCP
OPENROUTER_API_KEY="your-openrouter-api-key" # Optional, for MCP
GITHUB_TOKEN="your-github-token" # Optional, for enhanced GitHub access
`
* At least one of ANTHROPIC_API_KEY and OPENROUTER_API_KEY must be provided to use the mcp commands.

$3

cursor-tools supports multiple authentication methods for accessing the Google Gemini API, providing flexibility for different environments and security requirements. You can choose from the following methods:

1. API Key (Default)
- This is the simplest method and continues to be supported for backward compatibility.
- Set the GEMINI_API_KEY environment variable to your API key string obtained from Google AI Studio.
- Example:
`env
GEMINI_API_KEY="your-api-key-here"
`

2. Service Account JSON Key File
- For enhanced security, especially in production environments, use a service account JSON key file.
- Set the GEMINI_API_KEY environment variable to the path of your downloaded service account JSON key file.
- Example:
`env
GEMINI_API_KEY="./path/to/service-account.json"
`
- This method enables access to the latest Gemini models available through Vertex AI, such as gemini-2.0-flash.

3. Application Default Credentials (ADC) (Recommended for Google Cloud Environments)
- ADC is ideal when running cursor-tools within Google Cloud environments (e.g., Compute Engine, Kubernetes Engine) or for local development using gcloud.
- Set the GEMINI_API_KEY environment variable to adc.
- Example:
`env
GEMINI_API_KEY="adc"
`
- Setup Instructions: First, authenticate locally using gcloud:
`bash
gcloud auth application-default login
`

AI Team Features

$3

`bash


Get context-aware assistance

Plan Command Options:
- --fileProvider=: Provider for file identification (gemini, openai, anthropic, perplexity, modelbox, or openrouter)
- --thinkingProvider=: Provider for plan generation (gemini, openai, anthropic, perplexity, modelbox, or openrouter)
- --fileModel=: Model to use for file identification
- --thinkingModel=: Model to use for plan generation
- --fileMaxTokens=: Maximum tokens for file identification
- --thinkingMaxTokens=: Maximum tokens for plan generation
- --debug: Show detailed error information

Repository context is created using Repomix. See repomix configuration section below for details on how to change repomix behaviour.

Above 1M tokens cursor-tools will always send requests to Gemini 2.0 Pro as it is the only model that supports 1M+ tokens.

The Gemini 2.0 Pro context limit is 2M tokens, you can add filters to .repomixignore if your repomix context is above this limit.

$3

Important: The browser command requires the Playwright package to be installed separately in your project:
`bash
npm install playwright


or

1. open - Open a URL and capture page content:
`bash


Open and capture HTML content, console logs and network activity (enabled by default)

2. act - Execute actions using natural language - Agent tells the browser-use agent what to do:
`bash


Single action

3. observe - Analyze interactive elements:
`bash


Get overview of interactive elements

4. extract - Extract data using natural language:
`bash


Extract specific content

#### Browser Command Options
All browser commands (open, act, observe, extract, agent) support these options:
- --console: Capture browser console logs (enabled by default, use --no-console to disable)
- --html: Capture page HTML content (disabled by default)
- --network: Capture network activity (enabled by default, use --no-network to disable)
- --screenshot=: Save a screenshot of the page
- --timeout=: Set navigation timeout (default: 120000ms for Stagehand operations, 30000ms for navigation)
- --viewport=x: Set viewport size (e.g., 1280x720)
- --headless: Run browser in headless mode (default: true)
- --no-headless: Show browser UI (non-headless mode) for debugging
- --connect-to=: Connect to existing Chrome instance. Special values: 'current' (use existing page), 'reload-current' (refresh existing page)
- --wait=: Wait after page load (e.g., 'time:5s', 'selector:#element-id')
- --video=: Save a video recording (1280x720 resolution, timestamped subdirectory). Not available when using --connect-to
- --url=: Required for act, observe, extract, and agent commands
- --evaluate=: JavaScript code to execute in the browser before the main command

Additional options for the agent subcommand:
- --provider=: AI provider to use (openai, anthropic)
- --model=: Model to use for the agent:
- For OpenAI: computer-use-preview-2025-03-11
- For Anthropic: claude-3-5-sonnet-20240620 or claude-3-7-sonnet-20250219

Notes on Connecting to an existing browser session with --connect-to
- DO NOT ask browser act to "wait" for anything, the wait command is currently disabled in Stagehand.
- When using --connect-to, viewport is only changed if --viewport is explicitly provided
- Video recording is not available when using --connect-to
- Special --connect-to values:
- current: Use the existing page without reloading
- reload-current: Use the existing page and refresh it (useful in development)

#### Video Recording
All browser commands support video recording of the browser interaction in headless mode (not supported with --connect-to):
- Use --video= to enable recording
- Videos are saved at 1280x720 resolution in timestamped subdirectories
- Recording starts when the browser opens and ends when it closes
- Videos are saved as .webm files

Example:
`bash


Record a video of filling out a form

#### Browser Agent
The browser agent subcommand provides autonomous browser operation for complex multi-step tasks:

`bash


Execute an autonomous browser task with a single instruction

#### Console and Network Logging
Console logs and network activity are captured by default:
- Use --no-console to disable console logging
- Use --no-network to disable network logging
- Logs are displayed in the command output

#### Complex Actions
The act command supports chaining multiple actions using the pipe (|) separator:

`bash


Login sequence with console/network logging (enabled by default)

1. Element Not Found Errors
- Use --no-headless to visually debug the page
- Use browser observe to see what elements Stagehand can identify
- Check if the element is in an iframe or shadow DOM
- Ensure the page has fully loaded (try increasing --timeout)

2. Stagehand API Errors
- Verify your OpenAI or Anthropic API key is set correctly
- Check if you have sufficient API credits
- Try switching models using --model

3. Network Errors
- Check your internet connection
- Verify the target website is accessible
- Try increasing the timeout with --timeout
- Check if the site blocks automated access

4. Video Recording Issues
- Ensure the target directory exists and is writable
- Check disk space
- Video recording is not available with --connect-to

5. Performance Issues
- Use --headless mode for better performance (default)
- Reduce the viewport size with --viewport
- Consider using --connect-to for development

Skills

$3

`bash


List recent PRs or issues

Authentication Methods:
The commands support multiple authentication methods:
1. GitHub token via environment variable: GITHUB_TOKEN=your_token_here
2. GitHub CLI integration (if gh is installed and logged in)
3. Git credentials (stored tokens or Basic Auth)

Without authentication:
- Public repositories: Limited to 60 requests per hour
- Private repositories: Not accessible

With authentication:
- Public repositories: 5,000 requests per hour
- Private repositories: Full access (with appropriate token scopes)

$3

`bash


Available subcommands

Build Command Options:
`bash


Specify custom build path (derived data)

Run Command Options:
`bash


Run on iPhone simulator (default)

Here is an example of a typical cursor-tools.config.json file, showing some of the most common configuration options:
`json
{
// Commands
"repo": {
"provider": "openrouter",
"model": "google/gemini-2.0-pro-exp-02-05:free",
},
"doc": {
"provider": "openrouter",
"model": "anthropic/claude-3.7-sonnet",
"maxTokens": 4096
},
"web": {
"provider": "gemini",
"model": "gemini-2.0-pro-exp",
},
"plan": {
"fileProvider": "gemini",
"thinkingProvider": "perplexity",
"thinkingModel": "r1-1776"
},
"browser": {
"headless": false,
},
//...

// Providers
"stagehand": {
"model": "claude-3-7-sonnet-latest", // For Anthropic provider
"provider": "anthropic", // or "openai"
"timeout": 90000
},
"openai": {
"model": "gpt-4o"
},
//...
}
`

For details of all configuration options, see CONFIGURATION.md. This includes details of all the configuration options and how to use them.

$3

1. Environment Variable: Set GITHUB_TOKEN in your environment:
`env
GITHUB_TOKEN=your_token_here
`

2. GitHub CLI: If you have the GitHub CLI (gh) installed and are logged in, cursor-tools will automatically use it to generate tokens with the necessary scopes.

3. Git Credentials: If you have authenticated git with GitHub (via HTTPS), cursor-tools will automatically:
- Use your stored GitHub token if available (credentials starting with ghp_ or gho_)
- Fall back to using Basic Auth with your git credentials

To set up git credentials:
1. Configure git to use HTTPS instead of SSH:
`bash
git config --global url."https://github.com/".insteadOf git@github.com:
`
2. Store your credentials:
`bash
git config --global credential.helper store # Permanent storage
# Or for macOS keychain:
git config --global credential.helper osxkeychain
`
3. The next time you perform a git operation requiring authentication, your credentials will be stored

Authentication Status:
- Without authentication:
- Public repositories: Limited to 60 requests per hour
- Private repositories: Not accessible
- Some features may be restricted

- With authentication (any method):
- Public repositories: 5,000 requests per hour
- Private repositories: Full access (if token has required scopes)

cursor-tools will automatically try these authentication methods in order:
1. GITHUB_TOKEN environment variable
2. GitHub CLI token (if gh is installed and logged in)
3. Git credentials (stored token or Basic Auth)

If no authentication is available, it will fall back to unauthenticated access with rate limits.

$3

When generating documentation, cursor-tools uses Repomix to analyze your repository. By default, it excludes certain files and directories that are typically not relevant for documentation:
- Node modules and package directories (node_modules/, packages/, etc.)
- Build output directories (dist/, build/, etc.)
- Version control directories (.git/)
- Test files and directories (test/, tests/, __tests__/, etc.)
- Configuration files (.env, .config, etc.)
- Log files and temporary files
- Binary files and media files

You can customize the files and folders to exclude by adding a .repomixignore file to your project root.

Example .repomixignore file for a Laravel project:
`
vendor/
public/
database/
storage/
.idea
.env
`

This ensures that the documentation focuses on your actual source code and documentation files.
Support to customize the input files to include is coming soon - open an issue if you run into problems here.

#### Model Selection

The browser commands support different AI models for processing. You can select the model using the --model option:

`bash


Use gpt-4o