Create New Rails 8.1+ Application

Create a fully configured Rails 8.1+ application with modern tooling and Claude Code integration.

Usage

/rails-hotwire-toolkit:new-rails-app [app_name]

If no app name is provided, prompt the user for one.

What This Command Does

1. Validates the environment

   • Checks for Rails 8.1+ (rails -v)
   • Checks for PostgreSQL (psql --version)
   • Suggests fixes if tools are missing

2. Creates the Rails application

   rails new APP_NAME --database=postgresql --css=tailwind
   

3. Adds required gems

   • tidewave (development group) - Runtime Rails integration for Claude

4. Installs MCP servers

   • hotwire_club-mcp gem - Hotwire/Turbo/Stimulus knowledge base
   • Runs rbenv rehash if rbenv is detected

5. Creates Claude Code configuration

   .claude/settings.json with full auto-approval:

   {
     "permissions": {
       "allow": [
         "Bash", "Edit", "Write", "Read", "NotebookEdit", "WebFetch", "WebSearch",
         "mcp__tidewave__*",
         "mcp__hotwire-club-mcp__*",
         "mcp__chrome-devtools__*"
       ]
     },
     "enableAllProjectMcpServers": true
   }
   

   .mcp.json with project MCP servers:

   {
     "mcpServers": {
       "tidewave": {
         "type": "http",
         "url": "http://localhost:3000/tidewave/mcp"
       },
       "hotwire-club-mcp": {
         "command": "hwc-mcp",
         "args": []
       }
     }
   }
   

6. Creates the database

   bin/rails db:create db:migrate
   

7. Generates comprehensive CLAUDE_TOOLS.md documentation

8. Updates .gitignore to exclude .claude/settings.local.json

App Name Guidelines

• Use snake_case (e.g., my_awesome_app)
• Start with a lowercase letter
• Only letters, numbers, and underscores

Post-Creation Instructions

After the command completes, instruct the user:

1. Start the Rails server:

   cd APP_NAME
   bin/rails server
   

2. Open Claude Code in another terminal:

   cd APP_NAME
   claude
   

3. The following tools are now available:

   • Tidewave: get_models, get_logs, project_eval, execute_sql_query
   • Hotwire Club: Search Hotwire/Turbo/Stimulus patterns
   • Chrome DevTools: Browser automation and debugging (via plugin)
   • Context7: Documentation lookup (via plugin)

Browser Automation Preferences

IMPORTANT: When working with a Rails app that has Tidewave running:

1. Prefer Tidewave's built-in capabilities for Rails-specific tasks:

   • Use project_eval for running Ruby code
   • Use execute_sql_query for database queries
   • Use get_logs for checking application logs

2. Use Chrome DevTools MCP for:

   • Visual inspection and screenshots
   • Performance profiling and Core Web Vitals
   • Console error checking
   • Network request analysis
   • Testing UI interactions that require a real browser

3. Do NOT use external browser automation when Tidewave can accomplish the task directly.

Example Interaction

User: "Create a new Rails app for a bookmark manager"

Assistant actions:

1. Suggest app name: bookmark_manager
2. Confirm with user
3. Run the setup process
4. Provide next steps

Error Handling

• If Rails is not installed: Suggest gem install rails
• If PostgreSQL is not running: Suggest brew services start postgresql (macOS)
• If database creation fails: Show error and suggest manual fix
• If any gem installation fails: Show error and continue with manual steps