Plain English for the curious.

The Terminal

The Terminal is a window where you type commands and the computer runs them. It's not magic — it's the same computer, just without buttons.

• macOS: open the Terminal app (⌘ + Space, type "Terminal").
• Linux: open whatever terminal app your distro ships (GNOME Terminal, Konsole, etc.).

You'll see something like:

yourname@yourcomputer ~ %

The ~ is your home folder. The % (or $) is the prompt — the computer is waiting for you to type a command.

The six commands you need

That's it. Everything else you can ask Claude.

File paths

A path is the address of a file or folder. Two flavors:

• Absolute — starts at the root. /Users/jane/projects/finance/app.py
• Relative — starts where you are. If you're in /Users/jane/projects/, then finance/app.py is the same file.

Shortcuts:

• ~ means your home folder. ~/Documents = /Users/jane/Documents.
• . means "current folder."
• .. means "parent folder."

Files starting with . (like .env) are hidden by default — use ls -a to see them.

What is a project, structurally?

A project is just a folder with related files inside it. That's it. Convention:

~/projects/
  finance-helper/        ← one project
    README.md
    .env                 ← your secrets (never share)
    .gitignore           ← tells git what to ignore
    app.py
    requirements.txt
  meal-planner/          ← another project
    ...

Rules of thumb:

• One folder per project. Don't mix two tools in one folder.
• Keep projects under ~/projects/ so you can find them.
• Lowercase folder names with dashes: meal-planner, not Meal Planner.

Environment variables

An environment variable is a named value the operating system makes available to programs that run. Think of it like a sticky note the OS hands to every program.

Common ones:

• HOME — your home folder path
• PATH — list of folders where the OS looks for commands
• ANTHROPIC_API_KEY — Claude's SDK and many tools look for keys here

See them all with env. Set one for a single command:

ANTHROPIC_API_KEY=sk-ant-xxxx claude

…or for the whole shell session by adding it to ~/.zshrc (Mac) or ~/.bashrc (Linux). But the cleanest approach is a .env file.

The .env file

A .env file is a plain text file that stores secrets and config values for one specific project. It usually lives in the project's root folder. Example:

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxx
SIMPLEFIN_ACCESS_URL=https://bridge.simplefin.org/...
DATABASE_PATH=./finance.sqlite

Rules:

1. One key per line, format is NAME=value. No spaces around =.
2. Never put it in git. Add .env to a .gitignore file.
3. Lock the permissions so other users on the computer can't read it:

   chmod 600 .env

4. Always ship a .env.example alongside it — same keys, fake values — so future-you knows what to fill in.

Programs load .env files with a library (e.g. python-dotenv in Python). The library reads the file and makes the values available as environment variables to your code.

API keys

An API key is a long random string that identifies you to a service (like Anthropic's API, or your bank-data provider). It's a password your code uses instead of you typing one each time.

Where do you get one?

• Anthropic / Claude API: console.anthropic.com → API Keys → Create Key.
• Other services: each has its own dashboard. The pattern is always: sign in → developer/API section → create key.

How do you keep it safe?

1. Never paste it in chat, screenshots, or commit messages.
2. Never put it in a file that gets uploaded to GitHub. Use .env (and gitignore .env).
3. If you leak one, rotate it immediately — delete the key in the dashboard and create a new one. Assume the old one is compromised.
4. Set spending limits in the provider's dashboard if they offer them. Caps the damage if a key leaks.

How does it get used?

Your code reads it from the environment (e.g. os.environ["ANTHROPIC_API_KEY"]), and sends it as an HTTP header when calling the service. You shouldn't have to think about this — libraries handle it.

Git in 60 seconds

Git is the "undo button for your project." Every Claude Code project should use it from day one.

Setup once

git config --global user.name "Your Name"
git config --global user.email "[email protected]"

Per project

git init                  # turn this folder into a git repo
echo ".env" > .gitignore  # never track secrets
git add .                 # stage all current files
git commit -m "initial"   # snapshot them

Daily

git add .
git commit -m "added grocery list export"

To throw away uncommitted changes:

git restore .             # everything back to last commit

To see what changed:

git diff                  # unstaged changes
git log --oneline         # commit history

That's 95% of git for personal projects. You don't need GitHub unless you want to back up to the cloud or share.

How to actually iterate

This is the part most beginners get wrong: they ask Claude to "build the whole app" in one prompt, get a wall of code, can't debug it, and give up.

Better workflow

1. Write a short README first describing what you want. (Or use one of the project prompts.)
2. Open Claude Code in the project folder. cd ~/projects/my-thing && claude
3. First message: "Read the README. Ask me 5 clarifying questions before writing any code." Claude will surface assumptions you didn't realize you had.
4. Build in vertical slices. One feature, end-to-end, before moving on. Don't build the whole database schema, then the whole UI — build one feature all the way through, then the next.
5. Commit after every working slice. git add . && git commit -m "what changed". This is your undo button.
6. When something breaks, paste the full error into Claude and ask "what does this mean?" Don't paraphrase — copy verbatim.
7. When you're confused, ask Claude to explain. "Explain this file like I've never coded before."
8. When the conversation gets long, use /clear and start fresh in the same folder. Claude can re-read the files.

Anti-patterns to avoid

• "Just fix it" loops. If Claude's fix didn't work twice, stop. Step back, read the code together, ask "what's actually happening here?"
• Editing files manually without telling Claude. It'll keep operating on a stale mental model. Either let Claude make all edits, or tell it "I edited X by hand, please re-read."
• No commits. If you never commit, you can't undo. Commit early and often, even with bad messages.
• Pasting secrets into the chat. Put them in .env. Tell Claude "read the API key from .env," not "here's my API key: …"

A starter folder layout

For your overall machine:

~/projects/                  ← all your Claude Code projects
  finance-helper/
  meal-planner/
  knowledge-base/
~/.config/                   ← per-app config (some projects put secrets here)
  finance-sync/
    .env

And inside a typical project:

my-project/
  README.md                  ← what this project is
  .env                       ← secrets, gitignored
  .env.example               ← template, safe to commit
  .gitignore                 ← list of things git should ignore
  src/                       ← the code
  tests/                     ← the tests
  data/                      ← local data (often gitignored)

Claude will set this up for you if you ask. The point is: there's a place for everything, and "where does this go?" is never a guess.

When you get stuck

1. Read the error message. Out loud if you have to. The answer is usually in it.
2. Paste the error into Claude. Verbatim. Ask "what does this mean?"
3. Check your .env — typos in env vars are responsible for an alarming share of "it doesn't work."
4. Look at recent commits — git log --oneline. What did you change since it last worked?
5. git restore . to nuke uncommitted changes if you're hopelessly tangled.
6. /clear in Claude Code and start the conversation fresh.
7. Walk away for 10 minutes. Genuinely. Half the time the answer arrives in the shower.

Glossary

You now know more than 80% of people who claim to "use the terminal." Go start with Project 1; it takes fifteen minutes and you'll learn the loop.