Claude Code Tutorial: Complete Setup & Workflow Guide

Everything you need to go from zero to running parallel AI coding agents. Covers installation, your first session, advanced workflows, and scaling with amux.

What is Claude Code?

Claude Code is Anthropic's command-line coding agent. Unlike IDE-based assistants that suggest completions, Claude Code operates as an autonomous agent: you describe what you want, and it reads your codebase, writes code, runs tests, and commits changes. It runs in your terminal, uses your local tools (git, npm, pip, etc.), and works with any language or framework.

What makes Claude Code different from other AI coding tools is the depth of its reasoning. It can hold an entire codebase in context, plan multi-step refactors, and execute them without hand-holding. The tradeoff is that it runs one session at a time by default. That's where amux comes in — but first, let's get Claude Code itself set up properly.

Prerequisites

• Node.js 18+ — Claude Code is distributed as an npm package
• An Anthropic API key — or a Claude Pro/Teams subscription
• A terminal — macOS Terminal, iTerm2, Alacritty, Windows Terminal, or any Linux terminal
• Git — Claude Code works best in git repositories where it can commit changes

Step 1: Install Claude Code

Install Claude Code globally via npm:

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

Verify the installation:

claude --version

If you're using the API directly, set your key:

export ANTHROPIC_API_KEY=sk-ant-...

For Claude Pro or Teams subscribers, run claude and follow the OAuth login flow — no API key required.

Step 2: Your first session

Navigate to any project directory and start Claude Code:

cd ~/Dev/my-project
claude

You'll see an interactive prompt. Try a simple task first:

> Explain the structure of this project and list the main entry points.

Claude Code will read your files, analyze the codebase, and give you a structured overview. From here you can ask it to make changes:

> Add input validation to the signup form. Email must be valid, password must be 8+ chars.
> Write tests for the new validation logic.

Claude Code will edit files, run your test suite, and iterate until the tests pass. Every file change requires your approval by default — you'll see a diff and can accept or reject each edit.

Step 3: Understanding the approval flow

By default, Claude Code asks permission before every file write and every command execution. This is the safe way to work when you're learning. The approval categories are:

Once you're comfortable, you can enable YOLO mode (more on that in Step 6) to let Claude Code run unattended.

Step 4: Context management

Claude Code has a context window limit. For large codebases, you need to manage what's in context. Key techniques:

• CLAUDE.md files — Place a CLAUDE.md in your project root with architecture notes, conventions, and instructions. Claude Code reads this automatically at the start of every session.
• The /compact command — When your context gets full, type /compact to summarize the conversation and free up space. Do this proactively before hitting the limit.
• Focused prompts — Instead of "refactor the entire app," say "refactor the authentication module in src/auth/." Narrower scope means better results.
• Git worktrees — Each Claude Code session should work on its own branch. Git worktrees let multiple sessions work on the same repo without conflicts.

A good CLAUDE.md looks like this:

# My Project

## Architecture
- Express.js API in src/api/
- React frontend in src/web/
- PostgreSQL database, migrations in db/migrations/

## Conventions
- Use TypeScript strict mode
- All API routes must have integration tests
- Commit messages follow conventional commits

## Current sprint
- AUTH-42: Add OAuth2 Google login
- API-99: Rate limiting on public endpoints

Step 5: Multi-session workflows with amux

A single Claude Code session is powerful, but real projects have dozens of tasks. amux lets you run many Claude Code sessions in parallel, each in its own tmux pane with its own git worktree.

# Install amux
git clone https://github.com/mixpeek/amux && cd amux && ./install.sh

# Register your project
amux register myproject --dir ~/Dev/myproject

# Start sessions
amux start myproject

Now you can assign tasks to individual sessions. Each session gets its own branch, its own working directory, and its own Claude Code instance. The amux dashboard (at https://localhost:8822) shows all sessions, their output, and their status in real time.

A typical multi-session workflow:

# Session 1: working on auth
amux send auth "Implement Google OAuth2 login flow"

# Session 2: working on API
amux send api "Add rate limiting middleware to all public routes"

# Session 3: writing tests
amux send tests "Write integration tests for the payment module"

# Session 4: fixing bugs
amux send bugfix "Fix the race condition in the websocket handler (issue #142)"

All four agents work simultaneously. You monitor progress from the dashboard and merge completed branches when ready.

Step 6: YOLO mode for unattended work

YOLO mode removes all approval prompts. Claude Code reads, writes, runs commands, and commits without asking. This is essential for parallel workflows — you can't approve prompts for 10 sessions at once.

# Register with YOLO mode enabled
amux register myproject --dir ~/Dev/myproject --yolo

Safety considerations for YOLO mode:

• Always use git worktrees — each session works on its own branch, so a bad change can't corrupt your main branch
• Set up CI checks — require passing tests before merging any agent-generated branch
• Review diffs before merging — YOLO mode means the agent runs unattended, but you still review the output
• Use CLAUDE.md guardrails — add rules like "never delete migration files" or "never modify production config"

Step 7: Mobile monitoring

The amux dashboard is a web app, which means you can monitor your agents from your phone. Start the server and access it from any device on your network:

amux serve
# Dashboard available at https://localhost:8822
# Or on your local network: https://192.168.x.x:8822

From the mobile dashboard you can:

• See real-time output from all sessions
• Check which tasks are in progress, done, or blocked
• Send messages to individual sessions
• View the kanban board of all tasks

This lets you kick off a batch of tasks, close your laptop, and check progress from your phone while you're away from your desk.

Step 8: Advanced patterns

Task decomposition

Break large features into small, independently testable tasks. Instead of "build the payment system," create five tasks: "create the Stripe webhook handler," "build the subscription model," "add the billing page UI," "write payment integration tests," "add invoice PDF generation." Each task goes to a separate Claude Code session.

Chain-of-agents

Use the amux board to create dependency chains. An agent can mark its task as done and create follow-up tasks for other agents. For example, after the API agent finishes the new endpoint, it creates a task for the frontend agent to build the UI.

Cost optimization

Claude Code uses tokens, and parallel sessions use tokens in parallel. To optimize costs:

• Use /compact aggressively — shorter contexts mean fewer input tokens
• Write detailed CLAUDE.md files so the agent doesn't waste tokens exploring your codebase
• Scope tasks tightly — "fix the bug in utils/date.ts line 42" is cheaper than "find and fix date bugs"
• Use the amux dashboard to kill stuck sessions early

Common pitfalls and how to avoid them

• Context overflow — If Claude Code starts forgetting earlier instructions, use /compact or start a new session. Don't keep pushing more information into a full context.
• Merge conflicts — When multiple agents edit similar files, conflicts are inevitable. Assign agents to different parts of the codebase, or use a sequential workflow where one agent finishes before the next starts on related code.
• Runaway commands — In YOLO mode, an agent might run an infinite loop or a destructive command. Use amux's session monitoring to catch this early, and add guardrails in CLAUDE.md.
• Stale branches — Agents work on worktree branches that can drift from main. Rebase frequently, or use short-lived branches that merge quickly.

Next steps

You now have a complete Claude Code setup with parallel agent capabilities. From here:

• Read the Claude Code Best Practices guide for expert-level tips
• Check out the Vibe Coding Tools guide to build a complete AI-native dev environment
• Browse the demos to see amux in action on real projects

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822