Lesson 4: Setting Up Your Environment
Everything so far has been about how you interact with Claude Code. This lesson is about setting up your environment so every session starts better automatically.
Fast-track: Already have a CLAUDE.md file, permissions configured, and CLI tools installed? Skip to Lesson 5.
CLAUDE.md: persistent instructions
Every time you start a Claude Code session, it looks for a file called CLAUDE.md in your project folder. Think of it as a briefing document — "here's what you need to know about this project before you do anything."
Without it, Claude Code starts every session blind. It has to rediscover your tech stack, your conventions, and your preferences every time. With a CLAUDE.md, it already knows.
Create one
The easiest way: just ask Claude Code to do it. Open a session in your project folder and say:
Scan this project and create a CLAUDE.md file. Include the tech stack, how to run the dev server, how to run tests, and any conventions you can detect from the code.
Claude Code will read through your project — the files, the dependencies, the folder structure — and write a CLAUDE.md tailored to what it finds. You don't need to write it yourself or know what goes in it. Review what Claude Code created, and if something's off, just tell it to fix it.
What ends up in there
Claude Code will figure out the right content, but here's the kind of thing it captures:
| Example content | Why it matters |
|---|---|
| "This is a Next.js app with Supabase" | Claude Code uses the right tech stack from the start |
"Run npm run dev to start the dev server" | Claude Code knows how to test changes |
| "Use Tailwind for all styling, no CSS modules" | Prevents Claude Code from choosing the wrong approach |
"Tests are in __tests__/ and use Vitest" | Claude Code knows where tests live and how to run them |
You don't need to memorize this. Claude Code writes it for you and reads it every session.
Keep it lean
CLAUDE.md gets read at the start of every conversation, so every line takes up space in Claude Code's memory. A good rule: if removing a line wouldn't cause Claude Code to make mistakes, remove it. Keep only the instructions that prevent errors.
There are three levels:
- Project root:
./CLAUDE.md— applies to this project. Commit this to your repo so anyone using Claude Code on your project gets the same instructions. - Home directory:
~/.claude/CLAUDE.md— applies to all your projects. Use this for personal preferences. .claude/folder:./.claude/CLAUDE.md— same as project root but for instructions you don't want to commit (it's gitignored by default).CLAUDE.local.md— like CLAUDE.md but gitignored. Use this for personal overrides you don't want to share with your team.
Start with a project-root CLAUDE.md. That's all most people need.
Quick memory: just tell Claude Code to remember
CLAUDE.md is the formal way to set persistent instructions. But there's a faster way for things you discover mid-session: just ask Claude Code to remember.
Remember to always use shadcn/ui components when building UI elements.
Remember that our API routes always return JSON with a { data, error } shape.
Claude Code saves this to a memory file in ~/.claude/ that it reads at the start of every session. It's like CLAUDE.md, but conversational — you don't need to open a file, write markdown, and save it. You just tell Claude Code what to remember and it persists across sessions.
When to use which:
| Method | Best for |
|---|---|
| "Remember..." | Quick preferences discovered mid-session: "always use Tailwind", "prefer named exports" |
| CLAUDE.md | Structured project context: tech stack, commands, architecture decisions |
They work together. Use "remember" for things you notice as you work. Use CLAUDE.md for the big picture.
Permissions: stop the "allow?" prompts
By default, Claude Code asks permission before running commands. That's safe but slow. You can pre-approve commands you trust:
/permissions
This opens your permission settings. You can allowlist commands like:
| Command pattern | What it allows |
|---|---|
npm run dev | Starting the dev server |
npm test | Running tests |
npx vitest | Running Vitest directly |
git status | Checking git status |
Once allowlisted, Claude Code runs these without asking. Everything else still requires approval.
Permissions are stored in your project's .claude/settings.json file. They use glob-like patterns:
npm run *— allows any npm scriptgit *— allows any git command (be careful with this)npx vitest *— allows Vitest with any arguments
Start conservative. Allowlist specific commands as you encounter the prompts. You can always add more later.
Sandboxing: safe autonomy
If you want Claude Code to work more freely without approving every action, sandboxing is the safe way to do it:
/sandbox
This enables OS-level isolation that restricts what Claude Code can access on your filesystem and network. Claude Code can work more autonomously within defined boundaries — no permission prompts for safe actions, but it can't escape the sandbox to do damage.
Sandboxing is a better alternative to --dangerously-skip-permissions because it gives you autonomy with guardrails instead of no guardrails at all.
CLI tools Claude Code uses
Claude Code is more powerful when your system has the right tools installed. The most important one:
gh — GitHub CLI
Mac: The easiest way is to ask Claude Code to install it for you — just say "install the GitHub CLI." If you prefer to do it manually, download the installer from cli.github.com and follow the instructions.
Windows: Download the installer from cli.github.com and run it. Alternatively, run winget install --id GitHub.cli in your terminal.
winget install --id GitHub.cli
Then authenticate by running gh auth login:
gh auth login
Once installed and authenticated, Claude Code can:
- Create pull requests
- Check CI status
- Read issue descriptions
- Comment on PRs
Without gh, Claude Code has to use the GitHub API directly, which is slower and less reliable.
These are optional but helpful:
jq— JSON processor. Helps Claude Code parse API responses.ripgrep(rg) — Fast code search. Claude Code uses this behind the scenes.tree— Shows directory structure. Useful for understanding project layout.
Install any of these with brew install <tool-name> on Mac, or winget install <tool-name> / scoop install <tool-name> on Windows.
Component libraries: polished UI out of the box
When you ask Claude Code to build a UI, it creates components from scratch by default. This works, but you end up with basic-looking buttons, inputs, and cards that need a lot of polish.
Component libraries give you pre-built, professionally designed UI elements. Instead of Claude Code writing a button from scratch, it uses a polished button component with proper styling, hover states, focus rings, and accessibility built in.
The go-to recommendation is shadcn/ui. Browse the site to see the components — buttons, cards, dialogs, tables, and dozens more, all beautifully designed. It's not a traditional library you install as a dependency — it copies the component code directly into your project, so you own it and can customize everything. Claude Code is deeply trained on shadcn, so it produces excellent results with it.
How to use it: Add this to your CLAUDE.md:
Use shadcn/ui components for all UI elements. Install any components you need with `npx shadcn@latest add <component-name>`.
That one line transforms Claude Code's output. Every button, input, dialog, dropdown, and checkbox will use shadcn's polished components instead of raw HTML.
Initialize in your project:
npx shadcn@latest init
This sets up the configuration and base styles.
Add components as needed:
npx shadcn@latest add button card input dialog
Each component gets copied into src/components/ui/ where you can customize it. Claude Code knows how to install and use these automatically once you mention shadcn in your CLAUDE.md or prompt.
The key benefit: consistency. Every element in your app looks like it belongs together, without you tweaking CSS.
MCP servers: connecting external tools
MCP servers (Model Context Protocol) let Claude Code talk to external services directly. Instead of you copying data between tools, Claude Code can access them natively.
Examples:
- Supabase MCP — Claude Code can read your database schema, run queries, and create migrations
- Browser MCP — Claude Code can see and interact with web pages
- Sentry MCP — Claude Code can read error reports and stack traces
You don't need to set up MCP servers right now. Just know they exist. When you're working with a specific service and find yourself copying data back and forth, that's a sign an MCP server would help.
We'll set up specific MCP servers when they're needed in later modules.
Hooks: auto-run scripts
Hooks let you run scripts automatically when Claude Code does certain things. For example:
- After every file edit: Run the linter to catch formatting issues
- When Claude Code finishes responding: Verify all tests pass
- After tool use: Log what Claude Code is doing
Hooks are configured in .claude/settings.json. They're optional and advanced — but powerful if you have a specific workflow you want to enforce.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx eslint --fix"
}
]
}
]
}
}
Hook commands receive tool input as JSON via stdin. Here, jq extracts the file path and passes it to ESLint. Your code stays formatted without you thinking about it.
Custom slash commands
You can create reusable workflows as slash commands. These live in .claude/commands/ as markdown files.
Create the directory first (Claude Code can also do this for you):
Mac/Linux:
mkdir -p .claude/commands
Windows (PowerShell):
New-Item -ItemType Directory -Force -Path .claude\commands
Create a file like .claude/commands/review.md:
Review the current git diff for:
- Security issues
- Performance problems
- Missing error handling
- Code that doesn't follow our patterns in CLAUDE.md
Be specific about what to fix and where.
Now you can run /project:review in any Claude Code session. It's like a saved prompt that you can reuse across sessions.
Create a custom slash command in .claude/commands/review.md that reviews the current git diff for security issues, performance problems, and missing error handling.
Checkpoint
- I have a CLAUDE.md file in my project (ask Claude Code to create one if not)
- I know I can tell Claude Code "remember to always..." to save persistent preferences without editing files
- I understand the pruning rule: remove lines that don't prevent mistakes
- I've configured at least one permission allowlist entry
- I know that
gh(GitHub CLI) makes Claude Code more capable - I know about CLAUDE.md import syntax (
@path/to/file) and CLAUDE.local.md for personal overrides - I know about
/sandboxfor safe autonomous mode - I've heard of MCP servers, hooks, and custom slash commands (no need to set them up yet)