Installation & Prerequisites

Get VibeRails up and running on your machine. This guide covers system requirements, installing the CLI backends, and configuring VibeRails for first use.

System Requirements

VibeRails is a native macOS desktop application. You will need:

macOS 12 (Monterey) or later
Node.js 18+ — required for the Claude Code CLI
Git — for repository tracking and fix session branching
At least 8 GB RAM (16 GB recommended for large codebases)
An active Anthropic API key (for Claude Code) and/or OpenAI API key (for Codex)

Note: VibeRails bundles its own backend server. You do not need to install or run a separate API server.

Installing Claude Code CLI

Claude Code is the primary AI backend for VibeRails. Install it globally via npm:

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

After installation, verify it is available:

claude --version

You should see a version number like 1.x.x. If the command is not found, ensure your npm global bin directory is in your PATH.

Tip: If you use nvm to manage Node versions, make sure you install Claude Code under the same Node version you use day-to-day. VibeRails resolves the CLI from your system PATH at launch.

Installing Codex CLI (Optional)

Codex is an optional secondary backend powered by OpenAI. It can be used for discovery, verification, or fix passes independently or alongside Claude Code.

npm install -g @openai/codex

Verify the installation:

codex --version

Note: You can use VibeRails with only Claude Code installed. Codex adds the option for dual-backend verification (e.g., Claude discovers, Codex verifies).

Downloading VibeRails

Download the latest VibeRails release from the Downloads page. Available formats:

.dmg — Standard macOS disk image (drag to Applications)
.zip — Portable archive (Apple Silicon and Intel builds available)

After installing, open VibeRails from your Applications folder or Spotlight.

First Launch Configuration

When you launch VibeRails for the first time, the app will check for the Claude Code and Codex CLIs on your system. Navigate to Settings to verify their status.

From the Settings page you can:

Verify that both CLIs are detected and their versions are shown
Configure your default AI backend (Claude Code or Codex)
Enable or disable Extended Thinking for Claude
Set Reasoning Levels for Codex (low, medium, high)
Choose the default issue categories to scan for

Tip: You do not need to enter API keys in VibeRails. The app delegates authentication to the CLI tools, which manage their own credentials.

Next Steps

With VibeRails installed and configured, you are ready to add your first project.