Getting Started with Claude Code: A Guide for Non-Programmers

Getting a Terminal

Claude Code runs natively on Linux and macOS. On Windows, you need WSL to get a Linux environment. On macOS, you already have one.

Windows: WSL + Ubuntu

WSL stands for Windows Subsystem for Linux. Linux is an open-source operating system - the same one that runs most of the internet, the majority of cloud servers, and Android phones. It's what most developers work on. It is not Windows. WSL puts a real Linux environment inside Windows - not an emulator, not a virtual machine, a native layer Microsoft built into the OS.³ Your Windows files stay exactly where they are. Linux sits alongside them, and the two can talk to each other.

What you're installing alongside WSL is a Linux distribution (distro) - a packaged version of Linux. The core underneath is the same across all of them; what changes is what software comes pre-installed, how updates work, and what tools are available by default. There are dozens of distros. You don't need to care about most of them.

For getting started: Ubuntu 24.04 LTS.

Why Ubuntu: it has the largest community of any Linux distro. When something breaks, there's a Stack Overflow answer for it. When you search "how to install X on Linux," the example is almost always Ubuntu. LTS (Long Term Support) means it gets security updates for five years and won't randomly change on you.

Opening PowerShell

(This section is a good example of iterative development in action. My first pass just said "open PowerShell and run the command" - jd pushed back and asked me to be more explicit for a non-technical audience. One prompt, better output. That's the whole game.)

Press the Windows key, type PowerShell, and right-click on Windows PowerShell in the results. Click Run as administrator. Click Yes when Windows asks for permission.

You'll see a blue terminal window. Run this in it:

wsl --install -d Ubuntu-24.04

This downloads and installs both WSL and Ubuntu. It takes a few minutes. When it's done, it will ask you to create a username and password.

Note: Some machines require a reboot partway through. If Windows prompts you to restart, do it. After rebooting, open PowerShell as administrator again and run the same command - it will pick up where it left off and finish the install.

Troubleshooting: "network resource unavailable" error

If you open WSL from the Start menu after the install and get a dialog saying the feature is on a network resource that is unavailable, the installer didn't finish cleanly. Go back to your administrator PowerShell window and run:

wsl --upgrade

Keep the username short, lowercase, no spaces. Use a strong password you'll remember - or store it in a password manager like KeePass.

From now on, you get into Linux by going to Start -> WSL. Once you see a prompt that looks like yourname@YOURPC:~$, you're in Linux.

If you want to explore later: Debian is the lean alternative - fewer pre-installed packages, rock-solid stability. For your first time through, stick with Ubuntu.

macOS: Terminal

macOS is built on Unix, which means you already have a terminal and all the tools you need. Nothing to install.

Press Cmd+Space to open Spotlight, type Terminal, and hit Enter.

You'll see a window with a prompt that looks like yourname@Macbook ~ %. That's your terminal. Every command in this guide works here exactly as written.

Linux Basics

Two things to know before you touch anything. First, paths in Linux use forward slashes, not backslashes. C:\Users\you becomes /home/you. Second, ~ is shorthand for your home directory - wherever you are, cd ~ gets you back to your starting point.

These are the commands that cover 90% of what you'll need. All commands run in your terminal - Ubuntu on Windows, Terminal on macOS.

pwd

ls

ls -la

cd foldername

cd ..

cd ~

mkdir foldername

cp file.txt copy.txt

mv oldname.txt newname.txt

rm filename.txt

cat filename.txt

nano filename.txt

sudo somecommand

sudo apt install packagename

exit

A few notes: when sudo asks for your password, nothing will appear on screen while you type - that's normal, just hit Enter when done. In nano, Ctrl+O saves and Ctrl+X exits.

Installing Claude Code

Claude Code requires Node.js, and it requires a recent version. The package Ubuntu ships with apt is years out of date and will cause problems. Install nvm first, then use it to install Node.

1. Install nvm (Node Version Manager)

In your terminal:⁴

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

The version above may be out of date by the time you read this. Check the latest:

curl -s https://api.github.com/repos/nvm-sh/nvm/releases/latest | grep '"tag_name"' | cut -d'"' -f4

Close your terminal completely and open a new one. (Windows users: that's Start -> WSL.) Then install the current LTS release:

nvm install --lts

Verify it worked:

node --version

You should see something like v22.x.x. If you see command not found, close and reopen your terminal again.

2. Install Claude Code

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

3. Launch Claude Code

claude

The first time you run it, Claude Code opens a browser window and asks you to log in with your Anthropic account. Use the same account as your Claude Pro subscription. After authenticating, return to the terminal - you'll see a welcome prompt and a > cursor. Type your first request, or type /help to see available commands.

When you're done with a session, type /exit or /quit to close Claude Code and return to your terminal.

Memory Files and Organization

What is Markdown?

Markdown is a lightweight formatting language. It is plain text with a small set of symbols that control how the text looks when it is rendered. A # at the start of a line makes it a heading. **bold** makes text bold. A hyphen at the start of a line makes a bullet point. That's most of it.

A .md file is a text file that uses Markdown formatting. You can open one in any text editor - Notepad, VS Code, nano. The .md extension tells programs like GitHub, or a blog platform, to render it with formatting rather than showing raw text. You do not need to memorize Markdown syntax. Claude knows it and can write or edit these files for you. What matters is understanding what they are for.

CLAUDE.md - Briefing Claude Before You Start

CLAUDE.md is a plain text file that Claude Code reads automatically when it starts. It is a briefing document - you put in it everything you would otherwise have to explain at the start of every session.

There are two levels:

Global: ~/.claude/CLAUDE.md - loaded in every session, regardless of which project you are in. This is where your preferences live: communication style, technical background, things Claude should never do, how you want responses formatted.

Project-level: a CLAUDE.md inside your project folder, sitting alongside your code. Loaded only when you start Claude from that directory. Project-specific context goes here: what the project does, how it is structured, how to run it, what a new contributor would need to know.

Running /init to Generate CLAUDE.md

If you are starting in an existing project, run this inside a Claude Code session:

/init

Claude will read the files in your current directory - package.json, README, existing code, configuration files - and generate a CLAUDE.md describing the project. It is a starting point, not a finished product. Read what it generates, remove anything wrong or irrelevant, and add what it missed.

The ~/.claude/ Directory Structure

Over time, ~/.claude/ becomes your Claude configuration home. A real setup looks something like this:

~/.claude/
  CLAUDE.md                  ← global instructions, loaded every session
  contexts/
    finance/                 ← detailed docs loaded when working on budgets or investments
    home/                    ← smart home, Home Assistant, devices
    music/                   ← music library, studio gear
    personal/                ← family, calendar, contacts
    tech/                    ← active technical projects
    website/                 ← blog and consulting site context
    work/                    ← professional background, tools, stack
  projects/
    -home-jd/
      memory/
        MEMORY.md            ← index of auto-saved memories
        feedback_*.md        ← corrections and confirmed approaches
        project_*.md         ← ongoing project context
        user_*.md            ← user preferences and profile

Context files under contexts/ are detailed reference documents you load on demand. You tell Claude to read one at the start of a session when the task calls for it. They are too detailed to load every time.

The memory/ directory is where Claude's auto-memory system stores things it learns across sessions: corrections you made, approaches that worked, project state. The MEMORY.md file is an index - it loads automatically and points Claude to the relevant memory file when needed.

What Anthropic Recommends

Anthropic's guidance on CLAUDE.md: keep it focused. A few practical points.

The file is loaded into context at the start of every session. A very long CLAUDE.md eats into the budget Claude has available for actual work. Include things Claude genuinely needs to know upfront - not everything you have ever told it.

Separate concerns into separate files. Your global CLAUDE.md should cover you as a person and your general preferences. Project-specific details belong in the project's own CLAUDE.md. Deep reference material belongs in context files you load on demand.

Do not duplicate things the code already makes obvious. If your project has a clear README, Claude can read that. CLAUDE.md is for things that are not in the code.

Review it periodically. Preferences change, projects evolve. Instructions written six months ago may be stale or actively wrong.

Giving Claude Your Voice

The default Claude is competent but generic. It does not know your communication style, your technical vocabulary, what you already understand, or what you never want explained again. Context files fix that.

Context Files

A context file is a Markdown document in ~/.claude/contexts/ that describes a specific domain of your life or work in detail. You load it at the start of a session when it is relevant:

read ~/.claude/contexts/work/index.md

Claude reads the file and uses it for the rest of the session. Nothing else required.

A voice or profile context file captures how you communicate and what you want Claude to know about you as a collaborator:

• Your technical background - what you know cold versus what still needs explaining
• Communication preferences - short answers or full explanations, formal or casual
• Things you never want Claude to do - excessive caveats, restating what you just said, starting every response with "Certainly!"
• Domain vocabulary you use that has specific meaning in your context
• Preferred formats for code, commands, and output

The more specific and behavioral the instructions, the better they work. "Be concise" is vague. "One sentence per update, no trailing summaries" is something Claude can actually follow.

Feedback Memory

As you work with Claude, it gets things wrong. It over-explains something you know cold. It uses a format you dislike. It makes an assumption that does not apply to your situation.

When you correct it, Claude Code can save that correction as a memory - a small file in the memory directory that it reads in future sessions. Tell Claude explicitly to remember it - "remember this" is enough, but you can also scope it: "remember this when we write blog posts" or "remember this when we discuss music." Over time, corrections stack up. Claude stops repeating the same mistakes. The feedback_*.md files in the memory directory are exactly that: a record of adjustments that persist across sessions.

You can also save confirmations - things Claude did that worked well, approaches you want repeated. The memory system handles both.