How eastlondoner/cursor-tools works
Project Type and Purpose
• The project is a Node.js CLI tool that extends the capabilities of an AI coding agent (i.e. the Cursor Composer Agent). It integrates multiple external services (web search via Perplexity, large-codebase context via Gemini, browser automation via Stagehand, and GitHub issue/PR management) and helps generate local documentation.
• The README emphasizes “AI teamwork” and shows that the tool is both modular and extensible, providing various command modules tailored for different tasks (browser commands, GitHub integration, documentation generation, etc.).
File Structure
• Top Level – Besides configuration files (.gitignore, LICENSE, tsconfig.json, package.json, etc.), the main directories include:
• .cursor & .cursorrules: These files are used to integrate with Cursor’s runtime rules.
• local-docs: Where auto-generated documentation is placed.
• scripts: Contains release and stagehand verification logic.
• src: Contains the primary source code, organized into several subdirectories such as:
▫ commands/ – Further split into browser, GitHub, and other CLI command implementations.
▫ repomix – Configuration for repository context generation.
▫ utils and types – Shared utilities and type definitions.
• The tests and test-videos directories suggest that there is extensive testing (especially for browser automation and video recording features).
a. Main Components:
• CLI Entry Point:
• Main command entry point (src/index.ts) which routes and invokes various commands.
• Command Modules:
• Browser Commands Module: (src/commands/browser) – handles operations like open, act, observe, and extract. It further calls Stagehand functions for browser automation.
• GitHub Commands Module: (src/commands/github) – takes care of GitHub authentication, issue/pr handling, and interactions.
• Documentation & Repo Context Module: (src/commands/doc, src/repomix) – generates documentation using repomix and interacts with external repositories.
• Other Command Modules: (e.g., install, repo, doc) that integrate the core CLI operations.
• Configuration and Environment Management:
• Config file (cursor-tools.config.json) and environment variables (.cursor-tools.env or .env file samples) for API keys and settings.
• External Services and APIs:
• Perplexity API: For web search and research commands.
• Google Gemini API: For handling projects requiring a very high token context.
• GitHub API: For integration with GitHub issues and pull requests.
• Playwright: For browser automation (Stagehand uses this for command execution).
b. Relationships and Interactions:
• The CLI’s central dispatcher (the “Command Processor”) invokes different command modules based on user input.
• Each module (for browser or GitHub tasks) interacts with external services:
• E.g., the Browser Commands module uses Playwright for automation and then relays commands to either Gemini or Perplexity APIs for further processing.
• Configuration components ensure that API keys and external service endpoints are correctly injected for each command module.
• There is an integration flow between the AI agent (via Cursor integration) and the CLI tool. This is facilitated through rules files (e.g., .cursor/rules/cursor-tool.mdc).
c. Architectural Patterns and Design Principles:
• Modularity: Each command is isolated in its directory (e.g., browser commands are in one module, GitHub commands in another).
• Separation of Concerns: The project clearly separates command logic, configuration, type definitions, and external integrations.
• Extensibility: The architecture is built so that new functionality (e.g., additional commands or integrations) can be added with minimal changes to the core dispatcher.
• Dependency Injection / Configuration Management: External API keys and settings are loaded from configuration files and environment variables which keep secrets and custom settings decoupled from logic.
d. Relevant Technologies & Frameworks:
• Node.js (runtime environment).
• TypeScript (observed from .ts file extensions and tsconfig.json).
• Playwright for browser interaction.
• External APIs: Perplexity, Google Gemini, and GitHub.
• Command-line interfaces (CLI design) as an integration pattern for AI-based commands.
• Repomix for repository context generation.
Specific Elements
• CLI Dispatcher (entry point)
• Browser Commands Module (with sub-components if needed that illustrate Stagehand, browser utilities)
• GitHub Commands Module
• Documentation/Repo Context Module (Repomix integration)
• Config & Environment Module (cursor-tools.config.json and .env files)
• External Services: Perplexity API, Google Gemini API, GitHub API, Playwright.