Skip to main content
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

1

Install BrainGrid CLI

Install the CLI globally:
npm install -g @braingrid/cli
2

Authenticate

Log in to your BrainGrid account:
braingrid login
3

Initialize Your Project

Link your project to BrainGrid:
braingrid init
4

Install Cursor Integration

Set up slash commands, rules, and AGENTS.md:
braingrid setup cursor

​
What Gets Installed

The setup command installs four key components:

​
Slash Commands

Located in .cursor/commands/, these commands provide quick access to BrainGrid features:
CommandDescriptionExample
/specifyCreate AI-refined requirement from vague idea/specify Add user auth with OAuth2
/save-requirementSave a Cursor plan as a requirement/save-requirement
/breakdownBreak requirement into perfectly-prompted tasks/breakdown REQ-123
/buildGet 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:
1

Create Specification

In Cursor Agent, start with a vague idea and let AI refine it:
Cursor
/specify Add dark mode toggle in settings with theme persistence
This creates a structured requirement with clear scope and acceptance criteria.
2

Break Down into Tasks

Convert the requirement into AI-ready tasks:
Cursor
/breakdown REQ-1
This generates 5-10 focused tasks with clear prompts optimized for Cursor.
3

Create Feature Branch

Create a git branch to enable auto-detection:
Cursor
git checkout -b feature/REQ-1-dark-mode
BrainGrid automatically detects REQ-1 from your branch name.
4

Get Build Plan

In Cursor Agent, get the complete implementation plan to start building:
Cursor
/build REQ-1
This provides all task details in markdown format, perfect for Cursor.

​
MCP Server Installation

Prefer native tool integration? Install BrainGrid as an MCP server: Add braingrid MCP server to Cursor See the MCP vs CLI section below to choose the right approach, and visit the MCP Server documentation 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
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.

​
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:
Cursor
/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:
Cursor
/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: 
# 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

CLI Command Reference

Complete reference for all CLI commands

MCP Server Docs

Alternative tool-based integration

GitHub Repository

View source code and contribute

BrainGrid Web App

Manage projects in the browser