cursor-tools-wsl
Advanced tools
cursor-tools-wsl is a modified version of cursor-tools that focuses on providing seamless WSL support. It allows your AI agent to work effectively across Windows and Linux environments when using WSL.
Run the interactive setup:
# Using npm
npm install -g cursor-tools-wsl
# Or using npx without installation
npx cursor-tools-wsl@latest install .
This command will:
cursor-tools-wsl as a dev dependency in your package.jsonnpm install --global playwright)act, extract, and observe commands)Automatic path translation between Windows and WSL environments:
# In Windows
cursor-tools-wsl repo "explain this file: /mnt/c/projects/myapp/src/index.js"
# In WSL
cursor-tools-wsl repo "explain this file: C:\\projects\\myapp\\src\\index.js"
Seamless command execution in both Windows and WSL:
# Commands work the same way in both environments
cursor-tools-wsl web "search query"
cursor-tools-wsl repo "explain code"
cursor-tools-wsl browser "test webpage"
cursor-tools is optimized for Cursor Composer Agent but it can be used by any coding agent that can execute commands
After installation, to see AI teamwork in action just ask Cursor Composer to use Perplexity or Gemini. Here are two examples:
cursor-tools provides a CLI that your AI agent can use to expand its capabilities. cursor-tools works with with Cursor (and is compatible with other agents), When you run cursor-tools install we automatically add a prompt section to your Cursor project rules (.cursor/rules/cursor-tools.mdc or legacy .cursorrules file) so that it works out of the box with Cursor, there's no need for additional prompts.
cursor-tools requires a Perplexity API key and a Google AI API key.
cursor-tools is an node package. You can install it globally, at a node project level or run without installation using npx.
If you do something cool with cursor-tools please let me know on twitter or make a PR to add to this section!
To see cursor-tools GitHub and Perplexity skills: Check out this example issue that was solved using Cursor agent and cursor-tools
See cursor get approximately 5x more work done per-prompt with Gemini code review:
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.
Examples usages:
"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.
"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 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 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 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.
cursor-tools requires API keys for both Perplexity AI and Google Gemini. These can be configured in two ways:
cursor-tools install and follow the prompts~/.cursor-tools/.env in your home directory or .cursor-tools.env in your project root:
PERPLEXITY_API_KEY="your-perplexity-api-key"
GEMINI_API_KEY="your-gemini-api-key"
Use Perplexity AI to get up-to-date information directly within Cursor:
cursor-tools web "What's new in TypeScript 5.7?"
Leverage Google Gemini 2.0 models with 1M+ token context windows for codebase-aware assistance:
cursor-tools repo "Explain the authentication flow in this project, which files are involved?"
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.
Automate browser interactions for web scraping, testing, and debugging:
Important: The browser command requires the Playwright package to be installed separately in your project:
npm install playwright
# or
yarn add playwright
# or
pnpm add playwright
open - Open a URL and capture page content:# 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
act - Execute actions using natural language - Agent tells the browser-use agent what to do:# 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"
observe - Analyze interactive elements:# 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"
extract - Extract data using natural language:# 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
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 commandsNotes on Connecting to an existing browser session with --connect-to
--connect-to, viewport is only changed if --viewport is explicitly provided--connect-to--connect-to values:
current: Use the existing page without reloadingreload-current: Use the existing page and refresh it (useful in development)All browser commands support video recording of the browser interaction in headless mode (not supported with --connect-to):
--video=<directory> to enable recordingExample:
# 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 logs and network activity are captured by default:
--no-console to disable console logging--no-network to disable network loggingThe act command supports chaining multiple actions using the pipe (|) separator:
# 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"
Common issues and solutions:
Element Not Found Errors
--no-headless to visually debug the pagebrowser observe to see what elements Stagehand can identify--timeout)Stagehand API Errors
--modelNetwork Errors
--timeoutVideo Recording Issues
--connect-toPerformance Issues
--headless mode for better performance (default)--viewport--connect-to for developmentAccess GitHub issues and pull requests directly from the command line with rich formatting and full context:
# 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:
Authentication Methods: The commands support multiple authentication methods:
GITHUB_TOKEN=your_token_heregh is installed and logged in)Without authentication:
With authentication:
Generate comprehensive documentation for your repository or any GitHub repository:
# Document local repository
cursor-tools doc --output=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"
Customize cursor-tools behavior by creating a cursor-tools.config.json file:
{
"perplexity": {
"model": "sonar-pro",
"maxTokens": 8000
},
"gemini": {
"model": "gemini-2.0-pro-exp-02-05",
"maxTokens": 10000
},
"tokenCount": {
"encoding": "o200k_base"
},
"browser": {
"defaultViewport": "1280x720",
"timeout": 30000,
"stagehand": {
"env": "LOCAL",
"headless": true,
"verbose": 1,
"debugDom": false,
"enableCaching": false,
"model": "claude-3-5-sonnet-latest", // For Anthropic provider
"provider": "anthropic", // or "openai"
"timeout": 30000
}
}
}
The configuration supports:
perplexity.model: Perplexity AI model to useperplexity.maxTokens: Maximum tokens for Perplexity responsesgemini.model: Google Gemini model to usegemini.maxTokens: Maximum tokens for Gemini responsestokenCount.encoding: Tokenizer to use for counting tokens (defaults to o200k_base which is optimized for Gemini)browser.defaultViewport: Default viewport size for browser commandsbrowser.timeout: Default timeout for browser commandsbrowser.stagehand.env: Environment for browser commandsbrowser.stagehand.headless: Whether to run browser in headless modebrowser.stagehand.verbose: Verbosity level for browser commandsbrowser.stagehand.debugDom: Whether to enable debug output for browser commandsbrowser.stagehand.enableCaching: Whether to enable caching for browser commandsbrowser.stagehand.model: The default model to use. See "Model Selection" below.browser.stagehand.provider: The AI provider to use ("openai" or "anthropic"). Determines which API key is required.browser.stagehand.timeout: Timeout for operations in millisecondsThe GitHub commands support several authentication methods:
Environment Variable: Set GITHUB_TOKEN in your environment:
GITHUB_TOKEN=your_token_here
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.
Git Credentials: If you have authenticated git with GitHub (via HTTPS), cursor-tools will automatically:
ghp_ or gho_)To set up git credentials:
git config --global url."https://github.com/".insteadOf git@github.com:
git config --global credential.helper store # Permanent storage
# Or for macOS keychain:
git config --global credential.helper osxkeychain
Authentication Status:
Without authentication:
With authentication (any method):
cursor-tools will automatically try these authentication methods in order:
GITHUB_TOKEN environment variablegh is installed and logged in)If no authentication is available, it will fall back to unauthenticated access with rate limits.
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/, packages/, etc.)dist/, build/, etc.).git/)test/, tests/, __tests__/, etc.).env, .config, etc.)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.
The browser commands support different AI models for processing. You can select the model using the --model option:
# Use gpt-4o
cursor-tools browser act "Click Login" --url "https://example.com" --model=gpt-4o
# Use Claude 3.5 Sonnet
cursor-tools browser act "Click Login" --url "https://example.com" --model=claude-3-5-sonnet-latest
You can set a default provider in your cursor-tools.config.json file under the stagehand section:
{
"stagehand": {
"provider": "openai", // or "anthropic"
}
}
You can also set a default model in your cursor-tools.config.json file under the stagehand section:
{
"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:
o3-miniclaude-3-5-sonnet-latestAvailable models depend on your configured provider (OpenAI or Anthropic) in cursor-tools.config.json and your API key.
cursor-tools automatically configures Cursor by updating your project rules during installation. This provides:
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.
To get the benefits of cursor-tools you should use Cursor agent in "yolo mode". Ideal settings:
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.
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)--help: View all available options (help has not been implemented for all commands yet)Documentation command specific options:
--from-github: Generate documentation for a remote GitHub repository (supports @branch syntax)GitHub command specific options:
--from-github: Access PRs/issues from a specific GitHub repository (format: owner/repo)--repo: Alternative to --from-github, does the same thing (format: owner/repo)Execute commands in several ways:
# Global installation
cursor-tools web "query"
# without global installation
npx -y cursor-tools@latest web "query"
Command Not Found
cursor-tools is installed (globally or as a dev dependency)API Key Errors
.cursor-tools.env exists and contains valid API keyscursor-tools install to reconfigure API keysModel Errors
GitHub API Rate Limits
GITHUB_TOKEN=your_token_here
Documentation Generation Issues
--hint to focus on specific partsCursor Integration
cursor-tools install . to update# 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"
# 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?"
# Document specific aspects
cursor-tools doc --hint="Focus on the API endpoints and their usage"
# Document with custom output
cursor-tools doc --save-to=docs/architecture.md --hint="Focus on system architecture"
# Document dependencies
cursor-tools doc --from-github=expressjs/express --save-to=docs/EXPRESS.md
# 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
open subcommand examples:# 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:# 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"
cursor-tools is available on npm here
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.
Optimise your Vinted accounting with real-time analytics, inventory management, and tax compliance tools.
:link: Start scaling your Vinted business today
Automate your Vinted reselling business with advanced tools like autobuy, custom snipers, and one-click relisting.
:link: Take Vinted reselling to the next level
Build self-driving startups with autonomous AI agents that run your company.
:link: AI Engineer in London? Join the startup revolution
MIT License - see LICENSE for details.
FAQs
CLI tools for AI agents with WSL support
We found that cursor-tools-wsl demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.