> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braingrid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with Cursor

> How to use BrainGrid and Cursor together

The Cursor integration provides three powerful components:

* **Slash Commands** - Quick commands for creating specs and breaking down work
* **Always-On Rules** - Automatic BrainGrid context without manual activation
* **AGENTS.md Integration** - Persistent workflow guidance throughout your Cursor session

## Installation

<Steps>
  <Step title="Install BrainGrid CLI">
    Install the CLI globally:

    ```bash theme={null}
    npm install -g @braingrid/cli
    ```
  </Step>

  <Step title="Authenticate">
    Log in to your BrainGrid account:

    ```bash theme={null}
    braingrid login
    ```
  </Step>

  <Step title="Initialize Your Project">
    Link your project to BrainGrid:

    ```bash theme={null}
    braingrid init
    ```
  </Step>

  <Step title="Install Cursor Integration">
    Set up slash commands, rules, and AGENTS.md:

    ```bash theme={null}
    braingrid setup cursor
    ```
  </Step>
</Steps>

## What Gets Installed

The setup command installs four key components:

### Slash Commands

Located in `.cursor/commands/`, these commands provide quick access to BrainGrid features:

| Command             | Description                                                               | Example                              |
| ------------------- | ------------------------------------------------------------------------- | ------------------------------------ |
| `/specify`          | Create AI-refined requirement from vague idea                             | `/specify Add user auth with OAuth2` |
| `/save-requirement` | Save a Cursor plan as a requirement                                       | `/save-requirement`                  |
| `/breakdown`        | Break requirement into perfectly-prompted tasks                           | `/breakdown REQ-123`                 |
| `/build`            | Get complete implementation plan with all task prompts in markdown format | `/build REQ-123`                     |

In Cursor's Agent input type `/` to see all available commands. BrainGrid commands appear alongside Cursor's built-in commands.

### Always-On Rules

Located in `.cursor/rules/braingrid.mdc`, this file teaches Cursor about BrainGrid automatically:

* **No explaining needed** - Cursor already knows what BrainGrid is
* **Context-aware responses** - Cursor understands PROJ-X, REQ-Y, TASK-Z references
* **Workflow guidance** - Cursor suggests next steps in the BrainGrid workflow
* **Better task execution** - Cursor follows BrainGrid task prompts more accurately

The rules are always active (`alwaysApply: true`) - no manual activation required.

### AGENTS.md Integration

Located at your repository root, this file provides BrainGrid guidance:

* **Automatically loaded** - No manual activation needed
* **Persistent context** - Available throughout your Cursor session
* **Consistent guidance** - Same BrainGrid workflow across all projects

## Typical Workflow

Here's how to use BrainGrid with Cursor:

<Steps>
  <Step title="Create Specification">
    In Cursor Agent, start with a vague idea and let AI refine it:

    ```bash Cursor theme={null}
    /specify Add dark mode toggle in settings with theme persistence
    ```

    This creates a structured requirement with clear scope and acceptance criteria.
  </Step>

  <Step title="Break Down into Tasks">
    Convert the requirement into AI-ready tasks:

    ```bash Cursor theme={null}
    /breakdown REQ-1
    ```

    This generates 5-10 focused tasks with clear prompts optimized for Cursor.
  </Step>

  <Step title="Create Feature Branch">
    Create a git branch to enable auto-detection:

    ```bash Cursor theme={null}
    git checkout -b feature/REQ-1-dark-mode
    ```

    BrainGrid automatically detects `REQ-1` from your branch name.
  </Step>

  <Step title="Get Build Plan">
    In Cursor Agent, get the complete implementation plan to start building:

    ```bash Cursor theme={null}
    /build REQ-1
    ```

    This provides all task details in markdown format, perfect for Cursor.
  </Step>
</Steps>

## MCP Server Installation

Prefer native tool integration? Install BrainGrid as an MCP server:

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=braingrid&config=eyJ1cmwiOiJodHRwczovL21jcC5icmFpbmdyaWQuYWkvbWNwIiwidHJhbnNwb3J0IjoiaHR0cFN0cmVhbSJ9">
  <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add braingrid MCP server to Cursor" height="32" />
</a>

See the [MCP vs CLI](#mcp-vs-cli) section below to choose the right approach, and visit the [MCP Server documentation](/mcp-server/installation) for detailed installation instructions.

### MCP vs CLI

#### Prefer the CLI when:

* Don't want to bloat your context with more MCP servers.
* Speed matters, the CLI calls end up being faster than the MCP calls.
* You need to script custom workflows.

#### Prefer the MCP when:

* When you are in an environment that does not support the CLI.
* You are more comfortable with the MCPs than CLIs

<Note>
  **Choose one or the other, not both** - MCP and CLI are alternative approaches to integrating BrainGrid with Cursor. Select the approach that best fits your workflow.
</Note>

## Tips for Effective Use

### Writing Good Prompts for `/specify`

Include these elements for best results:

* **Problem** - What are you trying to solve?
* **Context** - Why is this needed? What's the background?
* **Constraints** - Any technical or business limitations?
* **Users** - Who will use this feature?
* **Success Criteria** - How will you know it's done?

**Example:**

```bash Cursor theme={null}
/specify Add user authentication for our web app. We need OAuth2 support
for Google and GitHub. Must work with our existing Express backend and
React frontend. Users should stay logged in for 30 days. Success means
users can sign up and log in without creating passwords.
```

### Using Additional Instructions with `/build`

Provide specific guidance for task implementation:

```bash Cursor theme={null}
/build REQ-123 Use TypeScript for all new code.
Follow the existing repository pattern in src/repositories/.
Include unit tests for all business logic.
```

### Git Branch Workflow

Name your branches with the requirement ID for automatic detection:

```bash theme={null}
# Good - auto-detects REQ-42
git checkout -b feature/REQ-42-stripe-integration

# Also works
git checkout -b fix/REQ-42-payment-bug
git checkout -b REQ-42-any-description

# Won't auto-detect
git checkout -b add-stripe-payments
```

## Learn More

<CardGroup cols={2}>
  <Card title="CLI Command Reference" icon="book" href="/cli/commands">
    Complete reference for all CLI commands
  </Card>

  <Card title="MCP Server Docs" icon="plug" href="/mcp-server/overview">
    Alternative tool-based integration
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/braingridai/braingrid-cli">
    View source code and contribute
  </Card>

  <Card title="BrainGrid Web App" icon="globe" href="https://app.braingrid.ai">
    Manage projects in the browser
  </Card>
</CardGroup>