Cursor Ruler is a self-hosted Github App that uses your team's PR comments and feedback to generate and manage Cursor rules files, turning Cursor into a collaborative force multiplier for your entire engineering team. 3 Minutes from git clone to production—give it a try!
Watch a quick demo.
Cursor rules are instructions that customize AI behavior in the Cursor. They function as specialized system prompts for the underlying language models, helping to control how AI responds in different contexts:
- Project Rules: Stored in the
.cursor/rulesdirectory, these provide granular control with file pattern matching using glob patterns - Semantic Descriptions: Each rule includes a description of when it should be applied
- Automatic Attachment: Rules can be automatically included when matching files are referenced
Cursor Ruler helps teams collaboratively develop these rules by capturing best practices and repository-specific instructions from PR comments, turning them into a cohesive set of rules that improve AI interactions across your codebase. This transforms Cursor from a powerful individual developer tool into a collaborative force multiplier for your entire engineering team.
Cursor Ruler streamlines the process of creating and managing Cursor rules through GitHub pull requests:
-
Automatic Analysis: The bot monitors PR comments and uses Anthropic's Claude to identify comments that could potentially be used as Cursor rules.
-
Rule Generation: When a relevant comment is detected, the bot uses an LLM to generate an appropriate Cursor rule and posts a suggestion as a reply to the original comment.
- Rules are currently generated according to the best practices outlined here
- These are subject to change, and the bot will need to be updated to reflect new best practices as these emerge.
- Rules are generated in the following general format, based on suggestions from the Cursor Community. The bot will try to follow these file naming and concept grouping guidelines:
- 001-099: Core/foundational rules
- 100-199: Integration/API rules
- 200-299: Pattern/role-specific rules
- 300-399: Testing/QA rules
- IMPORTANT: If you have no existing rules, the bot will always place any suggestions in a first rule file called
001-core-standards.mdc. We recommend adding a few basic rules to your repo before enabling this bot for the first time for best possible results. Rules should be fairly small and focused.
-
Review Process: The suggestion includes a diff showing the proposed changes to existing rules or creation of new rule files.
-
Acceptance Workflow: Team members can click an "Accept" button on suggestions they want to implement. The bot aggregates all accepted suggestions into a summary comment on the PR.
-
Finalization: When ready, a team member can comment with the command
/apply-cursor-rulesto trigger the bot to commit all accepted changes to the PR. After this commit, the bot stops analyzing further comments on that PR. -
Management Interface: A web-based frontend allows you to:
- View recent suggestions and their statuses
- Disable the bot globally or for specific repositories
- Enable "dry-run" mode to preview bot actions without making actual comments or commits
The frontend uses a state management system that persists configuration and recent activity in your chosen storage backend (Cloud Storage, S3, Azure Blob Storage, or local files). This ensures your settings and bot state are preserved across deployments and container restarts.
This workflow helps teams collaboratively develop and maintain Cursor rules while keeping the process integrated with your normal code review workflow. By aggregating collective best practices and repository-specific instructions from PR discussions, Cursor Ruler helps build a comprehensive set of rules that improve AI assistance throughout your development process.
The instructions below are for deploying to Google Cloud Run, but since Cursor Ruler is containerized with Docker, you can deploy it to any platform that supports Docker containers. The key requirements are:
- A platform that can run the Docker container (defined in
Dockerfile) - Exposing port 8000 for the application
- Setting the required environment variables:
GITHUB_APP_IDGITHUB_PRIVATE_KEY_BASE64WEBHOOK_SECRETANTHROPIC_API_KEYSTORAGE_URLand associated storage credentials
- Persistent storage configuration:
- For Cloud Run: Follow the GCS setup instructions below
- For AWS: Configure S3 bucket and AWS credentials
- For Azure: Configure Blob Storage and connection string
- For persistent servers: Ensure the local file path is writable
For other platforms like AWS, Azure, DigitalOcean, etc, you'll follow their specific instructions for deploying Docker containers while ensuring these requirements are met.
- Clone the repository:
# Open Google Cloud Shell Terminal
git clone https://github.com/alexyoung23j/cursor-ruler.git
cd cursor-ruler- Enable required APIs (run in Google Cloud Shell):
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
storage.googleapis.com- Set up Cloud Storage for persistent state:
# Set your Google Cloud project ID
export PROJECT_ID=$(gcloud config get-value project)
# Create a bucket for storing state
gsutil mb -l us-east1 gs://$PROJECT_ID-cursor-ruler-state
# Create a service account for accessing the bucket
gcloud iam service-accounts create cursor-ruler-sa \
--display-name="Cursor Ruler Service Account"
# Grant the service account full object access (create, read, update, delete)
gsutil iam ch \
serviceAccount:cursor-ruler-sa@$PROJECT_ID.iam.gserviceaccount.com:roles/storage.objectAdmin \
gs://$PROJECT_ID-cursor-ruler-state- Create Docker repository (run in Google Cloud Shell):
gcloud artifacts repositories create cursor-ruler \
--repository-format=docker \
--location=us-east1- Build and deploy (run in Google Cloud Shell):
# Build the container
gcloud builds submit . --tag us-east1-docker.pkg.dev/$PROJECT_ID/cursor-ruler/app
# Deploy to Cloud Run with storage configuration
gcloud run deploy cursor-ruler \
--image us-east1-docker.pkg.dev/$PROJECT_ID/cursor-ruler/app \
--platform managed \
--region us-east1 \
--allow-unauthenticated \
--port 8000 \
--service-account cursor-ruler-sa@$PROJECT_ID.iam.gserviceaccount.com \
--set-env-vars "STORAGE_URL=gs://$PROJECT_ID-cursor-ruler-state/state.json" \
--min-instances=1 # Prevents cold starts and maintains state- After deployment, you'll get a URL like
https://cursor-ruler-xxxxx.run.app- you'll need this for the GitHub App setup. Your deployment should appear in the Cloud Run dashboard.
Now that you have your Cloud Run service running, you can set up the GitHub App:
-
Create a GitHub App:
-
Go to your GitHub profile settings → Developer settings → GitHub Apps → New GitHub App
-
Fill in the required fields:
- Name: Cursor Rules Bot (or your preferred name)
- Homepage URL: Your Cloud Run URL (from step 4 above)
- Webhook URL: Your Cloud Run URL +
/webhook(e.g.,https://cursor-rules-xxxxx.run.app/webhook) - Webhook Secret: Generate a secure random string (at least 32 characters). You can generate one by running:
Save this value - you'll need it for the
# In your terminal openssl rand -hex 32WEBHOOK_SECRETenvironment variable.
-
Permissions:
- Repository permissions:
- Contents: Read & write
- Pull requests: Read & write
- Issues: Read & write
- Organization permissions:
- Members: Read-only
- Subscribe to events:
- Issue comment
- Pull request review comment
- Repository permissions:
-
Don't worry, the bot will never make any commits without your explicit approval!
-
Generate a Private Key:
- After creating the app, scroll down and click "Generate a private key"
- Download the key file (it will be a .pem file)
- Format the key for use in environment variables (either upload the pem file to cloud console in the cursor-ruler root or download the repo locally and run the script):
python scripts/format_private_key.py /path/to/your-private-key.pem
- Copy the base64-encoded output - you'll need this for the
GITHUB_PRIVATE_KEY_BASE64environment variable
-
Install the App:
- Click "Install App" in the sidebar
- Choose the repositories where you want to use the bot
-
(Optional) Give the app a profile picture (it will default to the Github User who set it up if you don't)
After setting up both Cloud Run and the GitHub App, you'll need to configure these environment variables in Cloud Run. It is easiest to do this with the Cloud Console UI, search for "Cloud Run" and you should see the cursor-ruler service.
Required Variables:
GITHUB_APP_ID- Your GitHub App's ID (accessed from the Github App settings page)GITHUB_PRIVATE_KEY_BASE64- Base64-encoded version of your github app private key (.pem file), generated in step 2WEBHOOK_SECRET- The webhook secret you created during GitHub App setup (must be a secure random string)ANTHROPIC_API_KEY- Your Anthropic API key
After setting these variables, visit the Cloud Run url to access the frontend. The app is now live!
The app will be automatically started in "Dry Run" mode, so it will not actually make any comments or commits but will still run rule generation code and allow you to see suggestions in the frontend. Use this to verify the app is generating rules that you approve of. The Dry Run mode can be toggled on and off in the frontend.
When you want to update the app with new code changes, (run in Google Cloud Shell):
# Navigate to your repository directory
cd cursor-ruler
# Pull latest code
git pull
# Build and deploy new version
export PROJECT_ID=$(gcloud config get-value project)
gcloud builds submit . --tag us-east1-docker.pkg.dev/$PROJECT_ID/cursor-ruler/app && \
gcloud run deploy cursor-ruler \
--image us-east1-docker.pkg.dev/$PROJECT_ID/cursor-ruler/app \
--platform managed \
--region us-east1 \
--allow-unauthenticated \
--port 8000Updating the app will reset the app to "Dry Run" mode (and remove all the ephemeral logs from the frontend).
- Set up Python environment:
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt- Start the servers:
# Start backend (in one terminal)
just start-backend
# Start frontend (in another terminal)
just start-frontend- Using ngrok for local webhook testing:
If you want to test the GitHub webhook integration locally, you can use ngrok to create a public URL that forwards to your local server:
# Install ngrok if you haven't already
brew install ngrok # on macOS
# or download from https://ngrok.com/download
# Start ngrok (after your backend is running)
ngrok http --url=<your-ngrok-url> 8000Use the ngrok URL (e.g., https://your-tunnel.ngrok-free.app) as your GitHub App's webhook URL during local development.
Cursor Ruler includes a test suite to ensure the bot functions correctly. The tests are organized into several categories that validate different aspects of the application:
All tests can be run using the just command runner. Here are the main testing commands:
# Run all tests
just test
# List all available test cases with their numbers
just list-casesThe test suite covers several key areas of functionality:
- Rule Generation Prompt Tests: Validate that the bot correctly identifies comments that should be turned into rules and generates appropriate rule content.
# Run a specific prompt test case
just test-prompts-case <test_case_number>- Format Suggestion Tests: Ensure that suggestion comments are properly formatted with the correct diff and UI elements.
# Run all format suggestion tests
just test-format
# Run a specific format suggestion test case
just test-format-case <n>- Merge Tests: Verify that multiple rule suggestions can be correctly merged without conflicts.
# Run all merge tests
just test-merges
# List available merge test cases
just list-merge-cases
# Run a specific merge test case
just test-merge-case <case_name>- Apply Tests: Test the functionality that applies accepted changes to the repository.
# Run a specific apply test case
just test-apply-case <case_name>Test cases are defined in YAML files in the tests/test_cases directory, with merge test cases in tests/merge_test_cases. These test definitions include sample PR comments, expected rule outputs, and other test parameters.
-
Webhook 500 Internal Server Error:
- Ensure your
WEBHOOK_SECRETis a secure random string (useopenssl rand -hex 32to generate one) - Make sure the webhook secret in GitHub App settings matches the
WEBHOOK_SECRETenvironment variable - Check that your GitHub private key is properly formatted (see below)
- Ensure your
-
GitHub Authentication Issues:
- Make sure you're using the base64-encoded private key
- Run
python scripts/format_private_key.py /path/to/your-private-key.pem - Copy the output exactly and set it as
GITHUB_PRIVATE_KEY_BASE64in Cloud Run - Do not modify the encoded string in any way
-
No Rule Suggestions Generated:
- Verify that your Anthropic API key is valid and has not expired
- Check the Cloud Run logs for any errors related to the LLM service
- Ensure your GitHub App has the correct permissions and webhook events configured
