Terminal Cross-Platform Setup

The terminal experience varies across operating systems. The core concepts from Terminal Fundamentals apply everywhere, but the specific programs, default shells, and setup steps differ. This note covers the practical setup for each platform and provides a translation table for when commands diverge.

macOS

macOS uses zsh as its default shell since Catalina (2019). Before that, it used bash. For practical purposes, the two are interchangeable for basic commands — anything in Essential Terminal Commands works identically in both.

Opening the Terminal

The quickest route: press Cmd + Space to open Spotlight, type “Terminal,” and press Enter. Terminal.app lives in /Applications/Utilities/ if you prefer to find it manually.

iTerm2: The Popular Upgrade

Many developers replace Terminal.app with iTerm2, a free third-party terminal that offers:

Split panes — run multiple terminal sessions side by side in one window
Better search — find text in terminal output with Cmd+F
Profiles — save different configurations for different projects or environments
Extensive customization — themes, fonts, keyboard shortcuts, transparency

iTerm2 is not required — Terminal.app works fine for everything Claude Code does. But if you’ll spend significant time in the terminal, iTerm2’s quality-of-life improvements are worth the five minutes of installation.

macOS-Specific Notes

Homebrew (brew) is the standard package manager. Most developer tools install through it.
macOS is case-insensitive by default (on APFS volumes), meaning File.txt and file.txt are treated as the same file. This can cause subtle bugs when deploying to Linux servers, which are case-sensitive.
Xcode Command Line Tools (installed via xcode-select --install) provides essential development tools including git. macOS prompts you to install these the first time you run a developer command.

Linux

Most Linux distributions default to bash and include a terminal emulator out of the box — GNOME Terminal on Ubuntu, Konsole on KDE, xfce4-terminal on Xfce. The experience is essentially identical to macOS for basic commands.

Getting Started

Your terminal is already installed. Find it in your application menu, or use the keyboard shortcut (often Ctrl+Alt+T on Ubuntu/GNOME).

Linux-Specific Notes

Package managers vary by distribution: apt for Debian/Ubuntu, dnf for Fedora, pacman for Arch. The terminal commands themselves are the same across distributions — it’s only the installation commands that differ.
Linux is case-sensitive. File.txt and file.txt are different files. This is the expected behavior for servers and deployment targets.
Permissions matter more visibly on Linux. You’ll encounter sudo more frequently for system-level operations.

Windows

Windows offers three distinct approaches to terminal usage, each with different tradeoffs.

Option 1: WSL (Recommended for Full Compatibility)

WSL (Windows Subsystem for Linux) runs a complete Linux environment within Windows. It’s the recommended approach for Claude Code because it provides full compatibility with Unix-based tools and commands.

# In PowerShell as Administrator
wsl --install

After restarting, you’ll have a full Ubuntu installation accessible from your Start menu. Inside it, everything works exactly like native Linux:

# In the new Ubuntu terminal
npm install -g @anthropic-ai/claude-code

WSL accesses your Windows files at /mnt/c/Users/YourName/. Your Windows C: drive is mounted as /mnt/c/, so you can work with files in either environment.

The tradeoff: WSL adds complexity. You’re running two operating systems simultaneously, with two file systems and two sets of PATH configurations. When things work, the experience is seamless. When they don’t, debugging requires understanding both Windows and Linux simultaneously.

Option 2: Git Bash (Simpler Setup)

Git Bash provides Unix-like commands and is supported by Claude Code. Install Git for Windows and use the included Git Bash terminal.

Git Bash gives you bash, ls, cd, grep, cat, and most standard Unix commands without the full weight of a Linux subsystem. It’s simpler to set up than WSL and sufficient for most Claude Code workflows.

The tradeoff: Some tools and scripts assume a full Unix environment that Git Bash doesn’t provide. Advanced workflows involving system services, background processes, or Unix-specific tools may hit limitations.

Option 3: Native PowerShell

Claude Code works in PowerShell, though some commands differ from their Unix equivalents. PowerShell is already installed on every Windows machine.

The tradeoff: PowerShell’s command syntax diverges significantly from bash/zsh. Tutorials, Stack Overflow answers, and Claude Code’s own suggestions often assume Unix commands. You’ll spend time translating.

Command Equivalents Across Platforms

When a tutorial or tool assumes Unix commands, this table provides the Windows equivalents:

Task	Mac/Linux	PowerShell	Windows CMD
List files	`ls`	`Get-ChildItem` or `ls`	`dir`
Change directory	`cd folder`	`cd folder`	`cd folder`
Current location	`pwd`	`Get-Location` or `pwd`	`cd` (no args)
View file	`cat file`	`Get-Content file`	`type file`
Search in file	`grep "text" file`	`Select-String "text" file`	`findstr "text" file`
Clear screen	`clear`	`Clear-Host` or `cls`	`cls`

PowerShell provides aliases for many Unix commands — ls, pwd, cat, and cd all work in PowerShell even though they’re aliases for native cmdlets. This makes the transition less painful for basic operations.

The Case Sensitivity Trap

One critical cross-platform difference deserves explicit attention: Linux is case-sensitive (File.txt and file.txt are different files), while Windows and macOS (by default) are not.

This rarely matters when working locally, but it creates real bugs when:

You develop on macOS or Windows and deploy to a Linux server
You import a file as ./Utils/Helper.js on macOS (works) but the actual filename is ./utils/helper.js (fails on Linux)
Git tracks a case change as a rename on Linux but ignores it on macOS

The practical advice: always use consistent casing. Prefer lowercase for filenames and directories. If you’re developing code that will run on Linux, test on Linux (or in WSL) before deploying.

Which Setup to Choose

For Claude Code specifically:

macOS users: You’re already set. Open Terminal.app and go.
Linux users: You’re already set. Open your terminal and go.
Windows users who will do significant development: Install WSL. The upfront complexity pays off in long-term compatibility.
Windows users who want to try Claude Code quickly: Use Git Bash. It’s lighter than WSL and sufficient for most tasks.
Windows users already comfortable with PowerShell: Claude Code works there too, but be prepared to translate Unix-centric examples.