Getting started with Claude Code

1Where Claude Code actually runs

There are four places you can run Claude Code: a terminal, the desktop app for Mac and Windows, the browser at claude.ai/code, and inside an editor like VS Code. They share the same brain. They differ in how much you see.

This guide uses the terminal: a plain text window where you type commands. It is the least polished of the four and the one worth learning first, because nothing is hidden from you. From there Claude Code can see your files, create new ones, run your site locally so you can preview it, and push your finished work online.

Why not just use the Claude website? Chatting with Claude is great for writing and thinking. Claude Code is different: it touches your files. It builds a whole project instead of describing one. That is the entire difference, and it is a big one.

Prefer buttons to commands? Install the desktop app instead and skip to step 4. Everything after that works the same. Come back to the terminal when you want to see what is actually happening.

2Pick a terminal

You need a terminal app. Four that work well:

• iTerm2: the one we use. Been around forever, handles long sessions and lots of tabs without complaining.
• Ghostty: newer, very fast, good defaults out of the box. The one to pick if you want to install it and never configure anything.
• Warp: has AI and command autocomplete built in. Good if you want help with the terminal itself, not just with your code.
• Terminal: already on your Mac. Applications → Utilities → Terminal. Nothing to install, works fine to start.

Why terminal instead of the Claude app? Tabs. You can have multiple projects open at the same time, each in its own tab. Like browser tabs, but for work sessions.

On Windows? Claude Code runs natively now, no setup required: open PowerShell and continue from step 3. Install Git for Windows too, it gives Claude a proper shell to run commands in. WSL is still worth it if you work with Linux tools, but it is no longer a requirement.

3Install Claude Code

Open your terminal and run this one command:

# Install Claude Codecurl -fsSL https://claude.ai/install.sh | bash# Windows, in PowerShellirm https://claude.ai/install.ps1 | iex

That is it. The native installer handles everything. No Node.js or npm needed. It also auto-updates in the background.

Alternative: with Homebrew, run brew install --cask claude-code. Homebrew does not auto-update, so you run brew upgrade claude-code yourself.

Now create a folder for your project and start Claude Code:

# Create a folder and go into itmkdir my-first-site && cd my-first-site# Start Claude Codeclaude

The first time you run claude it opens a browser and asks you to log in. This is the part people trip on: the free Claude plan does not include Claude Code. You need Pro at minimum. Pro is enough to build real things; Max is for all-day sessions where you hit the limits and want to keep going.

4Build your first site

Once Claude Code is running, just tell it what you want. Plain English, no special syntax.

You: Create a simple one-page website for my coffee shop.     Name: Grounds, location: Malaga, Spain.     Include a menu section and contact info.

Claude creates the files. Then follow up naturally:

Make the menu section bigger and add a hero image placeholderChange the font to something warmerAdd a WhatsApp button in the corner

To see it in a browser, ask for it. Claude starts the server itself and hands you the address:

You: Start a local preview server and give me the addressServing at http://localhost:3000

Open that address in your browser. Every time Claude makes changes, reload the page to see them. To run it yourself instead: pnpm dlx serve ..

5Make it plan before it builds

The single most useful habit in Claude Code: before a change of any size, press Shift+Tab until the mode indicator says plan. Claude then reads your project and writes out what it intends to do without touching a single file. You read the plan, say what is wrong, and only then let it build.

# Shift+Tab until the mode says plan, then askYou: Add online booking to the contact sectionClaude: here is the plan. 1. Add a form with name, date,party size. 2. Send submissions to your email via Resend.3. Add a confirmation message. Approve?

That is where you catch it choosing a payment provider you do not want, or rewriting three files when one would do. Correcting a plan costs one sentence. Correcting finished code costs an afternoon.

Rule of thumb. Small and obvious, just ask. Anything that touches more than one file, or that you would struggle to review afterwards, plan first.

6Teach Claude about your project

The single biggest upgrade you can make is a file called CLAUDE.md in your project folder. It is a plain-English note Claude reads at the start of every session: the stack you use, how you write, things to avoid, where the production site is.

The fastest way to make one is to ask Claude. Type /init and it writes a starter for you. Edit it like a living document:

# Project: Grounds Coffee## Stack- Plain HTML/CSS, no build step- Hosted on Vercel, domain via Porkbun## Brand voice- Warm, short sentences. No emojis on the site.- Always Spanish first, English second.## Things to avoid- No tracking scripts. No popups.- Never commit anything from .env.local.## Verify before claiming done- Load localhost:3000 and check the change before saying it works.

This file is also how you get a brand voice. Tell Claude how you write: short sentences, no buzzwords, never em-dashes, whatever you want. The first time you read your site after this, it sounds like you, not like a chatbot.

Add to it as you go. Start a message with # and Claude appends it to the file for you. Every time you correct the same thing twice, that is a line missing from your CLAUDE.md.

Two more places it looks. A CLAUDE.md at ~/.claude/CLAUDE.md applies to every project on your machine, so your writing rules live there and not in ten copies. And a line like @AGENTS.md pulls another file in, which is how you keep one set of rules shared across projects.

7Save your code on GitHub

GitHub is like Dropbox for code, but smarter. It stores every version of your project, and it connects to the tools that put your site online automatically.

Create a free account at github.com, then install the GitHub CLI and log in:

# Install GitHub CLI (Mac)brew install gh# Log in to your GitHub accountgh auth login

Follow the prompts. It opens a browser to confirm. Then push your project:

# Initialize git, stage all files, commitgit init && git add . && git commit -m "first version"# Create repo on GitHub and pushgh repo create my-first-site --public --source . --push

A GitHub account is your developer ID. Once you have one you can deploy to Vercel, Cloudflare or Netlify just by connecting it. You set this up once.

8Put it on the internet with Vercel

Vercel is the easiest way to host a website. Sign up at vercel.com with your GitHub account. Then do the rest from the terminal, where you can see what happened:

# Install the Vercel CLI and log inpnpm add -g vercel && vercel login# From your project folder. First run links the projectvercel --prod# Did it actually work?vercel lsmy-first-site  Ready  2m ago

Your site is live on a free URL like “my-first-site.vercel.app”, ready to share.

Two ways to deploy, and they are not the same. If you connect the GitHub repo in Vercel's dashboard, every push deploys by itself. If you only linked with the CLI, pushing to GitHub does nothing visible and you deploy with vercel --prod. Know which one you set up. Wondering why the site still shows yesterday's copy is almost always this.

Cloudflare Pages is a solid alternative. Same idea, also free, faster CDN in some regions.

9Add your own domain

The vercel.app URL works, but a real domain looks more professional. Buy one at Porkbun: most cost $10–15 a year with free privacy protection. Then attach it to your project and read back what Vercel wants:

# Attach the domain to this projectvercel domains add grounds-coffee.com# Then in Porkbun, under DNS, add what it asked forA record:     @ → 76.76.21.21CNAME record: www → cname.vercel-dns.com

Copy the records Vercel shows you, not the ones above. Those two are the common case, but newer projects get their own CNAME target that looks like a random string. Paste what your project actually prints.

What is DNS? The internet's phone book. When someone types your domain, DNS tells their browser which server to connect to.

It is not instant. DNS changes take 5 minutes to 48 hours to spread. Usually under an hour. If the domain does not work right away, wait and check again. Nothing is broken. To check without guessing, run curl -sI https://your-domain.com: a line saying 200 means you are live.

10Keep your secrets safe

If your site uses any external service, an AI API, a payment processor, a map, it comes with a key. Think of it as a password: if someone finds it, they use the service and you pay the bill.

The rule: never put keys in your code. Put them in .env.local, and tell Git to ignore that file:

# .env.local, never commit this fileANTHROPIC_API_KEY=sk-ant-your-key-hereSTRIPE_SECRET_KEY=sk-your-stripe-key# .gitignore, files Git should never track.env.localnode_modules/

That file stays on your machine, which means the live site knows nothing about it. Give Vercel its own copy:

vercel env add ANTHROPIC_API_KEY productionPaste the value when asked, then redeploy for it to take effect

If you accidentally push a key to GitHub: rotate it immediately. Go to the service, create a new key, deactivate the old one, update .env.local. Someone may already have copied it, rotating is the only fix.

11The daily workflow

Once everything is set up, your day-to-day looks like this:

# Go to your project foldercd my-first-site# Start Claude CodeclaudeYou: Add a booking form to the contact section# When done, push to GitHubgit add . && git commit -m "add booking form" && git push# Then deploy, unless GitHub does it for youvercel --prod

Pro tip: you do not have to run the git commands yourself. Tell Claude Code “commit and push with the message: add booking form” and it handles it.

Look before you call it done. Deployed is not the same as working. Load the real URL, and load it on your phone: text running off the side of the screen is the single most common thing to ship by accident. Thirty seconds of looking beats finding out from a customer.

When Claude goes off the rails. Press Esc to interrupt and explain what you actually wanted. It usually gets it on the second try. If it made a mess of your files, press Esc twice on an empty prompt and pick a point to rewind to: your files and the conversation both go back. If a whole session feels stuck, type /clear and start fresh.

12Stop pressing Yes all the time

By default Claude Code asks permission before writing files or running commands. Useful when learning, tiring after that. Three options:

1. Shift+Tab (recommended). Each press moves to the next mode and the indicator above the prompt tells you where you are:

Accept edits lets Claude write files without asking, which is the one you will live in. Plan is step 5. Manual is where you start.

2. Allowlist specific actions. Type /permissions to manage this in a menu, or write it yourself in .claude/settings.json:

{  "permissions": {    "allow": [      "Bash(git:*)",      "Bash(npm:*)",      "Bash(npx:*)"    ]  }}

3. Skip permissions entirely with claude --dangerously-skip-permissions. Fine for a throwaway project, risky for anything real.

+What to learn next

Once the daily workflow feels normal, these make Claude Code much more powerful. You do not need any of them on day one.

• Skills: small add-ons you install once and Claude can use forever. Browse the tools tag in Field Notes for the ones we actually use.
• MCP servers: let Claude talk to your database, calendar, Stripe or GitHub Issues directly. Configure once, then ask in plain English: show me the last 10 signups.
• Subagents: Claude spawns smaller helpers to do parts of a task in parallel. They inherit your CLAUDE.md, so they already know your project.
• Your own slash commands: a prompt you keep retyping, saved as a file in .claude/commands/. Ours deploy sites and run design checks. This is the cheapest one to start with.
• Hooks: run something automatically at a fixed moment, like formatting every file Claude saves. For rules you want enforced rather than remembered.

Try one when it makes sense. Do not chase them upfront. Build something boring first.