# Terminal Setup: From Zero to AI Coding Agent

**Requirements:** none to read this — a Mac or Windows computer and a terminal, nothing to install upfront — full walkthrough in [SETUP.md](SETUP.md)

A step-by-step guide for absolute beginners to set up and own their terminal — on Mac or Windows — and finish with a working AI coding agent (Claude Code) running locally.

## Why this matters

The terminal is the one interface every real building tool assumes you already have. Package managers, git, AI coding agents, deployment tools — they all expect you to be comfortable typing commands. Most tutorials skip this part because they assume it. This guide doesn't assume anything. It starts at "what do I even open" and ends with you running an AI agent that can write and edit code for you.

Follow it top to bottom once, and you will not need a beginner terminal guide again.

## Who this is for

Anyone who has never used a terminal, or has used one just enough to be dangerous. No prior command-line experience required. Pick your OS section (Mac or Windows) and go step by step — do not skip steps, later ones depend on earlier ones.

---

## Step 1: Open your terminal

### Mac

Your terminal app is called **Terminal.app**. It ships with every Mac — nothing to install.

1. Press `Cmd + Space` to open Spotlight search.
2. Type `Terminal` and press `Enter`.
3. A window opens with white or black background and a blinking cursor. That is your **shell prompt** — it's waiting for you to type a command.

### Windows

Your terminal app is called **Windows Terminal**, and it runs a shell called **PowerShell**. Windows Terminal ships with Windows 11 by default; on Windows 10 install it free from the Microsoft Store (search "Windows Terminal").

1. Press the `Windows` key, type `Terminal`, press `Enter`.
2. A window opens running PowerShell by default (you'll see a prompt like `PS C:\Users\yourname>`).

### What is a shell, in one paragraph

A shell is a program that reads text commands you type and runs them — starting programs, moving files, installing software, talking to the internet. It is a direct line to your computer with no buttons or menus in between. That directness is exactly why it is powerful: everything a graphical app can do, and a lot it can't, is reachable from the shell with the right command. You are not "hacking" anything by using it — you are using the same tool professional developers use every day.

---

## Step 2: Essential navigation

These commands work virtually identically on Mac (bash/zsh) and Windows (PowerShell). Type each one, press `Enter`, and read what happens before moving to the next.

| Command | What it does | Success looks like |
|---|---|---|
| `pwd` | Print Working Directory — shows the folder you're currently "in" | A path prints, e.g. `/Users/you` (Mac) or `C:\Users\you` (Windows) |
| `ls` (Mac) / `ls` or `dir` (Windows PowerShell also supports `ls`) | List the files and folders in your current directory | A list of names prints |
| `cd foldername` | Change Directory — move into a folder | Your prompt updates to show the new location |
| `cd ..` | Move up one folder (to the parent) | Prompt shows the parent folder |
| `mkdir myproject` | Make Directory — create a new folder called `myproject` | Running `ls` afterward shows `myproject` in the list |
| `cp source.txt destination.txt` | Copy a file | Running `ls` shows both files now exist |
| `mv oldname.txt newname.txt` | Move (or rename) a file | The old name is gone, the new name appears in `ls` |
| `rm filename.txt` | Remove (permanently delete) a file — there is no trash can, be careful | The file no longer appears in `ls` |

Two habits that will save you constantly:

- **Tab-complete**: start typing a file or folder name and press `Tab`. The shell finishes it for you. This prevents typos and is faster than typing full names.
- **Command history**: press the `Up` arrow to cycle back through commands you've already run. Useful for re-running or tweaking a previous command instead of retyping it.
- **Ctrl-C**: if a command is stuck, running forever, or you started the wrong thing, press `Ctrl + C` to stop it and get your prompt back. This works on both Mac and Windows terminals.

---

## Step 3: Install a package manager

A package manager installs and updates software with one command instead of you hunting for installers on the web.

### Mac: Homebrew

1. In Terminal, paste this exact command and press `Enter`:
   ```
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```
2. It will ask for your Mac password (you won't see characters as you type — that's normal) and press `Enter` to confirm the install steps.
3. When it finishes, it will print instructions to add Homebrew to your `PATH` (so the terminal knows where to find it). Run the one or two lines it shows you — they typically look like:
   ```
   echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
   eval "$(/opt/homebrew/bin/brew shellenv)"
   ```
4. Confirm it worked:
   ```
   brew --version
   ```
   Success looks like a version number printing, e.g. `Homebrew 4.x.x`.

### Windows: winget

`winget` ships built in on modern Windows 10/11. Confirm it's there:
```
winget --version
```
Success looks like a version number, e.g. `v1.x.x`. If it's missing, install "App Installer" from the Microsoft Store, which includes winget.

---

## Step 4: Install the modern basics

These four tools cover almost everything you'll need to build: version control, JavaScript runtime, Python, and fast file search.

### Mac (Homebrew)
```
brew install git node python3 ripgrep
```

### Windows (winget)
```
winget install --id Git.Git -e
winget install --id OpenJS.NodeJS.LTS -e
winget install --id Python.Python.3.12 -e
winget install --id BurntSushi.ripgrep.MSVC -e
```

After installing, **close and reopen your terminal** (this refreshes what commands it knows about), then verify each one:
```
git --version
node --version
python3 --version
rg --version
```
(On Windows, use `python --version` if `python3` isn't recognized.)

Success looks like each command printing a version number, not an error like "command not found."

---

## Step 5: Install an AI coding agent (Claude Code)

Claude Code is a terminal-based AI agent that can read your code, write it, run commands, and fix bugs — directly from the command line.

### Mac
```
curl -fsSL https://claude.ai/install.sh | bash
```
This downloads and runs the official installer. It places the `claude` command on your `PATH`.

### Windows
Open PowerShell and run:
```
irm https://claude.ai/install.ps1 | iex
```
This is the PowerShell equivalent of the Mac curl command — it downloads and runs the official installer script.

### First run (both platforms)

1. Close and reopen your terminal so it picks up the new `claude` command.
2. Confirm the install:
   ```
   claude --version
   ```
   Success looks like a version number printing.
3. Navigate into any project folder (or make one: `mkdir my-first-project && cd my-first-project`) and start Claude Code:
   ```
   claude
   ```
4. The first run will walk you through logging in with your Anthropic account (a browser window opens for you to authenticate). Once logged in, you'll see a prompt inside the terminal where you can type requests in plain English, like "create a Python script that prints hello world."

That's it — you now have an AI agent that reads and writes files, runs commands, and works inside your actual project, driven from the same terminal you just learned.

---

## Step 6: Make the terminal pleasant (optional but recommended)

### Nicer terminal apps

- **Mac**: [iTerm2](https://iterm2.com) or [Warp](https://www.warp.dev) — both are drop-in upgrades over Terminal.app with better tabs, search, and themes. Install with Homebrew: `brew install --cask iterm2` or `brew install --cask warp`.
- **Windows**: Windows Terminal (Step 1) already covers most of this — it supports tabs, themes, and splits out of the box. Warp also has a Windows version if you want it.

### zsh basics (Mac default shell)

Mac's default shell is `zsh`. Your personal configuration lives in a file called `~/.zshrc` (the `~` means your home folder, and the leading dot means it's hidden by default).

Open it in a simple text editor from the terminal:
```
nano ~/.zshrc
```
A minimal, useful `.zshrc` might contain:
```
# show a shorter, cleaner prompt
PROMPT='%~ %# '

# handy shortcuts (aliases)
alias ll='ls -la'
alias gs='git status'

# make sure Homebrew is on PATH
eval "$(/opt/homebrew/bin/brew shellenv)"
```
Save and exit `nano` with `Ctrl + O`, `Enter`, then `Ctrl + X`. Open a new terminal tab to see the changes take effect.

### Windows equivalent

PowerShell has a similar personal config file called your PowerShell profile. Check if you have one and where it lives:
```
$PROFILE
```
If it doesn't exist yet, create it:
```
New-Item -Path $PROFILE -Type File -Force
notepad $PROFILE
```
Add aliases the same way, e.g. `Set-Alias ll Get-ChildItem`, save, and restart your terminal.

---

## Step 7: SSH keys 101

SSH keys let you authenticate to services like GitHub without typing a password every time. A key comes in a **pair**: a public half and a private half.

- **Public key** (`id_ed25519.pub`): safe to share. You paste this into GitHub, a server, etc. It only lets people *verify* it's you — it cannot be used to impersonate you.
- **Private key** (`id_ed25519`, no `.pub`): this is your actual identity. **Never share it, paste it anywhere, commit it to a repo, or send it to anyone** — including in a support ticket or chat message. Anyone who has your private key can authenticate as you.

### Generate a key pair (same command on Mac and Windows PowerShell)

```
ssh-keygen -t ed25519 -C "your_email@example.com"
```
- When it asks where to save the file, press `Enter` to accept the default location.
- When it asks for a passphrase, you can press `Enter` twice for no passphrase (simpler) or set one (more secure — you'll be asked for it occasionally).

Success looks like output confirming the key fingerprint and the location of both files:
- Mac: `~/.ssh/id_ed25519` (private) and `~/.ssh/id_ed25519.pub` (public)
- Windows: `C:\Users\you\.ssh\id_ed25519` (private) and `.pub` (public)

### View your public key to copy it

Mac:
```
cat ~/.ssh/id_ed25519.pub
```
Windows:
```
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
```
Copy the full output (starts with `ssh-ed25519`) and paste it wherever you need to register a public key (for example, GitHub → Settings → SSH and GPG keys → New SSH key). Never paste the file without `.pub` — that's the private key.

---

## Make it your own

This guide is intentionally linear so you can run it once top to bottom on a fresh machine. From here:

- Swap `python3`/`node` versions or add more packages via `brew install <name>` or `winget install <name>` — the same pattern covers almost any dev tool.
- Add your own aliases and prompt customizations to `.zshrc` (Mac) or your PowerShell profile (Windows) as you find commands you repeat often.
- Once Claude Code is running, point it at a real project folder and start asking it to build things — that's the actual payoff of everything above.

If a command in this guide errors out, read the error message first — it almost always names the missing piece (a tool not installed, a `PATH` not refreshed, a typo). Closing and reopening your terminal fixes more problems than you'd expect, since it reloads your `PATH` and config files.