Install Rails on Your Mac with Claude Code

This guide takes you from a fresh Mac (running macOS 14 or later) to a working Rails application running in your browser, generated by Claude Code following modern Rails conventions. Rails is the framework that powers Shopify, GitHub, GitLab, Stripe, and Airbnb. No development experience required. Estimated time: 90 minutes.

If you've been chatting with Claude about a product idea for weeks and want to actually ship it, or you've tried Lovable, Bolt, or Cursor and ended up with code you don't trust, this is the alternative. You'll install a real development environment, install Claude as your hands in the terminal, install a set of skills that teach Claude how senior Rails developers actually build things, and generate a Rails app you can iterate on for years.

What you'll have at the end

• A modern Rails app on your Mac, running at localhost:3000 in your browser
• A real database (Postgres) ready to store your app's data
• The systems Rails uses for background tasks (sending emails, processing uploads) and live updates (notifications appearing without a page refresh), pre-configured
• A consistent development environment (a "dev container") so the project sets up the same way on any machine
• Claude Code installed and authenticated, with senior-Rails-developer playbooks loaded as skills
• A foundation you understand and own, not a black-box prototype

This is the first article in a four-part series. The next three cover translating your idea into a buildable spec, building features safely with the AI in the room, and deploying the app to the internet.

Before you start

Three things to address upfront, because they're the things people worry about.

This guide is Mac-only. It assumes you're on macOS 14 (Sonoma) or later. The steps install tools that are Mac-specific. A Linux/WSL version may follow, but everything below is for Mac.

You won't break your Mac. Every tool we install lives in your home folder or in /opt/homebrew (a special folder Homebrew creates for itself in Step 3). Nothing modifies the macOS-shipped Ruby, Node, or system files. Each tool can be uninstalled later with a single command if you ever want to undo this.

This costs you no extra money if you have Claude Pro or Max. Claude Code uses your existing subscription. No surprise API bills, no token-counting. Pro is sufficient.

You'll need:

• A Mac running macOS 14 (Sonoma) or later
• A Claude Pro or Max subscription
• About 90 minutes of focused time
• Around 10 GB of free disk space

(You'll need a GitHub or GitLab account when you're ready to commit code online, but that's the next article in this series, not this one.)

The path

Nine steps, roughly 90 minutes. Each step has a one-line purpose so you know why we're doing it before you do it.

1. Open Terminal - your command center for the rest of this guide
2. Install Xcode Command Line Tools - Apple's bundle of compilers and dev tools (and git) that almost everything else depends on
3. Install Homebrew - the standard Mac package manager, used to install most other tools
4. Install mise - a version manager for Ruby and Node, so you can keep them up to date without breaking anything
5. Install Ruby and Node via mise - the languages Rails needs to run
6. Install Claude Code - Claude in your terminal, with the ability to read and write files on your Mac
7. Install Julian's skills - the senior-Rails-developer playbooks that teach Claude Code how to build Rails apps the way professionals do
8. Generate your Rails app with jr-rails-new - Claude builds the app from those playbooks
9. Run the app - start the server and open the app in your browser

You can stop and resume anywhere. Steps 2 and 5 are slow (10-20 minutes each, mostly waiting). The rest are fast.

Step 1: Open Terminal

Why this matters. The Terminal is the app where you type commands instead of clicking. Every developer setup starts here. It's already on your Mac. You can't break anything by typing, and if you make a typo the worst that happens is the command doesn't work and you try again.

What to do. Press ⌘ + Space, type "Terminal", press Return.

You should see a window with a blinking cursor next to a % (or $) symbol. That's the prompt. It's waiting for you.

If something looks different. macOS uses different shells depending on your version. Modern macOS defaults to zsh with a % prompt. If you see $, you're on bash and everything in this guide works the same.

Done. You have a Terminal open.

Step 2: Install Xcode Command Line Tools

Why this matters. These are Apple's developer tools: compilers (programs that turn human-readable source code into something the Mac can run), the git version control system, and helpers that almost every other developer tool depends on. They're a one-time install per Mac and take 10-15 minutes (mostly downloading).

What to run:

xcode-select --install

A dialog box appears asking if you want to install. Click "Install" and accept the licence agreement.

You should see a progress window. The install runs in the background; you can keep using your Mac.

If you see "command line tools are already installed": you're done. Skip to Step 3.

If the install fails: open System Settings > General > Software Update, make sure macOS itself is up to date, then try again.

Done. You have Xcode Command Line Tools installed, including git.

Step 3: Install Homebrew

Why this matters. Homebrew is the standard package manager on Mac. Think of it as an App Store for command-line tools. Almost every other developer tool we'll install comes through Homebrew.

What to run. Copy this entire line and paste it into Terminal:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

You'll be prompted for your Mac password. Type it (the cursor won't move while you type, that's normal, it just hides characters for security) and press Return.

The install takes 5-10 minutes. At the very end, Homebrew prints a "Next steps" section that tells you to run a couple of commands to finish the install. The exact text depends on your Mac's username and shell, but they'll look very similar to this:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Just copy whatever Homebrew tells you to run, paste it line by line, and press Return after each. If Homebrew prints two commands, run two; if three, run three. Don't worry about understanding what they do (they tell your shell where Homebrew lives).

The >> symbol means "append to a file" - it adds one line to a config file in your home folder. Nothing destructive happens.

Verify it worked:

brew --version

You should see something like Homebrew 4.x.x.

If the install fails partway: run it again. Homebrew handles retries cleanly. For more on what Homebrew is and what it can do, see brew.sh.

Done. You have Homebrew installed.

Step 4: Install mise

Why this matters. Your Mac comes with old versions of Ruby and Node built in. They're frozen at whatever shipped with macOS, which is too old for modern Rails. mise lets you install and switch between modern versions without touching the system ones. This is the standard professional approach.

What to run:

brew install mise

After installing, add mise to your shell so it activates automatically in new Terminal windows:

echo 'eval "$(mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

(If your shell is bash instead of zsh, replace both zsh references with bash and the file with ~/.bashrc.)

Verify:

mise --version

You should see something like 2026.x.x.

Done. You have mise installed.

Step 5: Install Ruby and Node via mise

Why this matters. Rails is written in Ruby and uses some JavaScript via Node. We're installing the versions that current Rails (Rails 8) expects. mise downloads, compiles, and switches into the right versions globally.

What to run:

mise use --global ruby@4.0
mise use --global node@22

The Ruby install takes 5-10 minutes. You'll see lines of text scrolling, then long pauses where nothing seems to be happening. Both are normal: the Mac is building Ruby from its source code. Don't press Ctrl+C even if it looks frozen for 30+ seconds. Your fan may run loud; that's also fine. Node is faster, around 1 minute.

Verify:

ruby --version
node --version

You should see ruby 4.0.x and v22.x.x or similar.

If Ruby install fails with a compiler error: Step 2 (Xcode Command Line Tools) probably didn't complete. Run xcode-select --install again, wait for it to finish, then retry the mise use command.

Done. You have modern Ruby and Node installed.

Step 6: Install Claude Code

Why this matters. Claude Code is Claude (the AI you've been chatting with at claude.ai) but in your Terminal, with the ability to read and write files on your computer. Same Claude. With hands.

This is the moment everything starts to feel real.

What to run:

npm install -g @anthropic-ai/claude-code

(npm came with Node in Step 5. The -g flag installs Claude Code globally, so it's available in any folder on your Mac.)

Verify the install:

claude --version

Now authenticate. Run:

claude

The first time you run Claude Code, it walks you through logging in. Pick "Claude Pro" or "Claude Max" depending on your subscription, and follow the browser flow. This connects Claude Code to your existing subscription. No API key needed. No surprise bills.

Try it. Once Claude Code's startup screen is up, type:

What's the current time in Tokyo?

Claude answers in your Terminal.

You now have a senior development assistant in a window on your computer.

To exit Claude Code: press Ctrl+C twice or type /exit. For more on what Claude Code can do, see the official documentation.

Done. You have Claude Code installed and authenticated.

Step 7: Install Julian's skills

Why this matters. Skills tell Claude Code how you want things done. Without them, Claude Code is a smart generalist. With them, it's a smart generalist with senior Rails patterns built in: the kind of conventions experienced Rails developers reach for without thinking. The same patterns powering production at GitHub, Shopify, and GitLab.

The pack includes jr-rails-new (generates fresh Rails apps with the modern stack), jr-rails-classic (opinions for editing existing Rails code), jr-rails-phlex (opinions for the Phlex view layer), and a few others.

What to run:

npx skills add julianrubisch/skills -g -y

This installs the full pack in one shot. The -g flag installs globally so the skills are available in any project. The -y flag skips confirmation prompts.

Verify:

ls ~/.agents/skills | grep jr-rails

You should see at least jr-rails-classic, jr-rails-new, and jr-rails-phlex.

Done. You have Julian's Rails skills loaded.

Step 8: Generate your Rails app with jr-rails-new

Why this matters. This is where Claude Code uses the jr-rails-new skill to scaffold a fresh Rails 8 application. The skill walks you through 10 sequential questions, then builds the app and runs the initial setup. The result is a ready-to-run application configured to your choices.

Pick a folder for your projects. If you don't have one, create one:

mkdir -p ~/code
cd ~/code

Start Claude Code in that folder:

claude

In the Claude prompt, type:

Use the jr-rails-new skill to generate a new Rails app called myapp.

(Replace myapp with whatever you want to call it. Use lowercase, no spaces.)

What to expect. Claude asks 10 questions in sequence. You can press Enter through all ten of them to accept the defaults. For your first app, that's exactly what to do. Don't research the unfamiliar terms now; the defaults are what most production Rails apps use, and you can change any of them later.

For reference, here's what each question is asking:

Once you've pressed Enter through the ten questions, Claude runs through the build (5-10 minutes). You'll see lots of output scroll past. You don't need to read every line; just glance at it occasionally to see it's still moving.

You should see Claude report a successful generation and point to where the app lives. Files appear in ~/code/myapp/.

If something fails midway. Claude usually catches the error and offers a fix. Accept the fix. If Claude gets stuck and can't recover, exit Claude Code (Ctrl+C twice) and email info@minthesize.com with the last few lines of output and the step number you were on. I read every email and usually reply within a day.

Done. You have a brand-new Rails app on your Mac.

Step 9: Run the app

Why this matters. Now we boot the app. Rails apps run on your computer at a special address (localhost:3000) that means "this Mac, port 3000". When you visit that URL in your browser, you're talking to the Rails server running on your own computer.

The skill writes a CLAUDE.md file in your new project that tells Claude exactly how to start the server. So instead of you having to remember commands, you ask Claude.

What to do. Open Claude Code from inside the project directory:

cd ~/code/myapp
claude

Then ask:

Start the dev server.

Claude reads CLAUDE.md, picks the right command (which involves the dev container), and starts the server. After a few seconds, output settles into a "Listening on http://127.0.0.1:3000" line.

Open your browser and visit:

http://localhost:3000

(You may see http://127.0.0.1:3000 in some output instead; they're the same address, just two ways of writing it.)

The Rails welcome page loads.

You have a real Rails app, running on your computer, in your browser. Generated by AI from a template trusted by some of the largest tech companies in the world.

To stop the server, in the same Claude prompt, ask:

Stop the dev server.

Done. You have a running Rails app.

What now?

You've completed the bootstrap. You have:

• A real Rails 8 app on your Mac
• Postgres for storage, background-job and live-update systems, and a consistent dev environment
• Claude Code with senior Rails patterns loaded as skills
• An understanding of where your tools live and what each does

The next article in this series shows you how to translate the back-and-forth conversation you've been having with Claude.ai about your idea into a real, structured spec that Claude Code can build from. That's where the actual building starts.

Article 2: From Claude Desktop concept to a real spec - coming soon.

In the meantime, if you want a human to look at what you've built once you have something running, see the audit. Or if you want ongoing guidance, see how I work.

FAQ

Does Claude Code cost extra if I'm already on Claude Pro?

No. Claude Code uses your existing Pro or Max subscription. Same usage limits as your current plan. The CLI tool itself is free.

How is this different from Cursor or Lovable?

Cursor is a code editor with Claude integration; Lovable generates web apps but locks you into their platform. This guide gives you a standard Rails app you fully own, generated by Claude Code following senior Rails patterns. You can iterate forever, deploy anywhere, and read what's there.

Do I need to know Ruby?

Not to follow this guide. You'll need to learn some Ruby to make changes confidently to your app, but Claude Code can write most of the code for you. The next articles in this series cover that workflow.

How long does it actually take?

About 90 minutes if everything goes smoothly. Plan for 2-3 hours if you've never opened Terminal before. A chunk of that is wall-clock time waiting for downloads and compiles (Steps 2 and 5), not active typing.

What if I get stuck?

Email info@minthesize.com with the step you're stuck on and any error message you got. Most issues are fixable in one reply.

Can I do this on Linux or Windows?

This guide is Mac-specific. The steps are similar on Linux but the commands differ; on Windows the recommended path is WSL2, which is essentially Linux. A Linux/WSL version of this guide may follow.

Why Rails and not Next.js, Django, or Laravel?

Rails is the most token-efficient language for AI coding agents we've benchmarked. It's also the most coherent full-stack framework available today: every common task has a documented, conventional way to do it. That's what powers Shopify, GitHub, GitLab, Basecamp, and a long line of bootstrapped and venture-backed startups. For a non-developer building with AI, the convention-over-configuration philosophy is exactly what you want: fewer decisions for you, fewer chances for the AI to get something wrong.

Is jr-rails-new affiliated with Rails core?

No. It's a community skill maintained by Julian Rubisch that codifies modern Rails best practices into a form Claude Code can use directly.

Last updated: 2026-05-08