# eastlondoner/cursor-tools architecture

> Architecture diagram of the GitHub repository eastlondoner/cursor-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eastlondoner/cursor-tools
- Repository: https://github.com/eastlondoner/cursor-tools

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        CLI["CLI Dispatcher"]:::internal
        subgraph "Command Modules"
            BCM["Browser Commands Module"]:::module
            GCM["GitHub Commands Module"]:::module
            DOC["Documentation Module"]:::module
            REP["Repomix Module"]:::module
        end
    end

    %% Configuration and Integration
    subgraph "Configuration & Integration"
        CONF["Config File"]:::config
        ENV["Env File"]:::config
        CI["Cursor Integration"]:::config
    end

    %% External Services
    subgraph "External Services"
        PAPI["Perplexity API"]:::external
        GAPI["Google Gemini API"]:::external
        PLAY["Playwright Automation"]:::external
        GHAPI["GitHub API"]:::external
    end

    %% Connections from CLI
    CLI -->|"loadsConfig"| CONF
    CLI -->|"loadsEnv"| ENV
    CLI -->|"loadsRules"| CI

    CLI -->|"routesTo"| BCM
    CLI -->|"routesTo"| GCM
    CLI -->|"routesTo"| DOC
    CLI -->|"routesTo"| REP

    %% Module to External Services Relationships
    BCM -->|"uses"| PLAY
    BCM -->|"calls"| PAPI
    BCM -->|"calls"| GAPI

    GCM -->|"interactsWith"| GHAPI

    %% Optional internal relation between Documentation and Repomix modules
    DOC -->|"integrates"| REP

    %% Click Events for Component Mapping
    click CLI "https://github.com/eastlondoner/cursor-tools/blob/main/src/index.ts"
    click BCM "https://github.com/eastlondoner/cursor-tools/tree/main/src/commands/browser"
    click GCM "https://github.com/eastlondoner/cursor-tools/tree/main/src/commands/github"
    click DOC "https://github.com/eastlondoner/cursor-tools/blob/main/src/commands/doc.ts"
    click REP "https://github.com/eastlondoner/cursor-tools/tree/main/src/repomix"
    click CONF "https://github.com/eastlondoner/cursor-tools/blob/main/cursor-tools.config.json"
    click ENV "https://github.com/eastlondoner/cursor-tools/blob/main/.cursor-tools.env.example"
    click CI "https://github.com/eastlondoner/cursor-tools/blob/main/.cursor/rules/cursor-tool.mdc"

    %% Styles
    classDef internal fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef module fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef config fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef external fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
```
