# 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 ` or `winget install ` — 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.