BrainGrid

The AI Product Planner

BrainGrid is the AI Product Planner that helps you shape ideas, plan features, and scope tasks that your AI coding tools can build right the first time.

BrainGrid helps you turn half-baked thoughts into build-ready specs and perfectly-prompted tasks that AI coding agents like Cursor, or Claude Code, build fast without breaking things.

BrainGrid CLI is the command-line interface for managing your requirements, and tasks on the BrainGrid platform.

• ✨ Specify Requirements - Create build-ready requirement documents from messy ideas
• 🎯 Break Down into Tasks - Create perfectly-prompted tasks from requirements
• 🤖 Build with AI Agents - Get an implementation plan with prompts for each task to feed to Cursor, Claude Code, and other AI coding tools
• 📊 Track Progress - Manage and update task statuses
• 💾 Multiple Output Formats - View task prompts as formatted tables, JSON, Markdown, or XML for scripting

npm install -g @braingrid/cli

braingrid setup claude-code

Installs slash commands (/specify, /breakdown, /build), BrainGrid skill, and status line showing your project/requirement/task context in real-time.

→ Full Claude Code setup guide

braingrid setup cursor

Installs slash commands, always-on rules, and AGENTS.md integration for seamless BrainGrid workflows in Agent mode.

→ Full Cursor setup guide

# 1. Initialize your project
braingrid init

# 2. Create a requirement with AI refinement
braingrid specify --prompt "Add user authentication"

# 3. Break down requirement into tasks with AI
braingrid requirement breakdown REQ-1

# 4. Build requirement with all tasks (markdown with full content)
braingrid requirement build REQ-1

BrainGrid CLI uses a resource-oriented command structure: braingrid <resource> <action> [options]

braingrid login
braingrid whoami
braingrid logout

Initialize your repository with a BrainGrid project. The command will show you the detected project and ask for confirmation before proceeding:

# Step-by-step wizard to initialize your project
braingrid init

# Manually specify project by ID (short ID or UUID)
braingrid init --project PROJ-123

# Skip wizard and force reinitialization (useful for scripts)
braingrid init --force
braingrid init --project PROJ-123 --force

The init command creates a .braingrid/project.json file in the .braingrid/ directory. This tells the CLI what project it is working on so you don't have to pass it as a parameter.

Note: The init command always asks for confirmation before initializing unless you use the --force flag.

Install BrainGrid integration files for AI coding tools. These commands fetch integration files from the BrainGrid repository and install them in your project.

For detailed usage guides, see Claude Code setup or Cursor setup.

Prerequisites:

• GitHub CLI must be installed and authenticated
  • macOS: brew install gh
  • Windows: winget install GitHub.CLI
  • Linux: See GitHub CLI installation
  • After installing: gh auth login

Commands:

# Install Claude Code integration
braingrid setup claude-code

# Install Cursor integration
braingrid setup cursor

# Skip prompts and overwrite all existing files
braingrid setup claude-code --force

# Preview changes without making modifications
braingrid setup cursor --dry-run

What gets installed:

• Claude Code integration:

  • Commands in .claude/commands/ (specify, breakdown, build, save-requirement)
  • Skills in .claude/skills/braingrid-cli/
  • Status line script at .claude/statusline.sh
  • Hook script at .claude/hooks/sync-braingrid-task.sh for task status sync
  • Settings in .claude/settings.json (configures status line and hooks)
  • Content injected into CLAUDE.md (or creates it if it doesn't exist)

• Cursor integration:

  • Commands in .cursor/commands/ (specify, breakdown, build, save-requirement)
  • Rules in .cursor/rules/
  • Content injected into AGENTS.md (or creates it if it doesn't exist)

Options:

• --force - Skip prompts and overwrite all existing files without asking
• --dry-run - Show what would be done without making any changes

File Conflicts:

When files already exist, you'll be prompted to choose:

• [O]verwrite - Replace this file
• [S]kip - Keep existing file
• [A]ll - Overwrite all remaining files
• [Q]uit - Cancel installation

Marker-based Updates:

Running setup again will update the BrainGrid sections in CLAUDE.md or AGENTS.md without duplicating content. The CLI uses HTML comment markers to identify and replace existing BrainGrid content.

Learn more:

• Claude Code integration guide
• Cursor integration guide

braingrid project list [--format json] [--page 1] [--limit 20]
braingrid project show
braingrid project show [<id>] [--repository "owner/repo"]
braingrid project create --name "Project Name" [--description "Description"] [--repository-id <uuid>] [--repository "owner/name"]
braingrid project update <id> [--name "New Name"] [--description "New Description"]
braingrid project delete <id> [--force]

Note: project show displays the initialized project from your workspace when called without arguments. Use --repository "owner/repo" to list all projects for a specific repository, or provide a project ID directly to view a specific project.

Note: When creating a project, you can optionally link it to a repository using --repository-id <uuid> to link by repository UUID, or --repository "owner/name" (e.g., --repository "microsoft/vscode") to link by repository name. If --repository-id is provided, it takes precedence.

# Create requirement with AI refinement (specify command)
# With auto-detected project from workspace:
braingrid specify --prompt "Add user authentication with OAuth2"

# Specify project explicitly:
braingrid specify -p PROJ-123 --prompt "Implement real-time notifications"

# Output in different formats:
braingrid specify --prompt "Add dark mode support" --format json
braingrid specify --prompt "Add export feature" --format markdown
braingrid specify --prompt "Add search" --tags "search,backend"

# Working with the initialized project
braingrid requirement list [--status IDEA|PLANNED|IN_PROGRESS|REVIEW|COMPLETED|CANCELLED] [--tree] [--format json]
braingrid requirement create --name "Name" [--content "Description"] [--assigned-to <uuid>] [--tags "tag1,tag2"]
braingrid requirement show [id]
braingrid requirement update [id] [--status IDEA|PLANNED|IN_PROGRESS|REVIEW|COMPLETED|CANCELLED] [--name "New Name"] [--content "markdown"]
braingrid requirement delete [id] [--force]
braingrid requirement breakdown [id] [--format markdown|json|xml]
braingrid requirement build [id] [--format markdown|json|xml]
braingrid requirement create-branch [id] [--name <branch-name>] [--base <branch>]
braingrid requirement review [id] [--pr <number>]

# Tag management
braingrid requirement tag list [id]
braingrid requirement tag add [id] --name "Tag" --color "#FF0000"
braingrid requirement tag remove [id] --name "Tag"

# Working with a different project:
braingrid requirement list -p PROJ-456 [--status PLANNED]
braingrid requirement create -p PROJ-456 --name "Description"

Note: The -p/--project parameter is optional when working in an initialized repository. Use it to work with a different project.

Note: For the specify command, the prompt must be between 10-5000 characters. The AI will refine your prompt into a detailed requirement document.

Note: The -r/--requirement parameter is optional and accepts formats like REQ-456, req-456, or 456. The CLI will automatically detect the requirement ID from your git branch name (e.g., feature/REQ-123-description or REQ-123-fix-bug) if it is not provided.

Note: The requirement list command displays requirements with their status, name, branch (if assigned), and progress percentage.

Note: The create-branch command creates a GitHub branch for a requirement. It auto-generates a branch name in the format {username}/REQ-123-slug if not provided.

Note: The review command runs an AI-powered acceptance review on a pull request, validating it against the requirement's acceptance criteria. It auto-detects the PR number from the current branch if not provided.

# Working with the initialized project
braingrid task list -r REQ-456 [--format table|json|xml|markdown]
braingrid task create -r REQ-456 --title "Task Title" [--content "Description"] [--external-id <id>]
braingrid task show [id]
braingrid task update [id] [--status PLANNED|IN_PROGRESS|COMPLETED|CANCELLED] [--title "New Title"] [--external-id <id>]
braingrid task summary -r REQ-456
braingrid task specify -r REQ-456 --prompt "Task description"
braingrid task delete <id> [--force]

# Working with a different project:
braingrid task list -p PROJ-123 -r REQ-456
braingrid task create -p PROJ-123 -r REQ-456 --title "Task Title"

Note: The -p/--project parameter is optional when working in an initialized repository. Use it to work with a different project.

Note: The -r/--requirement parameter is optional and accepts formats like REQ-456, req-456, or 456. The CLI will automatically detect the requirement ID from your git branch name (e.g., feature/REQ-123-description or REQ-123-fix-bug) if it is not provided.

Note: Task status values are: PLANNED, IN_PROGRESS, COMPLETED, CANCELLED (tasks do not have IDEA or REVIEW status).

Note: task summary shows a compact overview table (number, status, title) without full content — useful for quick progress checks.

Note: task specify creates a single AI-generated task from a prompt (10-5000 characters), similar to how specify creates requirements.

Note: The requirement tag commands manage tags on requirements. Each requirement can have up to 5 tags. Tags require a name and hex color code (e.g., #FF0000).

Note: --external-id links tasks to external systems (e.g., Claude Code task IDs) for status synchronization.

braingrid status       # Show CLI status (authentication, git repo, configuration)
braingrid --version    # Show CLI version
braingrid --help       # Show help information

BrainGrid CLI supports tab completion for bash and zsh shells, making it faster to type commands and discover available options.

Automatically install completion for your current shell:

braingrid completion --setup

Then restart your terminal or source your shell config:

# For bash
source ~/.bashrc

# For zsh
source ~/.zshrc

Add to your ~/.bashrc:

# Option 1: Add to shell config
braingrid completion bash >> ~/.bashrc

# Option 2: Eval in current session (temporary)
eval "$(braingrid completion bash)"

Add to your ~/.zshrc:

# Option 1: Add to shell config
braingrid completion zsh >> ~/.zshrc

# Option 2: Eval in current session (temporary)
eval "$(braingrid completion zsh)"

• Commands: login, logout, project, requirement, task, etc.
• Subcommands: list, show, create, update, delete, breakdown, build, create-branch, review, summary, specify, tag
• Options: --help, --format, --status, --project, --requirement
• Values: Status values (IDEA, PLANNED, IN_PROGRESS, etc.), format options (table, json, xml, markdown)

Fish shell support is planned for a future release.

Update to the latest version:

braingrid update          # Update to the latest version
braingrid update --check  # Check for updates without installing

Join the BrainGrid community to connect with other AI builders, share workflows, and get help:

• BrainGrid Community

• BrainGrid
• Documentation
• BrainGrid MCP
• npm package