Claude Code for Everyone: A Briefing Doc

Because your non-programmer friends are suddenly building apps, and you might want to join them

How to Use This Doc

Just want to start? Jump to Quick Start

Want to understand first? Read the sections in order:

  1. Executive Summary - What is this?
  2. The Fundamental Shift: Chat vs Agent - Why this is different from ChatGPT
  3. Why Local Files Matter - The file system advantage
  4. Three Paths - Which tool for you?
  5. Terminal Basics - The scary-looking thing demystified
  6. Terminal 101: Keyboard Shortcuts - Navigate like a pro
  7. How to Chat with Claude Code - Get better results
  8. Getting Started - Step-by-step walkthrough
  9. Security & Privacy - What's safe, what's not

Looking something up? Use Cmd+F to search, or check:

Prefer a presentation view? Press S for slideshow mode (or click the monitor icon in the bottom-right). Use arrow keys to navigate.

🔑 Essential Terms (Read This First!)

Before you dive in, here are 6 terms you'll see throughout this guide:

Terminal/CLI

Claude Code

Git/GitHub

Artifact

npm

API

Pro tip: Don't try to memorize these! Just skim them now, come back when you see them in the guide and think "wait, what was that again?"

Executive Summary (The TL;DR)

What happened: Claude Code (Anthropic's AI coding tool) has "broken containment" into mainstream consciousness. Non-technical people are suddenly realizing they can build actual apps—and you might be one of them.

The big insight: With a paid Claude subscription (Pro/Max/Team/Enterprise) or an Anthropic Console account, you can run claude in your terminal and build things locally - outputs live on your computer, not in some cloud sandbox. You still get claude.ai for chat, but Claude Code availability and limits depend on your plan.1

Why this matters: The interface is just... conversation. You describe what you want, Claude builds it.

The Fundamental Shift: Chat vs Agent

Claude Code represents a different category of AI interaction. The distinction matters if you want to understand where these tools are heading.

The Old Way: AI as a Chat Partner

What you're used to (ChatGPT, claude.ai, Gemini):

You: "Write me a Python script to organize my photos"
AI:  "Here's the code: [code block]"
You: *copy-paste into a file*
You: *figure out how to run it*
You: *realize it has a bug*
You: *go back to chat, paste error*
AI:  "Ah, try this instead: [new code]"
You: *copy-paste again*

The pattern:

Great for:

Limitation:

The New Way: AI as an Agent

Claude Code (and similar agentic tools):

You: "Create a photo organizer that sorts by date"
Claude Code: *creates files*
           *writes the code*
           *tests it*
           *finds a bug*
           *fixes it*
           *installs dependencies*
           *shows you it works*
You: "Nice! Now add a GUI"
Claude Code: *modifies files*
           *adds interface*
           *updates everything*
           Done.

The pattern:

The technical term: This is "agentic AI" - AI that can take actions in an environment, not just generate text.

What "Agentic" Actually Means

Not agentic (chat):

You: "Help me find that email from Sarah about the budget"
AI:  "I can't access your email, but try searching for 'from:sarah budget'"
You: *manually searches*

Agentic (if connected to your email):

You: "Find that email from Sarah about the budget"
AI:  *searches your email*
     *finds 3 matches*
     *reads them*
     "Found it - sent Jan 15, she proposed $50k for Q1. Want me to summarize?"

The difference: The AI has tools it can use. In Claude Code's case:

Why This Matters Beyond Coding

The agentic pattern applies to ANY knowledge work where there's a gap between "knowing what to do" and "actually doing it."

Examples where agentic AI works differently:

Traditional Task Chat AI Helps You... Agentic AI Does...
Data Analysis Explains how to analyze the CSV Reads the CSV, runs analysis, generates charts, writes report
Research Suggests search terms Searches multiple sources, extracts key points, cross-references, writes synthesis
Documentation Writes the doc Reads your codebase, generates accurate docs, updates them when code changes
Debugging Suggests what the bug might be Reads your code, runs tests, identifies the bug, suggests AND tests the fix
File Management Tells you the commands to organize files Scans directories, creates structure, moves files, confirms results

The common thread: Agentic AI closes the "action gap" - the work between deciding what to do and having it done.

The Mental Model Shift

Chat AI mindset:

Agentic AI mindset:

Example conversation difference:

With chat AI:

You: "My website isn't deploying to Netlify"
AI:  "Could be several issues. Check your build settings, verify the build command..."
You: *checks each thing manually*
You: "The build command is 'npm run build'"
AI:  "That looks right. Check your output directory..."
You: *keeps checking*

With agentic AI:

You: "My website isn't deploying to Netlify"
Claude Code: *reads netlify.toml*
           *checks package.json*
           *runs build command locally*
           "Found it - your build outputs to 'dist' but Netlify config says 'build'.
            Should I fix the config?"
You: "Yes"
Claude Code: *updates netlify.toml*
           *commits change*
           "Fixed. Try deploying now."

When to Use Which

Use Chat AI (claude.ai, ChatGPT) when:

Use Agentic AI (Claude Code) when:

The overlap: Many tasks benefit from BOTH:

  1. Start with chat AI to brainstorm and plan
  2. Move to agentic AI to execute and iterate
  3. Return to chat AI for deeper questions or new directions

The Catch: Trust and Verification

Chat AI is low-risk:

Agentic AI requires trust:

The safety mechanisms in Claude Code:

  1. Git integration - Every change is tracked, reversible
  2. Working directory sandboxing - It operates in folders you allow.2
  3. Transparency - It shows planned actions by default.
  4. Permissions & policies - Default modes prompt you; settings can enable auto-accept/bypass.3

The Future State

Where this is heading:

Claude Code for programming is just the first mainstream example of this shift. The pattern will expand to:

What This Means for You

If you're learning Claude Code:

How it works in practice:

What this makes possible:

Why Local Files Matter (The Real Power)

Yes, you can use claude.ai on mobile. Yes, it syncs across devices. But for real work, local files give you capabilities the web version can't match.

The File System Advantage

Real persistence:

Professional workflows:

Actual deployment:

Multi-file projects:

Iteration speed:

The Mobile/Web Use Case (Still Valid!)

Use claude.ai web when:

Use Claude Code (local) when:

The "Sandbox" Isn't a Limitation - It's a Feature

Yes, Claude Code works in your current folder (sandbox). But that's the POINT:

The file system enables:

your-project/
  ├── src/              ← Source code
  ├── assets/           ← Images, fonts
  ├── tests/            ← Test files
  ├── docs/             ← Documentation
  ├── .git/             ← Version history
  ├── node_modules/     ← Dependencies
  └── package.json      ← Project config

This structure means:

In Practice

Mobile/web is great for ideas. Local files are for building.

Even if you only ever build one real project, going through the local files process teaches you how software actually works. That understanding carries over to other tools and contexts.

Quick Start (For the Impatient)

Skip the theory? Here's your 5-minute path to building something:

Step 1: Open Terminal

# On Mac: Press Cmd+Space, type "terminal", hit Enter

You'll see: A window with text (might say your username and a $ or % symbol)

If nothing happens: Make sure you fully typed "terminal" and pressed Enter (not just clicked away)

Step 2: Install Claude Code

# Copy-paste this whole line:
curl -fsSL https://claude.ai/install.sh | bash

Want to inspect the installer first? Download it, skim it, then run:

curl -fsSL https://claude.ai/install.sh -o install.sh
open install.sh
bash install.sh

You'll see: Text scrolling as it downloads and installs (takes 30-60 seconds)

Troubleshooting:

Step 3: Create a project folder

mkdir ~/my-first-project && cd ~/my-first-project

You'll see: Nothing! (In Terminal, silence means success)

What this did:

Troubleshooting:

Step 4: Launch Claude Code

claude

You'll see: A welcome screen that looks something like:

┌─ Welcome to Claude Code ─────────────────┐
│                                          │
│ Current directory: ~/my-first-project    │
│                                          │
│ What would you like to build?           │
│ >                                        │
└──────────────────────────────────────────┘

Troubleshooting:

Step 5: Tell it what to build

Make me a simple timer with start, stop, and reset buttons

(Type this at the > prompt and press Enter)

You'll see: Claude thinking, then creating files. It will show you:

Then open your creation:

open index.html

You'll see: Your browser opens with a working timer! You built that.

Troubleshooting:

What happens next

Want changes? Just ask Claude! Type your request at the > prompt:

Make the buttons bigger and add a dark mode toggle

To exit Claude Code: Press Ctrl+D or type exit

Come back to this doc when you want to understand what just happened, or jump to Terminal Basics to learn what all those commands meant.

Prefer clicking over typing? Download Claude Desktop from claude.com/download — visual interface, with Claude Code features available on eligible plans.5

Three Paths, Choose Your Adventure

Option 1: Claude Desktop (Visual App)

Option 2: Claude CLI (What This Doc Covers)

Option 3: Continue Using claude.ai

Terminal Basics for Normal Humans

What IS the Terminal?

That black screen with green text from hacker movies? It's just texting your computer instead of clicking buttons. No magic involved.

Think of it like a restaurant:

Both get you food. The text version is faster once you learn the "menu" (commands). And with Claude Code, you don't even need to memorize the menu—Claude knows it for you.

Why Terminal feels scary (but isn't):

macOS Terminal location:

Terminal 101: Keyboard Shortcuts You'll Actually Use

Once Terminal is open, these keyboard tricks will make you feel like a pro (even if you're not):

Navigating Command History

The Up/Down arrow keys are your best friends:

# You typed this 5 minutes ago:
npm install

# Press Up arrow → it appears again!
# Press Enter to run it again

Pro alternatives (for when you want to look fancy):

Finding Old Commands Fast

Ctrl+R = Reverse search (this one's worth learning)

# Press Ctrl+R, then start typing part of an old command
(reverse-i-search)`git`: git commit -m "Added dark mode"

# Keep pressing Ctrl+R to cycle through matches
# Press Enter to run it, or Right Arrow to edit it first

Real-world example:

Moving Around in a Line

You typed a long command and spotted a typo at the beginning. Don't delete everything!

Option+Click (the Mac way):

Keyboard alternatives:

# You typed:
cd ~/Dcuments/my-project
   ^
   # Oops, typo! Need to add 'o' in Documents

# Method 1: Hold Option, click between 'D' and 'c'
# Method 2: Ctrl+A to go to start, then Option+Right to jump words

Editing and Deleting

Ctrl+K: Kill (delete) everything from cursor to end of line

cd ~/Documents/wrong-folder/more-wrong/nope
              ↑ cursor here
# Press Ctrl+K → deletes "wrong-folder/more-wrong/nope"
# Result: cd ~/Documents/

Ctrl+U: Delete everything from cursor back to start

git commit -m "This message is way too long and rambling"
                                    ↑ cursor here
# Press Ctrl+U → deletes everything before cursor
# Useful for starting over

Ctrl+W: Delete the word before cursor

git commit -m "typo
               ↑
# Press Ctrl+W → deletes "typo"

Other Life-Savers

Ctrl+C: Stop/cancel the current command (if something's stuck)

# If a command is running forever or you made a mistake:
npm install some-huge-package
# Loading... Loading... (taking too long!)
# Press Ctrl+C to abort
^C  # You'll see this appear

Ctrl+L: Clear the screen (same as typing clear)

Tab: Auto-complete file/folder names

cd ~/Doc[TAB]
# Becomes: cd ~/Documents/

git add my-rea[TAB]
# Becomes: git add my-readme.md

Quick Reference Card

Shortcut What It Does When to Use It
↑ / ↓ Browse command history Running same commands repeatedly
Ctrl+R Search old commands "What was that command I ran yesterday?"
Option+Click Jump cursor to position Quick typo fixes
Ctrl+A / Ctrl+E Jump to start/end of line Editing long commands
Option+← / → Jump by word Navigating medium commands
Ctrl+K Delete to end of line Trimming end of command
Ctrl+U Delete to start of line Starting over
Ctrl+C Cancel current command Something's stuck or wrong
Ctrl+L Clear screen Clean up clutter
Tab Auto-complete Faster typing, fewer typos

The three you'll use every session:

  1. Up Arrow - recall last command
  2. Ctrl+C - stop something
  3. Tab - auto-complete paths

Pro tip: You don't need to memorize all of these! Start with Up Arrow and Tab. Add more as you feel the need for them.

What Could Terminal Do Pre-Claude Code?

Your Mac's terminal has always been powerful - here are things you could already do:

File Management (The Basics)

pwd           # Print Working Directory - "where am I?"

Output: /Users/yourname (shows your current location)

ls            # List - "show me files here"

Output: Desktop Documents Downloads Pictures (your folders)

cd Documents  # Change Directory - "go into this folder"
pwd           # Check where you are now

Output: /Users/yourname/Documents

mkdir my-project  # Make Directory - "create new folder"
ls                # Check it was created

Output: You'll see my-project in the list now

Running Programs

python script.py      # Run Python code
npm start            # Start a web app
open file.html       # Open file in browser

Git (Version Control)

git status           # What changed?
git add .            # Stage changes
git commit -m "msg"  # Save snapshot
git push            # Upload to GitHub

The terminal always had these powers. Claude Code just gives you an AI that knows how to use them.

How to Chat with Claude Code Effectively

Claude Code conversations are different from web chat. Here's how to get the best results:

Start with Context

Good: "Create a responsive dashboard with a sidebar and cards for displaying metrics"

Better: "Create a responsive admin dashboard. Sidebar on the left with nav links. Main area has 4 metric cards (users, revenue, orders, traffic). Use Tailwind for styling. Should work on mobile."

Why: More detail = fewer back-and-forth corrections. Claude makes better initial decisions when it knows your vision.

Be Iterative, Not Perfect

You don't need to describe everything upfront. Build in layers:

You: "Create a todo app"
Claude: *creates basic app*

You: "Add due dates to tasks"
Claude: *adds date picker*

You: "Color code tasks - red if overdue, yellow if due today"
Claude: *adds color logic*

You: "Add localStorage so tasks persist"
Claude: *adds persistence*

Pattern: Start simple → Add features one at a time → Refine details last

How to Ask for Changes

Vague (slower):

Specific (faster):

With code references:

Common Conversation Patterns

Bug fixing:

You: "When I click delete, nothing happens"
Claude: *reads code, identifies issue*
       "Found it - event listener wasn't attached. Fixed."

Refactoring:

You: "This code is repetitive - can you make it cleaner?"
Claude: *extracts reusable functions, consolidates logic*

Learning mode:

You: "How does the dark mode toggle work? Explain the code"
Claude: *walks through the logic with annotations*

Adding features:

You: "Add a search bar that filters the list"
Claude: *adds input field, implements filter logic*

What Claude Code Can See

Claude knows about:

Claude doesn't know:

Pro tip: If Claude seems confused, give more context:

Session Management

Starting fresh:

# Each time you run `claude`, it's a new session
claude

Claude remembers within a session:

Claude doesn't remember across new sessions by default:

Solution: Recap when you return:

You: "I'm back working on the todo app. Last time we added dark mode.
      Today I want to add categories for grouping tasks."

When Things Go Wrong

If Claude's code doesn't work:

  1. Describe what happened:
    • "The timer starts but doesn't stop"
    • "I see a blank page"
    • "Console error: X is not defined"
  2. Claude will diagnose and fix:
    • Reads the code
    • Identifies the issue
    • Proposes a fix
    • Updates the files
  3. Test and iterate:
    • Try the fix
    • Report if it works or what's still wrong
    • Claude adjusts

Don't be afraid to say "That didn't work" - it's part of the process!

Advanced: Multi-Step Requests

You can ask Claude to do several things at once:

You: "Create a weather app that:
      1. Has an input for city name
      2. Fetches data from OpenWeatherMap API
      3. Displays current temp, conditions, and 5-day forecast
      4. Uses nice icons for weather conditions
      5. Stores last searched city in localStorage"

Claude will: Break this down, tackle each piece, integrate them, and deliver a working app.

Conversation Tips Summary

Do:

Don't:

Claude Code is collaborative. You're the director, Claude is the executor. Clear requests get better results.

Security & Privacy Deep Dive

Your Claude Account Setup

⚠️ FIRST: Review your data privacy controls

Consumer accounts (Free, Pro, and Max) per Claude Code data usage docs:

Commercial accounts (Team, Enterprise, API) have different policies and typically are not used for training unless you opt in. See Claude Code data usage for details.

Plan details vary: Usage limits and features depend on your plan; check your account settings for current limits.

Understanding the Data Flow

┌─────────────────────────────────────────┐ │ YOUR COMPUTER (macOS) │ │ │ │ Terminal → Claude CLI │ │ ↓ │ │ Reads your files locally │ │ ↓ │ │ Sends context to → │ └─────────────────────┬───────────────────┘ │ ↓ (HTTPS - encrypted) ┌────────────────────────┐ │ ANTHROPIC'S SERVERS │ │ │ │ Claude processes │ │ Returns response │ └────────────────────────┘ ↓ ┌────────────────────────┐ │ BACK TO YOUR COMPUTER │ │ │ │ Creates/modifies files │ │ ALL LOCAL │ └────────────────────────┘

Important detail from the data usage docs: Claude Code runs locally, but prompts and model outputs are sent over the network to Anthropic services. Data is encrypted in transit via TLS and is not encrypted at rest.

The trade-off:

Sandboxing & Safeguards

What is sandboxing?
Think of it like giving someone keys to ONE room in your house, not the whole house:

The program runs in a restricted environment where it can't:

Claude Code's approach:

  1. Working directory: It operates in folders you explicitly navigate to
  2. Permission model: macOS security prompts when accessing sensitive areas
  3. Git integration: Version control = undo button for any changes
  4. You're always in the loop: It shows you what it's doing before executing

Best practices:

# Create a sandbox folder for experiments
mkdir ~/claude-projects
cd ~/claude-projects

# Or use version control
git init my-new-project
cd my-new-project
claude

Pro tip: Start projects in a dedicated folder. If things go sideways, you can delete the whole folder. Your real files elsewhere stay safe.

Implementation Strategy Matrix

Quick Comparison: Ways to Build with AI

Feature Claude CLI Claude Desktop claude.ai Cursor Bolt/Lovable
Cost Varies by plan Varies by plan Free + paid tiers Paid plans Paid plans
Where files live Local Local Cloud Local Cloud
Internet required Yes Yes Yes Partial Yes
GitHub integration Yes Yes Manual Yes Built-in
Best for Terminal users Visual interface Quick prototypes Pro devs Quick apps
Learning curve Medium Low Low Medium Low

Decision Tree: Which Tool When?

START: What are you building? ├─ Quick prototype/demo (< 1 hour) │ └─ Use: claude.ai Artifacts │ ↳ Single HTML file │ ↳ Share link instantly │ ↳ Limitation: Stuck in cloud ├─ Personal project/learning │ └─ Use: Claude CLI │ ↳ Files on your computer │ ↳ Full control │ ↳ Learn professional workflow ├─ Serious app you'll maintain │ └─ Use: Claude CLI + Git + GitHub │ ↳ Version control from day 1 │ ↳ Deploy to GitHub Pages │ ↳ Professional setup └─ Professional development work └─ Consider: Cursor (privacy mode; check policy) ↳ More control over AI behavior ↳ Enterprise features ↳ Different pricing model

Getting Started: From Zero to First Project

Prerequisites Checklist

Already have:

Need to install:

  1. Claude Code (the easiest way - no Node.js needed!) 
    # Open Terminal and paste this one line:
curl -fsSL https://claude.ai/install.sh | bash
    That's it! This downloads and installs everything automatically.
  2. Git (probably already installed, check with git --version)
    • If not installed, macOS will prompt you to install it

Alternative installation (deprecated npm method): 13

Your First Session (Detailed Walkthrough)

Already did Quick Start? This section goes deeper into what's happening at each step. If you just want to try it, jump to Quick Start instead.

Step 1: Open Terminal and create a project folder

mkdir ~/claude-projects/my-first-app
cd ~/claude-projects/my-first-app

What you'll see: Nothing! The command completes silently.

What actually happened:

Your Mac's file system:
/Users/yourname/
  ├── Desktop/
  ├── Documents/
  ├── Downloads/
  └── claude-projects/          ← Just created this!
      └── my-first-app/         ← You're now "inside" this folder

Verify it worked: Type pwd and press Enter

pwd
# Output: /Users/yourname/claude-projects/my-first-app

Step 2: Start Claude Code

claude

What you'll see: After 1-2 seconds, a welcome interface appears:

┌─────────────────────────────────────────────────┐
│ Welcome to Claude Code                          │
│                                                 │
│ I can help you build and modify code in:       │
│ /Users/yourname/claude-projects/my-first-app   │
│                                                 │
│ What would you like to build?                  │
│ >                                               │
└─────────────────────────────────────────────────┘

The blinking cursor after > means Claude is waiting for your instructions.

Step 3: Tell it what to make (in plain English)

Create a simple timer app with start, stop, and reset buttons

What you'll see: Claude's thought process displayed in real-time:

> Create a simple timer app with start, stop, and reset buttons

I'll create a timer app for you with those controls.

Creating files:
  - index.html (the main page)
  - styles.css (to make it look good)
  - script.js (the timer logic)

[Shows code being written...]

✓ Created index.html
✓ Created styles.css
✓ Created script.js

Your timer app is ready! Open index.html in your browser to try it.

Behind the scenes: Claude just created 3 files in your my-first-app folder. You can see them in Finder if you navigate to your home folder → claude-projects → my-first-app.

Step 4: Open your creation

open index.html

What you'll see: Your default browser launches and displays:

┌─────────────────────────┐
│                         │
│         00:00          │
│                         │
│  [Start] [Stop] [Reset] │
│                         │
└─────────────────────────┘

Click "Start" → the timer counts up! This is a real, working application. You built this.

Step 5: Want changes? Just ask

Make the buttons bigger and add a dark mode toggle

What you'll see: Claude modifies the existing files:

> Make the buttons bigger and add a dark mode toggle

I'll update the app with those changes.

Modifying files:
  - styles.css (bigger buttons, dark mode styles)
  - index.html (adding dark mode toggle)
  - script.js (dark mode toggle logic)

✓ Updated styles.css
✓ Updated index.html
✓ Updated script.js

Changes applied! Refresh your browser to see the updates.

In your browser: Press Cmd+R (Mac) to reload. Now you see:

Step 6: Understanding what just happened

The conversation pattern:

  1. You describe what you want in plain English
  2. Claude figures out what files/code are needed
  3. Claude creates or modifies those files
  4. You test the result
  5. You iterate with more requests

The files are REAL:

To exit Claude Code: Type exit or press Ctrl+D

Understanding the Interface

When you type claude, you get:

┌─ Welcome to Claude Code ─────────────────┐ │ │ │ Current directory: ~/claude-projects/... │ │ │ │ What would you like to build? │ │ > │ └──────────────────────────────────────────┘

Key differences from claude.ai:

Local vs Cloud: The Honest Trade-offs

Local (Claude CLI) Advantages

✅ Ownership:

✅ GitHub workflow:

✅ Privacy:

✅ Integration:

Local Disadvantages

❌ Setup complexity:

❌ No mobile/tablet:

❌ Internet still needed:

Cloud (claude.ai) Advantages

✅ Instant start:

✅ Sharing:

✅ Lower barrier:

Cloud Disadvantages

❌ Export complexity:

❌ Platform dependency:

Exporting from claude.ai to Local

Made something cool in claude.ai and want it on your computer?

The Easy Way (Recommended)

# 1. Start Claude Code locally
claude

# 2. Tell it what you built:
"I made an app in claude.ai that does [describe it].
Can you recreate it locally?"

# Claude will rebuild it with proper file structure.

The Manual Way

  1. In claude.ai: Click the Artifact → "Copy code"
  2. On your Mac: Create a file, paste the code 
    mkdir ~/my-project && cd ~/my-project
# Use any text editor to create index.html, paste your code
open index.html  # Opens in browser

Pro tip: If you think a project might grow, start in Claude Code from the beginning. Easier than exporting later.

Learning Path: Simple → Professional

Start Here (Your First Projects)

Build with just HTML/CSS/JS—no frameworks, no complexity:

Level Up (When Ready)

Add version control and multiple files:

git init                    # Track your changes
git add . && git commit -m "First save"  # Save a snapshot

Why: Safety net for experiments, professional habit

Go Pro (When You Feel Limited)

Modern tools solve real problems you'll eventually feel:

Add tools when you feel the need, not before. Claude Code can set up any of these when you're ready.

Workflow Diagram: The Full Loop

┌─────────────────────────────────────────────────────────┐ │ IDEA PHASE │ │ "I want to build a habit tracker" │ └─────────────────┬───────────────────────────────────────┘ ↓ ┌─────────────────┐ │ DECIDE TOOL │ │ Quick? → .ai │ │ Real? → CLI │ └────────┬────────┘ ↓ ┌────────────────────────────────────────────────────────┐ │ DEVELOPMENT (CLI Example) │ │ │ │ 1. Setup │ │ mkdir habit-tracker && cd habit-tracker │ │ git init │ │ claude │ │ │ │ 2. Build (Iterative) │ │ You: "Create habit tracker with..." │ │ Claude: *generates files* │ │ You: "Add streak counter" │ │ Claude: *modifies code* │ │ You: "Make it prettier" │ │ Claude: *updates styles* │ │ │ │ 3. Test locally │ │ open index.html (or npm run dev) │ │ │ │ 4. Version control │ │ git add . │ │ git commit -m "Working habit tracker" │ └────────────────┬───────────────────────────────────────┘ ↓ ┌────────────────┐ │ DEPLOY │ │ GitHub Pages │ │ OR Vercel │ │ OR Netlify │ └────────┬───────┘ ↓ ┌────────────────┐ │ SHARE │ │ yourusername. │ │ github.io/ │ │ habit-tracker │ └────────────────┘

Continuous Iteration Loop

┌──────────┐ │ USE │ │ Test it │ └────┬─────┘ │ ↓ ┌───────────────┐ ┌────→│ FEEDBACK │←────┐ │ │ "Needs dark │ │ │ │ mode!" │ │ │ └───────┬───────┘ │ │ ↓ │ │ ┌───────────────┐ │ │ │ IMPROVE │ │ │ │ Claude adds │ │ │ │ features │ │ │ └───────┬───────┘ │ │ ↓ │ │ ┌───────────────┐ │ └─────│ DEPLOY │─────┘ │ Push updates │ └───────────────┘

Conceptual Demystification

Key Terms, Plain English

CLI (Command Line Interface):

API (Application Programming Interface):

Git (Version Control System):

GitHub:

Repository (Repo):

npm (Node Package Manager):

Localhost:

Deploy/Deployment:

Build/Build Tool:

Environment:

Jargon Translation Table

Dev Speak Normal Human
"Clone the repo""Download the project"
"Push to origin""Upload changes to GitHub"
"Merge conflict""Two people edited same line"
"npm install""Download dependencies"
"Hot reload""Auto-refresh when you save"
"Localhost""Pretend website on your computer"
"Route""Page/screen in the app"
"Component""Reusable UI piece"
"Bundle""Combine code into one file"
"Deploy""Put on the internet"

Strategic Recommendations

For Complete Beginners

Start with claude.ai Artifacts:

  1. Build 3-5 simple projects in browser
  2. Export and learn to run locally
  3. Then graduate to Claude CLI

Rationale:

For "Vibe Coders" (People with Ideas, No CS Degree)

Jump straight to Claude CLI:

  1. One afternoon to learn terminal basics
  2. Skip the academic journey, learn by building
  3. Non-technical people are doing this successfully—it works!

Best first projects:

Key insight: You don't need to know how every line works. You need to:

Things to Watch Out For

Security Considerations

What Claude Code CAN do:

What it usually can't do (without your permissions or settings allowing it):

Good habits:

Privacy Mindset

Remember:

For sensitive projects:

Cost Management

Plans and limits change:

Watch out for:

The "Magic Black Box" Problem

Don't fall into trap of:

Better approach:

🚢 Quick Deploy Guide: GitHub Pages

Why GitHub Pages:

Step-by-Step Deploy

Prerequisites: You need a free GitHub account. If you don't have one, go to github.com → Sign Up (takes 2 minutes).

Part 1: Prepare Your Project Locally

In your project folder (where your files are), initialize Git:

# Initialize Git tracking
git init

# Stage all your files
git add .

# Save a snapshot
git commit -m "Initial commit: my awesome project"

What you'll see: Git confirms the commit with something like:

[main (root-commit) abc1234] Initial commit: my awesome project
 3 files changed, 42 insertions(+)
 create mode 100644 index.html
 create mode 100644 script.js
 create mode 100644 styles.css

Part 2: Create a Repository on GitHub (The Website Part)

Step 1: Open your browser and go to github.com/new

(Or: Click the + icon in the top-right corner of GitHub → "New repository")

Step 2: Fill out the form:

Repository name: my-timer-app (must match your project folder name - or pick any name you want)

Description: (optional) "A simple timer with start/stop/reset buttons"

Public or Private?

IMPORTANT: Do NOT check these boxes:

(You already have files - these options are for starting from scratch)

Step 3: Click the green "Create repository" button

Part 3: Connect Your Local Project to GitHub

You'll see a page with instructions. Look for the section that says:

…or push an existing repository from the command line

Copy the commands shown (they'll have YOUR username). They look like:

git remote add origin https://github.com/YOUR-USERNAME/my-timer-app.git
git branch -M main
git push -u origin main

Paste them into Terminal (in your project folder) and press Enter.

What you'll see: Git uploads your files:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (5/5), 1.2 KiB | 1.2 MiB/s, done.
Total 5 (delta 0), reused 0 (delta 0)
To https://github.com/YOUR-USERNAME/my-timer-app.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

What this did: Your local files are now on GitHub! Refresh the GitHub page in your browser - you should see your files listed.

Part 4: Enable GitHub Pages (Make It Live!)

Step 1: On your repo page, click "Settings" (top-right area, last tab in the menu)

Step 2: In the left sidebar, scroll down and click "Pages" (under "Code and automation")

Step 3: Under "Build and deployment":

Source: Select "Deploy from a branch" (should be default)

Branch:

Step 4: Click "Save"

You'll see: A blue/green box appears:

✓ Your site is live at https://YOUR-USERNAME.github.io/my-timer-app/

(Takes 30-60 seconds to build. Refresh the page if you don't see it yet)

Part 5: Visit Your Live Site!

Click the link (or type it in your browser):

https://YOUR-USERNAME.github.io/my-timer-app/

🎉 Your app is now on the internet! Anyone with the link can use it.

Making Updates Later

After you change your code:

# In your project folder
git add .
git commit -m "Made buttons bigger"
git push

GitHub Pages auto-updates (takes 1-2 minutes). Refresh your live site to see changes.

Troubleshooting

"404 - There isn't a GitHub Pages site here"

Page shows folder listing instead of website

Site doesn't update after pushing changes

For React/Vite projects:

# Add to vite.config.js:
base: '/projectname/'

# Build:
npm run build

# Deploy dist/ folder
# (Use gh-pages package or manual)

Other Tools Worth Knowing About

Tool What It Is When to Consider
VS Code + GitHub Copilot Code editor with AI autocomplete You want traditional dev experience
Cursor VS Code fork with deeper AI integration Privacy-focused, or power users
Lovable/Bolt/Replit Browser-based AI coding Zero setup, works on any device
claude.ai Artifacts Quick prototypes in browser Fast experiments before going local

Bottom line: Start with Claude Code. Explore others later if you hit specific needs.

Next Steps: Your Action Plan

This Week

Next Week

Next Month

Next Quarter

Final Thoughts: The New Normal

What's actually changed:

What you still need to learn:

Your advantage as a beginner:

What this enables:

Open that terminal. Type claude. Build something small. See what happens.

The files really do live on your computer. That's the point.

Resources

Official:

If Something Breaks:

Learning (Free):

Communities:

Footnotes

  1. Claude Code access requires a paid plan or Console account. Claude Code setup. ↩
  2. File access is limited to your working directory unless you add directories. Permissions & access. ↩
  3. Permission modes (including auto-accept/bypass) are configurable. Permissions & access. ↩
  4. Default access includes the current directory plus any added directories. Permissions & access. ↩
  5. Desktop app availability and plan eligibility. Claude product page. ↩
  6. Desktop app downloads for macOS and Windows. Claude Desktop download. ↩
  7. Claude Code features in Desktop require eligible plans. Claude product page. ↩
  8. Claude Code in Desktop is for Max/Pro/Team/Enterprise users. Claude product page. ↩
  9. CLI access requires an eligible plan or Console account. Claude Code setup. ↩
  10. Access to other directories requires adding them. Permissions & access. ↩
  11. System requirements: macOS 13+, Windows via WSL, Ubuntu/Debian. Claude Code setup. ↩
  12. Eligible plan or Console account required. Claude Code setup. ↩
  13. npm install method is deprecated. Claude Code setup. ↩
  14. WebFetch tool access is controlled by permissions. Permissions & access. ↩
  15. Access outside the working directory requires adding directories. Permissions & access. ↩
  16. Permission modes include prompts and auto-accept/bypass. Permissions & access. ↩
  17. GitHub Pages for public repos is available on Free plans. GitHub Pages usage limits. ↩
  18. GitHub Pages for private repos requires paid plans. GitHub Pages usage limits. ↩
  19. claude doctor is an installation health check. Claude Code setup. ↩
  20. claude doctor is an installation health check. Claude Code setup. ↩

Want to improve this guide? The source lives on GitHub — feel free to fork it, open a PR, or file an issue. If it helped, consider starring the repo.

Last updated: January 2026. If something's outdated, the beauty of local files is you can just... edit it.