## Design (high-level)
#### Channels
**Television**'s design is primarily based on the concept of **Channels**.
Channels are just structs that implement the `OnAir` trait.

As such, channels can virtually be anything that can respond to a user query and return a result under the form of a list of entries. This means channels can be anything from conventional data sources you might want to search through (like files, git repositories, remote filesystems, environment variables etc.) to more exotic implementations that might inclue a REPL, a calculator, a web browser, search through your spotify library, your email, etc.

**Television** provides a set of built-in **Channels** that can be used out of the box (see [Built-in Channels](#built-in-channels)). The list of available channels
will grow over time as new channels are implemented to satisfy different use cases.

#### Transitions
When it makes sense, **Television** allows for transitions between different channels. For example, you might want to
start searching through git repositories, then refine your search to a specific set of files in that shortlist of
repositories and then finally search through the textual content of those files.

This can easily be achieved using transitions.

#### Previewers
Entries returned by different channels can be previewed in a separate pane. This is useful when you want to see the
contents of a file, the value of an environment variable, etc. Because entries returned by different channels may
represent different types of data, **Television** allows for channels to declare the type of previewer that should be
used. Television comes with a set of built-in previewers that can be used out of the box and will grow over time.

docs/design.md


## Terminal Emulators Compatibility
Here is a list of terminal emulators that have currently been tested with `television` and their compatibility status.

| Terminal Emulator | Tested Platforms | Compatibility |
| --- | :---: | :---: |
| Alacritty | macOS, Linux | ✅ |
| Kitty | macOS, Linux | ✅ |
| iTerm2 | macOS | ✅ |
| Ghostty | macOS | ✅ |
| Wezterm | macOS, Linux, Windows | ✅ |
| macOS Terminal | macOS | functional but coloring issues |
| Konsole | Linux | ✅ |
| Terminator | Linux | ✅ |
| Xterm | Linux | ✅ |
| Cmder | Windows | ✖ |
| Foot | Linux | ✅ |
| Rio | macOS, Linux, Windows | ✅ |
| Warp | macOS | ✅ |
| Hyper | macOS | ✅ |

If you're able to test the application with a configuration not yet listed above, feel free to open a PR and add it here 🙏

docs/terminal_emulators.md

The revolution will (not) be televised 📺


---
name: Bug report
about: Create a report to help us improve
title: ''
labels: bug
assignees: ''

---

**Description**
A description of what the bug is.

**Example**
A [minimal reproducible code example](https://stackoverflow.com/help/minimal-reproducible-example) where the bug happens.

**Expected behavior**
A description of what you expected to happen.

**Actual behavior**
A description of what actually happens.

**Environment**
 - OS: [e.g. Windows]
 - Rust version: [e.g. 1.50.0]
 - Project version: [e.g. 0.1.0]
 - [Any other dependency version if needed]

**Additional context**
Any other context about the bug here.


---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: enhancement
assignees: ''

---

**Problem**
A description of what is the problem that can be fixed with the feature you propose.

**Feature**
A description of the feature you propose.

**Examples**
One or more code examples that shows the feature in action.

**Additional context**
Any other context about the feature request here.


# Changelog

All notable changes to this project will be documented in this file.

## [0.6.0-alpha.7] - 2025-02-25

### Added
- Added support for MCP server overrides in the marketplace
  - Implemented hardcoded overrides in `MCP_OVERRIDES` map
  - Added override for google-calendar-mcp to use eastlondoner fork
  - Overrides can specify custom `githubUrl`, `command`, and `args`
  - Preserves environment variables when using overrides
  - Type-safe implementation ensures overrides match the MCPServer interface
  - Overrides take precedence over marketplace data and automatic GitHub repository checks
  - Logs when an override is applied using console.log for transparency
  - Added support for user-configurable overrides in `cursor-tools.config.json`
    - Users can define custom overrides in the `mcp.overrides` section
    - Config overrides take precedence over hardcoded overrides
    - Warns when a config override replaces a hardcoded override

### Changed
- Updated all references to Claude 3.5 Sonnet models to Claude 3.7 Sonnet models throughout the codebase
  - Updated model references in configuration files, documentation, and source code
  - Updated default model settings for Anthropic provider
  - Updated error messages and model suggestions
  - Used `claude-3-7-sonnet` for most use cases and `claude-3-7-sonnet-thinking` for MCP client
- Updated @browserbasehq/stagehand dependency from 1.13.0 to 1.13.1

## [0.6.0-alpha.5] - 2024-03-22

### Changed
- cursor-tools now only recommends global installation
- Updated install command to check for and warn about cursor-tools dependencies in package.json files
  - Checks both dependencies and devDependencies in package.json
  - Provides clear instructions for removing local installations using npm, pnpm, or yarn
  - This is in response to multiple issues caused by local installation and execution under different js runtimes

## [0.6.0-alpha.4] - 2024-03-22

### Changed
- Added validation to require --tag alpha or --tag latest when running release command

## [0.6.0-alpha.3] - 2024-03-22

### Added
- Added ModelBox provider for access to a wider range of models through an OpenAI-compatible API
- Added OpenRouter provider to enable access to models from various providers including Perplexity

### Changed
- Improved browser command state management when using `--connect-to`:
    - Reuses existing browser tabs for subsequent commands in a session, preserving page state
    - Introduced `reload-current` as a special URL value to refresh the current page without losing the connected session

## [0.6.0-alpha.1] - 2024-03-22

### Fixed
- Fixed debug logging in all provider commands to properly pass through the debug flag
  - Fixed `ask` command to pass debug flag to provider
  - Fixed `web` command to properly handle debug flag
  - Fixed `doc` command to include debug flag in options
  - Fixed `plan` command to pass debug flag to both file and thinking providers
  - Standardized debug logging format across all providers
  - Debug logs now show full request and response details when enabled

### Changed
- Changed default thinking provider for plan command to OpenAI with o3-mini model for significantly faster plan generation, while maintaining plan quality
- Browser commands (`open`, `act`, `observe`, `extract`) now have `--console` and `--network` options enabled by default. Use `--no-console` and `--no-network` to disable them.
- Improved page reuse in browser commands when using `--connect-to`: now reuses existing tabs instead of creating new ones for better state preservation
- Improved error handling and type safety in cursor rules management
- Enhanced directory creation order in installation process
- Added user choice during installation for cursor rules location (legacy `.cursorrules` or new `.cursor/rules/cursor-tools.mdc`)
- Added `USE_LEGACY_CURSORRULES` environment variable to control cursor rules file location
- Improved output handling across all commands:
  - Centralized output handling in main CLI
  - Commands now yield output consistently
  - Better error handling for file writes
  - Added timeout protection for stdout writes
  - More reliable output flushing

### Added
- New `ask` command for direct model queries
  - Requires both provider and model parameters
  - Allows querying any model from any provider directly
  - Simple and focused command for direct questions
- Support for new Cursor IDE project rules structure
  - New installations now use `.cursor/rules/cursor-tools.mdc` by default
  - Maintain compatibility with legacy `.cursorrules` file via `USE_LEGACY_CURSORRULES=true`
  - Interactive choice during installation
  - When both exist, use path based on `USE_LEGACY_CURSORRULES` environment variable
  - Updated documentation to reflect new path structure
- Added support for the `gpt-4o` model in browser commands (`act`, `extract`, `observe`)
  - The model can be selected using the `--model=gpt-4o` command-line option
  - The default model can be configured in `cursor-tools.config.json`
  - If no model is specified, a default model is used based on the configured provider (OpenAI or Anthropic)
- **Internal:** Bundled Stagehand script directly into the codebase to prevent dependency issues
- **Build:** Added stagehand script verification to the release process
- Enhanced `plan` command with dual-provider architecture:
  - Separate providers for file identification and plan generation
  - `fileProvider` handles repository file analysis
  - `thinkingProvider` generates implementation plans
  - New command options:
    - `--fileProvider`: Provider for file identification (gemini, openai, or openrouter)
    - `--thinkingProvider`: Provider for plan generation (gemini, openai, 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
- Brand new provider system with enhanced error handling and configuration:
  - New provider interfaces for specialized tasks
  - Shared implementations via provider mixins
  - Better error messages and debugging support
  - Configurable system prompts for different tasks
- Added `--quiet` flag to suppress stdout output while still saving to file with `--save-to`
  - Useful for scripting and automated documentation generation
  - All commands now support quiet mode
  - Error messages are still displayed even in quiet mode

## [0.4.3-alpha.23] - 2024-03-22

### Fixed
- Fixed browser commands to respect system color scheme when using `--connect-to` by not forcing a specific color scheme

## [0.4.3-alpha.22] - 2024-03-22

### Fixed
- Fixed browser commands to not set viewport size in Stagehand when using `--connect-to`

## [0.4.3-alpha.21] - 2024-03-22

### Fixed
- Fixed browser commands to not set viewport size when using `--connect-to` without an explicit `--viewport` option

## [0.4.3-alpha.20] - 2024-03-22

### Changed
- Browser commands (`open`, `act`, `observe`, `extract`) now have `--console` and `--network` options enabled by default. Use `--no-console` and `--no-network` to disable them.

## [0.4.3-alpha.19] - 2024-03-22

### Fixed
- Fixed browser commands to always reuse existing tabs when using `--connect-to` instead of creating new ones

## [0.4.3-alpha.18] - 2024-03-22

### Changed
- Browser commands now preserve viewport size when using `--connect-to` unless `--viewport` is explicitly provided
- Added validation to prevent using `--video` with `--connect-to` as video recording is not supported when connecting to existing Chrome instances

## [0.4.3-alpha.17] - 2024-03-22

### Added
- Added `reload-current` as a special URL value for browser commands when using `--connect-to`. This allows refreshing the current page while maintaining the connection, which is particularly useful in development workflows.

## [0.4.3-alpha.15] - 2024-03-21

### Fixed
- Fixed console logging in browser act command by correcting parameter order in outputMessages call

## [0.4.3-alpha.13] - 2024-03-21

### Added
- Browser commands now support `--url=current` to skip navigation and use the current page
- Browser commands now automatically skip navigation if already on the correct URL
- Improved page reuse when connecting to existing Chrome instance

## [0.4.3-alpha.12] - 2025-02-07

### Added
- New `browser` command for AI-powered web automation and debugging, leveraging Stagehand AI for natural language interaction
  - `act <instruction> --url <url> [options]`: Execute actions on a webpage using natural language instructions
    - `<instruction>`: Natural language instruction describing the action (e.g., "Click Login", "Type 'hello' in the search box")
    - `--url <url>`: Required URL to navigate to before performing actions
    - Additional options:
      - `--delay=<milliseconds>`: Delay between actions (default: 100)
      - `--retry=<number>`: Number of retries for failed actions (default: 3)
  - `extract <instruction> --url <url> [options]`: Extract data from webpages based on natural language instructions
    - `<instruction>`: Natural language instruction describing the data to extract (e.g., "product names", "article content")
    - `--url <url>`: Required URL to navigate to
    - Additional options:
      - `--format=<json|csv|text>`: Output format (default: json)
      - `--flatten`: Flatten nested objects in output
  - `observe <instruction> --url <url> [options]`: Observe interactive elements on a webpage and suggest possible actions
    - `<instruction>`: Natural language instruction describing what to observe (e.g., "interactive elements", "login form")
    - `--url <url>`: Required URL to navigate to
    - Additional options:
      - `--interval=<milliseconds>`: Check interval for observation (default: 1000)
      - `--duration=<duration>`: Total observation time (e.g., '30s', '5m')
      - `--changes-only`: Only report when changes are detected
  - `open <url> [options]`: Open and interact with web pages
    - Capture HTML content with `--html`
    - Monitor console logs with `--console`
    - Track network activity with `--network`
    - Take screenshots with `--screenshot=<file path>`
    - Configure viewport size with `--viewport=<width>x<height>`
    - Debug with visible browser using `--no-headless`
    - Connect to existing Chrome instances with `--connect-to=<port>`
  - Common options for all browser commands:
    - `--timeout=<milliseconds>`: Set navigation timeout (default: 30000)
    - `--viewport=<width>x<height>`: Set viewport size (e.g., 1280x720)
    - `--headless`: Run browser in headless mode (default: true)
    - `--no-headless`: Show browser UI for visual inspection and debugging
    - `--connect-to=<port>`: Connect to an existing Chrome instance
    - `--wait=<duration or selector>`: Wait after page load, supports:
      - Time duration: '5s', '1000ms', '2m' (seconds, milliseconds, minutes)
      - CSS selector: '#element-id', '.my-class'
      - Explicit format: 'time:5s', 'selector:#element-id', 'css:.my-class'
  - Made Playwright a peer dependency for lighter installation
  - Added browser configuration options in config file (headless mode, viewport, timeout)
  - Integrated Stagehand AI for browser automation
    - Support for OpenAI and Anthropic providers
    - Auto-selection of provider based on available API keys
    - Configurable timeout and debug options

### Changed
- Moved Playwright from direct dependency to peer dependency
  - Users need to install Playwright separately to use browser commands
  - Added clear installation instructions and error messages

## [0.4.3-alpha.10] - 2025-02-07

### Fixed
- Fixed punycode deprecation warning by properly redirecting both `punycode` and `node:punycode` imports to `punycode/`

## [0.4.3-alpha.9] - 2025-02-07

### Fixed
- Fixed dynamic require issues with Node.js built-in modules by using proper ESM imports
- Improved handling of Node.js built-in modules in build configuration

## [0.4.1] - 2025-02-06

### Changed
- Changed default tokenizer to `o200k_base` for better compatibility with Gemini models
- Added configurable tokenizer support through `tokenCount.encoding` in config file
- Updated documentation to reflect new tokenizer configuration options

## [0.4.0] - 2025-02-06

### Improvements
- Big improvements to robustness of command line arguments
- Introduces doc command to generate documentation for local or remote repositories
- Introduces github command to access PRs and issues from github
  - Support for listing recent PRs and issues
  - Detailed view of PR/issue discussions and code review comments
  - Multiple authentication methods:
    - GitHub token via environment variable
    - GitHub CLI integration for automatic token generation
    - Git credentials support (stored tokens or Basic Auth)
  - Support for both local and remote repositories
  - Markdown-formatted output for readability
- Use token count estimation to switch gemini models to pro if repository is large to fit any other model
- Updates GitHub model names to latest versions
- Updates Perplexity model names to latest versions
- Added version command to display the current version of cursor-tools

### Fixed
- Improved GitHub authentication error handling and rate limit messages
- Better detection of stored GitHub tokens in git credentials
- Fixed authentication status messages to accurately reflect available methods

## [0.3.4] - 2025-02-05

### Fixed
- Fixed ESM compatibility issues with Node.js built-in modules
- Removed bundling of Node.js built-ins for better ESM support
- Reduced bundle size by externalizing Node.js core modules

## [0.3.3] - 2025-02-05

### Fixed
- Fixed dynamic require issues with Node.js built-in modules
- Updated build configuration to properly handle Node.js built-ins in ESM context

## [0.3.2] - 2025-02-05

### Fixed
- Fixed dynamic require of url module in ESM context
- Updated import-meta-url.js to use proper ESM imports

## [0.3.1] - 2025-02-05

### Changed
- Improved release process with dedicated release script
- Fixed ESM compatibility issues with dependencies
- Added better error handling for git operations during release

## [0.3.0] - 2025-02-05

### Changed
- Updated build configuration to output ES Module format for better Node.js 20+ compatibility
- Changed output file from CommonJS (.cjs) to ES Module (.mjs)
- Fixed ESM compatibility issues with dependencies

## [0.2.0] - 2025-02-05

### Added
- Added branch support for GitHub repositories in `doc` command
  - Support for specifying branch using `@branch` syntax (e.g. `--fromGithub=username/repo@branch`)
  - Works with both HTTPS URLs and shorthand format
  - Properly integrates with repomix API using the `ref` parameter

## [0.1.0] - 2025-02-04

### Added
- New `doc` command to generate comprehensive repository documentation
  - Support for local repository documentation generation
  - Support for remote GitHub repository documentation via `--fromGithub` option
  - Option to save documentation to file with `--output`
- Development mode support via `pnpm dev` for running latest code without building

### Changed
- Updated `.cursorrules` to include documentation for the new `doc` command
- Improved command-line argument parsing for better option handling

## [0.0.14] - Previous Release

Initial release with basic functionality:
- Web search using Perplexity AI
- Repository context-aware answers using Google Gemini
- Installation and configuration utilities

CHANGELOG.md

Give Cursor Agent an AI Team and Advanced Skills


# cursor-tools Configuration Guide

This document provides detailed configuration information for cursor-tools.

## Configuration Overview
cursor-tools can be configured through two main mechanisms:
1. Environment variables (API keys and core settings)
2. JSON configuration file (provider settings, model preferences, and command options)

## Environment Variables
Create `.cursor-tools.env` in your project root or `~/.cursor-tools/.env` in your home directory:
```env
# Required API Keys
PERPLEXITY_API_KEY="your-perplexity-api-key"    # Required for web search
GEMINI_API_KEY="your-gemini-api-key"            # Required for repository analysis

# Optional API Keys
OPENAI_API_KEY="your-openai-api-key"            # For browser commands with OpenAI
ANTHROPIC_API_KEY="your-anthropic-api-key"      # For browser commands with Anthropic
GITHUB_TOKEN="your-github-token"                # For enhanced GitHub access

# Configuration Options
USE_LEGACY_CURSORRULES="true"                   # Use legacy .cursorrules file (default: false)
```

## Configuration File (cursor-tools.config.json)
Create this file in your project root to customize behavior. Here's a comprehensive example with all available options:
```json
{
  "perplexity": {
    "model": "sonar-pro",           // Default model for web search
    "maxTokens": 8000               // Maximum tokens for responses
  },
  "gemini": {
    "model": "gemini-2.0-pro-exp",  // Default model for repository analysis
    "maxTokens": 10000              // Maximum tokens for responses
  },
  "plan": {
    "fileProvider": "gemini",       // Provider for file identification
    "thinkingProvider": "openai",   // Provider for plan generation
    "fileMaxTokens": 8192,          // Tokens for file identification
    "thinkingMaxTokens": 8192       // Tokens for plan generation
  },
  "repo": {
    "provider": "gemini",           // Default provider for repo command
    "maxTokens": 10000              // Maximum tokens for responses
  },
  "doc": {
    "maxRepoSizeMB": 100,          // Maximum repository size for remote docs
    "provider": "gemini",          // Default provider for doc generation
    "maxTokens": 10000             // Maximum tokens for responses
  },
  "browser": {
    "defaultViewport": "1280x720", // Default browser window size
    "timeout": 30000,              // Default timeout in milliseconds
    "stagehand": {
      "env": "LOCAL",              // Stagehand environment
      "headless": true,            // Run browser in headless mode
      "verbose": 1,                // Logging verbosity (0-2)
      "debugDom": false,           // Enable DOM debugging
      "enableCaching": false,      // Enable response caching
      "model": "claude-3-7-sonnet-latest",  // Default Stagehand model
      "provider": "anthropic",     // AI provider (anthropic or openai)
      "timeout": 30000            // Operation timeout
    }
  },
  "tokenCount": {
    "encoding": "o200k_base"      // Token counting method
  },
  "openai": {
    "maxTokens": 8000  // Will be used when provider is "openai"
  },
  "anthropic": {
    "maxTokens": 8000  // Will be used when provider is "anthropic"
  }
}
```

## Configuration Sections

### Perplexity Settings
- `model`: The AI model to use for web searches
- `maxTokens`: Maximum tokens in responses

### Gemini Settings
- `model`: The AI model for repository analysis
- `maxTokens`: Maximum tokens in responses
- Note: For repositories >800K tokens, automatically switches to gemini-2.0-pro-exp

### Plan Command Settings
- `fileProvider`: AI provider for identifying relevant files
- `thinkingProvider`: AI provider for generating implementation plans
- `fileMaxTokens`: Token limit for file identification
- `thinkingMaxTokens`: Token limit for plan generation

### Repository Command Settings
- `provider`: Default AI provider for repository analysis
- `maxTokens`: Maximum tokens in responses

### Documentation Settings
- `maxRepoSizeMB`: Size limit for remote repositories
- `provider`: Default AI provider for documentation
- `maxTokens`: Maximum tokens in responses

### Browser Automation Settings
- `defaultViewport`: Browser window size
- `timeout`: Navigation timeout
- `stagehand`: Stagehand-specific settings including:
  - `env`: Environment configuration
  - `headless`: Browser visibility
  - `verbose`: Logging detail level
  - `debugDom`: DOM debugging
  - `enableCaching`: Response caching
  - `model`: Default AI model
  - `provider`: AI provider selection
  - `timeout`: Operation timeout

### Token Counting Settings
- `encoding`: Method used for counting tokens
  - `o200k_base`: Optimized for Gemini (default)
  - `gpt2`: Traditional GPT-2 encoding

## GitHub Authentication
The GitHub commands support several authentication methods:

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 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.

## Repomix Configuration

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
cursor-tools browser act "Click Login" --url "https://example.com" --model=gpt-4o

# Use Claude 3.7 Sonnet
cursor-tools browser act "Click Login" --url "https://example.com" --model=claude-3-7-sonnet-latest
```

You can set a default provider in your `cursor-tools.config.json` file under the `stagehand` section:

```json
{
  "stagehand": {
    "provider": "openai", // or "anthropic"
  }
}
```

You can also set a default model in your `cursor-tools.config.json` file under the `stagehand` section:

```json
{
  "stagehand": {
    "provider": "openai", // or "anthropic"
    "model": "gpt-4o"
  }
}
```

If no model is specified (either on the command line or in the config), a default model will be used based on your configured provider:

- **OpenAI:** `o3-mini`
- **Anthropic:** `claude-3-7-sonnet-latest`

Available models depend on your configured provider (OpenAI or Anthropic) in `cursor-tools.config.json` and your API key.

## Cursor Configuration
`cursor-tools` automatically configures Cursor by updating your project rules during installation. This provides:
- Command suggestions
- Usage examples
- Context-aware assistance

For new installations, we use the recommended `.cursor/rules/cursor-tools.mdc` path. For existing installations, we maintain compatibility with the legacy `.cursorrules` file. If both files exist, we prefer the new path and show a warning.

### Cursor Agent Configuration

To get the benefits of cursor-tools you should use Cursor agent in "yolo mode". Ideal settings:

![image](https://github.com/user-attachments/assets/783e26cf-c339-4cae-9629-857da0359cef)

## Command-Specific Configuration

### Ask Command
The `ask` command requires both a provider and a model to be specified. While these must be provided via command-line arguments, the maxTokens can be configured through the provider-specific settings:

```json
{
  "openai": {
    "maxTokens": 8000  // Will be used when provider is "openai"
  },
  "anthropic": {
    "maxTokens": 8000  // Will be used when provider is "anthropic"
  }
}
```

### Plan Command
The plan command uses two different models:
1. A file identification model (default: Gemini with gemini-2.0-pro-exp)
2. A thinking model for plan generation (default: OpenAI with o3-mini)

You can configure both models and their providers:
```json
{
  "plan": {
    "fileProvider": "gemini",
    "thinkingProvider": "openai",
    "fileModel": "gemini-2.0-pro-exp",
    "thinkingModel": "o3-mini",
    "fileMaxTokens": 8192,
    "thinkingMaxTokens": 8192
  }
}
```

The OpenAI o3-mini model is chosen as the default thinking provider for its speed and efficiency in generating implementation plans.

CONFIGURATION.md


Give Cursor Agent an AI team and advanced skills

## Table of Contents
- [The AI Team](#the-ai-team)
- [New Skills](#new-skills-for-your-existing-agent)
- [How to Use](#how-do-i-use-it)
  - [Example: Using Perplexity](#asking-perplexity-to-carry-out-web-research)
  - [Example: Using Gemini](#asking-gemini-for-a-plan)
- [What is cursor-tools](#what-is-cursor-tools)
- [Installation](#installation)
- [Requirements](#requirements)
- [Tips](#tips)
- [Additional Examples](#additional-examples)
  - [GitHub Skills](#github-skills)
  - [Gemini Code Review](#gemini-code-review)
- [Detailed Cursor Usage](#detailed-cursor-usage)
  - [Tool Recommendations](#tool-recommendations)
  - [Command Nicknames](#command-nicknames)
  - [Web Search](#use-web-search)
  - [Repository Search](#use-repo-search)
  - [Documentation Generation](#use-doc-generation)
  - [GitHub Integration](#use-github-integration)
  - [Browser Automation](#use-browser-automation)
  - [Direct Model Queries](#use-direct-model-queries)
- [Authentication and API Keys](#authentication-and-api-keys)
- [AI Team Features](#ai-team-features)
  - [Perplexity: Web Search & Research](#perplexity-web-search--research)
  - [Gemini 2.0: Repository Context & Planning](#gemini-20-repository-context--planning)
  - [Stagehand: Browser Automation](#stagehand-browser-automation)
    - [Browser Command Options](#browser-command-options)
    - [Video Recording](#video-recording)
    - [Console and Network Logging](#console-and-network-logging)
    - [Complex Actions](#complex-actions)
    - [Troubleshooting Browser Commands](#troubleshooting-browser-commands)
- [Skills](#skills)
  - [GitHub Integration](#github-integration)
  - [Documentation Generation](#documentation-generation-uses-gemini-20)
- [Configuration](#configuration)
  - [cursor-tools.config.json](#cursor-toolsconfigjson)
  - [GitHub Authentication](#github-authentication)
  - [Repomix Configuration](#repomix-configuration)
  - [Model Selection](#model-selection)
  - [Cursor Configuration](#cursor-configuration)
    - [Cursor Agent Configuration](#cursor-agent-configuration)
- [cursor-tools cli](#cursor-tools-cli)
  - [Command Options](#command-options)
  - [Execution Methods](#execution-methods)
- [Troubleshooting](#troubleshooting)
- [Examples](#examples)
  - [Web Search Examples](#web-search-examples)
  - [Repository Context Examples](#repository-context-examples)
  - [Documentation Examples](#documentation-examples)
  - [GitHub Integration Examples](#github-integration-examples)
  - [Browser Command Examples](#browser-command-examples)
    - [open subcommand examples](#open-subcommand-examples)
    - [act, extract, observe subcommands examples](#act-extract-observe-subcommands-examples)
- [Node Package Manager](#node-package-manager-npm)
- [Contributing](#contributing)
- [Sponsors](#sponsors)
- [License](#license)

### The AI Team
- 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)

### New Skills for your existing Agent
- Work with GitHub Issues and Pull Requests
- Generate local agent-accessible documentation for external dependencies

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

### How do I use it?

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`, and `observe` 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

### GitHub Skills
To see cursor-tools GitHub and Perplexity skills: Check out [this example issue that was solved using Cursor agent and cursor-tools](https://github.com/eastlondoner/cursor-tools/issues/1)

### Gemini code review
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.

### Tool Recommendations
- `cursor-tools ask` allows direct querying of any model from any provider. It's best for simple questions where you want to use a specific model or compare responses from different models.
- `cursor-tools web` uses an AI teammate with web search capability to answer questions. `web` is best for finding up-to-date information from the web that is not specific to the repository such as how to use a library to search for known issues and error messages or to get suggestions on how to do something. Web is a teammate who knows tons of stuff and is always up to date.
- `cursor-tools repo` uses an AI teammate with large context window capability to answer questions. `repo` sends the entire repo as context so it is ideal for questions about how things work or where to find something, it is also great for code review, debugging and planning.  is a teammate who knows the entire codebase inside out and understands how everything works together.
- `cursor-tools plan` uses an AI teammate with reasoning capability to plan complex tasks. Plan uses a two step process. First it does a whole repo search with a large context window model to find relevant files. Then it sends only those files as context to a thinking model to generate a plan it is great for planning complex tasks and for debugging and refactoring. Plan is a teammate who is really smart on a well defined problem, although doesn't consider the bigger picture.
- `cursor-tools doc` uses an AI teammate with large context window capability to generate documentation for local or github hosted repositories by sending the entire repo as context. `doc` can be given precise documentation tasks or can be asked to generate complete docs from scratch it is great for generating docs updates or for generating local documentation for a libary or API that you use! Doc is a teammate who is great at summarising and explaining code, in this repo or in any other repo!
- `cursor-tools browser` uses an AI teammate with browser control (aka operator) capability to operate web browsers. `browser` can operate in a hidden (headless) mode to invisibly test and debug web apps or it can be used to connect to an existing browser session to interactively share your browser with Cursor agent it is great for testing and debugging web apps and for carrying out any task that can be done in a browser such as reading information from a bug ticket or even filling out a form. Browser is a teammate who can help you test and debug web apps, and can share control of your browser to perform small browser-based tasks.

Note: For repo, doc and plan commands the repository content that is sent as context can be reduced by filtering out files in a .repomixignore file.

### Command Nicknames
When using cursor-tools with Cursor Composer, you can use these nicknames:
- "Gemini" is a nickname for `cursor-tools repo`
- "Perplexity" is a nickname for `cursor-tools web`
- "Stagehand" is a nickname for `cursor-tools browser`

### Use web search
"Please implement country specific stripe payment pages for the USA, UK, France and Germany. Use cursor-tools web to check the available stripe payment methods in each country."

Note: in most cases you can say "ask Perplexity" instead of "use cursor-tools web" and it will work the same.

### Use repo search
"Let's refactor our User class to allow multiple email aliases per user. Use cursor-tools repo to ask for a plan including a list of all files that need to be changed."

Note: in most cases you can say "ask Gemini" instead of "use cursor-tools repo" and it will work the same.

### Use doc generation
"Use cursor-tools to generate documentation for the Github repo https://github.com/kait-http/kaito" and write it to docs/kaito.md"

Note: in most cases you can say "generate documentation" instead of "use cursor-tools doc" and it will work the same.

### Use github integration
"Use cursor-tools github to fetch issue 123 and suggest a solution to the user's problem"

"Use cursor-tools github to fetch PR 321 and see if you can fix Andy's latest comment"

Note: in most cases you can say "fetch issue 123" or "fetch PR 321" instead of "use cursor-tools github" and it will work the same.

### Use browser automation
"Use cursor-tools to open the users page and check the error in the console logs, fix it"

"Use cursor-tools to test the form field validation logic. Take screenshots of each state"

"Use cursor-tools to open https://example.com/foo the and check the error in the network logs, what could be causing it?"

Note: in most cases you can say "Use Stagehand" instead of "use cursor-tools" and it will work the same.

### Use direct model queries
"Use cursor-tools ask to compare how different models answer this question: 'What are the key differences between REST and GraphQL?'"

"Ask OpenAI's o3-mini model to explain the concept of dependency injection."

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
`cursor-tools` requires API keys for both Perplexity AI and Google Gemini. These can be configured in two ways:

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"
   ```

## AI Team Features

### Perplexity: Web Search & Research
Use Perplexity AI to get up-to-date information directly within Cursor:
```bash
cursor-tools web "What's new in TypeScript 5.7?"
```

### Gemini 2.0: Repository Context & Planning
Leverage Google Gemini 2.0 models with 1M+ token context windows for codebase-aware assistance and implementation planning:

```bash
# Get context-aware assistance
cursor-tools repo "Explain the authentication flow in this project, which files are involved?"

# Generate implementation plans
cursor-tools plan "Add user authentication to the login page"
```

The plan command uses multiple AI models to:
1. Identify relevant files in your codebase (using Gemini by default)
2. Extract content from those files
3. Generate a detailed implementation plan (using o3-mini by default)

**Plan Command Options:**
- `--fileProvider=<provider>`: Provider for file identification (gemini, openai, anthropic, perplexity, modelbox, or openrouter)
- `--thinkingProvider=<provider>`: Provider for plan generation (gemini, openai, anthropic, perplexity, modelbox, or openrouter)
- `--fileModel=<model>`: Model to use for file identification
- `--thinkingModel=<model>`: Model to use for plan generation
- `--fileMaxTokens=<number>`: Maximum tokens for file identification
- `--thinkingMaxTokens=<number>`: 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.

### Stagehand: Browser Automation
Automate browser interactions for web scraping, testing, and debugging:

**Important:** The `browser` command requires the Playwright package to be installed separately in your project:
```bash
npm install playwright
# or
yarn add playwright
# or
pnpm add playwright
```

1. `open` - Open a URL and capture page content:
```bash
# Open and capture HTML content, console logs and network activity (enabled by default)
cursor-tools browser open "https://example.com" --html

# Take a screenshot
cursor-tools browser open "https://example.com" --screenshot=page.png

# Debug in an interactive browser session
cursor-tools browser open "https://example.com" --connect-to=9222
```

2. `act` - Execute actions using natural language - Agent tells the browser-use agent what to do:
```bash
# Single action
cursor-tools browser act "Login as 'user@example.com'" --url "https://example.com/login"

# Multi-step workflow using pipe separator
cursor-tools browser act "Click Login | Type 'user@example.com' into email | Click Submit" --url "https://example.com"

# Record interaction video
cursor-tools browser act "Fill out registration form" --url "https://example.com/signup" --video="./recordings"
```

3. `observe` - Analyze interactive elements:
```bash
# Get overview of interactive elements
cursor-tools browser observe "What can I interact with?" --url "https://example.com"

# Find specific elements
cursor-tools browser observe "Find the login form" --url "https://example.com"
```

4. `extract` - Extract data using natural language:
```bash
# Extract specific content
cursor-tools browser extract "Get all product prices" --url "https://example.com/products"

# Save extracted content
cursor-tools browser extract "Get article text" --url "https://example.com/blog" --html > article.html

# Extract with network monitoring
cursor-tools browser extract "Get API responses" --url "https://example.com/api-test" --network
```

#### Browser Command Options
All browser commands (`open`, `act`, `observe`, `extract`) 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=<file path>`: Save a screenshot of the page
- `--timeout=<milliseconds>`: Set navigation timeout (default: 120000ms for Stagehand operations, 30000ms for navigation)
- `--viewport=<width>x<height>`: 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=<port>`: Connect to existing Chrome instance. Special values: 'current' (use existing page), 'reload-current' (refresh existing page)
- `--wait=<time:duration or selector:css-selector>`: Wait after page load (e.g., 'time:5s', 'selector:#element-id')
- `--video=<directory>`: Save a video recording (1280x720 resolution, timestamped subdirectory). Not available when using --connect-to
- `--url=<url>`: Required for `act`, `observe`, and `extract` commands
- `--evaluate=<string>`: JavaScript code to execute in the browser before the main command

**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=<directory>` 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
cursor-tools browser act "Fill out registration form with name John Doe" --url "http://localhost:3000/signup" --video="./recordings"
```

#### 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)
cursor-tools browser act "Click Login | Type 'user@example.com' into email | Click Submit" --url "http://localhost:3000/login"

# Form filling with multiple fields
cursor-tools browser act "Select 'Mr' from title | Type 'John' into first name | Type 'Doe' into last name | Click Next" --url "http://localhost:3000/register"

# Record complex interaction
cursor-tools browser act "Fill form | Submit | Verify success" --url "http://localhost:3000/signup" --video="./recordings"
```

#### Troubleshooting Browser Commands
Common issues and solutions:

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

### GitHub Integration
Access GitHub issues and pull requests directly from the command line with rich formatting and full context:

```bash
# List recent PRs or issues
cursor-tools github pr
cursor-tools github issue

# View specific PR or issue with full discussion
cursor-tools github pr 123
cursor-tools github issue 456
```

The GitHub commands provide:
- View of 10 most recent open PRs or issues when no number specified
- Detailed view of specific PR/issue including:
  - PR/Issue description and metadata
  - Code review comments grouped by file (PRs only)
  - Full discussion thread
  - Labels, assignees, milestones and reviewers
- Support for both local repositories and remote GitHub repositories
- Markdown-formatted output for readability

**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)

### Documentation Generation (uses Gemini 2.0)
Generate comprehensive documentation for your repository or any GitHub repository:
```bash
# Document local repository and save to file
cursor-tools doc --save-to=docs.md

# Document remote GitHub repository (both formats supported)
cursor-tools doc --from-github=username/repo-name@branch
cursor-tools doc --from-github=https://github.com/username/repo-name@branch

# Save documentation to file (with and without a hint)
# This is really useful to generate local documentation for libraries and dependencies
cursor-tools doc --from-github=eastlondoner/cursor-tools --save-to=docs/CURSOR-TOOLS.md
cursor-tools doc --from-github=eastlondoner/cursor-tools --save-to=docs/CURSOR-TOOLS.md --hint="only information about the doc command"
```

## Configuration

### cursor-tools.config.json
Customize `cursor-tools` behavior by creating a `cursor-tools.config.json` file. This file can be created either globally in `~/.cursor-tools/cursor-tools.config.json` or locally in your project root.

The cursor-tools.config file configures the local default behaviour for each command and provider.

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](CONFIGURATION.md). This includes details of all the configuration options and how to use them.

### GitHub Authentication
The GitHub commands support several authentication methods:

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.

### Repomix Configuration

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
cursor-tools browser act "Click Login" --url "https://example.com" --model=gpt-4o

# Use Claude 3.7 Sonnet
cursor-tools browser act "Click Login" --url "https://example.com" --model=claude-3-7-sonnet-latest
```

You can set a default provider in your `cursor-tools.config.json` file under the `stagehand` section:

```json
{
  "stagehand": {
    "model": "claude-3-7-sonnet-latest", // For Anthropic provider
    "provider": "anthropic", // or "openai"
    "timeout": 90000
  }
}
```

You can also set a default model in your `cursor-tools.config.json` file under the `stagehand` section:

```json
{
  "stagehand": {
    "provider": "openai", // or "anthropic"
    "model": "gpt-4o"
  }
}
```

If no model is specified (either on the command line or in the config), a default model will be used based on your configured provider:

- **OpenAI:** `o3-mini`
- **Anthropic:** `claude-3-7-sonnet-latest`

Available models depend on your configured provider (OpenAI or Anthropic) in `cursor-tools.config.json` and your API key.

### Cursor Configuration
`cursor-tools` automatically configures Cursor by updating your project rules during installation. This provides:
- Command suggestions
- Usage examples
- Context-aware assistance

For new installations, we use the recommended `.cursor/rules/cursor-tools.mdc` path. For existing installations, we maintain compatibility with the legacy `.cursorrules` file. If both files exist, we prefer the new path and show a warning.

#### Cursor Agent Configuration:

To get the benefits of cursor-tools you should use Cursor agent in "yolo mode". Ideal settings:

![image](https://github.com/user-attachments/assets/783e26cf-c339-4cae-9629-857da0359cef)

## cursor-tools cli

In general you do not need to use the cli directly, your AI coding agent will call the CLI but it is useful to know it exists and this is how it works.

### Command Options
All commands support these general options:
- `--model`: Specify an alternative model
- `--max-tokens`: Control response length
- `--save-to`: Save command output to a file (in addition to displaying it, like tee)
- `--quiet`: Suppress stdout output (only useful with --save-to)
- `--debug`: Show detailed error information
- `--help`: View all available options
- `--provider`: AI provider to use. Valid values: openai, anthropic, perplexity, gemini, openrouter

Documentation command specific options:
- `--from-github`: Generate documentation for a remote GitHub repository (supports @branch syntax)
- `--hint`: Provide additional context or focus for documentation generation

Plan command specific 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

GitHub command specific options:
- `--from-github=<GitHub username>/<repository name>[@<branch>]`: Access PRs/issues from a specific GitHub repository. `--repo` is an older, still supported synonym for this option.

Browser command specific 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`: 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
- `--wait`: Wait after page load (e.g., 'time:5s', 'selector:#element-id')
- `--video`: Save a video recording (1280x720 resolution, timestamped subdirectory)
- `--url`: Required for `act`, `observe`, and `extract` commands. Url to navigate to on connection or one of the special values: 'current' (use existing page), 'reload-current' (refresh existing page).
- `--evaluate`: JavaScript code to execute in the browser before the main command

### Execution Methods
Execute commands using:
```bash
cursor-tools <command> [options]
```

For example:
```bash
cursor-tools web "What's new in TypeScript 5.7?"
```

## Troubleshooting

1. **Command Not Found**
    - Ensure `cursor-tools` is installed globally using `npm install -g cursor-tools`
    - Check your system's PATH environment variable to ensure it includes npm's global bin directory
    - On Unix-like systems, the global bin directory is typically `/usr/local/bin` or `~/.npm-global/bin`
    - On Windows, it's typically `%AppData%\npm`

2. **API Key Errors**
    - Verify `.cursor-tools.env` exists and contains valid API keys
    - Run `cursor-tools install` to reconfigure API keys
    - Check that your API keys have the necessary permissions
    - For GitHub operations, ensure your token has the required scopes (repo, read:user)

3. **Model Errors**
    - Check your internet connection
    - Verify API key permissions
    - Ensure the specified model is available for your API tier

4. **GitHub API Rate Limits**
    - GitHub API has rate limits for unauthenticated requests. For higher limits you must be authenticated.
    - If you have the gh cli installed and logged in cursor-tools will use that to obtain a short lived auth token. Otherwise you can add a GitHub token to your environment:
      ```env
      GITHUB_TOKEN=your_token_here
      ```
    - Private repositories always require authentication

5. **Documentation Generation Issues**
    - Repository too large: Try using `--hint` to focus on specific parts
    - Token limit exceeded: The tool will automatically switch to a larger model
    - Network timeouts: The tool includes automatic retries
    - For very large repositories, consider documenting specific directories or files

6. **Cursor Integration**
    - If .cursorrules is outdated, run `cursor-tools install .` to update
    - Ensure Cursor is configured to allow command execution
    - Check that your Cursor version supports AI commands

### Examples

#### Web Search Examples
```bash
# Get information about new technologies
cursor-tools web "What are the key features of Bun.js?"

# Check API documentation
cursor-tools web "How to implement OAuth2 in Express.js?"

# Compare technologies
cursor-tools web "Compare Vite vs Webpack for modern web development"
```

#### Repository Context Examples
```bash
# Architecture understanding
cursor-tools repo "Explain the overall architecture of this project"

# Find usage examples
cursor-tools repo "Show me examples of error handling in this codebase"

# Debugging help
cursor-tools repo "Why might the authentication be failing in the login flow?"
```

#### Documentation Examples
```bash
# Document specific aspects and save to file without stdout output
cursor-tools doc --save-to=docs/api.md --quiet --hint="Focus on the API endpoints and their usage"

# Document with hint to customize the docs output
cursor-tools doc --save-to=docs/architecture.md --quiet --hint="Focus on system architecture"

# Document dependencies
cursor-tools doc --from-github=expressjs/express --save-to=docs/EXPRESS.md --quiet
```

#### GitHub Integration Examples
```bash
# List PRs with specific labels
cursor-tools github pr --from-github facebook/react

# Check recent issues in a specific repository
cursor-tools github issue --from-github vercel/next.js

# View PR with code review comments
cursor-tools github pr 123 --from-github microsoft/typescript

# Track issue discussions
cursor-tools github issue 456 --from-github golang/go
```

#### Browser Command Examples

##### `open` subcommand examples:
```bash
# Open a URL and get HTML
cursor-tools browser open "https://example.com" --html

# Open and capture console logs and network activity
cursor-tools browser open "https://example.com" --console --network

# Take a screenshot
cursor-tools browser open "https://example.com" --screenshot=page.png

# Run in non-headless mode for debugging
cursor-tools browser open "https://example.com" --no-headless
```

##### `act`, `extract`, `observe` subcommands examples:
```bash
# AI-powered action
cursor-tools browser act "Click on 'Sign Up'" --url "https://example.com"

# AI-powered extraction
cursor-tools browser extract "Get the main content" --url "https://example.com/blog"

# AI-powered observation
cursor-tools browser observe "What can I do on this page?" --url "https://example.com"
```

## Node Package Manager (npm)

cursor-tools is available on npm [here](https://www.npmjs.com/package/cursor-tools)

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. If you used cursor-tools to make your contribution please include screenshots or videos of cursor-tools in action.

## Sponsors

### [Vinta.app](https://vinta.app)
**Optimise your Vinted accounting** with real-time analytics, inventory management, and tax compliance tools.

:link: [Start scaling your Vinted business today](https://vinta.app)

---

### [Resoled.it](https://resoled.it)
**Automate your Vinted reselling business** with advanced tools like autobuy, custom snipers, and one-click relisting.

:link: [Take Vinted reselling to the next level](https://resoled.it)

---

### [iterate.com](https://iterate.com)
**Build self-driving startups** with autonomous AI agents that run your company.

:link: [AI Engineer in London? Join the startup revolution](https://iterate.com)

## License

MIT License - see [LICENSE](LICENSE) for details.

README.md


Packing repository using Repomix...
Analyzing repository using gemini-2.0-flash-thinking-exp...
Okay, I've reviewed the test plan in `test-plan.md` against the functionalities of cursor-tools, the file summaries, and especially the recent changes detailed in `CHANGELOG.md`. Here's my feedback:

**Overall Completeness and Adequacy:**

The test plan is quite comprehensive and covers a good range of `cursor-tools` functionalities. It's well-structured and organized by command, which makes it easy to follow. It directly addresses the recent changes highlighted in the `CHANGELOG.md`, demonstrating a clear effort to validate the latest updates.

**Specific Feedback and Suggestions:**

1.  **MCP Server Overrides:**
    *   The test plan includes a test case for MCP `run` with overrides: `cursor-tools mcp run "using google-calendar-mcp list upcoming events"`. This is good and directly targets the new override feature.
    *   **Suggestion:** It would be beneficial to add a test case that explicitly verifies that a *user-configured* override (in `cursor-tools.config.json`) is also working as expected, not just the hardcoded override.  This could involve a temporary config file modification for the test.

2.  **Claude 3.7 Sonnet Model Updates:**
    *   The test plan mentions verifying Claude 3.7 Sonnet in the `ask` and `browser` command sections. This is important to ensure the model switch was successful.
    *   **Improvement:** While mentioned, it's not explicitly a separate test case. Consider adding a test case specifically to confirm that commands using default models (where Claude 3.7 Sonnet should now be used) are indeed using the correct updated model and functioning as expected. For example, for `ask` command without specifying a model, and for `browser act` without specifying a model (if it defaults to Anthropic/Claude).

3.  **Stagehand Dependency Update (1.13.0 to 1.13.1):**
    *   The test plan mentions testing with the updated Stagehand dependency, which is good.
    *   **Suggestion:**  It's not clear *what* specifically about the Stagehand update is being tested. Add specific test cases that would highlight any potential regressions or improvements from the Stagehand update. For example, are there any known bug fixes or feature enhancements in 1.13.1 that you can verify? If not explicitly, then ensure the existing browser command tests are run thoroughly to catch any regressions.

4.  **Global Installation Recommendation Change:**
    *   This change is more about documentation and user guidance than functionality. The test plan doesn't need to directly test this.
    *   **Feedback:**  The test plan is fine as is concerning this change, as it's not a functional change.

5.  **Validation for `--tag` in Release Command:**
    *   This is a change to the release script, not the core functionality.  The test plan doesn't need to directly test this.
    *   **Feedback:**  The test plan is fine as is concerning this change, as it's a release process change.

6.  **ModelBox and OpenRouter Provider Addition:**
    *   The `ask`, `web`, `plan`, and `repo` command sections all mention testing with different providers, including ModelBox and OpenRouter. This is good.
    *   **Improvement:**  For each of these commands, explicitly include ModelBox and OpenRouter in the list of providers tested in the "Test Cases" subsections. For example, in `web`, add a test case like `cursor-tools web "Explain OpenRouter models" --provider openrouter`. This will ensure these new providers are specifically tested in each relevant command.

7.  **Browser Command State Management with `--connect-to` and `reload-current`:**
    *   The test plan includes test cases for `browser open` with `--connect-to`.
    *   **Missing Test Case:**  Crucially missing is a test case that verifies the *state persistence* and the functionality of `reload-current`. Add a test case like:
        *   `cursor-tools browser open "tests/commands/browser/test-browser-persistence.html" --connect-to=9222` (open test page, interact with it)
        *   `cursor-tools browser act "Click 'Button 2'" --url=current --connect-to=9222` (verify state is maintained)
        *   `cursor-tools browser act "Click 'Button 3'" --url=reload-current --connect-to=9222` (verify state is maintained after reload).
        *   Verify that the output and browser behavior are as expected across these steps.

8.  **Debug Logging Fixes:**
    *   The test plan mentions using the `--debug` flag in several test cases. This is good.
    *   **Suggestion:**  Add a specific point to the "Test Execution Plan" to "Verify debug output is generated and contains useful information when `--debug` is used for each command". This will ensure that the debug logging fixes are actually validated during testing.

9.  **Default Thinking Provider Change to OpenAI o3-mini:**
    *   The `plan` command section includes tests with different thinking providers.
    *   **Improvement:** Add a test case for the `plan` command *without* specifying `--thinkingProvider` or `--thinkingModel` to verify that the default is indeed OpenAI `o3-mini` and that it functions correctly.

10. **Default Console and Network Options for Browser Commands:**
    *   The test plan doesn't explicitly test the default `console` and `network` options being enabled.
    *   **Missing Test Case:** Add a test case for `browser act` or `browser open` *without* `--no-console` or `--no-network` flags and verify that console logs and network activity are indeed captured in the output. Also, add test cases with `--no-console` and `--no-network` to verify they are correctly disabled.

11. **Page Reuse and Viewport Size Preservation in Browser Commands with `--connect-to`:**
    *   Viewport preservation is partially covered by the suggested `--connect-to` test case above.
    *   **Suggestion:**  Explicitly add a step in the `--connect-to` test case in the "Test Execution Plan" to "Verify viewport size is preserved when reusing pages with `--connect-to`, and that `--viewport` option correctly overrides it".

12. **New `ask` Command:**
    *   The test plan has a dedicated section for the `ask` command, which is excellent. The test cases are good for basic functionality.
    *   **Improvement:** Add test cases to verify error handling, specifically:
        *   `cursor-tools ask "Question" --provider openai` (missing `--model` - should throw `ModelNotFoundError`)
        *   `cursor-tools ask "Question" --model o3-mini` (missing `--provider` - should throw `ProviderError`)
        *   `cursor-tools ask "Question" --provider invalid-provider --model o3-mini` (invalid provider - should throw `ProviderError`)

13. **New Cursor Rules Directory Structure and `USE_LEGACY_CURSORRULES`:**
    *   The test plan doesn't explicitly cover the cursor rules changes.
    *   **Missing Test Cases:** Add test cases to verify the install command in relation to cursor rules:
        *   Test `cursor-tools install .` with `USE_LEGACY_CURSORRULES=false` and verify `.cursor/rules/cursor-tools.mdc` is created/updated correctly.
        *   Test `cursor-tools install .` with `USE_LEGACY_CURSORRULES=true` and verify `.cursorrules` is created/updated correctly.
        *   Test `cursor-tools install .` when both `.cursorrules` and `.cursor/rules/cursor-tools.mdc` exist and `USE_LEGACY_CURSORRULES` is toggled, verifying the correct file is updated based on the environment variable.

14. **Dual-Provider Architecture for `plan` Command:**
    *   The test plan *does* include test cases with split providers for the `plan` command. This is good.
    *   **Feedback:** The existing test cases seem sufficient to cover this feature.

15. **New Provider System and Error Handling:**
    *   Error handling is partially covered by the `ask` command test case suggestions.
    *   **Improvement:**  In the "Test Execution Plan", add a point to "Verify error messages are user-friendly and informative for common error scenarios (API key missing, model not found, network errors, etc.) across all commands".

16. **`--quiet` Flag Addition:**
    *   The test plan does not explicitly test the `--quiet` flag.
    *   **Missing Test Case:** Add test cases to verify the `--quiet` flag works as expected:
        *   `cursor-tools web "Test query" --save-to test-output.txt --quiet` (verify no output to stdout, output is saved to file)
        *   `cursor-tools repo "Test query" --save-to test-output.txt --quiet` (verify no output to stdout, output is saved to file)
        *   Test with other commands as well to ensure `--quiet` is consistently applied across all commands.

**Other Issues/Suggestions:**

*   **Test Environment Setup:**  It would be helpful to add a section to the test plan describing the required test environment setup, including:
    *   API keys needed and how to set them (mention `.cursor-tools.env`)
    *   Playwright installation instructions (for browser command tests)
    *   Test server setup (for browser command testing, mention `pnpm serve-test`)
*   **Test Data/HTML Files:** Mention the location of test HTML files (`tests/commands/browser/`) and how to access them via the test server (`http://localhost:3000/filename.html`).
*   **Success Criteria Clarity:** While the "Success Criteria" section is present, it's quite high-level. Consider adding more specific success criteria for each command or test category. For example, for browser commands, success might include "Verify console logs are captured and formatted correctly", "Verify screenshots are generated at the correct path", etc.
*   **Consider Categorizing Test Cases:**  For each command, you could categorize test cases into "Positive Tests" (verifying expected behavior), "Negative Tests" (verifying error handling), and "Boundary/Edge Cases" (testing limits, unusual inputs, etc.). This can improve the structure and coverage of the test plan.

**In Summary:**

The test plan is a strong starting point and already covers many important aspects. By incorporating the suggested improvements, especially adding the missing test cases for `--connect-to` state persistence, `--quiet` flag, cursor rules installation, and more explicit error handling verification, and by clarifying the test environment and success criteria, you can make it even more robust and comprehensive, ensuring thorough validation of the latest cursor-tools features.

gemini-review.md


# Cursor-Tools Test Plan

## Purpose
This test plan aims to verify the functionality of cursor-tools commands, with particular focus on:
1. Features documented in the README
2. Recently changed functionality (from CHANGELOG)
3. Different models and providers across commands

## Recent Changes to Test
From the CHANGELOG, key areas to test include:
- MCP server overrides in the marketplace (both hardcoded and user-configured)
- Updated references to Claude 3.7 Sonnet models (from Claude 3.5)
- Updated @browserbasehq/stagehand dependency (1.13.0 to 1.13.1)
- Browser command state management with `--connect-to` and `reload-current`
- Default console and network options for browser commands
- New cursor rules directory structure (`.cursor/rules/cursor-tools.mdc`)
- Dual-provider architecture for `plan` command
- `--quiet` flag for suppressing stdout while saving to file

## Test Environment Setup
1. Required API keys:
   - Set up `.cursor-tools.env` with:
     - `PERPLEXITY_API_KEY`
     - `GEMINI_API_KEY`
     - `OPENAI_API_KEY` (for browser commands)
     - `ANTHROPIC_API_KEY` (for MCP commands and browser commands)
     - `GITHUB_TOKEN` (optional, for GitHub commands)

2. For browser command testing:
   - Install Playwright: `npm install --global playwright`
   - Start test server: `pnpm serve-test` (runs on http://localhost:3000)
   - Test files located in `tests/commands/browser/`

## Test Approach
For each command, we will:
1. Test basic functionality (positive tests)
2. Test error handling (negative tests)
3. Test with different providers where applicable
4. Test with different models where applicable
5. Verify output quality and correctness
6. Test recent changes and edge cases

## Commands to Test

### 1. Direct Model Queries (`ask`)
- Test with different providers (OpenAI, Anthropic, Perplexity, Gemini, ModelBox, OpenRouter)
- Verify Claude 3.7 Sonnet model works correctly (previously 3.5)
- Compare output quality across models
- Test error handling

#### Test Cases:
- Basic query: `cursor-tools ask "What is cursor-tools?" --provider openai --model o3-mini`
- Complex query: `cursor-tools ask "Explain the differences between REST and GraphQL" --provider anthropic --model claude-3-7-sonnet`
- Technical query: `cursor-tools ask "How does JavaScript event loop work?" --provider perplexity --model perplexity-online-latest`
- ModelBox query: `cursor-tools ask "What are the benefits of TypeScript?" --provider modelbox --model claude-3-7-sonnet`
- OpenRouter query: `cursor-tools ask "Explain the SOLID principles" --provider openrouter --model anthropic/claude-3-7-sonnet`

#### Error Handling Tests:
- Missing model: `cursor-tools ask "Test question" --provider openai` (should throw ModelNotFoundError)
- Missing provider: `cursor-tools ask "Test question" --model o3-mini` (should throw ProviderError)
- Invalid provider: `cursor-tools ask "Test question" --provider invalid-provider --model o3-mini` (should throw ProviderError)
- Invalid model: `cursor-tools ask "Test question" --provider openai --model invalid-model` (should throw ModelNotFoundError)

### 2. Web Search (`web`)
- Test with different providers (Perplexity, Gemini, ModelBox, OpenRouter)
- Test saving output to file
- Test with debug flag
- Test quiet flag

#### Test Cases:
- Current technology: `cursor-tools web "Latest TypeScript features" --provider perplexity`
- Technical documentation: `cursor-tools web "Next.js app router documentation" --provider gemini`
- Saving output: `cursor-tools web "cursor-tools installation guide" --save-to web-results.md`
- ModelBox provider: `cursor-tools web "React 19 new features" --provider modelbox --model claude-3-7-sonnet`
- OpenRouter provider: `cursor-tools web "Node.js best practices 2024" --provider openrouter`
- Debug flag: `cursor-tools web "TypeScript 5.7 features" --debug`
- Quiet flag with save: `cursor-tools web "Angular vs React in 2024" --save-to web-compare.md --quiet`

### 3. Repository Context (`repo`)
- Test with different providers and models
- Test on this repository
- Test with token limit considerations
- Test default Claude 3.7 model (previously 3.5)

#### Test Cases:
- Code explanation: `cursor-tools repo "Explain the MCP server override implementation"`
- Architecture question: `cursor-tools repo "How are providers implemented in the codebase?"`
- Different models: `cursor-tools repo "What's the structure of browser commands?" --provider openai --model o3-mini`
- ModelBox provider: `cursor-tools repo "Explain the dual-provider architecture for plan command" --provider modelbox`
- OpenRouter provider: `cursor-tools repo "How is cursor rule integration implemented?" --provider openrouter`
- Debug flag: `cursor-tools repo "Analyze error handling in the codebase" --debug`
- Quiet flag: `cursor-tools repo "Summarize recent changes" --save-to repo-changes.md --quiet`

### 4. Implementation Planning (`plan`)
- Test with different file and thinking providers
- Test with various combinations of models
- Test default thinking provider (OpenAI with o3-mini model)
- Test small and larger planning tasks

#### Test Cases:
- Basic plan: `cursor-tools plan "How to add a new command to cursor-tools?"`
- Default providers (verify o3-mini is used): `cursor-tools plan "Add a health check endpoint" --debug`
- Split providers: `cursor-tools plan "Implement a health check endpoint" --fileProvider gemini --thinkingProvider openai --thinkingModel o3-mini`
- Complex task: `cursor-tools plan "Implement TypeScript strict mode across the codebase" --fileProvider gemini --thinkingProvider anthropic --thinkingModel claude-3-7-sonnet`
- ModelBox provider: `cursor-tools plan "Add support for a new AI provider" --fileProvider modelbox --thinkingProvider modelbox`
- OpenRouter provider: `cursor-tools plan "Implement a new browser command feature" --fileProvider openrouter --thinkingProvider openrouter`
- Quiet flag: `cursor-tools plan "Refactor error handling" --save-to plan-errors.md --quiet`

### 5. Documentation Generation (`doc`)
- Test local repository documentation
- Test remote GitHub repository documentation
- Test with different hints for focused documentation
- Test with different models including Claude 3.7 Sonnet

#### Test Cases:
- Local repo: `cursor-tools doc --save-to repo-docs.md`
- Remote repo: `cursor-tools doc --from-github=eastlondoner/cursor-tools --save-to cursor-tools-docs.md`
- Focused docs: `cursor-tools doc --hint="Focus on browser commands" --save-to browser-docs.md`
- With Anthropic provider: `cursor-tools doc --provider anthropic --model claude-3-7-sonnet --save-to anthropic-docs.md`
- With specific branch: `cursor-tools doc --from-github=eastlondoner/cursor-tools@main --save-to main-docs.md`
- Quiet flag: `cursor-tools doc --from-github=eastlondoner/cursor-tools --save-to docs.md --quiet`

### 6. GitHub Integration
- Test PR listing
- Test issue listing
- Test specific PR and issue viewing
- Test remote repository specification

#### Test Cases:
- List PRs: `cursor-tools github pr`
- List issues: `cursor-tools github issue`
- View specific PR: `cursor-tools github pr 1` (if available)
- View specific issue: `cursor-tools github issue 1` (if available)
- From remote repo: `cursor-tools github pr --from-github=eastlondoner/cursor-tools`
- Quiet flag: `cursor-tools github pr --save-to prs.md --quiet`

### 7. Browser Automation
- Test each browser subcommand (open, act, observe, extract)
- Test with updated Stagehand dependency
- Test with different models including Claude 3.7 Sonnet
- Test default console and network options
- Test state persistence with `--connect-to` and `reload-current`

#### Test Cases:
- Open webpage: `cursor-tools browser open "https://example.com" --html`
- Default console/network: `cursor-tools browser open "http://localhost:3000/test-logging.html"` (verify console/network logs are captured)
- Disable console/network: `cursor-tools browser open "http://localhost:3000/test-logging.html" --no-console --no-network` (verify logs are not captured)
- Perform action: `cursor-tools browser act "Click on the first link" --url "https://example.com" --model claude-3-7-sonnet-latest`
- Default model: `cursor-tools browser act "Click the submit button" --url "http://localhost:3000/test-form.html" --provider anthropic` (verify claude-3-7-sonnet is used)
- Observe page: `cursor-tools browser observe "What interactive elements are visible?" --url "https://example.com"`
- Extract data: `cursor-tools browser extract "Get all heading text" --url "https://example.com"`

#### State Persistence Test Sequence:
1. `cursor-tools browser open "http://localhost:3000/test-state.html" --connect-to=9222`
2. `cursor-tools browser act "Click the 'Counter' button" --url=current --connect-to=9222` (verify state is maintained)
3. `cursor-tools browser act "Check the counter value" --url=current --connect-to=9222` (verify state persisted from previous action)
4. `cursor-tools browser act "Click the 'Counter' button" --url=reload-current --connect-to=9222` (verify reload works while maintaining connection)
5. `cursor-tools browser act "Check the counter value" --url=current --connect-to=9222` (verify counter was reset after reload)

### 8. MCP Commands
- Test MCP search functionality
- Test MCP run with overrides (recent feature)
- Test different MCP servers
- Test both hardcoded and user-configured overrides

#### Test Cases:
- Search: `cursor-tools mcp search "git operations"`
- Run command: `cursor-tools mcp run "list files in the current directory"`
- Hardcoded override: `cursor-tools mcp run "using google-calendar-mcp list upcoming events"` (testing the eastlondoner fork override)

#### User-Configured Override Test:
1. Temporarily modify `cursor-tools.config.json` to add user override:
   ```json
   {
     "mcp": {
       "overrides": {
         "test-mcp-server": {
           "githubUrl": "https://github.com/example/test-mcp-server",
           "command": "custom-command",
           "args": []
         }
       }
     }
   }
   ```
2. Run: `cursor-tools mcp run "using test-mcp-server perform test action"`
3. Verify that the user-configured override is applied (check logs)
4. Restore original `cursor-tools.config.json`

### 9. Installation and Cursor Rules
- Test cursor rules installation with different environment settings
- Test new `.cursor/rules/cursor-tools.mdc` file creation
- Test legacy `.cursorrules` file creation

#### Test Cases:
- New cursor rules format: `USE_LEGACY_CURSORRULES=false cursor-tools install .` (verify `.cursor/rules/cursor-tools.mdc` is created/updated)
- Legacy cursor rules format: `USE_LEGACY_CURSORRULES=true cursor-tools install .` (verify `.cursorrules` is created/updated)
- Default behavior: `cursor-tools install .` (verify correct file is updated based on default behavior)

## Test Execution Plan
1. Set up environment with all required API keys
2. Start test server for browser testing: `pnpm serve-test`
3. Execute tests for each command category
4. For each test:
   - Document command executed
   - Record output
   - Verify debug output when `--debug` flag is used
   - Verify no stdout output when `--quiet` flag is used
   - Confirm file output when `--save-to` is used
   - Note any errors or unexpected behavior
   - Assess response quality and correctness
5. Test environment cleanup

## Success Criteria

### General Criteria
- All commands execute without unexpected errors
- Output quality meets expectations
- Different providers and models can be successfully used
- Debug output is informative when `--debug` flag is used
- No stdout output occurs when `--quiet` flag is used with `--save-to`
- File output is correct when `--save-to` is used

### Recent Changes Validation
- Claude 3.7 Sonnet model works correctly in all commands (replacing Claude 3.5)
- MCP server overrides (both hardcoded and user-configured) function correctly
- Browser commands with Stagehand 1.13.1 function correctly
- Console and network logs are captured by default in browser commands
- Browser state is maintained correctly when using `--connect-to=current`
- Browser state is reset correctly when using `--connect-to=reload-current`
- Default thinking provider for plan command is OpenAI with o3-mini model
- Cursor rules are installed to the correct location based on `USE_LEGACY_CURSORRULES`
- Error messages are user-friendly and informative across all commands

test-plan.md


# Implementation Plan: Add 'ask' Command

## Overview
Add a new `ask` command endpoint that requires model and provider parameters and a question. The command will use the specified model and provider to answer the question directly.

## Step 1: Create the AskCommand File

Create a new file at `src/commands/ask.ts`:

```typescript
import type { Command, CommandGenerator, CommandOptions } from '../types';
import { loadEnv, loadConfig, defaultMaxTokens } from '../config';
import { createProvider } from '../providers/base';
import { ProviderError, ModelNotFoundError } from '../errors';

export class AskCommand implements Command {
  private config;
  constructor() {
    // Load environment variables and configuration.
    loadEnv();
    this.config = loadConfig();
  }
  async *execute(query: string, options?: CommandOptions): CommandGenerator {
    // Ensure provider was passed, otherwise throw an error.
    const providerName = options?.provider;
    if (!providerName) {
      throw new ProviderError("The 'ask' command requires a provider parameter (e.g. --provider openai).");
    }
    // Ensure model parameter was passed.
    const model = options?.model;
    if (!model) {
      throw new ModelNotFoundError(providerName);
    }
    // Set maxTokens from provided options or fallback to the default.
    const maxTokens = options?.maxTokens || defaultMaxTokens;
    // Create the provider instance.
    const provider = createProvider(providerName);
    let answer: string;
    try {
      // Provide a very simple system prompt.
      answer = await provider.executePrompt(query, {
        model,
        maxTokens,
        systemPrompt: "You are a helpful assistant. Answer the following question directly and concisely.",
      });
    } catch (error) {
      throw new ProviderError(
        error instanceof Error ? error.message : 'Unknown error during ask command execution',
        error
      );
    }
    // Yield the answer as the result.
    yield answer;
  }
}
```

## Step 2: Register the Command

Update `src/commands/index.ts`:

```typescript
import type { CommandMap } from '../types';
import { WebCommand } from './web.ts';
import { InstallCommand } from './install.ts';
import { GithubCommand } from './github.ts';
import { BrowserCommand } from './browser/browserCommand.ts';
import { PlanCommand } from './plan.ts';
import { RepoCommand } from './repo.ts';
import { DocCommand } from './doc.ts';
import { AskCommand } from './ask';  // <-- New Import

export const commands: CommandMap = {
  web: new WebCommand(),
  repo: new RepoCommand(),
  install: new InstallCommand(),
  doc: new DocCommand(),
  github: new GithubCommand(),
  browser: new BrowserCommand(),
  plan: new PlanCommand(),
  ask: new AskCommand(),  // <-- Register new command
};
```

## Step 3: Test and Validate

1. Ensure proper environment variables are set for the selected provider (e.g., OPENAI_API_KEY for OpenAI)
2. Test the command with appropriate flags:
   ```bash
   cursor-tools ask "What is the capital of France?" --provider openai --model o3-mini
   ```
3. Verify that the question is sent to the provider and the response is printed

## Notes

- Both `--provider` and `--model` parameters are required
- The command is intentionally simple and focused on just forwarding the question
- Additional options (e.g., maxTokens) can be passed via CommandOptions
- Error handling is implemented for missing parameters and provider errors

todo.md


🎉 cursor-tools 0.6.0-alpha is here! Your AI teammates just got even smarter. Let me show you what's cooking... 🧵

---

🕵♂ Your browser commands are now like having DevTools on autopilot! Console logs and network activity captured by default:

```bash
cursor-tools browser act "Add pizza to cart" --url=pizzaplace.com
# Now automagically shows you all console logs and network calls!
```

---

🔄 Browser sessions got that smooth jazz feel with improved page reuse:

```bash
cursor-tools browser act "Login" --url=myapp.com --connect-to=current
# Keeps your existing page state, no more starting fresh every time!
```

---

🤝 Introducing the ultimate AI power couple! Mix and match providers:

```bash
cursor-tools repo "Plan new feature" --fileProvider=openai --thinkingProvider=anthropic
# It's like having Batman AND Superman on your team
```

---

🤫 Sometimes you just want the answer without the chit-chat. New --quiet mode has got you covered:

```bash
cursor-tools web "what's 42 * 42?" --quiet
1764
# That's it. That's the tweet.
```

---

📹 Lights, Camera, Automation! Record your browser sessions:

```bash
cursor-tools browser act "Buy concert tickets" --url=ticketmaster.com --video=./recordings
# Never miss a beat in your automation choreography 🎵
```

---

🎯 Pro tip: Chain those browser actions like a boss:

```bash
cursor-tools browser act "Click Login | Type 'cool.dev@example.com' into email | Smash that Submit button" --url=devsite.com
# One command to rule them all!
```

---

🚀 Ready to upgrade your AI team?

```bash
cursor-tools web "Should I try these new features?"
# Spoiler alert: Yes, yes you should!
```

Get it now at https://github.com/getcursor/cursor-tools

#AI #DevTools #OpenSource #CursorTools

tweets.md


Querying perplexity using sonar-pro for: Angular vs React in 2024 with maxTokens: 8000
In 2024, both Angular and React remain popular choices for front-end development, each with its own strengths and use cases. Here's a comprehensive comparison of Angular vs React in 2024:

## Architecture and Purpose

**Angular:**
- Full-fledged structural framework based on TypeScript[1]
- Designed for developing dynamic web apps and complex enterprise-grade applications[1][3]
- Enforces a structured MVC (Model-View-Controller) architecture[2]

**React:**
- JavaScript-based library focused on building interactive UI components[1]
- Component-based architecture - flexible and modular[2]
- Ideal for creating reusable UI elements and interactive interfaces[1][3]

## Performance

**Angular:**
- High performance, but can slow down as the number of data bindings increases[2]
- Optimizes page loading through 'tree-shaking' technique[3]
- Uses real DOM, which can be slower for large-scale applications[1]

**React:**
- Generally faster due to its virtual DOM implementation[1][2]
- Efficient rendering and update process, especially for large applications[3]
- Smaller bundle size contributes to faster load times[1]

## Data Binding and State Management

**Angular:**
- Two-way data binding, simplifying model-view synchronization[1][3]
- Built-in state management solutions[3]

**React:**
- One-way data flow from parent to child components[2][3]
- Requires additional libraries like Redux for complex state management[1]

## Learning Curve and Development Experience

**Angular:**
- Steeper learning curve due to its comprehensive framework nature[1][4]
- TypeScript knowledge is recommended[2]

**React:**
- Easier to learn and quicker to get started with[1][4]
- More flexible, allowing developers to choose their preferred tools and libraries[3]

## Community and Ecosystem

**React:**
- Larger community with over 222k stars on GitHub (as of May 2024)[2]
- Extensive ecosystem of third-party libraries and tools[3]

**Angular:**
- Strong but smaller community compared to React[2]
- Comprehensive built-in solutions reducing the need for external libraries[3]

## Use Cases

**Angular:**
- Ideal for large-scale enterprise applications[1][3]
- Well-suited for complex projects requiring a rigorous structure[3]
- Good for developing progressive web apps and single-page applications[1]

**React:**
- Excellent for building interactive and dynamic user interfaces[1][3]
- Preferred for projects requiring high performance and quick loading[3]
- Suitable for both small and large-scale applications[1]

## Popularity and Job Market

- React continues to dominate in terms of developer usage and job opportunities[2][7]
- Angular remains a strong choice, especially in enterprise environments[7]

## Conclusion

In 2024, the choice between Angular and React depends on your project requirements, team expertise, and specific use case:

- Choose **Angular** if you need a full-fledged framework for large, complex enterprise applications with a structured architecture.

- Opt for **React** if you prioritize flexibility, performance, and want to build interactive UIs with a gentler learning curve.

Both frameworks continue to evolve and maintain their relevance in the web development landscape. The decision should be based on your project's specific needs, your team's skills, and the long-term goals of your application.

web-compare.md