Chapter 1: Introduction to Claude Code

Source Videos: Building Claude Code with Boris Cherny, Mitchell Hashimoto's New Way of Writing Code, 567 Hours of Claude Code Lessons in 20 Minutes, The ONLY Claude Code Tutorial You'll Ever Need in 2026, Claude Code 2.0 MASSIVE Upgrade!

What Is Claude Code?

Claude Code is a terminal-native AI coding agent built by Anthropic. It lives directly in your terminal or inside an IDE like Visual Studio Code, and it can read files, write code, execute bash commands, run tests, install dependencies, and interact with your entire development environment. It is not a chatbot with a coding feature bolted on. It is an autonomous agent that uses tools to accomplish real engineering tasks.

Unlike browser-based AI assistants where you paste code snippets into a chat window, Claude Code operates directly on your file system. It sees your project structure, reads your code, and makes changes in place. You watch those changes happen in real time.

Key Insight from The Pragmatic Engineer: "The model is its own thing. You give it tools. You give it programs that it can run. You let it run programs. You let it write programs, but you don't make it a component of this larger system. Just let the model do its thing. Don't try to put it in a box." -- Boris Cherny, Building Claude Code with Boris Cherny

The Tool in a Nutshell

A Brief History

Claude Code started as a personal side project by Boris Cherny, who joined Anthropic in 2024 after 7 years at Meta leading code quality across Instagram, Facebook, WhatsApp, and Messenger. When he arrived at Anthropic, there was an internal tool called "Clyde" -- a janky Python predecessor that took 40 seconds to start and was not agentic at all.

Boris's first pull request at Anthropic was rejected -- not because the code was bad, but because he wrote it by hand. His ramp buddy, Adam Wolf, told him to use Clyde instead. That tool one-shotted a working PR, and Boris had his first "aha" moment with AI coding.

From there, Boris began building what would become Claude Code. It started as a simple chatbot that hit the Anthropic API from the terminal. Then he gave it the bash tool -- and everything changed.

Key Insight from The Pragmatic Engineer: "I asked it 'what music am I listening to' and it just wrote a little AppleScript program to open up my music player and query it. This thing, if you give it a tool, it will figure out how to use it to get the thing done." -- Boris Cherny, Building Claude Code with Boris Cherny

The internal adoption at Anthropic went vertical -- virtually 100% of technical employees now use it daily, and even non-technical staff (like half the sales team) have adopted it. Dario Amodei, Anthropic's CEO, asked Boris if people were being forced to use it. They were not. People simply voted with their feet.

The decision to release Claude Code publicly was driven by safety research: Anthropic wanted to study how an agentic AI behaves in the wild, not just in synthetic evaluations. The tool turned out to be one of the fastest-growing developer tools in history.

The Origin Story in Detail

The progression from chatbot to agent happened through a series of discoveries:

  1. The Chatbot Phase: Boris built a simple terminal-based chatbot that hit the Anthropic API. It was conversational AI -- useful for answering questions, but not transformative.

  2. The Tool-Use Revelation: When tool use became available, Boris gave the chatbot a single tool: bash. He asked it "what music am I listening to?" and it wrote an AppleScript program to query his music player. This was the moment he realized the model wants to use tools -- it will figure out how to apply them to solve problems.

  3. Adding File Editing: The second tool was file edit. With bash and file editing, Claude Code became capable of actually writing and modifying code in a project.

  4. Internal Viral Adoption: The tool spread across Anthropic engineering organically. The internal adoption chart went "vertical" -- from zero to near-100% adoption among technical employees. When Dario Amodei asked if people were being forced to use it, Boris said no -- people simply voted with their feet.

  5. The Safety Decision: There was a genuine internal debate about whether to keep Claude Code as an internal-only productivity advantage. The decision to release it publicly was made so that Anthropic could study model safety "in the wild" -- seeing how real users interact with an agentic AI, rather than only studying it in synthetic lab conditions. This decision proved transformative for both the product and for safety research.

  6. General Availability: Claude Code launched in research preview initially, then reached general availability around the time of the Sonnet 4 release. From the outside, it appeared to be a deliberate product launch. From the inside, it was a research project that became a product because it was genuinely useful.

How Claude Code Actually Works (Architecture)

The architecture of Claude Code is deliberately simple. Boris describes it as:

Key Insight from The Pragmatic Engineer: "There's not much to it. There's a core query loop. There's a few tools. We delete tools all the time. We add new tools all the time. We're always experimenting. Then there's a ton of different pieces around security -- making sure everything Claude Code does is safe and that there's a human in the loop." -- Boris Cherny, Building Claude Code with Boris Cherny

Anthropic's Internal Usage: Claude Code Writing Claude Code

One of the most fascinating aspects of Claude Code development is that it is self-referential: Claude Code is used to build Claude Code. When changes are made to the Claude Code codebase, Claude will test itself -- launching itself in a subprocess to verify it still works end-to-end. This is not explicitly programmed behavior; with Opus 4.5+, it spontaneously began doing this.

Additionally, every pull request at Anthropic is automatically code-reviewed by Claude Code (using the agent SDK, claude -p). This catches approximately 80% of bugs in the first pass. A human engineer then does a second review. There is always a human in the loop for approving changes.

Why Use Claude Code? The Creator's Philosophy

Boris Cherny's philosophy for Claude Code centers on a principle borrowed from machine learning research: the bitter lesson. The bitter lesson states that general methods that leverage computation tend to win over methods that try to encode human knowledge. Applied to AI coding tools, this means: don't try to constrain the model into narrow boxes. Give it tools and let it figure out how to solve your problem.

The Anti-Scaffold Philosophy

Many AI coding tools take the approach of putting the model into a box -- defining rigid interfaces, stubbing out specific functions, and saying "this part is AI." Claude Code takes the opposite approach. You give it tools (bash, file editing, web access), describe what you want, and let it figure out the path.

Key Insight from The Pragmatic Engineer: "Everyone essentially had this mental model of: you take the model and you put it in a box and you figure out what is the interface. Essentially, you stub out some function, and you say, 'Okay, this is now AI.' But otherwise, the rest of the program is just a program. This is just not the way to think about the model." -- Boris Cherny, Building Claude Code with Boris Cherny

Built to Be Hackable

Claude Code is deliberately designed so that every engineer can customize it to their own workflow. There is no single "right way" to use it. Boris is explicit about this:

Key Insight from The Pragmatic Engineer: "There's no one right way to use Claude Code. The way we build it is we build it to be hackable because we know every engineer's workflow is different. There's no two engineers that have the same workflow." -- Boris Cherny, Building Claude Code with Boris Cherny

This hackability manifests in CLAUDE.md configuration files, custom skills, hooks, sub-agents, plugins, MCP integrations, and the ability to tailor permission modes and model selection to each task.

The Printing Press Metaphor

Boris draws a comparison between this moment in software engineering and the invention of the printing press in the 1400s. Before the printing press, there was a class of scribes who knew how to write -- some kings were illiterate and employed them. After the press, scribes ceased to exist as scribes, but a new category of writers and authors emerged. The market for literature expanded enormously.

Key Insight from The Pragmatic Engineer: "If you think about what happened to the scribes, they ceased to become scribes, but now there's a category of writers and authors. These people now exist. And the reason they exist is because the market for literature just expanded a ton." -- Boris Cherny, Building Claude Code with Boris Cherny

The implication: the role of the software engineer is not disappearing. It is transforming. The people who thrive will be those who learn to leverage these tools effectively, not those who resist them.

How It Transforms Developer Workflow

Mitchell Hashimoto's Perspective on AI-Native Coding

Mitchell Hashimoto -- co-founder of HashiCorp, creator of Terraform, and builder of the Ghosty terminal -- is one of the most hands-on practitioners of AI-assisted development. He always keeps an agent running in the background and describes AI coding tools as "revolutionary."

His key insight is that the appropriate level of oversight depends entirely on context:

Key Insight from The Pragmatic Engineer: Mitchell describes a spectrum from "I review every line" to "I don't care what the code looks like -- did it work?" The right approach depends entirely on the stakes of your project. -- Mitchell Hashimoto's New Way of Writing Code

Mitchell also raises a critical observation about the future of version control: Git and GitHub in their current form do not work well with agentic infrastructure. When AI generates large volumes of code, the pull request itself can become meaningless -- what matters is the prompt history and the intent behind the changes.

Key Insight from The Pragmatic Engineer: "Changes will happen. Git and GitHub forges in their current form do not work with agentic infrastructure today. I'm on the receiving end as both an agent user and a maintainer, and I'm like -- this isn't working." -- Mitchell Hashimoto, Mitchell Hashimoto's New Way of Writing Code

The Open Source Challenge

Mitchell also highlights a significant challenge that AI tools are creating for open source software. With AI agents, it has become trivial to create "plausible looking but incorrect and low-quality contributions." The signal-to-noise ratio in pull requests has dropped dramatically. For Ghosty, his terminal project, he now rejects all AI-generated PRs that are not tied to an accepted feature request. He does not even read the code -- if it looks AI-generated and there is no linked issue, it is closed immediately.

This reveals an important dynamic: as AI makes it easier to generate code, the value shifts to curation, taste, and judgment about what should be built and why.

Key Insight from The Pragmatic Engineer: "Open source has always been a system of trust. Now it's just default deny and you must earn trust. AI makes it trivial to create plausible looking but incorrect and low-quality contributions." -- Mitchell Hashimoto, Mitchell Hashimoto's New Way of Writing Code

The "Everything Is Changing" Moment

Mitchell is an optimist who has been in the industry for 20 years. He describes the current moment as the first time in his career where so many fundamental practices are simultaneously up for change -- editors, version control, CI/CD, code review, testing, and the very structure of how teams work together. For him, this is exciting rather than threatening.

Boris Cherny's Daily Workflow

Boris's personal workflow reveals how a power user operates with Claude Code:

  1. Five terminal tabs, each with a separate checkout of the repository (or using git work trees for isolation).
  2. Almost always starts in plan mode (Shift+Tab twice).
  3. Round-robins between tabs: starts Claude in plan mode in tab 1, moves to tab 2 to start another task while tab 1 is working, and so on.
  4. Overflows to the Claude desktop app (which has built-in work tree support) and even the iOS app for starting agents on the go.
  5. Ships 20-30 PRs per day, with Opus writing 100% of the code. He has not manually edited a single line since switching to Opus 4.5.

Key Insight from The Pragmatic Engineer: "I wrote maybe 10-20 pull requests every day. Opus 4.5 and Claude Code wrote 100% of every single one. I didn't edit a single line manually. Opus introduced maybe two bugs, whereas if I had written that by hand, that would have been 20 bugs or something." -- Boris Cherny, Building Claude Code with Boris Cherny

Boris even uninstalled his IDE -- he realized he had not been using it for a month and simply did not need it anymore.

The Learn Mode for Onboarding

For engineers who are new to a codebase, Boris recommends using Claude Code's learn mode (or explanatory mode). You access it via /config and set the output style. This mode has Claude explain what it is doing and why, making it an excellent onboarding tool for new team members or unfamiliar codebases.

Once you are familiar with the codebase, the workflow shifts to productivity: start in plan mode, get the plan right, and let Claude one-shot the implementation.

Claude Code 2.0: What's New

Claude Code has undergone continuous, rapid improvement. The most recent Claude Code 2.0 update introduces several significant features:

Interactive Charts and Diagrams (Desktop App)

The Claude desktop app now supports building interactive charts and diagrams directly in chat. This feature is available in beta on all plans (including free) and enables you to visualize data and ideas without leaving your conversation. Users have created everything from Cessna 172 instrument panels to directory structure visualizations.

The /btw Command (By The Way)

This is a side-channel that lets you ask a quick question about your current work without adding it to the conversation history. While Claude is implementing a feature, you can type /btw why did you use that library? and get an answer inline without interrupting the main task.

Key Insight from WorldofAI: "The /btw command lets you ask a quick question about your current work without adding it to the conversation history. It's extremely useful when you want a fast answer but don't want to clutter the main context or derail Claude from a long-running task." -- Claude Code 2.0 MASSIVE Upgrade!

Benefits of /btw: - No context pollution -- neither the question nor the answer enters conversation history. - Does not interrupt Claude's work -- the main task keeps running in the background. - Uses the prompt cache of the main session, so cost is very low.

Limitations: - Single turn only -- you cannot ask a follow-up question. - Read only -- no tool access, so it cannot create files or diagrams.

For deeper exploration that requires tool access or follow-up questions, use /fork or the claude -c --fork session approach instead.

The /loop Command

The /loop command lets you run prompts on a schedule using a cron-style system. You can poll for status updates, set up one-time reminders, or schedule recurring tasks directly inside a Claude Code session.

/loop every 30m "Check for new PRs and summarize any that were merged"

This is a session-level scheduler -- it runs as long as your session is active.

Scheduled Tasks (Desktop App)

The Claude Code desktop app now supports persistent scheduled tasks. As long as your computer is awake and the app is open, Claude can start new local sessions at times and frequencies you choose. Use cases include:

Improved Memory System

The system prompt has been updated to improve how Claude stores feedback and project memories. The new structured format requires each memory entry to follow this template:

This structured approach makes stored memories far more useful and helps Claude recall context more accurately across sessions.

Voice Mode

Claude Code now has voice mode available to all users. Toggle it with:

/v voice

You can speak your prompts instead of typing them, which is especially useful for complex instructions or when you are away from your keyboard.

Agent Skills Creator (Revamped)

The agent skills creator has been overhauled to let authors test, measure, and refine skills without coding. New features include:

Effort Levels

Every session now asks what effort level you want: low, medium, high, or max (also called ultra mode). This controls how deeply Claude reasons, how long it works, and how much it costs.

/model
# Then select effort level: low | medium | high | max

Code Review

A deep multi-agent code review system is now available for Team and Enterprise users. This is the same system Anthropic runs on nearly every internal PR. It costs approximately $15-25 per run and catches bugs that even human reviewers often miss.

Key Insight from The Pragmatic Engineer: "Every pull request at Anthropic is code reviewed by Claude Code. It catches maybe 80% of bugs. There's always an engineer that does the second pass of code review -- there always has to be a person in the loop approving the change." -- Boris Cherny, Building Claude Code with Boris Cherny

Boris also describes how deterministic checks complement the AI review. The team uses type checkers, linters, and the build system alongside Claude's non-deterministic review. Claude is particularly good at writing lint rules -- when Boris notices a recurring code pattern issue during review, instead of writing the lint rule himself, he tags Claude on the PR and says "please write a lint rule for this." Multiple parallel agents can also do "best of N" reviews to increase the probability of catching issues.

Claude as API Mentor

Claude Code now has improved knowledge of the Anthropic API itself. You can ask it about features like prompt caching, adaptive thinking, effort levels, and tool use, and it will guide you on integration. This effectively turns Claude Code into a live API documentation tool.

Excel and PowerPoint Integration (Desktop App)

The Claude desktop app now offers seamless integration with Excel and PowerPoint through add-ins. When you have multiple files open, Claude shares the full context of your conversation between them. You can pull data from spreadsheets, build tables, and update presentation decks without re-explaining any step. Skills are also available in both add-ins, so teams can save standard workflows (like running a variance analysis or building a client deck) and let others run them with a single click.

Key Concepts Overview

Before diving deeper into the subsequent chapters, here are the core concepts you will encounter throughout this guide:

Terminal-First Design

Claude Code was born in the terminal and remains terminal-first. While it integrates beautifully with VS Code, the desktop app, and even mobile, its fundamental nature is a CLI tool that interacts with your file system through bash and file editing tools.

The Permission System

Claude Code has a layered permission system that controls what it can do autonomously versus what requires your approval. Modes range from "ask for everything" to "bypass all permissions" (the latter requiring --dangerously-skip-permissions flag and a safe environment like a container or VM). Understanding permissions is essential to balancing speed with safety.

The Context Window

Claude Code operates within a 200,000-token context window. Managing this context is one of the most critical skills for effective usage. Context rot begins at roughly the halfway mark (100K-120K tokens), at which point Claude's effectiveness degrades significantly. The tools /context and /clear are your primary instruments for managing this.

Skills and Plugins Ecosystem

Skills are markdown files that teach Claude how to handle specific tasks. They load on demand (unlike CLAUDE.md, which loads every time), saving context window space. The plugin marketplace (/plugin) provides official and community-contributed skills, hooks, sub-agents, and MCP server configurations.

MCP (Model Context Protocol)

MCP servers connect Claude Code to external services -- Notion, Figma, Slack, Gmail, Playwright (browser automation), and many more. They give Claude the ability to interact with the broader software ecosystem beyond your local file system.

Sub-Agents and Agent Teams

Sub-agents delegate work to specialized child agents, each with their own system prompt, model, tools, permissions, and context window. Agent teams (experimental) take this further by having multiple agents work in parallel on different tasks, coordinating through a team leader.

Work Trees

Work trees allow multiple Claude Code instances to work on different git branches simultaneously without conflicts. Each instance operates in its own branch and the features merge when complete.

claude --work-tree feature-dark-mode
claude --work-tree feature-export

The Mindset Shift

The most important insight from all of these sources is not about any specific feature or command. It is about the mindset shift required to use Claude Code effectively.

For Technical Users

If you are an experienced developer, the shift is from writing code yourself to directing an agent that writes code for you. Your value moves from typing speed and syntax knowledge to:

Key Insight from The Pragmatic Engineer: "Always understand the layer under. It's really important because that gives you depth and more levers to work at the layer that you actually work at. The advice is the same as 10 years ago. It's still the advice today. But the layer under is a little bit different now. Before it was 'understand the VM if you're writing JavaScript.' Now it's 'understand the model.'" -- Boris Cherny, Building Claude Code with Boris Cherny

For Non-Technical Users

If you do not have a programming background, Claude Code is accessible -- but you must take an active role. Do not become what one creator calls an "accept monkey" who just hits accept on everything.

Key Insight from Chase AI: "You don't need to know how to code, but you do need to understand how these building blocks come together. Or else, what is the point of you even being there besides just hitting accept? Claude Code is so good that you can get pretty far by just being an accept monkey. But at a certain point, you need to begin to internalize what's going on, or you're going to fall on your face when you start doing more complicated projects." -- 567 Hours of Claude Code Lessons

The practical advice: ask Claude Code to explain its decisions. Ask "What am I not thinking about?" Ask "Is this the best way forward?" Ask "What would an expert do in this scenario?" You do not need to know the answers, but you must know what to ask.

The Research Agent Mindset

Claude Code is not limited to writing code. It can search the web, look up best practices, and incorporate live data. When you ask it to improve a UI, do not just say "make it look nicer." Say "make it look nicer -- use your web search to look up best practices for UI design in 2026."

This is especially important because Claude has a knowledge cutoff (approximately 9 months from the current date for Opus 4.6). By directing it to use web search, you bring current information into your workflow.

Key Insight from Chase AI: "Instead of just saying 'make this app look nicer,' I can say 'make this app look nicer -- use your web search to look up best practices for UI design in 2026.' This is super important because Claude Code has a knowledge cutoff. By telling it to use the web search tool, it'll go out online and figure out what the current best practices are." -- 567 Hours of Claude Code Lessons

The Active Learner Mindset

The most successful Claude Code users maintain a posture of active curiosity. This means:

  1. Ask Claude why it made certain decisions. When it tells you it changed files, ask what those changes mean if you do not understand them.
  2. Ask what you are not thinking about. Claude has broad knowledge and can surface considerations you might miss.
  3. Ask if there is a better way. Sometimes the first approach is not optimal, and Claude can suggest alternatives if prompted.
  4. Ask what an expert would do. Frame questions as "What would someone who is an expert in [your domain] be doing in this scenario?"
  5. Learn from the tools Claude uses. Pay attention to the bash commands it runs, the libraries it chooses, and the patterns it follows. Over time, this builds your own understanding.

The goal is not to become a passive consumer of AI-generated code. The goal is to become an informed director who can guide, evaluate, and learn from the AI's work. This is what separates an "AI developer" from what one creator calls a "brain dead vibe coder."

The Importance of Code Quality for AI

Boris Cherny brings a unique perspective from his time at Meta, where he led code quality initiatives across all of Meta's products. His research showed that code quality contributes double-digit percentages to engineering productivity -- a finding validated at the largest scale in the industry.

This matters even more in the AI era. When your codebase is clean, modular, and well-organized:

Key Insight from The Pragmatic Engineer: "If every time you build a feature, you have to think about 'do I use framework X or Y or Z' because the codebase is in a partially migrated state -- as an engineer, you're going to have a bad time. As a model, you might just pick the wrong thing. The better thing is to always have a clean codebase, always make sure that when you start a migration you finish the migration. This is great for engineers and nowadays it's great for models too." -- Boris Cherny, Building Claude Code with Boris Cherny

Who Is Claude Code For?

Claude Code serves a remarkably broad range of users. Based on the source videos, here are the primary audiences and how they benefit:

Experienced Software Engineers

For professional developers, Claude Code is a productivity multiplier. Boris Cherny was already one of the most prolific code authors at Instagram (top 2-3 by code volume). With Claude Code, he now ships 20-30 PRs per day across vastly more diverse tasks than was possible before. The key shift is that experienced engineers contribute their knowledge of architecture, design patterns, and system thinking while Claude handles implementation.

Engineers Onboarding to New Codebases

Claude Code's learn mode and explanatory output style make it an excellent onboarding companion. Instead of spending weeks reading documentation and asking teammates for context, new team members can use Claude Code to explore the codebase interactively, ask questions about design decisions, and understand how components connect.

Non-Technical Founders and Entrepreneurs

The tutorials from Chase AI and Zinho Automates demonstrate that people with no coding background can build functional web applications, deploy them to hosting platforms, and connect external services like Gmail and payment processing. The key caveat is that non-technical users must invest in understanding the building blocks, not just blindly accepting output.

Creative Professionals

The Claude desktop app's integrations with Excel, PowerPoint, and interactive chart building make it useful for analysts, marketers, and other professionals who work with data and presentations but do not write code as their primary function.

Open Source Maintainers

For project maintainers like Mitchell Hashimoto, Claude Code assists with bug fixing, feature implementation, and lint rule creation. However, as Mitchell notes, the tools also create challenges around AI-generated low-quality contributions that require new policies and workflows to manage.

Practical Use Cases Demonstrated in Source Videos

Throughout the source videos, several concrete use cases are demonstrated end-to-end:

Use Case Source Key Takeaway
Building a luxury chocolate brand website from scratch The ONLY Claude Code Tutorial Plan mode + skills + screenshot debugging = complete workflow
Building an IT services landing page with SvelteKit Claude Code Tutorial (Deutsch) CLAUDE.md + Playwright MCP + sub-agents for review/fix
Building a RAG pipeline with multimodal embeddings Google's New Model + Claude Code Plan mode + API integration + chat app in 30 minutes
Email triage and priority scoring Google's New Tool Just 10x'd Claude Code GWS CLI + business context = automated email management
Task tracker app with React 567 Hours of Claude Code Lessons TDD + plan mode + Git workflow
Shipping 20-30 PRs/day at Anthropic Building Claude Code with Boris Cherny Parallel tabs + plan mode + work trees
Scheduling Telegram notifications Claude Code 2.0 MASSIVE Upgrade! Scheduled tasks + bot integration

What Comes Next

In the chapters that follow, we will cover:

Each chapter builds on the foundation laid here: Claude Code is a powerful, hackable, terminal-first agent that rewards users who understand its concepts and take an active role in the human-AI collaboration.

Next Chapter: Setup and Configuration

Chapter 2: Setup and Configuration

Source Videos: The ONLY Claude Code Tutorial You'll Ever Need in 2026, 567 Hours of Claude Code Lessons in 20 Minutes, Claude Code Tutorial: Installation, Agents, MCP, Skills, Hooks & Plugins, Google's New Tool Just 10x'd Claude Code, Google's New Model + Claude Code Just Changed RAG Forever

Installation

Claude Code installation has been streamlined to a single command per operating system. Open your terminal and run the command for your platform:

macOS

brew install claude-code

Windows

winget install Anthropic.ClaudeCode

Linux

curl -fsSL https://claude.ai/install.sh | sh

Key Insight from Chase AI: "They have drastically smoothed out this process over the last couple months, and it is literally one line of code. Whether you're on Mac, Windows, or Linux, you're just going to copy the command for your operating system, open up your terminal, paste it in, hit enter, and it will walk you through the setup process. It takes less than a minute." -- 567 Hours of Claude Code Lessons

Post-Installation Setup

After installation, the setup wizard will walk you through:

  1. Theme selection -- Choose dark or light mode.
  2. Account connection -- Connect your Claude subscription (recommended over raw API for cost efficiency).
  3. Security acknowledgment -- Confirm you understand the tool's capabilities.
  4. Terminal setup -- Allow Claude Code to configure your terminal environment.
  5. Folder trust -- Grant Claude Code access to your current working directory.

PATH Configuration (macOS/Linux)

If your terminal reports that the claude command is not found after installation, you may need to add the installation directory to your PATH:

# The installer will suggest the exact command, typically something like:
export PATH="$HOME/.local/bin:$PATH"

Add this line to your shell configuration file (~/.zshrc, ~/.bashrc, or equivalent) to make it permanent.

Key Insight from Philip Thomas: "After installation, if your system reports that the local bin folder is not in your PATH, you will need to run the export command the installer suggests. After that, typing claude in your terminal will start Claude Code." -- Claude Code Tutorial

Subscription Requirements

To use Claude Code, you need at minimum a Claude Pro subscription ($20/month). The Claude Max subscription provides more token capacity (higher weekly limits) but the same features. You can also use the Anthropic API directly if you prefer pay-per-token pricing.

/usage    # Check your current usage against weekly limits

The /usage command shows you: - How much of your daily allocation you have consumed - How much of your weekly limit is used (e.g., "15% of weekly limit") - Extra usage charges if you have enabled API overflow

IDE Setup

While Claude Code works perfectly well in a standalone terminal, the recommended approach for most users is to run it inside Visual Studio Code.

Why VS Code?

The layout gives you three panels of information simultaneously:

Left Panel Center Panel Right Panel
File explorer -- see all folders and files Code editor -- view file contents Claude Code terminal -- interact with the agent

Key Insight from Zinho Automates: "VS Code basically gives you everything in one place. The files are on the left, the code is in the middle, and Claude Code on the right side. You can see exactly what Claude is doing to your project in real time. Every file that it creates, every line that it changes -- especially when you are learning the basics, you want to understand what exactly is going on." -- The ONLY Claude Code Tutorial

Installing VS Code and the Extension

  1. Download VS Code from code.visualstudio.com (free for all platforms).
  2. Open VS Code and navigate to the Extensions marketplace (the four-squares icon in the left sidebar).
  3. Search for "Claude Code" and install the official extension from Anthropic.
  4. Verify it is the one with millions of downloads and a verification checkmark.
  5. Click the orange icon in the top right corner of VS Code to open Claude Code.

Opening a Project

Before interacting with Claude Code, always open a project folder first:

  1. Go to File > Open Folder.
  2. Select or create the folder for your project.
  3. Claude Code will operate within whatever folder you have open -- it can read, create, and edit files inside that folder.

Key Insight from Chase AI: "Other options include things like Cursor or even Claude Code Desktop, which again, you're getting the full power of Claude Code, but now we're doing it in a graphical interface that's a bit easier to manage." -- 567 Hours of Claude Code Lessons

Alternative Environments

Beyond VS Code, Claude Code can run in:

Model Selection

Claude Code gives you access to multiple models, each with different trade-offs between speed, capability, and token cost. You switch models using:

/model

Available Models

Model Strengths Best For Cost
Opus 4.6 Most powerful reasoning, deepest thinking Planning, architecture, complex debugging, building from scratch Highest
Opus 4.6 (Extended) Same capability with larger context window Long conversations, complex multi-file projects Highest
Sonnet 4.6 Faster, cheaper, still highly capable Quick edits, simple components, routine tasks Moderate
HaQ (Haiku) Smallest, cheapest, fastest Simple questions, trivial edits, budget-conscious work Lowest

Practical Model Strategy

Key Insight from Zinho Automates: "My recommendation is to use Opus for planning and complex builds and then use Sonnet for quick edits and simple tasks." -- The ONLY Claude Code Tutorial

A cost-effective workflow pattern:

  1. Use Opus for planning. When starting a new feature or project, switch to Opus and enter plan mode. Get a thorough, well-reasoned plan.
  2. Switch to Sonnet for execution. Once you have a solid plan, the execution can often be handled by the faster, cheaper model.
  3. Use HaQ for trivial tasks. For simple questions, renaming variables, or quick lookups, HaQ saves significant tokens.

Key Insight from Philip Thomas: "You can differentiate which model handles which task. Use a better model for complex tasks like planning and code review, then use smaller, cheaper models for executing the plan. This way you optimize your subscription's token budget." -- Claude Code Tutorial

Effort Levels

Beyond model selection, you can also adjust the effort level within each model. This controls how much "thinking" Claude does:

/model
# Select your model, then choose effort: low | medium | high | max

You do not always need high-effort Opus 4.6 for every task. Matching effort to task complexity is a key part of being efficient with your tokens.

Key Insight from Chase AI: "You can adjust the effort level -- how much thinking Opus does -- because chances are I don't always need to use high-effort Opus 4.6, a nuclear bomb for every single task." -- 567 Hours of Claude Code Lessons

CLAUDE.md Configuration

The CLAUDE.md file is one of the most important configuration mechanisms in Claude Code. It is a markdown file that Claude reads automatically at the start of every session. Think of it as a rulebook for your project.

What Goes in CLAUDE.md

A typical CLAUDE.md might include:

Example CLAUDE.md

# Project: IT Services Landing Page

## Tech Stack
- SvelteKit 2 with Svelte 5
- Tailwind CSS 3
- DaisyUI 4

## Code Style
- Always add descriptive comments to code
- Use TypeScript strict mode
- Follow mobile-first responsive design

## Design
- Minimalist Apple-inspired aesthetic
- Use Bento grid layouts where appropriate
- Hero section should include cursor spotlight effect

Levels of CLAUDE.md

CLAUDE.md files can exist at multiple levels, each scoping the instructions differently:

Level Location Scope
Global (Home) ~/.claude/CLAUDE.md Applies to ALL Claude sessions in every project
Project Root ./CLAUDE.md (in project root) Applies to all sessions within this project
Parent Directory CLAUDE.md in a parent folder Inherited by child projects
Child Directory CLAUDE.md in a subdirectory Applies only when working within that subdirectory

Key Insight from Philip Thomas: "You can have a CLAUDE.md in your home folder that applies to all sessions in every project -- put things there that are universally relevant. A CLAUDE.md in your project root applies just to that project. And you can even have CLAUDE.md files in subdirectories for folder-specific rules, like different conventions for your test folder versus your components folder." -- Claude Code Tutorial

The Critical Rule: Keep It Minimal

The CLAUDE.md file is always fully loaded into the context window at the start of every session. Every token in your CLAUDE.md consumes part of your 200K context budget. This means:

Only include information that Claude needs in every single interaction.

Key Insight from Philip Thomas: "Since the CLAUDE.md is always fully loaded into the context, you should keep it as short as possible. Only include the most important information that you really need at every point. Otherwise, you waste context unnecessarily." -- Claude Code Tutorial

If Claude only needs certain information for specific tasks (like a style guide for frontend work), put it in a skill instead. Skills load on demand, so they only consume context when they are actually needed.

Auto-Generating CLAUDE.md

If you already have an existing codebase, you can have Claude analyze it and generate a CLAUDE.md automatically:

/init

This command has Claude examine your project structure, dependencies, and codebase, then create a CLAUDE.md with relevant context about your tech stack and conventions.

Key Insight from Zinho Automates: "Create a CLAUDE.md file for this project. Always use the Noir Chocolate brand colors -- dark brown, gold, and cream. Always add comments to the code. Always make sure the site is mobile responsive. From this point on, every time you start a new session in this project, Claude reads those instructions before doing anything." -- The ONLY Claude Code Tutorial

Settings and the /config Menu

The /config command opens Claude Code's settings panel where you can adjust a variety of behaviors:

/config

Key Settings

Output Style for Learning

If you are new to a codebase or new to development entirely, set the output style to explanatory:

/config
# Navigate to Output Style > Explanatory

Key Insight from The Pragmatic Engineer: "For people that are onboarding to the Claude Code team or to Anthropic, we recommend explanatory mode -- it tends to be better for new codebases that you haven't been in before." -- Boris Cherny, Building Claude Code with Boris Cherny

API Key Management

Claude Code can connect to the Anthropic API in two ways:

During setup, choose "Claude Account with Subscription" and authorize through your browser. This connects your Pro or Max subscription directly. Benefits:

2. Direct API Key

For developers who want pay-per-token pricing or need to connect to specific Anthropic API features, you can use a direct API key. You can also enable Extra Usage in your account settings, which uses the API as overflow when your subscription quota is exhausted.

Third-Party API Keys

When working with external services (MCP servers, RAG pipelines, etc.), you will often need additional API keys. A common pattern is to store them in a .env file:

# .env
PINECONE_API_KEY=your-key-here
GEMINI_API_KEY=your-key-here
OPENROUTER_API_KEY=your-key-here

Key Insight from Nate Herk: "I went ahead and switched to plan mode. I copied the documentation URL, pasted it in, and said, 'Hey, Claude Code, I want to use this embeddings model with a Pine Cone database. Please build me a plan, create a .env file with the placeholders, and I will drop in my API keys.' Claude built the plan, created the .env, and I just filled in the three keys. That was it." -- Google's New Model + Claude Code Just Changed RAG Forever

Security Warning

Never commit API keys or .env files to version control. Always add them to your .gitignore:

# .gitignore
.env
.env.local
*.key
credentials.json

Before deploying any project, run a security review:

Review this project for security issues

Key Insight from Zinho Automates: "Always remember to run a security check before deploying. Just type 'review this project for security issues.' Claude scans for exposed keys, vulnerabilities, and risks." -- The ONLY Claude Code Tutorial

.cloudignore for Excluding Files

The .cloudignore file tells Claude Code which files and directories to ignore. This is similar to .gitignore in concept. It prevents Claude from reading or modifying files that should not be part of its context.

Common .cloudignore Patterns

# Dependencies
node_modules/
vendor/
.venv/

# Build outputs
dist/
build/
.next/

# Secrets
.env
.env.*
credentials/
*.key
*.pem

# Large binary files
*.zip
*.tar.gz
*.mp4
*.mov

# IDE and OS files
.DS_Store
.idea/
.vscode/settings.json

# Generated files that should not be modified
package-lock.json
yarn.lock

Why .cloudignore Matters

  1. Context efficiency -- Prevents Claude from reading large, irrelevant files that consume tokens.
  2. Safety -- Keeps sensitive files (credentials, secrets) out of Claude's reach.
  3. Focus -- Directs Claude's attention to the files that actually matter for your task.
  4. Performance -- Prevents Claude from wasting time analyzing generated or binary files.

Connecting External Tools

MCP Servers

MCP (Model Context Protocol) servers extend Claude Code's capabilities by connecting it to external services. Common integrations include:

Service What It Enables
Playwright Browser automation -- Claude can open pages, take screenshots, validate visual output
Gmail Send/receive emails, notifications from contact forms
Notion Read/write Notion pages and databases
Slack Post messages, read channels
Figma Access design files
Google Workspace Full access to Drive, Docs, Sheets, Calendar, Gmail via GWS CLI

Installing an MCP Server

From the Claude Code documentation, popular MCP servers have one-line installation commands:

# Example: Install Playwright for browser automation
claude mcp add stdio-server playwright --command "npx @anthropic/mcp-playwright"

For MCP servers not in the documentation, you can use natural language:

Set up the Gmail MCP server. Use your web search for guidance.

Key Insight from Philip Thomas: "To install Playwright as an MCP server for browser automation, just run the command from the documentation. After restarting Claude Code, you can use /mcp to verify the server is connected. Now Claude can open browsers, navigate to pages, take screenshots at different resolutions, and identify visual issues." -- Claude Code Tutorial

The Google Workspace CLI (GWS)

One of the most powerful recent integrations is the Google Workspace CLI, which gives Claude Code access to your entire Google ecosystem through a single tool:

Key Insight from Nate Herk: "Google just dropped what some are already calling the most powerful workspace CLI on the internet. Any of my Claude Code projects can access everything in my Google environment. And all I had to do was install one simple thing. It has over 100 built-in skills -- chain command patterns for common tasks like creating docs from templates, reading sheet data and creating reports, finding free time and scheduling meetings." -- Google's New Tool Just 10x'd Claude Code

To install the GWS CLI:

  1. Copy the GitHub repository URL.
  2. Tell Claude Code: "I want to install this GWS CLI, read through the documentation, and help me install everything I need."
  3. Claude reads the docs, checks prerequisites, and walks you through the setup.
  4. Create a Google Cloud project and set up OAuth credentials (desktop app type).
  5. Download the client secret JSON and place it in ~/.config/gws/.
  6. Enable the required Google APIs (Gmail, Drive, Docs, Sheets, Calendar, etc.).
  7. Run gws oauth login to authenticate.

Key Insight from Nate Herk: "It's not the same as having all these different API endpoints or MCP configs and tools that would take up more context. It's basically just one tool with structured JSON responses that our AI agent is really good at working with." -- Google's New Tool Just 10x'd Claude Code

MCP Context Warning

MCP servers consume context window space, even when you are not actively using them. Some heavy MCP servers can consume 10-20% of your context window just by being loaded.

Key Insight from Chase AI: "Don't forget MCP servers do take up some portion of your context window. Sometimes they're small, but there are very heavy MCP servers that can right off the bat eat up 10, 15, 20% of your context window, even if you're not using them. If they're loaded, they're taking up tokens." -- 567 Hours of Claude Code Lessons

Installing Plugins and Skills

The Plugin Marketplace

Access the plugin marketplace with:

/plugin

This shows available plugins that can contain any combination of: - Skills -- Markdown instruction files Claude loads on demand - Hooks -- Commands that run before or after Claude performs certain actions - Sub-agents -- Specialized child agents with their own models and context - MCP servers -- External service connections

The official Anthropic marketplace comes pre-configured. As of early 2026, there are 56+ plugins available.

Installing a Plugin

/plugin
# Navigate to "Discover"
# Select a plugin (e.g., "Front-End Design")
# Choose installation scope:
#   - User scope (available in all your projects)
#   - Project scope for all collaborators (checked into repo)
#   - Project scope for you only (local)

Key Insight from Philip Thomas: "When you install a plugin, you choose the scope: user-level (global for you), project-level for all collaborators (shared via the repo), or project-level just for you (local). For something like front-end design skills, user-level usually makes sense so it is available everywhere." -- Claude Code Tutorial

Plugin Safety

Be cautious with third-party plugin sources. Stick to reputable sources:

Key Insight from Philip Thomas: "Make sure you use reputable sources for plugins. Check that GitHub repositories have a reasonable number of stars -- at least a few thousand -- so you don't install something that could cause harm." -- Claude Code Tutorial

Creating a Custom Status Line

One practical setup tip is creating a persistent status line that always shows your context window usage:

Build me a status line that always shows:
- Current folder
- Active model
- Context window percentage used

This gives you a running indicator at the bottom of your terminal that looks like:

📁 my-project | 🤖 Opus 4.6 | 📊 Context: 34%

Key Insight from Chase AI: "You can have Claude Code create a status line that always shows the amount of context used. It shows what folder you're in, what model you're on, and your context percentage. So you always have a running tally of where you're at. This doesn't come out of the box -- you can just prompt Claude Code and say 'build me a status line with context window percentage always visible' and it will build it for you." -- 567 Hours of Claude Code Lessons

Git and GitHub Setup

Claude Code integrates deeply with Git and GitHub. Setting up this connection early is essential for version control.

Connecting GitHub

Connect my GitHub account, commit this code, and push

Claude walks you through: 1. Authenticating with GitHub 2. Initializing a git repository (if one does not exist) 3. Creating commits with meaningful messages 4. Pushing to a remote repository

Installing the GitHub App

For more advanced GitHub integration (like tagging Claude on pull requests or issues):

/setup github

This installs the GitHub app, which enables: - Tagging @claude on any pull request or issue for AI-powered code review - Automated PR reviews on every push - AI-written lint rules directly in PR comments

Key Insight from The Pragmatic Engineer: "You can run /setup github or something similar in Claude Code and it'll install the GitHub app, which then makes it so you can tag Claude on any pull request, any issue. I use this every single day." -- Boris Cherny, Building Claude Code with Boris Cherny

Quick Reference: Essential Slash Commands

Here is a reference table of the most important slash commands you will use during setup and daily work:

Command Purpose
/model Switch between models and set effort levels
/config Open settings panel
/plugin Browse and install plugins
/mcp Manage MCP server connections
/usage Check subscription usage and limits
/init Auto-generate CLAUDE.md from existing codebase
/context View current context window usage
/clear Clear conversation and reset context
/memory View and edit Claude's stored memories
/permissions Manage tool permissions
/hooks Configure pre/post action hooks
/agents Create and manage sub-agents

When setting up Claude Code for the first time, follow this sequence:

  1. Install Claude Code using the one-line command for your OS.
  2. Install VS Code and the Claude Code extension from Anthropic.
  3. Connect your Claude subscription during the setup wizard.
  4. Open your project folder in VS Code before starting Claude Code.
  5. Create a minimal CLAUDE.md in your project root with tech stack and core conventions.
  6. Install essential plugins via /plugin (e.g., Front-End Design if you do UI work).
  7. Set up Git/GitHub if not already configured.
  8. Install relevant MCP servers (Playwright for web projects, Gmail for notifications, etc.).
  9. Create a .cloudignore to exclude node_modules, .env files, and build artifacts.
  10. Build a status line showing your context window usage.
  11. Set your default model via /model (Opus 4.6 for complex work, Sonnet 4.6 for routine tasks).
  12. Test your setup by giving Claude a small task and verifying the end-to-end workflow.

Previous Chapter: Introduction | Next Chapter: Core Concepts

Chapter 3: Core Concepts

Source Videos: Anthropic Just Dropped the Feature Nobody Knew They Needed, 567 Hours of Claude Code Lessons in 20 Minutes, Claude Code Tutorial: Installation, Agents, MCP, Skills, Hooks & Plugins, The ONLY Claude Code Tutorial You'll Ever Need in 2026, Building Claude Code with Boris Cherny, Claude Code 2.0 MASSIVE Upgrade!

Context Window Management

If there is one concept that separates effective Claude Code users from struggling ones, it is understanding and managing the context window. This is not optional knowledge -- it is the single most important operational concept for getting consistent, high-quality results.

What Is the Context Window?

The context window is the total amount of information Claude can "hold in mind" during a session. For Claude Code, this is 200,000 tokens. Everything costs tokens:

Think of it as a budget. Every interaction draws from this budget, and once it is spent, the quality of responses degrades.

Context Rot: The Invisible Danger

The critical insight is not about running out of tokens -- it is about context rot. Research and practical experience show that when you reach approximately 50-60% of the context window (around 100,000-120,000 tokens), Claude's effectiveness drops significantly.

Key Insight from Chase AI: "Context rot tells us that when we hit about 100,000 -- so the halfway mark for Claude Code, or about 120,000 tokens -- the effectiveness of our AI system drops drastically. It begins to nose dive. If we know that, then it's very important that we stay out of this danger area of the back half of our context window." -- 567 Hours of Claude Code Lessons

This means your effective working budget is closer to 100K tokens, not 200K. Planning around this reality is essential.

Monitoring Your Context Usage

Use the /context command at any time to see where you stand:

/context

This displays a visual breakdown of your context window:

Context Window Usage (21,000 / 200,000 tokens - 11%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]

Breakdown:
  System Prompt:    ████  8%
  System Tools:     ██    4%
  Custom Agents:    █     2%
  Memory/Skills:    █     1%
  Messages:         ███   6%
  Free Space:              79%

Key Insight from Philip Thomas: "With /context I can see a nice visualization -- the system prompt, system tools, custom agents, memory files, skills, then the messages (everything I've written with Claude), and how much free space is left." -- Claude Code Tutorial

Clearing and Compacting Context

When you approach the danger zone (50-60% usage), you have several options:

Full Clear

/clear

This wipes your entire conversation history and resets the token count. Unlike web-based AI tools, this is not catastrophic -- Claude Code can always re-read your files and project structure to regain context about your codebase.

Key Insight from Chase AI: "You might think clearing the whole history is scary because you're used to web AI where clearing history means talking to a random bot with no idea what's going on. Inside Claude Code, it always has context because it can always look at your files and project. Restarting the conversation isn't really a hit." -- 567 Hours of Claude Code Lessons

Compact (Summarize)

/compact

This preserves a summary of the conversation rather than wiping it entirely. Claude compresses the history into a condensed version that retains the key decisions and context but uses far fewer tokens. This happens automatically when Claude hits the token limit (called "autocompact"), but you should not wait for that.

Key Insight from Philip Thomas: "Claude Code compresses context automatically after a certain point -- you'll see 'Compacting' appear. But it's much better to manage this yourself rather than letting it hit the wall. Use /clear when switching to an entirely new task, or /compact when you want to keep a summary of what you've done." -- Claude Code Tutorial

Strategic Clearing

The best practice is to clear context at natural transition points:

Context Management Best Practices

  1. Keep CLAUDE.md minimal. It loads every session and consumes tokens permanently.
  2. Use skills instead of CLAUDE.md for specialized knowledge. Skills load on demand.
  3. Use sub-agents for complex tasks. Each sub-agent has its own context window.
  4. Use plan mode first, then clear and execute. The plan is stored in Claude's understanding of your files, not just in conversation history.
  5. Never let autocompact manage your context. Take active control with /context, /clear, and /compact.
  6. Build a status line that shows context percentage so you always know where you stand.
  7. Be aware of MCP server overhead. Heavy MCP servers can consume 10-20% of context even when idle.

Key Insight from Chase AI: "By managing your context window in this manner, this will put you way ahead of the competition that doesn't think about this at all and instead allows Claude Code to just autocompact. We don't want to do that." -- 567 Hours of Claude Code Lessons

Permission Modes

Claude Code's permission system controls what the agent can and cannot do without your explicit approval. Understanding these modes is critical for balancing speed with safety.

Cycling Through Modes

You can cycle through permission modes at any time by pressing Shift+Tab:

Default → Accept Edits → Plan Mode → [back to Default]

The Five Permission Modes

1. Default (Standard Behavior)

Prompts for permission on first use of each tool. Claude can read files on its own, but must ask before editing files, running bash commands, or performing any action that modifies your system.

2. Accept Edits

Automatically accepts file edit permissions for the session. Claude can create and modify files without asking, but still needs permission for bash commands (installing dependencies, deleting files, running scripts).

Key Insight from Chase AI: "Accept Edits means Claude can make file changes on its own without asking. But if it wants to do bash commands -- actually interact with your computer, whether that's installing dependencies or doing file deletions -- it's going to ask for explicit permission." -- 567 Hours of Claude Code Lessons

3. Plan Mode

Claude can analyze files and create plans but cannot modify files or execute commands. This is a read-only, thinking-only mode.

Key Insight from Philip Thomas: "In Plan Mode, Claude can analyze but not modify files or execute commands. It's purely about making a plan -- what should be done, what steps to take, what files to change. No actual execution happens." -- Claude Code Tutorial

4. Don't Ask

Auto-denies all tool usage unless specifically pre-approved. This is a restrictive mode where Claude cannot do anything unless you have explicitly whitelisted specific permissions via /permissions.

5. Bypass Permissions

Skips all permission prompts. Claude can edit files, run any bash command, install packages, delete files, and interact with your system without any approval gates.

This mode requires a special startup flag:

claude --dangerously-skip-permissions

Key Insight from Chase AI: "Bypass permissions is a bit more dangerous, but it does allow you to run through your workflows more quickly. As you become more advanced, this is something you'll probably be doing, but at the beginning, if that seems too scary, just stick with Accept Edits." -- 567 Hours of Claude Code Lessons

Permission Management via /config

For persistent permission settings (not just session-level cycling):

/config
# Navigate to "Default Permission Mode"
# Select your preferred default

You can also grant specific persistent permissions:

/permissions
# Whitelist specific tools or patterns

For example, you might allow all npm install commands but still require approval for other bash operations.

Plan Mode: Your Most Important Workflow

Plan mode deserves its own section because it is arguably the most important workflow pattern in Claude Code. Every experienced user interviewed across the source videos emphasizes the same thing: always start with plan mode for new projects and complex features.

Why Plan Mode Matters

Without plan mode, Claude takes your prompt and immediately starts coding. It makes assumptions, picks frameworks, chooses file structures -- all without consulting you. For simple tasks, this is fine. For anything complex, it leads to rework, wrong assumptions, and wasted context.

With plan mode, Claude instead:

  1. Asks clarifying questions
  2. Proposes an architecture
  3. Outlines the file structure
  4. Lists the steps it will take
  5. Waits for your approval before executing anything

Activating Plan Mode

Three ways to enter plan mode:

# Method 1: Shift+Tab twice in the terminal
Shift+Tab → Accept Edits → Shift+Tab → Plan Mode

# Method 2: Via /config
/config
# Set "Default Permission Mode" to Plan Mode

# Method 3: Specify in your prompt
"In plan mode, create a plan for a task tracker app with React"

The Plan Mode Workflow

Here is the complete workflow Boris Cherny uses for every task:

  1. Enter plan mode (Shift+Tab twice).
  2. Give Claude your prompt. Be specific about what you want but do not over-specify implementation details.
  3. Claude asks clarifying questions. Answer them. This is a collaborative conversation.
  4. Claude produces a plan. It includes setup steps, file structure, design decisions, implementation steps, and a verification strategy.
  5. Review the plan. Is anything wrong? Is there a better approach? Tell Claude before it starts coding.
  6. Approve and execute. When the plan looks right, you typically say "Yes, clear context and bypass permissions."
  7. Claude executes in a checklist pattern. You can watch it check off items in real time.

Key Insight from Chase AI: "Plan mode is one of the most powerful features of Claude Code, and it's what you need to be on settings-wise every single time you start a new project or try to implement a brand new feature. Instead of taking your command and running with it and starting to code right away, Claude has a back and forth with you where it asks questions and you figure out the best path forward." -- 567 Hours of Claude Code Lessons

Example: Plan Mode in Action

User (Plan Mode ON):
Build a premium chocolate brand website with a luxury design,
product showcase, and contact form.

Claude:
Before I start, I have a few clarifying questions:
1. What is the brand name?
2. What color scheme do you prefer?
3. Is this e-commerce (with purchasing) or a showcase site?
4. Do you want real product images or placeholders?
5. Any specific sections beyond the product showcase and contact form?

User:
Brand name is "Noir Chocolate". Colors: dark brown, gold, cream.
Showcase only (no e-commerce). Placeholders for images.
Add an About section and customer testimonials.

Claude:
Here is my plan:

## Project Structure
- index.html (main page)
- styles.css (styling)
- script.js (interactions)

## Sections
1. Navigation bar
2. Hero section with brand statement
3. Product grid with hover effects
4. About section
5. Customer testimonials
6. Contact form
7. Footer

## Design Approach
- Minimalist luxury aesthetic
- Dark brown, gold, cream palette
- Responsive mobile-first design
- Subtle animations on scroll

## Steps
1. Create project structure
2. Build HTML skeleton
3. Implement CSS styling
4. Add JavaScript interactions
5. Test responsiveness
6. Verify all sections

Shall I proceed?

The "Clear Context" Pattern

When a plan is approved and you are ready to execute, the recommended pattern is to say:

Yes, clear context and bypass permissions

This clears the planning conversation (which has served its purpose) and gives Claude full autonomy to execute the plan efficiently. The plan itself is reflected in the files Claude creates, so the conversation history of the planning phase is no longer needed.

Key Insight from Philip Thomas: "The strategic use of Plan Mode is essential. Before you let Claude loose to make changes and potentially go down the wrong path, use Plan Mode to see how it would approach the problem. If something is wrong, correct it before execution. This saves enormous amounts of time and tokens." -- Claude Code Tutorial

Boris Cherny's Parallel Planning

Boris takes plan mode further by running multiple planning sessions in parallel:

  1. Start Claude in plan mode in Tab 1 with Task A. While it is thinking, move to Tab 2.
  2. Start Claude in plan mode in Tab 2 with Task B. While it is thinking, move to Tab 3.
  3. Continue through Tabs 3, 4, 5.
  4. Return to Tab 1 when notified it is done, review the plan, approve.
  5. Cycle through all tabs approving and executing plans.

Key Insight from The Pragmatic Engineer: "I enter plan mode, I give it a prompt. As it's chugging along, I'll go to my second tab and start the second Claude also in plan mode. Get it chugging along. Then go to the third tab, the fourth one. With Opus 4.6, once there is a good plan, it will one-shot the implementation almost every time." -- Boris Cherny, Building Claude Code with Boris Cherny

Conversation Management

Claude Code provides several tools for managing your conversation flow without polluting your context or losing progress.

/btw -- The Side Channel

The /btw command lets you ask a question about Claude's current work without adding it to the conversation history. This is the feature Ray Amjad describes as "the feature nobody knew they needed."

/btw why did you choose that library?
/btw summarize the changes so far
/btw what does this function do?

How it works: - The question appears in an inline overlay. - Claude answers using the full context of the current conversation (it can see everything done so far). - Neither the question nor the answer enters the conversation history. - The main task continues running in the background while the answer is generated. - Uses the prompt cache of the main session, so cost is very low. - Press Escape, Enter, or Space to dismiss the answer.

Key Insight from Ray Amjad: "This is a side channel built into Claude Code where you can ask any question you want without polluting the main conversation and keep all the context of what was done so far. The main session behind it is still working away. Since answering the question uses the prompt cache of the main session, the cost to answering any question is really low." -- Anthropic Just Dropped the Feature Nobody Knew They Needed

Limitations of /btw

When to use /btw vs. fork:

Use Case Tool
Quick factual question /btw
"Why did you do X?" /btw
Need a diagram or artifact Fork session
Want to explore an alternative approach /fork
Need to read additional files Fork session
Deep dive into architecture Fork session

/fork -- Branch the Conversation

The /fork command creates a branching point in your conversation. It moves you to a forked version where you can explore different approaches without affecting the main conversation.

/fork

After forking: - You are now on the forked branch. - Changes you make here do not affect the original session. - You can copy the resume command from the fork to continue the original session in another terminal pane.

Fork Session (External)

For deeper explorations, you can create a completely separate session that copies the context:

# In a new terminal pane (Ctrl+D to split):
claude -c --fork session

This creates a copy of the last session. You can: - Ask detailed questions without polluting the main conversation - Create artifacts (mermaid diagrams, documentation) - Explore alternative implementations - Close the fork (Ctrl+W) and resume the main session

Key Insight from Ray Amjad: "I would personally use /btw as a quick question and then use fork session for any deep dives -- anything that requires reading files (since /btw can't read files, it only uses the context in the conversation so far), producing artifacts like mermaid diagrams, or exploring a different approach." -- Anthropic Just Dropped the Feature Nobody Knew They Needed

/rewind -- Go Back in Time

The /rewind command lets you go back to a previous point in both the conversation and the code. Think of it as a save point restore.

/rewind
# Select the point in the conversation to restore to
# Choose "Restore code and conversation"

This is one of the most powerful recovery tools in Claude Code. If Claude goes down the wrong path:

  1. Do not try to argue with it in the current context (this adds bad context).
  2. Do not press Escape/Ctrl+C and try to correct from where you are.
  3. Instead, use /rewind to go back to before the mistake happened.
  4. Re-prompt with the correct information.

Key Insight from Ray Amjad: "Rather than arguing with some stale context where Claude made a bad decision early on -- and having that stale wrong context polluting 20-30% of the context window -- you should instead /rewind earlier on and then reprompt with the correct prompt that has the additional detail." -- Anthropic Just Dropped the Feature Nobody Knew They Needed

The Context Pollution Principle

The key idea that ties /btw, /fork, and /rewind together is context pollution. As your agent works, you do not want to interrupt it with tangential questions, explanations, or corrections that add noise to the conversation. Every piece of irrelevant information in the context window degrades future outputs.

Key Insight from Ray Amjad: "A good analogy is when it comes to humans. If you're working on a task in deep focus, someone taps you on the shoulder and asks a quick question. It can take you a while to resume the task. This is kind of like adding a random question-answer into the LLM context window. You're polluting it with things the LLM did not need and only you needed." -- Anthropic Just Dropped the Feature Nobody Knew They Needed

Rules for avoiding context pollution:

  1. Use /btw for tangent questions -- never interrupt the main flow.
  2. Use fork for deep dives -- keep exploration separate from execution.
  3. Use /rewind instead of correction prompts -- go back to a clean state rather than adding "actually, I meant..." messages.
  4. Clear context at natural break points -- do not let old conversation accumulate indefinitely.
  5. Only the plan you specified at the beginning is necessary for the agent to complete its goal. Everything else is noise.

The Memory System

Claude Code has two memory mechanisms that persist across sessions: CLAUDE.md (manual) and Auto-Memory (automatic).

CLAUDE.md (Manual Memory)

As covered in Chapter 2, CLAUDE.md files provide explicit instructions that load at every session start. This is your deliberate, curated memory.

Key constraint: CLAUDE.md loads fully every session, consuming tokens. Keep it minimal and factual.

Auto-Memory

Auto-Memory is Claude's built-in mechanism for automatically saving useful patterns and preferences it discovers while working with you. These are stored in a .claude/memory.md file in a project-specific directory.

Examples of auto-memories: - "This project uses flexbox for layouts" - "The developer prefers detailed comments" - "Tests should use the vitest framework" - "Environment variables are stored in .env.local"

The Structured Memory Format

Claude Code 2.0 introduced a structured format for memory entries. Each memory should follow this template:

## [Rule/Fact]
- **Fact:** What the rule or pattern is
- **Why:** The reason or motivation behind the rule
- **How to Apply:** When and how this rule should influence behavior

Example:

## Use TypeScript Strict Mode
- **Fact:** All new files should use TypeScript with strict mode enabled
- **Why:** The team decided strict mode catches more bugs at compile time
  and the codebase has been fully migrated
- **How to Apply:** When creating new .ts files, always include strict
  type checking. When editing existing files, add proper type annotations
  to any functions that lack them.

Key Insight from WorldofAI: "Memory writing rules now enforce a structured format. Each memory should begin with the rule or fact, followed by why (the reason or motivation), and how to apply it (when or how this rule should influence Claude's behavior). This structured template makes stored memories far more useful and helps Claude recall context more accurately." -- Claude Code 2.0 MASSIVE Upgrade!

Managing Memory

View and edit Claude's stored memories:

/memory

This opens the memory file for inspection. You can: - Review what Claude has stored - Delete memories that are no longer relevant - Add memories manually - Correct inaccurate memories

Key Insight from Zinho Automates: "You can view and edit all of this anytime with the /memory command. So you are always in control of what Claude remembers." -- The ONLY Claude Code Tutorial

Memory vs. Skills vs. CLAUDE.md

Understanding when to use each storage mechanism is important:

Mechanism When It Loads Best For Token Cost
CLAUDE.md Every session, always Core tech stack, universal rules, project identity Constant (always loaded)
Auto-Memory Every session, always Learned patterns, user preferences Constant (always loaded)
Skills On demand, when relevant Specialized workflows, detailed instructions Only when needed

The key optimization: if information is only needed sometimes, it should be a skill, not a CLAUDE.md entry or memory. Skills load on demand and do not consume context when they are not in use.

Key Insight from Philip Thomas: "That is the biggest difference from CLAUDE.md -- skills are only loaded into context when Claude actually needs them. This saves tokens. If Claude needs to do frontend work, it loads the frontend skill. If it is doing backend work, it does not load the frontend skill." -- Claude Code Tutorial

Voice Mode

Claude Code supports voice input, allowing you to speak your prompts instead of typing them.

Activating Voice Mode

/v voice

This toggles voice mode on, and you can begin speaking to Claude Code. Your speech is transcribed and treated as a normal text prompt.

When Voice Mode Is Useful

Key Insight from WorldofAI: "Claude Code had released voice mode, which is where you can prompt any sort of generation with your voice. You simply use the /v voice command to toggle it on and you can speak to your Claude Code agent. It has now been rolled out to every user of Claude Code." -- Claude Code 2.0 MASSIVE Upgrade!

The @ Symbol: Surgical File Targeting

When you want Claude to modify a specific file without touching anything else, use the @ symbol:

@styles.css Make all the buttons gold with a hover effect that makes them slightly darker

This tells Claude exactly which file to edit. It will not touch other files -- no changes to HTML, no changes to JavaScript, only the specified CSS file.

Key Insight from Zinho Automates: "By using the @ symbol, I'm telling Claude exactly which file to edit. You can see it's only editing styles.css. It's not touching the HTML. It's not touching the JavaScript. Just the CSS file. That's the power of the @ symbol -- surgical precision on which files Claude edits." -- The ONLY Claude Code Tutorial

This is especially useful when: - You have a multi-file project and only want changes in one place - You want to prevent unintended side effects - You are making targeted style or content changes

Screenshot Debugging

One of Claude Code's most practical features is the ability to debug visual issues using screenshots. Instead of describing a layout problem in words, you can show Claude what is wrong.

The Workflow

  1. Take a screenshot of the issue (e.g., a broken mobile layout).
  2. Drag the screenshot directly into the Claude Code prompt.
  3. Describe the problem briefly: "Fix this alignment problem. The products are stacking weird on mobile."
  4. Claude analyzes the screenshot, identifies the CSS issue, and rewrites the code to fix it.

Key Insight from Zinho Automates: "Instead of trying to explain the problem in words, I just took a screenshot of the issue, dragged it right into Claude, and said 'fix this alignment problem.' Claude analyzed the screenshot, looked at the layout, the spacing, the breakpoints, identified the issue in the CSS, and rewrote it. This is screenshot debugging. It's a game changer. You don't need to know CSS or media queries. You just show Claude the problem and it fixes it." -- The ONLY Claude Code Tutorial

Enhanced Visual Debugging with Playwright

For automated visual validation, connect the Playwright MCP server. This gives Claude the ability to:

Key Insight from Philip Thomas: "With Playwright connected, Claude can open the browser, navigate to the project, take screenshots at mobile, tablet, and desktop resolutions, identify visual problems, and fix them -- all autonomously. It took 9 minutes, but it found 5 issues and implemented fixes for all of them, including verifying each fix with new screenshots." -- Claude Code Tutorial

Sub-Agents and Delegation

Sub-agents are specialized child agents that Claude Code's main agent can delegate work to. Each sub-agent has its own:

Creating Sub-Agents

/agents
# Select "Create new agent"
# Choose scope: Project-level or Global
# Choose creation method: Manual or AI-assisted

When creating via AI assistance, you describe what the agent should do:

This agent should perform code reviews whenever code is written
or modified. After analysis, it should return a comprehensive
summary of suggested changes.

Then specify: - Tools: Which tools it can access (all, or a subset) - Model: Which model it should use (Opus for complex reasoning, Sonnet for execution) - Color: Visual indicator in the terminal (e.g., red for review, green for fixing) - Memory: Whether the agent should maintain its own memory

Practical Example: Review and Fix Pipeline

A powerful pattern from the Philip Thomas tutorial is creating two complementary sub-agents:

Agent 1: Code Reviewer (Opus, Red) - Runs on the more capable model (Opus) - Reads and analyzes code for issues - Returns a detailed review with suggestions

Agent 2: Code Fixer (Sonnet, Green) - Runs on the faster, cheaper model (Sonnet) - Takes the review output and implements fixes - Optimizes code based on reviewer suggestions

You then invoke them:

Please review the code with the appropriate sub-agent and
then fix the issues with the appropriate sub-agent.

Key Insight from Philip Thomas: "I can differentiate which model handles which task. I use Opus for the code review agent because it needs deep reasoning, and Sonnet for the code fixer because it already has detailed instructions from the reviewer. This way I optimize my token budget -- the expensive model only handles the complex analysis, and the cheaper model handles execution." -- Claude Code Tutorial

Why Sub-Agents Help with Context

Sub-agents are not just about task specialization. They are a context management strategy. Each sub-agent has its own context window, which means:

Key Insight from Philip Thomas: "Sub-agents are also helpful for context management. Each sub-agent has its own context window, so they help offload work from the main agent. For complex tasks, the main agent might run out of context, but by delegating to sub-agents, each piece of work fits within its own context budget." -- Claude Code Tutorial

Hooks: Deterministic Automation

Hooks let you define commands that run automatically before or after Claude performs certain actions. Unlike AI-driven behavior (which is probabilistic), hooks are deterministic -- they always execute when their trigger condition is met.

Hook Types

Trigger When It Fires
Post Tool Use (Edit/Write) After Claude edits or creates a file
Post Tool Use (Bash) After Claude runs a bash command
Session Start When a new Claude Code session begins
Sub-Agent Start When a sub-agent is launched

Common Hook Example: Auto-Format

The most common hook is running a code formatter after every file edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ["edit", "write"],
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

This ensures every file Claude creates or modifies is automatically formatted with Prettier.

Creating Hooks

/hooks
# Select trigger type (e.g., "After Tool Execution")
# Add matcher (e.g., "write, edit")
# Add command (e.g., the Prettier command)
# Choose storage scope (User settings, Project settings local, Project settings shared)

Key Insight from Philip Thomas: "The advantage of hooks is that they are deterministic. It is not up to the AI to decide whether to run the formatter -- it always happens. Every time Claude uses the edit or write tool, the hook fires." -- Claude Code Tutorial

Frameworks and Advanced Patterns

Claude Code Frameworks

Several community frameworks modify how Claude Code approaches problems. These are not replacements for Claude Code -- they are overlays that change its workflow logic:

Key Insight from Chase AI: "Frameworks are like mods for Claude Code. It's still Claude Code doing everything, but if you use something like GSD, it changes the logic for how it approaches certain problems. It's a personal preference, but there are good frameworks that can improve your ability to create complex projects." -- 567 Hours of Claude Code Lessons

Work Trees for Parallel Development

Work trees allow multiple Claude Code instances to work simultaneously on different git branches without conflicts:

# Terminal 1
claude --work-tree feature-dark-mode

# Terminal 2
claude --work-tree feature-export-pdf

Each instance works in its own branch. When both are done, you merge the features together.

Key Insight from Chase AI: "Work trees allow us to have different versions of Claude Code working on different tasks simultaneously in different git branches. You open separate terminals with the --work-tree flag and whatever feature you're implementing. Once they're both done, you merge the features." -- 567 Hours of Claude Code Lessons

Agent Teams (Experimental)

Agent teams are an experimental feature that takes parallel work further. Instead of isolated work tree instances, agent teams coordinate through a team leader:

Use agent teams to:
1. Improve the UI
2. Add a blog section
3. Add authentication
4. Add a newsletter signup

Claude breaks this into four parallel tasks, each handled by a team member, with a coordinator ensuring everything integrates properly.

Key Insight from Chase AI: "In agent teams, they talk to one another. The agent doing UI, the one doing the blog, and the one doing authentication all speak to each other and they even have a team leader coordinating all their actions. It's meant to mock an actual dev crew." -- 567 Hours of Claude Code Lessons

Test-Driven Development with Claude Code

A pro tip from multiple sources is to instruct Claude to use test-driven development (TDD) from the planning stage:

During the plan stage, tell Claude Code to execute this in
a test-driven development manner.

This means Claude will: 1. Write tests first that define the expected behavior 2. Implement the code to pass those tests 3. Verify by running the test suite 4. Catch issues before they reach production

Key Insight from Chase AI: "The third troubleshooting step is to just try to avoid problems altogether. During your plan stage, tell Claude Code to execute in a test-driven development manner." -- 567 Hours of Claude Code Lessons

Claude Code often spontaneously runs tests on its own (especially with Opus 4.5+), but explicitly requesting TDD ensures it is built into the workflow from the start.

Quick Reference: Core Commands

Command Purpose Context Impact
/context View context window usage None
/clear Clear conversation history completely Frees all message tokens
/compact Summarize and compress conversation Reduces message tokens
/btw [question] Ask a side question without polluting context None
/fork Branch the conversation Creates separate context
/rewind Restore to a previous save point Removes later messages
/model Switch model and effort level None
/memory View/edit stored memories None
/v voice Toggle voice mode None
@filename Target a specific file for edits None
Shift+Tab Cycle permission modes None
/hooks Configure automation hooks None
/agents Create/manage sub-agents None
/loop Schedule recurring prompts Adds scheduled tasks

Putting It All Together: A Complete Workflow

Here is how all these concepts combine in a real development session:

  1. Start Claude Code in your project folder with VS Code open.
  2. Check your context: /context to verify a clean starting point.
  3. Enter plan mode: Shift+Tab twice.
  4. Describe your task with enough detail for Claude to ask good questions.
  5. Answer Claude's clarifying questions during the planning phase.
  6. Review the plan and make corrections before execution.
  7. Approve with: "Yes, clear context and bypass permissions."
  8. Monitor execution as Claude checks off its task list.
  9. Use /btw for any questions that come up during execution.
  10. If something goes wrong, use /rewind to go back to a clean state.
  11. When the task is complete, use /clear or /compact before starting the next task.
  12. Commit your code using Git (Claude can handle this for you).
  13. Repeat for the next feature, always starting fresh with plan mode.

This workflow leverages every core concept: context management, permissions, plan mode, conversation hygiene, and the side-channel tools that keep your context clean and your output high-quality.

Previous Chapter: Setup and Configuration

Chapter 4: Tools and Workflows

Source Videos: 10 Claude Code Plugins to 10X Your Projects (Chase AI), 567 Hours of Claude Code Lessons in 20 Minutes (Chase AI), The ONLY Claude Code Tutorial You'll Ever Need in 2026 (Zinho Automates), Mitchell Hashimoto's New Way of Writing Code (The Pragmatic Engineer), Claude Code 2.0 Has Arrived (Simon Scrapes), Google's New Tool Just 10x'd Claude Code (Nate Herk)

Claude Code's real power comes not just from the AI model itself, but from the ecosystem of tools it can leverage and the workflows you build around them. This chapter covers the built-in tools, the best external CLI and automation tools, and the debugging workflows that separate productive developers from those who just "accept, accept, accept."

4.1 Built-In Tools

Claude Code ships with a set of built-in tools that it uses automatically to interact with your project. Understanding these tools helps you understand what Claude Code can and cannot do without additional setup.

File Editing Tools

Claude Code has two primary file manipulation tools:

When Claude Code modifies your project, you will see it request permission to use one of these tools (unless you have accept edits mode enabled). The distinction matters because hooks (covered in Chapter 6) can be triggered specifically on write or edit events.

Search and Read Tools

Claude Code can read any file in your project directory and search across your codebase. It uses tools like:

These tools are available by default and do not require any permission grants. Claude Code uses them constantly to understand your project structure before making changes.

Bash / Command Execution

Claude Code can execute terminal commands on your machine. This is the tool that requires the most careful permission management (see Chapter 2 on permissions). Through bash, Claude Code can:

Key Insight from The Pragmatic Engineer: Mitchell Hashimoto, creator of Terraform and Ghostty terminal, keeps an AI agent "always running in the background" while he works. The terminal has become central to AI-assisted development -- as he notes, if you told him in 2023 that terminal usage would go up, he would have said no. But Claude Code and similar tools have driven a surge in terminal-based workflows. -- Mitchell Hashimoto's New Way of Writing Code

Claude Code has a built-in web search tool that allows it to find current information online. This is particularly valuable because the underlying model has a knowledge cutoff.

Make this app look nicer (use your web search to look up
best practices for UI design in 2026)

Key Insight from Chase AI: "This is super important and definitely is a value add because remember Claude Code has a knowledge cutoff. Opus 4.6's cutoff is about 9 months ago. But there's things that have happened since then that perhaps you want to bring into your application." -- 567 Hours of Claude Code Lessons

4.2 Git Workflow Integration

Git is not just a nice-to-have with Claude Code -- it is your safety net. Claude Code is deeply fluent in Git and GitHub operations, and building a disciplined Git workflow is one of the most important things you can do to protect your work.

Why Git Matters for AI-Assisted Development

When Claude Code makes changes, those changes happen to real files on your real filesystem. Unlike a chat interface where you can just start over, Claude Code's edits persist. Git gives you:

  1. Save points -- Every commit is a snapshot you can return to.
  2. Rollback capability -- If Claude makes a mistake, you can revert.
  3. Branch isolation -- Experimental changes can happen on a branch without affecting your main code.
  4. History -- A clear record of what changed, when, and why.

Setting Up Git with Claude Code

Getting started is as simple as telling Claude Code what you want:

Connect my GitHub account, commit this code, and then push.

Claude Code will walk you through connecting your GitHub account, creating an initial commit, and pushing to a repository. It handles the entire flow conversationally.

Key Insight from Chase AI: "Think of GitHub as a free place where you can store all your code save points. Claude Code is very much an expert in how to use Git and GitHub." -- 567 Hours of Claude Code Lessons

Frequent Commits, Clear Histories

The best practice with AI-assisted development is to commit frequently -- more frequently than you might in traditional development. Here is why:

Claude Code can handle commit messages for you:

Commit the current changes with a descriptive message

Or you can be more specific:

Commit these changes. The message should describe
that we added responsive mobile layout to the product grid.

The /rewind Command vs. Git

Claude Code offers /rewind, which lets you go back to a previous point in the conversation and the code simultaneously. Think of it as going back to a previous save point.

However, /rewind is what Chase AI calls "a novice's approach to code save points and version control." It works within a single session but does not persist across sessions and does not give you the full power of branching, merging, and collaborative workflows that Git provides.

Use /rewind for: Quick undo within a session when you want to try a different approach.

Use Git for: Everything else -- persistent save points, collaboration, deployment, and professional version control.

Worktrees for Parallel Development

For advanced users, Git worktrees allow you to run multiple Claude Code sessions on different features simultaneously, each in its own Git branch:

claude --worktree feature-dark-mode
claude --worktree feature-export-pdf

Each terminal runs its own Claude Code instance working on a separate branch. When both features are complete, you merge them together. This is similar to agent teams but with proper Git branch isolation.

Key Insight from Chase AI: "Work trees allows us to do the same thing [as agent teams], but they work in different git branches. You open up separate terminals with this command, and then you'll actually merge the features once they're both done." -- 567 Hours of Claude Code Lessons

4.3 Image and Screenshot Debugging

One of Claude Code's most powerful and underutilized features is its ability to analyze images. You can drag and drop screenshots directly into the Claude Code prompt, just as you would in the Claude web interface.

The "Fix This" Workflow

The screenshot debugging workflow is simple and remarkably effective:

  1. See a visual problem in your app (layout issue, styling bug, broken component).
  2. Take a screenshot of the problem.
  3. Drag the screenshot into the Claude Code prompt.
  4. Say "fix this" and describe the issue briefly.
[screenshot dragged in]
Fix this alignment problem. The products are stacking
weird on mobile and the spacing is off.

Key Insight from Zinho Automates: "This is screenshot debugging. And as you can see, it's a game-changer. You don't need to explain the problem in words. You don't need to know CSS or media queries. You just show Claude the problem and it fixes it for you. This alone has saved hours of debugging time." -- The ONLY Claude Code Tutorial

Design Reference Workflow

Beyond debugging, you can use screenshots as design references:

  1. Take a screenshot of a website or design you admire.
  2. Drag it into Claude Code.
  3. Tell Claude to match that style.
[screenshot of luxury brand website]
Make my website look more like this. I want the same
elegant high-end feel.

Claude Code will analyze the image and update your CSS to match the aesthetic. You can then iterate:

Make the header more elegant. Add a subtle animation
to the hero section. Make the product grid more premium
with hover effects.

Key Insight from Zinho Automates: "Take a screenshot of a luxury chocolate brand website and then drag it into Claude. And then say, 'Make my website look more like this.' Claude analyzed the image. It updates the CSS and you get a high-end look instantly." -- The ONLY Claude Code Tutorial

Visual Validation with Playwright

For automated visual checking, you can combine screenshots with the Playwright browser automation tool (covered in Section 4.6). Claude Code can use Playwright to:

Key Insight from Philip Thomas: In his tutorial, Philip demonstrates Claude Code using Playwright MCP to navigate to a local development server, take screenshots at mobile/tablet/desktop resolutions, identify five visual problems (including text wrapping issues and broken grid layouts), and fix them all -- then re-screenshot to verify the fixes. -- Claude Code Tutorial (Deutsch)

4.4 The @filename Directive for Surgical Editing

When you want Claude Code to edit only specific files and leave everything else untouched, use the @ symbol followed by the filename.

Basic Usage

@styles.css Make all the buttons gold with a hover
effect that makes them slightly darker.

When you use @styles.css, Claude Code knows to only edit that one file. It will not touch your HTML, JavaScript, or any other files -- just the CSS.

Why This Matters

Without the @ directive, Claude Code may decide to modify multiple files to accomplish your request. This is often desirable for complex features, but for targeted changes it can cause unintended side effects.

Use @ when you want: - Surgical precision on a single file - To prevent Claude from modifying files you have already reviewed - To make a quick style change without risking structural modifications - To focus Claude's attention on a specific component

Skip @ when you want: - Claude to determine which files need modification - A feature that spans multiple files - Claude to refactor across your codebase

Key Insight from Zinho Automates: "By using the @ symbol, I'm telling Claude exactly which file to edit. You can see it's only editing styles.css. It's not touching the HTML. It's not touching the JavaScript, just the CSS file. And that's the power of the @ symbol -- you get surgical precision on which files Claude edits." -- The ONLY Claude Code Tutorial

4.5 Google Workspace CLI (GWS)

The Google Workspace CLI is a game-changing tool that gives Claude Code access to your entire Google ecosystem through simple bash commands. Released by Google as an open-source project, it replaces the need for complex MCP servers or API integrations.

What GWS Can Do

GWS provides Claude Code with one unified interface to:

Service Capabilities
Google Drive Search, list, upload, download, move, copy, share files
Gmail Read, send, label, archive, search emails
Google Calendar Create, edit, delete, search events
Google Docs Create, read, edit documents with proper formatting
Google Sheets Read, write, manipulate spreadsheet data
Google Slides Create and edit presentations

On top of individual service access, GWS comes with over 100 built-in "recipes" -- pre-made multi-step workflow patterns like creating docs from templates, reading sheet data to generate reports, or finding free time and scheduling meetings.

Key Insight from Simon Scrapes: "It's one tool that gives Claude Code access to your entire Google ecosystem. Drive, Gmail, Calendar, Docs, Sheets, Slides, absolutely everything. And it comes with over 100 built-in recipes." -- Claude Code 2.0 Has Arrived

Why GWS Beats API-Based Approaches

If you have ever used tools like n8n or Make to create Google Docs programmatically, you know the pain: documents come out with raw markdown formatting, and you need additional API calls to make them look presentable.

GWS is different because it runs bash commands that talk directly to Google. The result is properly formatted documents with headers, images, links, and styling -- not raw markdown dumps.

Key Insight from Nate Herk: "I know how many times you guys have tried to use something like Claude or n8n to build you a Google doc and you do this over API and it ends up just looking like raw markdown. This in contrast is running bash commands that talk directly to Google. So you get properly formatted docs with headers, images, links, everything." -- Google's New Tool Just 10x'd Claude Code

Installing GWS

The simplest approach is to give Claude Code the GWS GitHub repository link and let it handle the installation:

I want to install the GWS CLI. Here's the repo:
https://github.com/google/gws
Read through the documentation and help me install
everything I need.

Claude Code will read the docs, check your prerequisites, and walk you through the setup.

GWS Authentication Setup

The setup requires creating a Google Cloud project and configuring OAuth:

  1. Create a Google Cloud project at console.cloud.google.com.
  2. Set up an OAuth consent screen (Internal for personal use, External with test users for broader access).
  3. Create OAuth credentials -- choose "Desktop app" as the application type.
  4. Download the client secret JSON and save it to ~/.config/gws/.
  5. Enable the APIs you want to use (Gmail, Drive, Docs, Sheets, Calendar, Slides) in your Google Cloud project.
  6. Run gws auth login to authenticate.

Key Insight from Nate Herk: "If you just go back and forth a little bit with Claude Code, say 'Hey, that didn't work. Hey, this is what I'm seeing.' It will be able to get you there. It's going to be your best friend for something like this because remember, it can read all of the actual documentation." -- Google's New Tool Just 10x'd Claude Code

Practical GWS Use Cases

Email triage and prioritization:

Grab my unread emails from today. Based on what you know
about my business and priorities, give them a priority
score. If the score is below 5, mark them as read.

Document creation from content:

Take this YouTube transcript and create a resource guide
as a Google Doc. Include proper headers, links, and
formatting.

Slide deck creation:

Create a presentation in Google Slides about our Q1
results. Use my brand guidelines and logo.

Key Insight from Nate Herk: On visual validation for slides -- Nate describes giving Claude Code access to ChromeDevTools so it could screenshot its own Google Slides output, identify spacing issues, and fix them automatically. This created a "visual validation loop" for programmatic document creation. -- Google's New Tool Just 10x'd Claude Code

GWS Limitations to Know

4.6 Playwright for Browser Automation

Playwright is an open-source browser automation tool from Microsoft that Claude Code can use to interact with web browsers -- navigating pages, filling forms, clicking buttons, taking screenshots, and more.

Installation

# Install from the Playwright CLI GitHub
# Or simply ask Claude Code:

Install the Playwright CLI and its skills for me.

After installing the dependencies, install the skills:

playwright-cli install-skills

Use Cases

UI testing and visual validation:

Use Playwright to open my app at localhost:3000,
navigate through all pages, and report any visual
issues you find.

Form testing:

Use Playwright to test the signup form. Try submitting
with empty fields, invalid email, and valid data.
Report what happens in each case.

Browser automation:

Use Playwright to go to [website], fill in the search
form with "Claude Code tutorial", and save the first
five results.

The /show command: Playwright CLI includes a show command that gives you a visual dashboard of what all your browser agents are doing, even when running headless.

Key Insight from Chase AI: "Anything you could essentially normally do in a browser, you could do using Playwright. And it's also great for things like testing UI design or testing form submissions, anything that's kind of laborious when you're changing something inside your project and you need to manually test it." -- 10 Claude Code Plugins to 10X Your Projects

4.7 Firecrawl for Web Scraping

Firecrawl is a web scraping tool designed to return data in a format optimized for AI agents. It goes beyond Claude Code's built-in web search by providing structured, deep web scraping capabilities.

Installation

# Single command installs both CLI and skill:
firecrawl-cli install

Four Core Commands

Command Purpose
scrape Extract content from a single URL
crawl Follow links and scrape multiple pages from a site
map Discover the structure of a website
search Search the web and return AI-optimized results

You do not need to remember which command to use -- Claude Code will choose the right one based on your request.

Use Cases

Key Insight from Chase AI: "If you've never used Firecrawl, the pitch is that it's web scraping, but the data it brings back is tailor-made for AI agents. It's definitely a step above just asking Claude Code to use its web search tool." -- 10 Claude Code Plugins to 10X Your Projects

4.8 The CLI vs. MCP Principle

This is one of the most important principles in the Claude Code ecosystem, and it is easy to miss:

Always prefer CLI tools over MCP servers when both options exist.

Why CLI Beats MCP

MCP (Model Context Protocol) servers were created in 2024 as a standard for connecting AI assistants to external systems. They work, but they carry overhead:

  1. Context window cost -- MCP servers consume tokens just by being loaded, even when not in use. Heavy MCP servers can eat 10-20% of your context window immediately.
  2. Additional complexity -- MCP is essentially trying to replicate what CLI tools already do natively.
  3. Less reliable -- CLI tools are purpose-built for terminal environments; MCP servers add an abstraction layer.

CLI tools, by contrast, are native to the terminal where Claude Code lives. They are purpose-built, well-tested, and add zero context overhead until actually used.

Key Insight from Chase AI: "I myself, someone who was looking at these tools all day, all the time, had been using the Supabase MCP up until very recently. I didn't even realize the Supabase CLI actually existed, which is kind of wild because I use Supabase all the time. I understand that CLI tools are in general superior to MCP tools. Yet me, who -- this is like my profession -- didn't even realize that. If you feel like you're overwhelmed, I promise you're okay." -- 10 Claude Code Plugins to 10X Your Projects

The Supabase Case Study

Chase AI uses Supabase as the canonical example of this principle:

Installation of the CLI:

Hey, download and install the Supabase CLI tool.

Claude Code will download and install the dependency, and then you interact with Supabase through natural language, just as you would with the MCP -- but with better performance and lower token cost.

When to Use MCP

MCP servers still have their place:

The CLI + Skill Pattern

When you install a new CLI tool, pair it with an appropriate skill that teaches Claude Code how to use that specific tool effectively:

Anytime you install a new CLI, make sure you check their
GitHub or documentation to see if they already have
purpose-built skills for this tool.

Most well-maintained CLI tools now provide Claude Code skills. Supabase, Vercel, Playwright, and Firecrawl all offer dedicated skills that can be installed alongside the CLI.

4.9 Debugging Workflows

Effective debugging with Claude Code goes beyond just throwing errors at it. Here are the three primary debugging workflows, ordered from simplest to most sophisticated.

Workflow 1: Screenshot Debugging

As covered in Section 4.3, this is the fastest path for visual bugs:

  1. See the problem in your browser.
  2. Screenshot it.
  3. Drag into Claude Code.
  4. Say "fix this."

This works remarkably well for layout issues, styling bugs, responsive design problems, and UI inconsistencies.

Workflow 2: Copy-Paste Error Debugging

When you encounter errors outside of Claude Code's immediate environment -- such as deployment errors on Vercel, runtime errors in a browser console, or CI/CD failures -- the workflow is:

  1. Copy the error message from wherever it appears.
  2. Paste it into Claude Code with context about what you were doing.
I'm having this deployment issue on Vercel:

[paste error message here]

The deployment was working yesterday. I only changed
the product grid component.

Key Insight from Chase AI: "The second troubleshooting step is just to copy and paste the errors into Claude Code. Let's say I had an issue deploying my application and I'm getting an error somewhere outside of the Claude Code infrastructure. It's as simple as copying this code, bringing it into Claude Code and saying, 'Hey, I'm having this issue.'" -- 567 Hours of Claude Code Lessons

Workflow 3: Test-Driven Development

The most proactive debugging approach is to avoid bugs altogether by telling Claude Code to write tests first:

Execute this in a test-driven development manner.
Write the tests first, then implement the feature
to pass those tests.

This approach: - Catches bugs before they happen - Creates a regression test suite that protects against future changes - Gives Claude Code clear success criteria for implementation - Makes it easier to verify that the feature works correctly

Key Insight from Chase AI: "The third troubleshooting step is to just try to avoid it altogether. During your plan stage, tell Claude Code to execute this in a test-driven development manner." -- 567 Hours of Claude Code Lessons

Combining All Three

The most effective debugging workflow combines all three approaches:

  1. Proactive: Start with TDD to minimize bugs.
  2. Reactive (visual): When you see visual issues, use screenshot debugging.
  3. Reactive (errors): When you hit errors, copy-paste them in with context.

And always, always commit your working code before starting a debugging session so you have a clean rollback point.

4.10 Additional CLI Tools Worth Knowing

Beyond the tools covered in depth above, here are other CLI tools frequently recommended by the Claude Code community:

GitHub CLI

The GitHub CLI (gh) lets Claude Code manage your entire GitHub workflow from the terminal -- creating issues, opening pull requests, reviewing code, and managing releases.

# Installation varies by OS -- or just ask Claude Code:

Install the GitHub CLI for me.

Claude Code is already deeply knowledgeable about Git and GitHub, so you often do not even need a dedicated skill for this one.

Key Insight from Chase AI: "Coding agents like Claude Code are so spun up on Git and GitHub that you really don't need a skill to use this to its full potential." -- 10 Claude Code Plugins to 10X Your Projects

Vercel CLI

For deployment workflows, the Vercel CLI allows Claude Code to deploy, check deployment status, and manage your hosting -- all from the terminal.

# Install the Vercel CLI and its skill:

Install the Vercel CLI and the Vercel deployment skill.

This pairs especially well with agent loops for monitoring deployment status:

/loop every 5 minutes check the Vercel deployment
status and notify me if there are any errors.

NotebookLM-PY

This CLI tool connects NotebookLM to Claude Code, allowing you to offload research, analysis, and content creation (videos, infographics, slide decks, flashcards, podcasts) to NotebookLM -- all through natural language in the terminal.

# Install from the NotebookLM-PY GitHub:
# Copy install commands, then:
notebooklm-skill install

Excalidraw Diagram Skill

Created by community member Cole Medin, this skill lets you create diagrams through natural language with Claude Code. Particularly useful for presentations and documentation.

Create a system architecture diagram showing the
relationship between our frontend, API layer,
database, and authentication service.

Key Insight from Chase AI: "All of these diagrams -- I didn't do any of this manually. All of these things were created using Claude Code, which saves me a ton of time and actually gave me something to speak to." -- 10 Claude Code Plugins to 10X Your Projects

4.11 The Tool Selection Framework

With so many tools available, it is easy to fall into the trap of installing everything. Here is a framework for deciding what to add to your stack:

Questions to Ask Before Adding a Tool

  1. Do I actually need this? Not every project needs web scraping or browser automation.
  2. Is there a CLI version? Always check for a CLI before installing an MCP.
  3. Does it have a skill? Tools with dedicated Claude Code skills work better.
  4. What is the context window cost? MCP servers consume tokens just by being loaded.
  5. Am I adding capability or just complexity? More tools do not equal better output.

Key Insight from Chase AI: "We don't want to fall into the trap of thinking increased capability equals increased performance. There is a sweet spot somewhere, there is that middle ground that we're always searching for, and hopefully we're getting you closer to that place." -- 10 Claude Code Plugins to 10X Your Projects

Starter Stack Recommendation

For most projects, start with:

  1. Git/GitHub CLI -- Version control (essential)
  2. One deployment tool -- Vercel CLI or equivalent
  3. One database tool -- Supabase CLI or equivalent
  4. Web search -- Built-in, no setup needed
  5. Playwright -- If you need browser automation or visual testing

Add more only when you have a specific need. Every tool you add is another thing to maintain, another potential point of failure, and another consumer of your mental bandwidth.

Chapter Summary

Tool Type Purpose CLI or MCP?
File Edit/Write Built-in Modify project files Built-in
Bash Built-in Execute terminal commands Built-in
Web Search Built-in Find current information Built-in
Git/GitHub CLI CLI Version control and collaboration CLI
GWS CLI Google Workspace access CLI
Playwright CLI/MCP Browser automation and testing Either
Firecrawl CLI Web scraping for AI agents CLI
Supabase CLI Database and authentication CLI (not MCP)
Vercel CLI Deployment CLI
NotebookLM-PY CLI Research and content creation CLI
Excalidraw Skill Diagram creation Skill

The golden rules: 1. Always prefer CLI over MCP when both exist. 2. Pair every CLI tool with an appropriate skill. 3. Commit frequently -- Git is your safety net. 4. Use screenshots for visual debugging -- do not describe what you can show. 5. Start with a minimal tool stack and add only when needed.

Chapter 5: MCP Servers

Source Videos: Claude Code Plugins: The Complete Guide (Hyperautomation Labs), Claude Code Tutorial (Deutsch) (Philip Thomas), 10 Claude Code Plugins to 10X Your Projects (Chase AI), The ONLY Claude Code Tutorial You'll Ever Need in 2026 (Zinho Automates), Google's New Tool Just 10x'd Claude Code (Nate Herk)

MCP servers are the bridge between Claude Code and the outside world. While Claude Code is powerful on its own for reading, writing, and reasoning about code, MCP servers extend its reach to external services -- databases, browsers, email platforms, design tools, and more. This chapter covers what MCP servers are, how to configure them, the most important ones to know, and when to choose MCP over other extension mechanisms.

5.1 What Are MCP Servers?

MCP stands for Model Context Protocol. It is an open standard created by Anthropic in 2024 that defines how AI assistants connect to and interact with external systems.

Think of MCP servers as specialized translators. Each MCP server knows how to talk to a specific external service and presents that service's capabilities to Claude Code in a standardized way. When you install the Playwright MCP server, Claude Code gains the ability to control a web browser. When you install the Supabase MCP server, Claude Code can create and query databases.

Key Insight from Hyperautomation Labs: "Model Context Protocol lets Claude talk to external services. GitHub, databases, APIs, deployment platforms." -- Claude Code Plugins: The Complete Guide

How MCP Servers Work

At a high level, the MCP architecture works like this:

You (prompt) --> Claude Code --> MCP Server --> External Service
                                    |
                              Response flows
                              back through
                              the same chain
  1. You ask Claude Code to do something that requires an external service (e.g., "check my Gmail for new emails").
  2. Claude Code recognizes it has an MCP server available for Gmail.
  3. Claude Code sends a request to the MCP server.
  4. The MCP server translates that request into the appropriate API calls to the external service.
  5. The external service responds, and the data flows back through the MCP server to Claude Code.
  6. Claude Code processes the response and presents the results to you.

What MCP Servers Provide

Each MCP server typically exposes one or more of the following to Claude Code:

Key Insight from Philip Thomas: "MCP steht fur Model Context Protocol und dient dazu, dass man LLMs die Moglichkeit gibt mit Anwendungen und Diensten zu interagieren." (MCP stands for Model Context Protocol and serves to give LLMs the ability to interact with applications and services.) -- Claude Code Tutorial (Deutsch)

5.2 MCP Configuration

MCP servers are configured through JSON files that tell Claude Code which servers to load, how to start them, and what credentials to use.

Configuration Locations

MCP servers can be configured at three levels:

Level File Location Scope
User ~/.claude/mcp.json Available in all projects
Project (shared) .claude/mcp.json (in project root) Shared with team via version control
Project (local) .claude/settings.local.json Private to your machine

Configuration Format

A basic MCP configuration in mcp.json looks like this:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@anthropic/mcp-server-playwright"
      ]
    },
    "supabase": {
      "command": "npx",
      "args": [
        "@supabase/mcp-server",
        "--project-ref",
        "your-project-ref"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Each server entry has:

Installing MCP Servers via Command Line

Many popular MCP servers provide a one-line installation command. For example, to install Playwright:

claude mcp add stdio playwright -- npx @anthropic/mcp-server-playwright

This command adds the Playwright MCP server to your local configuration file. After running it, restart Claude Code to pick up the new server.

Verifying MCP Server Status

Once Claude Code has restarted, you can check the status of your MCP servers:

/mcp

This opens the MCP management interface where you can see all configured servers and their connection status.

Key Insight from Philip Thomas: After installing the Playwright MCP, he runs /mcp to verify: "Hier sehen wir schon Playwright ist connected." (Here we can see Playwright is connected.) -- Claude Code Tutorial (Deutsch)

5.3 Key MCP Servers

Supabase MCP Server

Purpose: Database management and user authentication.

Supabase provides a PostgreSQL database, vector database for RAG, and authentication system with a generous free tier.

Installation:

# One-line install from Claude Code docs:
claude mcp add stdio supabase -- npx @supabase/mcp-server --project-ref <your-ref>

Use cases: - Creating and managing PostgreSQL databases - Setting up user authentication flows - Vector database operations for RAG applications - Managing database schemas through natural language

Important caveat: As discussed in Chapter 4, you should actually use the Supabase CLI instead of the MCP server for most tasks. The CLI is more reliable, consumes no context window tokens when idle, and has dedicated Claude Code skills.

Key Insight from Chase AI: "You should actually never use the Supabase MCP server in reality. There's no point because we should be using the Supabase CLI instead. We always, always, always try to use CLIs instead of MCPs." -- 10 Claude Code Plugins to 10X Your Projects

When to use the MCP anyway: If you are completely new to Supabase and want the simplest possible setup to get started, the MCP is a reasonable first step. Just know that you should migrate to the CLI as you gain experience.

Playwright MCP Server

Purpose: Browser automation and visual testing.

Playwright gives Claude Code the ability to control a web browser programmatically -- navigating pages, clicking elements, filling forms, taking screenshots, and validating visual output.

Installation:

claude mcp add stdio playwright -- npx @anthropic/mcp-server-playwright

Use cases:

Key Insight from Philip Thomas: In his demonstration, he tells Claude Code: "Schau dir das Webprojekt unter dieser Adresse an und prufe, ob es visuelle Probleme gibt bei unterschiedlichen Auflosungen. Fixe die Probleme, die dir auffallen." (Look at the web project at this address and check if there are visual problems at different resolutions. Fix the problems you notice.) Claude Code then opens a browser, takes screenshots at mobile/tablet/desktop sizes, identifies five problems, and fixes them all. -- Claude Code Tutorial (Deutsch)

Playwright workflow example:

Use Playwright to navigate to http://localhost:5173.
Take screenshots at mobile (375px), tablet (768px),
and desktop (1440px) widths. Identify any visual
problems and fix them. Then re-screenshot to verify
the fixes.

Claude Code will: 1. Request permission to use Playwright tools 2. Navigate to the URL 3. Take screenshots at each viewport size 4. Analyze the screenshots for visual issues 5. Edit the CSS/HTML to fix the problems 6. Re-screenshot to verify the fixes worked

Database MCP Servers

Beyond Supabase, there are MCP servers for various database systems:

The pattern is the same for all of them: install the MCP server, authenticate, and then Claude Code can create tables, write queries, and manage data through natural language.

Service Integration MCP Servers

MCP servers exist for connecting Claude Code to services you already use:

Service Purpose
GitHub Issues, PRs, code review
Slack Messaging and notifications
Notion Documentation and wikis
Figma Design file access
Linear / Asana Project management
Sentry Error monitoring

Key Insight from Hyperautomation Labs: "External integration plugins connect Claude to services you already use. GitHub for issues and PRs. Slack for messaging. Linear and Asana for project management. Figma for design. Sentry for error monitoring. Notion for docs." -- Claude Code Plugins: The Complete Guide

Installing via the Plugin System

You can also discover and install MCP servers through the plugin marketplace:

/plugin

Browse the available plugins and look for MCP integrations. Some plugins bundle MCP servers with skills and hooks in a single installable package.

Key Insight from Zinho Automates: "MCP lets Claude talk to outside tools, things like Gmail, Google Sheets, Notion, databases, you name it. You can also install MCP servers through the plugin system -- just type /plugin and search for an integration." -- The ONLY Claude Code Tutorial

5.4 Google Workspace: GWS CLI vs. MCP

The Google Workspace integration deserves special attention because it represents a turning point in how Claude Code connects to external services -- and it perfectly illustrates the CLI vs. MCP principle.

The Problem with Google Workspace MCP

Before GWS CLI, getting Claude Code to work with Google Workspace was painful:

Key Insight from Simon Scrapes: "If you have ever tried to get Claude Code to create a Google Doc or manage your files through the built-in skills, you'll know this pain. For some reason, you can only manage emails and your calendar." -- Claude Code 2.0 Has Arrived

The GWS CLI Solution

Google released the Google Workspace CLI (GWS) as an open-source tool that replaces all of those separate MCP servers with a single CLI:

One tool, entire ecosystem:

GWS CLI --> Gmail, Drive, Docs, Sheets, Slides, Calendar, Admin

Key advantages over MCP: - Single tool -- One CLI replaces multiple MCP servers. - Lower overhead -- A CLI tool consumes no context window tokens when idle, unlike loaded MCP servers. - Better formatting -- Documents created via GWS bash commands come out properly formatted, unlike API-based approaches. - JSON-first responses -- Structured output that Claude Code can work with effectively. - Auto-discovery -- When Google adds new API endpoints, GWS picks them up automatically. - 100+ built-in recipes -- Pre-made multi-step workflows.

Key Insight from Nate Herk: "It's not the same as like having all these different API endpoints or all of these different MCP configs and tools that would take up more context. It's basically just one tool." -- Google's New Tool Just 10x'd Claude Code

GWS Setup: Step by Step

The full setup process (detailed in Chapter 4) involves:

  1. Install the GWS CLI -- Either directly in terminal or through Claude Code.
  2. Create a Google Cloud project -- Go to console.cloud.google.com.
  3. Set up OAuth consent screen:
  4. Choose "Internal" for personal/org use, or "External" with test users.
  5. Fill in app name and contact information.
  6. Create OAuth Client ID:
  7. Navigate to APIs & Services > Credentials.
  8. Create a new OAuth Client ID.
  9. Select "Desktop app" as the application type.
  10. Download the client secret JSON file.
  11. Save credentials:
  12. Place the downloaded JSON in ~/.config/gws/.
  13. Enable APIs:
  14. In Google Cloud Console, enable each API you need:
    • Gmail API
    • Google Drive API
    • Google Docs API
    • Google Sheets API
    • Google Calendar API
    • Google Slides API
  15. Authenticate: bash gws auth login
  16. This opens a browser window for OAuth consent.
  17. Choose your Google account and grant permissions.

Key Insight from Nate Herk: "If you already have a project that has all these APIs enabled, then you can just use that project and generate that OAuth client ID." -- Google's New Tool Just 10x'd Claude Code

Troubleshooting GWS Setup

The setup is not always smooth on the first try. Common issues and solutions:

The best advice: use Claude Code itself to troubleshoot. It can read the GWS documentation and guide you through issues.

The GWS auth isn't working. Here's the error I'm seeing:
[paste error]. Help me fix this.

5.5 Playwright Browser Automation via MCP

While Playwright was briefly covered in Section 5.3, it deserves a deeper treatment because it is one of the few tools where MCP genuinely provides unique value over a simple CLI.

Why Playwright Works Well as an MCP

Unlike databases or email services where a CLI can handle everything, browser automation requires:

These requirements align well with the MCP server model, which maintains a persistent connection.

Practical Playwright Workflows

Visual bug detection and fixing:

1. Navigate to my local app
2. Take screenshots at mobile, tablet, and desktop sizes
3. Identify visual problems
4. Fix the CSS/HTML
5. Re-screenshot to verify

Key Insight from Philip Thomas: His demonstration shows a complete visual validation loop. Claude Code identifies issues like text wrapping problems in CTAs, broken Bento grid layouts on tablets, and overlapping elements. For each issue, Claude edits the code, then re-screenshots to verify the fix -- a process he describes as "sehr praktisch" (very practical). -- Claude Code Tutorial (Deutsch)

Cross-browser/viewport testing:

Use Playwright to test my app at these breakpoints:
- 375px (iPhone SE)
- 390px (iPhone 14)
- 768px (iPad)
- 1024px (iPad landscape)
- 1440px (Desktop)
- 1920px (Large desktop)

Report any layout issues at each size.

Automated user flow testing:

Use Playwright to test the complete signup flow:
1. Navigate to /signup
2. Fill in name, email, and password
3. Click "Create Account"
4. Verify the confirmation page appears
5. Check that a welcome email notification shows up

Visual validation for generated content:

Nate Herk demonstrates using Playwright in combination with GWS to validate Google Slides. Claude Code creates a slide deck programmatically, then uses browser automation to open it, screenshot each slide, identify spacing and layout issues, and fix them.

Key Insight from Nate Herk: "I gave it access to ChromeDevTools so that it could open the page, screenshot it, look at it, and then we built a plan to add visual validation to this Google Slide Creator skill." -- Google's New Tool Just 10x'd Claude Code

5.6 When to Use MCP vs. CLI vs. Plugins

Choosing the right extension mechanism for Claude Code can be confusing. Here is a decision framework:

Decision Tree

Do you need to connect to an external service?
|
|-- YES: Does a CLI tool exist for it?
|   |
|   |-- YES: Use the CLI + a skill
|   |       (Lower overhead, more reliable)
|   |
|   |-- NO: Does an MCP server exist?
|       |
|       |-- YES: Use the MCP server
|       |-- NO: Can you build a simple CLI wrapper?
|           |
|           |-- YES: Build it
|           |-- NO: Look for community MCP servers
|
|-- NO: Do you need to change Claude's behavior?
    |
    |-- For specific tasks: Use a Skill
    |-- For automated responses: Use a Hook
    |-- For delegating work: Use a Subagent

Comparison Table

Criteria CLI MCP Skill Hook
Context window cost None (until used) Always loaded Only when triggered None
Best for External tool access Persistent connections Behavioral instructions Automated responses
Reliability High (native terminal) Medium (extra layer) High (just markdown) High (deterministic)
Setup complexity Low-Medium Medium Low Low-Medium
Requires restart No Yes No Yes

Rules of Thumb

  1. CLI first, always. If the tool has a CLI, use it. Add a skill to teach Claude Code how to use it.

  2. MCP for persistent connections. Browser automation (Playwright), real-time data feeds, and services requiring long-lived sessions are good MCP candidates.

  3. MCP for services without CLI alternatives. Some services (Figma, Notion, Slack) only offer MCP integrations.

  4. Watch your context window. MCP servers consume tokens just by being loaded. Heavy MCP servers can eat 10-20% of your context window before you even use them.

  5. Plugins bundle everything. When a plugin packages an MCP server with skills and hooks, install the plugin -- it is designed to work as a cohesive unit.

Key Insight from Chase AI: "MCPs came out in 2024 as an Anthropic creation to connect our AI assistants to different systems. However, today in 2026, our AI assistants live inside the terminal with us. So they have the ability to use CLI systems. We like the CLI more than MCP because MCP is pretty much just trying to ape what a CLI tool does, but because it's not in the terminal, there's some additional overhead." -- 10 Claude Code Plugins to 10X Your Projects

5.7 Setup and Authentication Patterns

Most MCP servers require some form of authentication. Here are the common patterns you will encounter.

Pattern 1: API Key in Environment Variable

The simplest pattern. The MCP server reads an API key from an environment variable.

{
  "mcpServers": {
    "service-name": {
      "command": "npx",
      "args": ["@service/mcp-server"],
      "env": {
        "SERVICE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Used by: Many database servers, API integrations.

Security note: API keys in mcp.json are stored in plain text. For shared projects, use .claude/settings.local.json (which should be in .gitignore) to keep secrets out of version control.

Pattern 2: OAuth Browser Flow

Used by services that require user-level authentication. When you first use the MCP server, it opens a browser window for you to sign in and grant permissions.

Used by: Google Workspace (GWS), Gmail, services with user accounts.

Setup flow: 1. Install the MCP server or CLI. 2. Run the authentication command (e.g., gws auth login). 3. Browser opens with a consent screen. 4. Sign in and grant permissions. 5. Token is stored locally for future use.

Pattern 3: Project Reference + Token

Used by platform services where you need to specify both which project to connect to and authenticate.

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "@supabase/mcp-server",
        "--project-ref",
        "abcdefghijklmnop"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "sbp_xxxxx"
      }
    }
  }
}

Used by: Supabase, Firebase, cloud platform services.

Pattern 4: CLI Authentication with MCP Wrapper

Some tools authenticate through their CLI and then the MCP server uses those stored credentials.

# Authenticate via CLI first:
supabase login

# Then the MCP server uses the stored credentials

Used by: Services with both CLI and MCP options.

Letting Claude Code Handle Authentication

In many cases, you do not need to manually configure authentication. Claude Code can walk you through the process:

Set up the Supabase MCP server. I have a Supabase
account but haven't connected it yet.

Or for services not listed in the documentation:

Set up the [service name] MCP server. Use your web
search to find the documentation and guide me through
the setup process.

Key Insight from Chase AI: "If the MCP server you want to use isn't on the list with a command already ready to go, you can just use plain language. Say, 'Hey, set up the whatever MCP server you want.' And you can tell it, 'Use your web search for guidance.' That way, it's not just fumbling around -- it will go out on the web, find the documentation, and set it up accordingly." -- 567 Hours of Claude Code Lessons

5.8 MCP Server Management Best Practices

Keep Your MCP List Lean

Every loaded MCP server consumes context window tokens. The more MCP servers you have configured, the less room you have for actual conversation and code reasoning.

Key Insight from Chase AI: "Don't forget MCP servers do take up some portion of your context window. Sometimes they're small, but there are very heavy MCP servers that can right off the bat eat up 10, 15, 20% of your context window right away, even if you're not even using them. If they're loaded, they're taking up tokens." -- 567 Hours of Claude Code Lessons

Recommendations: - Only install MCP servers you actively use. - Use project-level configuration for project-specific servers (don't load a database MCP for every project). - Periodically review and remove MCP servers you no longer need.

Use Trusted Sources

MCP servers have access to your data and can execute actions on external services. Be careful about what you install.

Key Insight from Philip Thomas: "Da sollte man naturlich immer drauf aufpassen, dass man dann auch seriose Quellen benutzt, sich nicht einfach alles mogliche da hinzufugt. Vielleicht schaut, dass die Git Repositories eine gewisse Anzahl an Sternen haben, also zumindest ein paar tausend." (You should always make sure to use reputable sources, not just add anything. Perhaps check that the Git repositories have a certain number of stars, at least a few thousand.) -- Claude Code Tutorial (Deutsch)

Checklist for evaluating MCP servers: - Is it from a known organization (Anthropic, the service provider itself)? - Does the GitHub repository have significant stars and recent activity? - Is the source code available for review? - Are there other users reporting successful use?

Scope Your Installations

When installing MCP servers through the plugin system, you will be asked about scope:

Key Insight from Hyperautomation Labs: "Choose your scope. User scope makes it available everywhere. Project scope shares it with your team through version control. Local scope keeps it private to one repo." -- Claude Code Plugins: The Complete Guide

5.9 Bundling MCP Servers in Plugins

If you are building tools for your team, you can bundle MCP servers within plugins for easy distribution.

Plugin MCP Configuration

To include an MCP server in a plugin, add an mcp.json file at the plugin root:

{
  "mcpServers": {
    "my-service": {
      "command": "node",
      "args": [
        "${CLAUDE_PLUGIN_ROOT}/mcp-server/index.js"
      ]
    }
  }
}

The ${CLAUDE_PLUGIN_ROOT} variable is important because plugins get cached after installation. Hardcoded paths will break; this variable ensures paths resolve correctly regardless of where the plugin is cached.

Key Insight from Hyperautomation Labs: "Use the CLAUDE_PLUGIN_ROOT variable for paths since plugins get cached. Your MCP server starts automatically when the plugin is enabled." -- Claude Code Plugins: The Complete Guide

When to Bundle vs. Standalone

Bundle in a plugin when: - The MCP server works together with skills and hooks as a cohesive unit. - You are distributing to a team and want one-click setup. - The MCP server is custom-built for your organization.

Keep standalone when: - It is a general-purpose MCP server (e.g., Playwright). - Different projects may need different configurations for the same server. - You want to update the MCP server independently of other components.

Chapter Summary

MCP servers extend Claude Code's reach to external services, but they come with trade-offs in context window usage and complexity. The key takeaways:

  1. Understand the hierarchy: CLI > MCP > Manual API integration. Always prefer the simpler option.

  2. Key MCP servers to know:

  3. Playwright -- Browser automation (one of the few cases where MCP genuinely adds value over CLI).
  4. Supabase -- Database and auth (but prefer the CLI).

  5. Service integrations -- GitHub, Slack, Notion, Figma for connecting to your workflow tools.

  6. Google Workspace: Use the GWS CLI, not an MCP server. One tool replaces multiple MCP servers with lower overhead and better output formatting.

  7. Context window awareness: Every loaded MCP server costs tokens. Keep your list lean and use project-level scoping.

  8. Security matters: Only install MCP servers from trusted sources. Check GitHub stars, review source code, and be cautious with credentials.

  9. Let Claude Code help: For setup and troubleshooting, Claude Code can read documentation and walk you through authentication flows. Use it.

Chapter 6: Hooks

Source Videos: Claude Code Plugins: The Complete Guide (Hyperautomation Labs), Claude Code Tutorial (Deutsch) (Philip Thomas)

Hooks are one of Claude Code's most powerful and most overlooked features. While skills tell Claude Code how to do things and MCP servers give it access to external services, hooks tell Claude Code what must always happen -- automatically, deterministically, every single time. No AI decision-making involved. If a hook is configured, it fires. Period.

6.1 What Are Hooks?

Hooks are deterministic actions that Claude Code executes in response to specific events. The key word is deterministic -- unlike skills (which Claude Code may or may not choose to use based on context), hooks always fire when their trigger conditions are met.

Think of hooks as automated rules:

These are not suggestions to Claude Code. They are hard rules that execute without AI involvement.

Key Insight from Philip Thomas: "Bei Hooks ist naturlich auch der Vorteil, dass das Ganze tatsachlich deterministisch ist. Also es ist wirklich festgelegt. Jedes Mal, wenn er dieses Tool benutzt, macht er das dann auch. Ist jetzt nicht irgendwie, dass die KI dann selber entscheidet, ob sie das tut oder nicht, sondern das sind wirklich harte Hooks. Wenn das passiert, dann mach bitte auch dies." (With hooks, the advantage is that everything is truly deterministic. It is really fixed. Every time it uses this tool, it does it. It's not like the AI decides on its own whether to do it or not -- these are really hard hooks. If this happens, then please also do this.) -- Claude Code Tutorial (Deutsch)

Why Hooks Matter

Without hooks, you are relying on Claude Code to remember and follow rules. Even with instructions in CLAUDE.md or skills, there is always a chance the AI will skip a step, forget a convention, or decide a rule does not apply in a particular context.

Hooks eliminate that uncertainty for critical operations:

6.2 Hook Events

Claude Code supports several event types that can trigger hooks. Each event fires at a specific point in Claude Code's workflow.

Post-Tool Use (post_tool_use)

Fires after Claude Code uses a tool. This is the most common hook type and is used for tasks like formatting code after edits or running tests after file changes.

When it fires: After Claude Code has successfully completed a tool action (e.g., after writing a file, after executing a bash command).

Common use cases: - Auto-format code with Prettier after every file write or edit - Run a linter after every code change - Trigger a build check after modifying source files - Update documentation after API changes

Pre-Tool Use (pre_tool_use)

Fires before Claude Code uses a tool. This is used for validation, blocking, and security checks.

When it fires: Before Claude Code executes a tool action. If the hook returns an error or blocks the action, the tool use is prevented.

Common use cases: - Block writes to production configuration files - Validate that bash commands do not target production databases - Check file permissions before edits - Require confirmation for destructive operations

User Prompt Submit (user_prompt_submit)

Fires when you press Enter on a prompt. This is used for preprocessing your input.

When it fires: After you type a prompt and submit it, but before Claude Code processes it.

Common use cases: - Log all prompts for audit purposes - Inject additional context automatically - Transform input formatting

Session Start (session_start)

Fires when Claude Code boots up. This is used for initialization tasks.

When it fires: Once, at the beginning of a new Claude Code session.

Common use cases: - Run a security audit script - Check for dependency updates - Validate the development environment - Load project-specific configurations

Subagent Start

Fires when Claude Code spawns a subagent. This is used for controlling subagent behavior.

When it fires: Each time a subagent is created by the main Claude Code agent.

Common use cases: - Validate subagent permissions - Log subagent creation for monitoring - Inject additional constraints into subagent context

Key Insight from Hyperautomation Labs: "Post tool use fires after Claude uses a tool like write or edit. Pre-tool use fires before. User prompt submit fires when you hit enter. Session start fires when Claude boots up." -- Claude Code Plugins: The Complete Guide

6.3 The Matcher Field

The matcher field is what makes hooks precise. Without a matcher, a hook would fire on every instance of its event type. The matcher lets you filter which specific tools or conditions trigger the hook.

Basic Matcher Syntax

The matcher specifies which tools the hook applies to. For post_tool_use and pre_tool_use events, the matcher filters by tool name:

{
  "hooks": {
    "post_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

In this example, the hook only fires when Claude Code uses the write or edit tools -- not when it uses read, bash, or any other tool.

Available Tool Names for Matching

Tool Name Description
write Creating or overwriting a file
edit Making targeted edits to an existing file
bash Executing a terminal command
read Reading a file's contents
glob Searching for files by pattern
grep Searching file contents

Matcher Examples

Match only file writes (not edits):

{
  "matcher": {
    "tool_name": ["write"]
  }
}

Match both writes and edits:

{
  "matcher": {
    "tool_name": ["write", "edit"]
  }
}

Match bash commands (for pre-tool security checks):

{
  "matcher": {
    "tool_name": ["bash"]
  }
}

Key Insight from Hyperautomation Labs: "The matcher field lets you filter which tools trigger the hook. Want to auto-format every file Claude writes? One hook. Want to block writes to production config? One hook." -- Claude Code Plugins: The Complete Guide

6.4 Practical Examples

Example 1: Auto-Format with Prettier After File Write

This is the most commonly cited hook example and one of the most immediately useful. Every time Claude Code writes or edits a file, Prettier automatically formats it.

Configuration:

{
  "hooks": {
    "post_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
          }
        ]
      }
    ]
  }
}

What this does: 1. Claude Code writes or edits a file (e.g., src/components/Button.tsx). 2. The hook fires immediately after the tool completes. 3. The command runs npx prettier --write on the file that was just modified. 4. The file is now consistently formatted regardless of how Claude Code structured the code.

Why this matters: - Claude Code produces code that generally follows good formatting, but not always perfectly. - Without this hook, you might need to manually format or remind Claude Code about your project's style conventions. - With this hook, formatting is guaranteed -- every time, every file.

Key Insight from Philip Thomas: He demonstrates this exact hook setup in his tutorial, showing the configuration in the settings file: "Er wurde immer, wenn er Dinge geschrieben oder editiert hat, halt folgenden Befehl ausfuhren. Und zwar, dass er halt eben diese Datei dann mit Hilfe eines Prettiers sauber formatiert." (It would always, whenever it has written or edited things, execute the following command -- formatting the file cleanly with Prettier.) -- Claude Code Tutorial (Deutsch)

Example 2: Block Production Changes

Use a pre_tool_use hook to prevent Claude Code from modifying production configuration files.

Configuration:

{
  "hooks": {
    "pre_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_FILE_PATH\" | grep -q 'production\\|prod.config\\|\\.env.prod' && echo 'BLOCKED: Cannot modify production files' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

What this does: 1. Before Claude Code writes or edits any file, this hook runs. 2. It checks whether the file path contains "production," "prod.config," or ".env.prod." 3. If the file matches a production pattern, the hook exits with code 1, blocking the action. 4. If the file does not match, it exits with code 0, allowing the action to proceed.

Why this matters: - In a real project, accidentally modifying production configuration can cause outages. - A skill or CLAUDE.md instruction saying "don't modify production files" might be forgotten by the AI. - A hook makes this rule absolute -- no exceptions, no AI judgment calls.

Example 3: Run Linter After Code Changes

Configuration:

{
  "hooks": {
    "post_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint \"$CLAUDE_FILE_PATH\" --fix"
          }
        ]
      }
    ]
  }
}

This runs ESLint with auto-fix on every file Claude Code modifies, catching issues like unused variables, missing imports, or style violations immediately.

Example 4: Security Check on Session Start

Configuration:

{
  "hooks": {
    "session_start": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx audit-ci --moderate"
          }
        ]
      }
    ]
  }
}

Every time you start a Claude Code session, it runs a security audit on your dependencies and warns you about vulnerabilities before you begin work.

Example 5: Block Destructive Bash Commands

Configuration:

{
  "hooks": {
    "pre_tool_use": [
      {
        "matcher": {
          "tool_name": ["bash"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_BASH_COMMAND\" | grep -qE 'rm -rf|drop table|DROP DATABASE|format|mkfs' && echo 'BLOCKED: Destructive command detected' && exit 1 || exit 0"
          }
        ]
      }
    ]
  }
}

This intercepts bash commands before they execute and blocks any that match known destructive patterns.

6.5 Hook Types

Hooks support different action types, each suited to different use cases.

Shell Commands

The most common hook type. Runs a shell command on your machine.

{
  "type": "command",
  "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
}

Available environment variables: - $CLAUDE_FILE_PATH -- The path to the file being written or edited. - $CLAUDE_BASH_COMMAND -- The bash command being executed (for bash tool hooks).

Exit codes: - 0 -- Success. For pre_tool_use hooks, allows the action to proceed. - Non-zero -- Failure. For pre_tool_use hooks, blocks the action.

HTTP Requests

Send an HTTP request when a hook fires. Useful for logging, notifications, and external integrations.

{
  "type": "http",
  "url": "https://your-webhook.example.com/claude-actions",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-token"
  },
  "body": "{\"event\": \"file_modified\", \"file\": \"$CLAUDE_FILE_PATH\"}"
}

Use cases: - Send a Slack notification when Claude Code modifies critical files. - Log all Claude Code actions to an external monitoring system. - Trigger CI/CD pipelines when specific files change. - Update a dashboard with real-time development activity.

LLM Prompts

Run a separate LLM call as part of the hook. This allows you to have a secondary AI review or validate Claude Code's actions.

{
  "type": "llm_prompt",
  "prompt": "Review the following code change and flag any security concerns: $CLAUDE_DIFF"
}

Use cases: - Automated security review of code changes. - Style and convention validation by a separate AI call. - Documentation generation for modified files.

Trade-off: LLM prompt hooks consume additional tokens and add latency. Use them sparingly for high-value checks rather than on every file edit.

Key Insight from Hyperautomation Labs: "You can run shell commands, send HTTP requests, or even run LLM prompts as hooks." -- Claude Code Plugins: The Complete Guide

6.6 hooks.json Configuration

Where Hooks Are Configured

Hooks are configured in your Claude Code settings files. There are several locations where hook configurations can live:

Location File Scope
User settings ~/.claude/settings.json All projects, all sessions
Project settings (shared) .claude/settings.json (in project root) This project, all collaborators
Project settings (local) .claude/settings.local.json This project, only you
Plugin <plugin>/hooks/hooks.json When plugin is enabled

Full Configuration Structure

A complete hooks configuration within settings.json:

{
  "hooks": {
    "pre_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_FILE_PATH\" | grep -q '\\.env' && echo 'BLOCKED' && exit 1 || exit 0"
          }
        ]
      },
      {
        "matcher": {
          "tool_name": ["bash"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_BASH_COMMAND\" | grep -q 'rm -rf /' && exit 1 || exit 0"
          }
        ]
      }
    ],
    "post_tool_use": [
      {
        "matcher": {
          "tool_name": ["write", "edit"]
        },
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
          },
          {
            "type": "command",
            "command": "npx eslint \"$CLAUDE_FILE_PATH\" --fix"
          }
        ]
      }
    ],
    "session_start": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Claude Code session started at $(date)' >> ~/.claude/session.log"
          }
        ]
      }
    ]
  }
}

Key structural points: - Each event type (pre_tool_use, post_tool_use, session_start) contains an array of hook groups. - Each hook group has an optional matcher and an array of hooks. - Multiple hooks can fire for the same event -- they run in order. - For pre_tool_use, if any hook exits with a non-zero code, the action is blocked.

Creating Hooks with the /hooks Assistant

You do not have to write JSON by hand. Claude Code provides an interactive assistant for creating hooks:

/hooks

This opens a guided interface where you:

  1. Choose the event type -- "Before Tool Execution" or "After Tool Execution"
  2. Add a matcher -- Specify which tools trigger the hook (e.g., write, edit)
  3. Define the hook command -- Enter the shell command to execute
  4. Choose the scope -- Project settings (local), project settings (shared), or user settings

Key Insight from Philip Thomas: He walks through the /hooks assistant step by step: "Ich gebe /hooks ein und dann startet hier der Assistent und hier habe ich dann einmal die Moglichkeit auszuwahlen, wann das Ganze passieren soll. Also jetzt hier zum Beispiel Before Tool Execution oder After Tool Execution." (I enter /hooks and the assistant starts and I have the option to choose when it should happen -- Before Tool Execution or After Tool Execution.) -- Claude Code Tutorial (Deutsch)

Having Claude Code Create Hooks

You can also ask Claude Code directly to create hooks:

Create a hook that runs Prettier on every file after
you write or edit it. Save it to the project local settings.

Claude Code will create the appropriate configuration. However, always verify the result:

Key Insight from Philip Thomas: "Ich kann naturlich auch Cloud selber das Ganze machen lassen. Ich kann ihm auch sagen, dass er einen Hook anlegen soll, aber da sollte ich dann naturlich am Ende noch mal kontrollieren, ob er das dann auch wirklich so gemacht hat, wie ich es mir vorstelle." (I can of course also let Claude do it itself. I can tell it to create a hook, but I should check at the end whether it really did it the way I intended.) -- Claude Code Tutorial (Deutsch)

6.7 Hooks vs. Skills: Understanding the Distinction

Hooks and skills are both ways to extend Claude Code's behavior, but they serve fundamentally different purposes. Confusing them is a common mistake.

Skills: Advisory Instructions

Example: A "frontend design" skill that instructs Claude Code to follow specific design patterns when building UI components. Claude Code will try to follow these patterns, but it is ultimately a suggestion.

Hooks: Mandatory Automation

Example: A Prettier hook that formats code after every file write. This runs every single time, guaranteed, regardless of what Claude Code "thinks" about it.

Comparison Table

Aspect Skills Hooks
Nature Advisory instructions Mandatory automation
Determinism Non-deterministic (AI decides) Deterministic (always runs)
Context cost Metadata always; full content when used Zero
Triggered by AI judgment about task relevance Event + matcher match
Can be skipped Yes, AI may choose not to use it No, fires every time conditions are met
Best for Teaching Claude how to do things Ensuring things always happen
Format Markdown files JSON configuration
Scope User, project, or plugin User, project, or plugin

When to Use Which

Use a skill when: - You want Claude Code to follow certain patterns or conventions. - The instruction is about how to approach a task. - Some flexibility in application is acceptable. - The guidance requires AI understanding to apply.

Use a hook when: - An action must happen every single time, without exception. - The action is mechanical (formatting, linting, logging). - You cannot trust AI judgment for this particular rule. - The action is a safety or security measure.

Using Them Together

The most powerful patterns combine skills and hooks:

Skill: "When writing React components, follow our design system conventions, use TypeScript interfaces, and include JSDoc comments."

Hook: "After every file write or edit, run npx prettier --write and npx eslint --fix."

The skill guides Claude Code's creative decisions. The hook ensures the output always meets baseline quality standards regardless of whether Claude Code perfectly followed the skill.

6.8 Advanced Hook Patterns

Chaining Multiple Hooks

You can define multiple hooks for the same event. They execute in order:

{
  "post_tool_use": [
    {
      "matcher": {
        "tool_name": ["write", "edit"]
      },
      "hooks": [
        {
          "type": "command",
          "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
        },
        {
          "type": "command",
          "command": "npx eslint \"$CLAUDE_FILE_PATH\" --fix"
        },
        {
          "type": "command",
          "command": "echo \"Modified: $CLAUDE_FILE_PATH at $(date)\" >> .claude/edit.log"
        }
      ]
    }
  ]
}

This chain: formats with Prettier, then lints with ESLint, then logs the modification.

Conditional Hooks with File Type Filtering

You can make hooks conditional on file types by using the command itself to check:

{
  "type": "command",
  "command": "echo \"$CLAUDE_FILE_PATH\" | grep -qE '\\.(ts|tsx|js|jsx)$' && npx prettier --write \"$CLAUDE_FILE_PATH\" || true"
}

This only runs Prettier on TypeScript and JavaScript files, silently skipping everything else.

Notification Hooks

Combine shell commands with notification tools for real-time alerts:

{
  "type": "command",
  "command": "echo \"$CLAUDE_FILE_PATH\" | grep -q 'security\\|auth\\|credentials' && osascript -e 'display notification \"Claude modified a security-sensitive file: $CLAUDE_FILE_PATH\" with title \"Security Alert\"' || true"
}

On macOS, this triggers a system notification whenever Claude Code modifies files related to security or authentication.

Testing Hooks

Before deploying hooks in production, test them manually:

  1. Run the command directly in your terminal with sample values: bash CLAUDE_FILE_PATH="src/App.tsx" npx prettier --write "$CLAUDE_FILE_PATH"

  2. Check exit codes for pre-tool-use hooks: bash echo "src/.env.production" | grep -q '\.env' && echo 'BLOCKED' && exit 1 || exit 0

  3. Start a test session after adding hooks to verify they fire correctly.

6.9 Hooks in Plugins

Hooks can be packaged within plugins for distribution to teams. This is particularly useful for enforcing organizational standards.

Plugin Hook Structure

my-plugin/
  .claude-plugin/
    plugin.json
  hooks/
    hooks.json
  skills/
    my-skill/
      skill.md

The hooks/hooks.json file uses the same format as settings-based hooks:

{
  "post_tool_use": [
    {
      "matcher": {
        "tool_name": ["write", "edit"]
      },
      "hooks": [
        {
          "type": "command",
          "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
        }
      ]
    }
  ]
}

When the plugin is installed and enabled, the hooks activate automatically.

Key Insight from Hyperautomation Labs: "Create a hooks folder with a hooks.json file. You specify which events to listen for and what to run. Plugins can bundle MCP servers and LSP servers [alongside hooks]." -- Claude Code Plugins: The Complete Guide

Organizational Standards Enforcement

Plugins with hooks are ideal for enforcing team-wide standards:

This approach is far more reliable than relying on CLAUDE.md instructions or individual developer discipline, because hooks are deterministic and cannot be forgotten or overridden by the AI.

6.10 Common Pitfalls and Best Practices

Pitfall 1: Hooks That Are Too Broad

A hook that fires on every tool use without a matcher will slow down your workflow significantly:

// BAD: Fires on every tool use, including reads and searches
{
  "post_tool_use": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "echo 'Tool used' >> log.txt"
        }
      ]
    }
  ]
}

// GOOD: Only fires on file modifications
{
  "post_tool_use": [
    {
      "matcher": {
        "tool_name": ["write", "edit"]
      },
      "hooks": [
        {
          "type": "command",
          "command": "echo 'File modified: $CLAUDE_FILE_PATH' >> log.txt"
        }
      ]
    }
  ]
}

Pitfall 2: Slow Hook Commands

Hooks run synchronously -- Claude Code waits for them to complete before proceeding. If a hook takes 10 seconds to run, every file edit will be delayed by 10 seconds.

Guidelines: - Keep hook commands under 2-3 seconds. - For slow operations, consider running them in the background: command &. - If you need heavy processing, use an HTTP webhook to offload it.

Pitfall 3: Forgetting to Verify AI-Created Hooks

When you ask Claude Code to create hooks for you, always review the output:

Show me the current hooks configuration in my settings.

Or check the file directly at .claude/settings.local.json or .claude/settings.json.

Best Practices Summary

  1. Always use matchers. Do not let hooks fire on every tool use.
  2. Keep hooks fast. Slow hooks degrade the interactive experience.
  3. Use the right scope. Security hooks should be at the user level; project-specific hooks at the project level.
  4. Test manually first. Run your hook commands in the terminal before configuring them.
  5. Verify AI-generated hooks. If Claude Code creates a hook for you, review it before relying on it.
  6. Combine with skills. Use skills for guidance and hooks for enforcement.
  7. Document your hooks. In team settings, add comments or documentation explaining why each hook exists.
  8. Start with formatting and linting. The Prettier and ESLint hooks are the highest-value, lowest-risk starting point.

Chapter Summary

Hooks are the enforcement layer of your Claude Code setup. While skills suggest and MCP servers connect, hooks guarantee.

Key takeaways:

  1. Hooks are deterministic. They always fire when conditions are met. No AI judgment, no exceptions.

  2. Four event types: post_tool_use (after actions), pre_tool_use (before actions, can block), user_prompt_submit (when you press Enter), session_start (when Claude boots up).

  3. Matchers make hooks precise. Filter by tool name (write, edit, bash) to target exactly what should trigger your hook.

  4. Three hook action types: Shell commands (most common), HTTP requests (for external notifications), and LLM prompts (for AI-powered validation).

  5. Hooks vs. skills: Skills are advisory and non-deterministic. Hooks are mandatory and deterministic. Use skills for guidance, hooks for enforcement. Best results come from combining both.

  6. Start simple: Begin with a Prettier formatting hook on post_tool_use for write and edit tools. This single hook will immediately improve the consistency of every file Claude Code touches.

  7. Configuration locations: User settings (global), project settings (shared with team), or project local settings (just you). Choose based on whether the hook is personal preference or team standard.

  8. Setup options: Write JSON manually, use the /hooks interactive assistant, or ask Claude Code to create hooks for you (but always verify the result).

Chapter 7: Skills and Plugins

Source Videos: Claude Code Plugins: The Complete Guide, Claude Code Skills Just Got Even Better, Claude Code Skills Just Got a MASSIVE Upgrade, 10 Claude Code Plugins to 10X Your Projects, Stop Fixing Your Claude Skills. Autoresearch Does It For You, Claude Code 2.0 Has Arrived, Claude Code 2.0 MASSIVE Upgrade!

Skills and plugins are what transform Claude Code from a capable coding assistant into a deeply customized, extensible development platform. This chapter covers the plugin architecture, skill creation, evaluation testing, and the key plugins that power professional workflows.

7.1 The Plugin System: Anatomy and Architecture

A plugin in Claude Code is a self-contained package that can extend Claude with new capabilities across five component types. Think of plugins like VS Code extensions, but for your AI coding agent.

Key Insight from Hyperautomation Labs: "A plugin is a self-contained package that extends Claude Code with new capabilities. It can add slash commands, specialized AI agents, event hooks, connections to external tools through MCP, and real-time code intelligence through LSP." --- Claude Code Plugins: The Complete Guide

The Five Component Types

Component What It Does Example
Skills Slash commands and instructions (/deploy, /review) Front-end design skill, PDF creator
Agents Specialized AI workers Claude can invoke automatically Security reviewer, performance tester
Hooks Event handlers that fire automatically on triggers Auto-format after every file edit
MCP Servers Connections to external services via Model Context Protocol GitHub, Slack, Supabase
LSP Servers Real-time code intelligence via Language Server Protocol TypeScript diagnostics, Go to Definition

Plugin Directory Structure

A minimal plugin requires just a directory with a claude-plugin folder containing a plugin.json manifest:

my-plugin/
  claude-plugin/
    plugin.json          # Manifest: name, description, version
    skills/
      my-skill/
        skill.md         # YAML front matter + markdown instructions
    hooks/
      hooks.json         # Event handler definitions
    agents/
      my-agent/
        agent.md         # Agent definition
    mcp.json             # MCP server configurations (optional)
    lsp.json             # LSP server configurations (optional)

The plugin.json manifest is deliberately minimal:

{
  "name": "my-plugin",
  "description": "What this plugin does",
  "version": "1.0.0"
}

Key Insight from Hyperautomation Labs: "No build step, no compilation, just markdown and JSON." --- Claude Code Plugins: The Complete Guide

7.2 Plugin Scopes: User, Project, and Local

When you install a plugin, you choose where it lives and who can access it. This scoping system controls visibility and sharing.

The Three Scopes

Scope Visibility Use Case
User Available in every project on your machine Personal productivity tools, universal skills
Project Shared with your team through version control Team conventions, project-specific workflows
Local Private to a single repository, not committed Personal experiments, repo-specific tweaks

When installing a plugin, Claude Code prompts you to choose:

Install options:
  1. Install for user (everywhere)
  2. Install for all collaborators in this repository (project)
  3. Install for you in this repo only (local)

Key Insight from Philip Thomas: "User scope makes it globally available. Project scope shares it with your team through version control. Local scope keeps it private to one repo." --- Claude Code Tutorial

Best Practice: Start Local, Graduate to Shared

Begin with standalone configuration in your .claude directory. Once you have something working well, convert it to a plugin when you are ready to share with your team or the community.

7.3 The Plugin Marketplace and /plugin Command

The official Anthropic Marketplace comes preloaded with 56+ plugins organized into three categories.

Browsing and Installing Plugins

/plugin                    # Opens the plugin manager
/plugin install <name>     # Install a specific plugin

The plugin manager has four tabs: - Discover -- Browse all available plugins - Installed -- View what you have active - Marketplaces -- Manage connected plugin sources - Errors -- Debug plugin issues

Plugin Categories in the Official Marketplace

Code Intelligence Plugins provide real-time diagnostics for 11 languages: - TypeScript, Python, Rust, Go, Java, Kotlin, Swift, C++, C, PHP, Lua

These plugins install language server binaries so Claude instantly sees type errors after every edit.

External Integration Plugins connect Claude to services: - GitHub (issues/PRs), Slack (messaging), Linear/Asana (project management) - Figma (design), Sentry (error monitoring), Notion (docs) - Supabase/Firebase (backend), Vercel (deployments)

Development Workflow Plugins add commands for: - Git commits, PR reviews, skill creation, and more

Adding Third-Party Marketplaces

A marketplace is a Git-hosted marketplace.json catalog. You can add custom marketplaces with one command. Plugin sources can be: - Relative paths in the same repo - GitHub repositories or Git URLs - Git subdirectories (for monorepos) - npm or pip packages

Key Insight from Philip Thomas: "Be careful with third-party marketplaces. Make sure repositories have a decent number of stars -- at least a few thousand -- so you are not loading something that could cause damage." --- Claude Code Tutorial

Enterprise teams can configure project settings to auto-suggest marketplaces to new developers. Admins can restrict which marketplaces users can add using strict_known_marketplaces in managed settings.

7.4 Understanding Skills: The Foundation

Skills are the most commonly used plugin component. At their core, they are just markdown files with YAML front matter and text instructions.

Key Insight from Nate Herk: "A skill is basically just a recipe. When you ask your agent to make you a LinkedIn post, it will read the recipe and get it right every single time. And when I say recipes, I literally just mean text." --- Claude Code Skills Just Got Even Better

Skill File Structure

Each skill is a skill.md file:

---
name: front-end-design
description: >
  Use this skill when building user interfaces, web pages, or any
  front-end components. Applies modern design principles including
  typography, color theory, layout patterns, and responsive design.
disable_model_invocation: false
argument_hint: "Optional: specific design style or framework"
---

# Front-End Design Skill

## Design Principles
- Use modern, clean typography (Inter, Geist, system fonts)
- Apply consistent color schemes with proper contrast ratios
- Implement responsive layouts using CSS Grid and Flexbox
...

How Skills Load Into Context

This is an important architectural detail. Skills are NOT all preloaded into the system prompt. Instead:

  1. Claude Code maintains a list of all your skills with just the title and a short description (from the YAML front matter)
  2. When you give a task, Claude checks that list to decide which skill is relevant
  3. Only the relevant skill's full markdown body gets loaded into context

Key Insight from Chase AI: "You could have 100 skills. They don't just live in the system prompt. Instead, Claude Code essentially has a list of all your skills with the title and like a 100-word description." --- Claude Code Skills Just Got a MASSIVE Upgrade

This is why skills are superior to putting everything in claude.md -- they load on demand and save context tokens.

Invoking Skills

There are two ways to trigger a skill:

  1. Natural language: Just describe the task and Claude matches it to the right skill automatically
  2. Slash command: Type /skill-name to explicitly invoke it
# Natural language (automatic matching)
Build me a beautiful landing page for a SaaS product

# Explicit invocation
/front-end-design Build me a landing page for a SaaS product

Creating Custom Skills

You can create skills manually or ask Claude Code to help:

I want to create a custom skill that generates weekly reports
from my project's Git history in a specific format.

Claude will create the skill.md file with proper YAML front matter and markdown instructions in your skills directory.

7.5 Two Types of Skills: Capability Uplift vs. Encoded Preference

Understanding this distinction is critical because it affects how you test, maintain, and evolve your skills over time.

Capability Uplift Skills

These teach Claude how to do something better than it otherwise would. Claude can already attempt the task, but the skill significantly improves output quality.

Examples: - Front-end design skill (better websites than default output) - PDF creation skill (proper form filling) - PowerPoint creator - MCP builder

Key characteristic: These may become less necessary as models improve. If Opus 5 produces better front-end designs out of the box than Opus 4.6 with the design skill, the skill may need to be retired.

Key Insight from Nate Herk: "What if Opus 5 drops and default Opus 5 is better at front-end design than Opus 5 with a front-end skill? At that point, you might just need to retire that skill completely." --- Claude Code Skills Just Got Even Better

Encoded Preference Skills

These define a specific workflow -- Claude already understands the individual pieces, but you want them executed in a particular order, with specific outputs.

Examples: - Idea mining: Analyze YouTube comments, research trends, spin up parallel agents, cross-reference and score, produce video ideas - YouTube pipeline: Search YouTube, upload to NotebookLM, analyze, create deliverables - Content repurposing: Take a video, create newsletter copy, write tweets

Key characteristic: These are more durable because the process is specific to your business and workflow. A new model version will not be trained on your particular sequence of steps.

Key Insight from Chase AI: "Encoded preference skills are more durable, but they are only as valuable as their fidelity to your actual workflow. The evals verify that fidelity." --- Claude Code Skills Just Got a MASSIVE Upgrade

Why the Distinction Matters for Testing

Aspect Capability Uplift Encoded Preference
Eval focus Is output quality better WITH the skill? Does it follow ALL steps in order?
Regression risk Model upgrade may make skill unnecessary Workflow fidelity may degrade
Testing approach A/B test: skill vs. no skill Fidelity check: does it run every step?
Longevity May fade as models improve Durable because process is unique to you

7.6 Skills 2.0: Built-In Evaluation and Benchmarking

The upgraded Skill Creator skill from Anthropic introduces proper evaluation, benchmarking, and trigger tuning capabilities. This is the shift from "skills that seem like they work" to "skills you know work."

Installing the Skill Creator

/plugin
# Search for "skill-creator"
# Install the official Anthropic plugin
# Restart Claude Code (/exit and reopen)

Verify the installation:

Do you have the skill creator skill? What does it do?

The Skill Creator can: 1. Create new skills from scratch 2. Modify and improve existing skills 3. Run evals to test skill quality 4. Run benchmarks for A/B comparisons 5. Optimize trigger descriptions for better matching

Writing Effective Evals

The key to good evals is being specific about criteria rather than asking generic "test this skill" requests.

Key Insight from Simon Scrapes: "If you just say 'run some tests,' you will get generic results that are not very useful. The key is being specific about what you are actually trying to optimize the test for." --- Claude Code 2.0 Has Arrived

Good eval prompt:

Run a new test optimized for making sure my copy follows the
persuasive techniques listed in my persuasion toolkit reference
file. The criteria are:
1. Does it always use the reference file?
2. Does it use curiosity and open loops?
3. How often does it use proof or founder-led stories?

Test by writing landing page copy for my school community.
Run it 5 times and test against that exact criteria.

Bad eval prompt:

Run some tests on my copywriting skill.

Eval Best Practices

  1. Use binary yes/no criteria. "Does this diagram contain legible text?" has only two possible answers. Avoid Likert scales (rate 1-7) because you compound variability at each step.

  2. Test 1-3 criteria per iteration. Don't try to optimize six things at once -- too many moving parts. Pick your criteria, test, improve, then move to the next batch.

  3. Run 5-10 times per test. Skills (like all prompts) are inherently noisy. Running once tells you nothing. Running multiple times reveals the distribution of outputs.

  4. Don't make criteria too narrow. If you say "make sure this is under X words" or "must not include these characters," the model may find ways to game the test while producing low-quality output.

Key Insight from Nick Saraev: "Go binary wherever possible. Don't go so concrete and narrow that the model starts optimizing for silly things. If you give the model way too many evals, it will find a way to parrot every single evaluation point back to you, even if the actual quality is not very good." --- Stop Fixing Your Claude Skills

Running Benchmarks

Benchmarks let you compare skill performance with concrete data:

Benchmark the PDF skill with and without the skill loaded
and show me side-by-side results so I can see the uplift.

A benchmark report includes: - Pass rate (percentage of criteria met) - Total time per run - Total tokens consumed - Per-run evaluation breakdown (which criteria passed/failed for each run)

The Skill Creator runs multiple variations in parallel using sub-agents, so benchmarking is fast.

Catching Regressions

Run evals when a model updates to detect two scenarios:

  1. Regression: The new model uses your skill worse because it thinks differently. This is your signal to evolve the skill.
  2. Growth: The new model does a better job WITHOUT the skill. Time to archive the skill and stop spending tokens on it.

Key Insight from Chase AI: "Anytime we can get away from the black box of AI and actually see what is happening under the hood and make informed decisions, the better. You want control. You want consistency. You want anything that gets you away from just being an accept monkey." --- Claude Code Skills Just Got a MASSIVE Upgrade

Trigger Tuning: Fixing False Triggers and Misfires

As your project accumulates 10+ skills, you may notice: - False triggers: Claude uses the wrong skill for a task - Misfires: Claude does not use any skill when it should

The Skill Creator's trigger tuning analyzes your skill descriptions, tests different prompts, and edits descriptions to improve matching accuracy.

The description in your YAML front matter is the key lever: - Too broad: False triggers (wrong skill fires) - Too narrow: Misfires (skill never fires)

The trigger tuner threads this needle automatically by testing prompt variations and refining descriptions.

Key Insight from Anthropic (via Nate Herk): "Over time, a natural language description of what the skill should do may be enough, with the model figuring out the rest." --- Claude Code Skills Just Got Even Better

7.7 Key Plugins for Your Stack

Based on extensive real-world usage, here are the most impactful plugins and tools to add to Claude Code.

1. Skill Creator (Anthropic Official)

The most important plugin. Creates, tests, benchmarks, and optimizes all your other skills.

/plugin
# Search: skill-creator
# Install

2. GSD (Get Stuff Done) Framework

An orchestration layer that sits on top of Claude Code and changes how it approaches new projects. Provides: - Spec-driven development with phased execution - Automatic context rot management via fresh context windows - Sub-agent delegation for each phase

# Install
# (Copy the single command from the GSD GitHub repo)

# Usage
/gsd new project

Key Insight from Chase AI: "If you are looking for something that is going to create your projects from scratch in an extremely regimented way, I cannot recommend GSD enough." --- 10 Claude Code Plugins to 10X Your Projects

3. Excalidraw Diagram Skill

Creates hand-drawn style diagrams through natural language. Excellent for presentations, documentation, and architecture overviews.

# Clone the repo and copy into your project's skill directory
# Then use natural language:
Create a system architecture diagram showing the data flow
between the API gateway, auth service, and database layer.

4. NotebookLM CLI

Connects Claude Code to Google's NotebookLM for research, analysis, and content creation -- even though there is no official NotebookLM API.

# Install from the notebooklm-cli GitHub
# Install dependencies
# Run: notebooklm   (to authenticate via browser)
# Install skill: notebooklm skill install

Capabilities: research analysis, podcast generation, flashcards, infographics, slide decks -- all from the terminal.

5. Vercel CLI

Handles deployment workflows directly from Claude Code.

# Install
npm i -g vercel

# Install the Vercel skill from their website
# Works great with agent loops for deployment monitoring

6. Supabase CLI (Not the MCP!)

For databases and authentication. The CLI is always preferred over the MCP server.

Key Insight from Chase AI: "All things being equal, if you are looking at something and there is a CLI and an MCP version, go with the CLI. It is essentially purpose-built for AI coding agents like Claude Code." --- 10 Claude Code Plugins to 10X Your Projects

# Install the Supabase CLI for your OS
# Then install the Supabase Claude Code plugin from the marketplace

7. Playwright CLI

Browser automation for testing, web scraping, and UI validation.

# Install from the playwright-cli GitHub
# Install skills: playwright-cli install-skills
# Bonus: playwright-cli show   (visual dashboard of browser agents)

8. Firecrawl CLI

Web scraping optimized for AI agents. Four core commands: scrape, crawl, map, and search.

# Install from the firecrawl-cli GitHub (includes skill install)

CLI vs. MCP: The Rule of Thumb

When both a CLI and MCP version exist for a tool, prefer the CLI: - CLIs are purpose-built for terminal-based agents - MCPs add overhead by trying to replicate what CLIs do natively - When installing a CLI tool, always look for an accompanying skill

Key Insight from Chase AI: "MCPs came out in 2024 as a standard for connecting AI assistants to external systems. However, today our AI assistants live inside the terminal with us. So they have the ability to use CLI systems directly." --- 10 Claude Code Plugins to 10X Your Projects

7.8 Custom Agents as Default Behavior

Plugins can ship with a settings.json that activates a custom agent as the default behavior for Claude Code. When the plugin is enabled, that agent becomes the main thread with its own: - System prompt - Tool restrictions - Optionally a different model

This means a security-focused plugin can make Claude act as a security reviewer by default. A project management plugin could make Claude operate as a PM agent.

{
  "agent": "my-plugin/agents/security-reviewer"
}

Key Insight from Hyperautomation Labs: "Plugins can ship with a settings.json that activates a custom agent as the default behavior. Set the agent key to one of your plugin's agent definitions. When the plugin is enabled, that agent becomes the main thread." --- Claude Code Plugins: The Complete Guide

7.9 Plugin Development Best Practices

  1. Start with standalone config. Build in your .claude directory first. Convert to a plugin when ready to share.

  2. Use semantic versioning. Bump the version every time you change code. Users will not see updates due to caching if the version number stays the same.

  3. Keep the plugin self-contained. External file references break after installation because plugins are cached. Use symlinks if you need shared files.

  4. Test locally first. Use the --plugin-dir flag to test your plugin before distributing: bash claude --plugin-dir /path/to/my-plugin

  5. Don't overload with too many skills. There is a sweet spot between capability and complexity. As Chase AI puts it: "Increased capability does not equal increased performance. There is a sweet spot somewhere."

7.10 The Future of Skills

Anthropic has signaled that skills will become increasingly powerful as models improve:

The practical takeaway: invest your time in building encoded preference skills around your unique workflows. These represent lasting value that compounds over time, regardless of model improvements.

Chapter Summary

Concept Key Takeaway
Plugins Self-contained packages: skills + agents + hooks + MCP + LSP
Scopes User (global), Project (team), Local (personal)
Marketplace 56+ official plugins, browse with /plugin
Skills Markdown files with YAML front matter, loaded on demand
Capability Uplift Makes Claude better at tasks; may fade as models improve
Encoded Preference Defines specific workflows; durable and unique to you
Skill Creator Create, modify, test, benchmark, and tune trigger accuracy
Eval rules Binary criteria, 1-3 per iteration, run 5-10 times
CLI vs. MCP Always prefer CLI when both exist
settings.json Can set a custom agent as default Claude behavior

Chapter 8: Advanced Usage

Source Videos: Claude Code + Autoresearch = SELF-IMPROVING AI, Stop Fixing Your Claude Skills. Autoresearch Does It For You, Claude Code Just Got a MASSIVE Upgrade (Agent Loops), Claude Code 2.0 Has Arrived, 567 Hours of Claude Code Lessons, Claude Code Tutorial (Deutsch), Claude Code 2.0 MASSIVE Upgrade!

This chapter covers Claude Code's most powerful features for automation, parallel work, and self-improving systems. You will learn when to use agent loops versus scheduled tasks versus GitHub Actions, how to run agent teams and worktrees, and how to implement the auto-research pattern for autonomous optimization.

8.1 Agent Loops: Session-Based Recurring Tasks

The /loop command lets you schedule recurring prompts inside your current Claude Code session. Think of it as a lightweight, temporary cron job that lives within your terminal window.

Basic Usage

/loop every 10 minutes check my inbox for important emails

/loop every morning use the Slack MCP to give me a summary
of the top posts I was tagged in

/loop every 5 minutes run playwright and check to make sure
the form submission still works

By default, loops run every 10 minutes if you do not specify an interval.

Under the hood, Claude Code uses three tools to manage loops: - cron_create -- Set up a new recurring task - cron_list -- View all active loops - cron_delete -- Remove a loop

Key Insight from Simon Scrapes: "Loop lets you schedule recurring prompts inside your current session. You can say /loop every 10 minutes, check my inbox for important emails. Claude creates a cron job that fires automatically." --- Claude Code 2.0 Has Arrived

One-Off Reminders

You can also use the loop system for single reminders:

/loop in one minute remind me to talk about one-off reminders

Reminders are one-off. Loops are recurring. Both are created the same way under the hood using cron jobs.

Critical Limitations

Understanding these limitations is essential. Many sources have overhyped this feature as "Claude 2.0" or a "24/7 agent," which it is not.

Limitation Detail
Expires after 3 days Automatic safety limit to prevent runaway loops
Session-based If you close the terminal, all loops are gone
Requires app open Computer must be on, terminal must be running
Same session Output appears in the same terminal window
No catch-up If the session is closed when a loop should fire, it simply never runs
Interrupts work If you are mid-conversation when a loop fires, it waits until Claude finishes

Key Insight from Chase AI: "Agent loops are great for micro tasks that we constantly repeat during a singular work session. Anything you are constantly doing inside of Claude Code, we can now systematically do it via the loop." --- Claude Code Just Got a MASSIVE Upgrade (Agent Loops)

Ideal Use Cases for Loops

Loops are for right now, on this project scenarios -- not long-term automation.

8.2 Scheduled Tasks: Persistent Desktop Automation

Scheduled tasks are available in Claude Code Desktop (not the terminal CLI). They are more powerful than loops in key ways.

Creating a Scheduled Task

In Claude Code Desktop, go to the scheduled tasks section and click "New Task," or use:

/schedule every day check my YouTube for new videos and run
my content repurposing skill to create a newsletter and tweet

You provide: - Name and description - Prompt (what Claude should do) - Frequency (daily, weekly, hourly, custom) - Model to use - Folder to work in (optional)

How Scheduled Tasks Differ from Loops

Feature Agent Loops (/loop) Scheduled Tasks (Desktop)
Platform Terminal / VS Code / Desktop Desktop app only
Expiry 3 days max Never expires
Session Same session (shared context) Creates a NEW session each run
Survives restart No Yes
Catches up on missed runs No Yes, when you reopen the app
Computer must be on Yes Yes
App must be open Yes (terminal) Yes (desktop)
Interrupts work Yes (same session) No (separate session)

Key Insight from Chase AI: "Agent loops are great for things I want to do in a certain time interval within a specific work session. If I am trying to do something that is longer range in scope, every single day I want a morning report, Cloud Code Desktop is perfect for that." --- Claude Code Just Got a MASSIVE Upgrade (Agent Loops)

Important Caveat: Session Volume

Because scheduled tasks create a new session every time they run, be mindful of frequency. Running something every minute means 60 new sessions in an hour. Plan your intervals carefully.

Connecting Scheduled Tasks to Messaging

You can connect scheduled tasks to Telegram or Slack for automated notifications:

  1. Add a Telegram messaging module using the Telegram bot builder skill
  2. Create a bot using BotFather on Telegram
  3. Add bot credentials to your .env file
  4. End your scheduled task prompt with: "Send a message into Telegram using that module"

Key Insight from WorldofAI: "Whenever you create a scheduled task, simply end the prompt by instructing Claude to send a message into Telegram using that module. Claude will automatically deliver the task output to Telegram every time it runs." --- Claude Code 2.0 MASSIVE Upgrade!

8.3 GitHub Actions: Cloud-Based Automation

For truly persistent, always-on automation, GitHub Actions runs Claude Code on GitHub's infrastructure. No local machine needed.

When to Use GitHub Actions

Scenario Best Tool
Check deployment every 10 min during work /loop
Daily morning report Scheduled task (Desktop)
Run auto-research every 4 hours, 24/7 GitHub Actions
Process PRs and fix build issues automatically GitHub Actions
Long-running optimization pipelines GitHub Actions

Key Advantages

Key Limitation

GitHub Actions is scoped for GitHub itself. It makes sense for PRs, code implementation, automated testing, and deployment workflows. It does NOT make sense for "talk to Claude via Telegram" type scenarios.

Key Insight from Chase AI: "GitHub Actions runs Claude Code inside of GitHub. Your computer does not need to be on. But understand GitHub Actions is scoped for GitHub itself -- PRs, code implementation, these sorts of things." --- Claude Code Just Got a MASSIVE Upgrade (Agent Loops)

GitHub Actions Cron Scheduling

For auto-research or recurring optimization tasks, use cron expressions in your workflow file:

name: Auto-Research Pipeline
on:
  schedule:
    - cron: '0 */4 * * *'  # Every 4 hours
  workflow_dispatch:         # Manual trigger option

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run optimization
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Install Claude Code
          # Run the orchestrator
          python orchestrator.py

8.4 Decision Framework: Loops vs. Tasks vs. Actions

Use this decision tree to pick the right tool:

Is this a short-term task (hours to 3 days)?
  YES --> Is it within a single work session?
    YES --> /loop
    NO  --> Scheduled Task (Desktop)
  NO  --> Is it GitHub/code focused?
    YES --> GitHub Actions
    NO  --> Scheduled Task (Desktop) with messaging integration

Quick reference:

Need Use
"Check this every 10 min while I work" /loop
"Every morning, give me a report" Scheduled Task
"Run optimization every 4 hours, 24/7" GitHub Actions
"Babysit my PRs for the next few hours" /loop
"Daily deploy check + Telegram alert" Scheduled Task + Telegram
"Process PRs automatically in the cloud" GitHub Actions

8.5 Agent Teams and Subagents

Agent teams let you run multiple Claude instances working in parallel on different tasks, coordinated by a team leader.

Enabling Agent Teams

Agent teams are an experimental feature, disabled by default:

# Paste the enablement prompt from Claude Code docs
# into your Claude Code session

Or find instructions at the official Claude Code documentation under "agent teams."

How Agent Teams Work

Each team member is a separate Claude Code instance with: - Its own context window (prevents context rot) - A specific task assignment - The ability to communicate with other team members - Coordination by a team leader

Key Insight from Chase AI: "In agent teams, they talk to one another. The guy doing the UI and the guy doing the blog and the guy doing authentication, they all speak to one another and they even have a team leader coordinating all their actions." --- 567 Hours of Claude Code Lessons

Using Agent Teams

You must explicitly request agent teams:

Use agent teams to:
1. Improve the UI design
2. Add a blog section
3. Implement authentication
4. Create a newsletter signup

Claude Code will: - Break down what each team member does - Assign specific files to each member - Show active agents (e.g., "4 local agents") - Coordinate results through the team leader

Subagents (Standard)

Even without agent teams enabled, Claude Code uses subagents. These are delegated workers with: - Their own system prompt - Specific tool access - A designated model (you can assign cheaper models to simpler tasks) - Their own context window - Foreground or background execution

Key Insight from Philip Thomas: "I can assign different models to different subagents. Use the flagship model for planning and code review, and a smaller model for execution -- since the plan is already detailed enough for a less powerful model to follow." --- Claude Code Tutorial

Creating a subagent via the assistant:

/agents
# Select "Create new agent"
# Choose project or global scope
# Describe what the agent should do
# Select which tools it can access
# Choose the model (Opus for complex tasks, Sonnet for simple ones)
# Set a color for terminal visibility
# Enable memory if desired

8.6 Worktrees: Isolated Parallel Development

Worktrees let you run multiple Claude Code instances on the same repository without conflicts, each in its own Git branch.

How Worktrees Work

Each worktree is an isolated copy of your repository:

# Terminal 1
claude --worktree feature-dark-mode

# Terminal 2
claude --worktree feature-export-pdf

Both terminals run simultaneously. Each Claude instance works in its own Git branch, modifying files independently. When both are done, you merge the branches.

Worktrees vs. Agent Teams

Aspect Worktrees Agent Teams
Isolation Separate Git branches, fully isolated Same branch, coordinated
Communication None between worktrees Team members talk to each other
Use case Independent features Interdependent tasks
Merge Git merge after completion Automatic coordination

Key Insight from Chase AI: "Work trees allow us to do the same thing as agent teams, but they work in different Git branches. Open up separate terminals with the --worktree flag." --- 567 Hours of Claude Code Lessons

8.7 The Auto-Research Pattern

Auto-research is a methodology for autonomous, self-improving optimization. It originates from Andrej Karpathy's open-source repo where he had AI agents autonomously experiment with machine learning hyperparameters overnight.

Key Insight from Nick Saraev: "An open source project just dropped that when you combine it with Claude Code literally becomes self-improving AI. Andrej Karpathy built an elegant pipeline called auto research that essentially completely and fully automates the process of experimentation." --- Claude Code + Autoresearch = SELF-IMPROVING AI

The Three Ingredients

For auto-research to work, you need:

  1. An objective metric -- A number you can measure. Not "feels faster" or "resonates more." An actual number.
  2. Website load time (milliseconds)
  3. Cold email reply rate (percentage)
  4. Eval pass rate (score out of N)

  5. Conversion rate

  6. A measurement tool -- Automated, reliable, no human in the loop.

  7. Google Lighthouse for website performance
  8. API analytics for email campaigns

  9. A test suite that runs evals automatically

  10. Something to change -- The input variable you modify between experiments.

  11. Code changes (for performance)
  12. Email copy (for reply rates)
  13. Skill instructions / prompt text (for quality)
  14. Landing page content (for conversions)

The Auto-Research Loop

          +------------------+
          |  Start with      |
          |  Baseline        |
          +--------+---------+
                   |
          +--------v---------+
          |  Create           |
          |  Challenger       |
          +--------+---------+
                   |
          +--------v---------+
          |  Run Both         |
          |  Side by Side     |
          +--------+---------+
                   |
          +--------v---------+
          |  Measure Results  |
          |  (Objective       |
          |   Metric)         |
          +--------+---------+
                   |
          +--------v---------+
          |  Pick Winner      |
          |  (New Baseline)   |
          +--------+---------+
                   |
          +--------v---------+
          |  Log Learnings    |
          |  to resource.md   |
          +--------+---------+
                   |
                   +-------> Loop back to "Create Challenger"

The File Structure

Karpathy's original repo has three files that matter. Adapted for business use:

File Purpose Your Equivalent
program.md Instructions for the orchestrator agent Your orchestrator prompt
train.py The thing being optimized Your skill.md, email copy, landing page
prepare.py Data preparation (ML-specific) Your data ingestion scripts

For a practical implementation, you typically need:

auto-research-project/
  orchestrator.py          # Top-level agent that runs the loop
  config/
    baseline.md            # The starting version to beat
    resource.md            # Accumulated learnings from all experiments
    test.md                # Goal metric + high-level instructions
  scripts/
    api_client.py          # API calls to measure results
    deploy.py              # Deploy new variants
    harvest.py             # Collect results from previous experiment
  .github/
    workflows/
      optimize.yml         # GitHub Actions cron schedule

Real-World Example: Cold Email Optimization

Key Insight from Nick Saraev: "I have my metric -- reply rate. The thing I can adjust is my cold email copy. The orchestrator runs every 4 hours and at the end of every 4 hours I actually have better copy that is self-evolving over time based on the results from my previous test." --- Claude Code + Autoresearch = SELF-IMPROVING AI

The workflow: 1. Baseline: Your manually written cold email (the champion) 2. Challenger: AI-generated variant with specific hypotheses (e.g., "baseline is too long, buries the offer, lacks specific CTA time") 3. Deploy: Both go live via the Instantly API with separate lead pools 4. Harvest: After 4 hours, pull reply rates from the API 5. Pick winner: Challenger becomes new baseline if it wins 6. Log: Learnings go into resource.md for future agents 7. Repeat: GitHub Actions cron triggers the next cycle

The Slack webhook provides notifications:

New experiment deployed:
  Baseline: "Quick question" (2.4% reply rate)
  Challenger: Shorter, frontloads risk reversal, concrete time ask
  Hypothesis: Baseline too long, buries the offer

Applicable Use Cases

Auto-research works for anything with: - A fast feedback loop (minutes to hours, not days) - A clear, objective metric - API access to change inputs

Use Case Metric Input to Change API/Tool
Cold email Reply rate Email copy Instantly API
Landing pages Conversion rate Page content Website builder API
Ad creatives Click-through rate Ad copy/images Facebook/Google Ads API
YouTube titles View count Title text YouTube Data API v3
Newsletter subjects Open rate Subject line Email platform API
Product descriptions Sales Listing copy Amazon/Shopify API
Chatbot scripts CSAT score Response templates Chat platform API
Website performance Load time (ms) Code changes Google Lighthouse

Key Insight from Nick Saraev: "Over the course of about 67 different tests, this auto-research methodology took my load speed from about 1100 milliseconds literally down to 67. An 81.3% improvement in time." --- Stop Fixing Your Claude Skills

What Does NOT Work Well

Avoid auto-research when: - Feedback loops are slow (days/weeks to see results) -- optimization crawls - Metrics are fuzzy (subjective qualities like "warmth") -- use proxies instead - No API access to change inputs -- manual changes defeat the purpose

8.8 Combining Auto-Research with Skills

The most powerful application of auto-research is self-improving skills. Instead of optimizing cold email copy, you optimize the skill prompt itself.

The Setup

Your skill.md  -->  [Auto-research loop]  -->  Improved skill.md
                         |
                    Eval test suite
                    (binary criteria)

Step-by-Step Process

  1. Define your eval criteria (binary yes/no questions): ```
  2. Is all text in the diagram legible and grammatically correct?
  3. Does it use pastel colors (no bright reds, oranges, neon greens)?
  4. Is the layout linear (left-to-right or top-to-bottom)?

  5. Is it free of numbers, ordinals, and ordering? ```

  6. Set up the auto-research loop: ``` Every 2 minutes:

  7. Generate 10 outputs using the skill
  8. Evaluate each output against the 4 criteria
  9. Score out of 40 (10 outputs x 4 criteria)
  10. If score < previous best, discard changes
  11. If score > previous best, keep the mutation

  12. Alter the skill prompt and repeat ```

  13. Let it run autonomously: The loop generates outputs, evaluates them with a vision model (for diagrams) or text analysis, mutates the prompt, and keeps the winner.

Key Insight from Nick Saraev: "We started with a 32 out of 40. Eventually the runs get so good that we hit 39 out of 40 on this experiment, which is like getting 97.5% on a test. I am fine with 97.5%." --- Stop Fixing Your Claude Skills

Cost Estimation

If each generation costs about 2 cents (using a fast model like Nano Banana Pro 2 for image generation): - 10 generations per test = 20 cents - 50 tests to reach a good result = about $10 total - For skills that drive significant business value, this is an outstanding ROI

The Meta-Skill

You can create a meta-skill that goes through every skill in your repo and performs auto-research optimization on each one. This compounds the improvement across your entire skill library.

8.9 Auto-Research on GitHub Actions

For fully autonomous, hands-off optimization, put your auto-research pipeline on GitHub Actions:

name: Skill Optimizer
on:
  schedule:
    - cron: '0 */4 * * *'  # Every 4 hours
  workflow_dispatch:

jobs:
  optimize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run orchestrator
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          INSTANTLY_API_KEY: ${{ secrets.INSTANTLY_API_KEY }}
        run: python orchestrator.py
      - name: Commit results
        run: |
          git add resource.md results/
          git commit -m "Auto-research: experiment results" || true
          git push

Add a Slack webhook for notifications so you can monitor progress without checking GitHub:

# In your orchestrator
import requests

def notify_slack(message):
    webhook_url = os.environ['SLACK_WEBHOOK']
    requests.post(webhook_url, json={"text": message})

notify_slack(f"Experiment {run_id}: Baseline {baseline_score}% vs Challenger {challenger_score}%")

Key Insight from Nick Saraev: "The models log all of their learnings to a resource.md that significantly improves future models' abilities to make changes. Imagine this running for a year instead of a few days." --- Claude Code + Autoresearch = SELF-IMPROVING AI

8.10 Practical Patterns for Advanced Workflows

Pattern 1: The Background Agent

Mitchell Hashimoto (co-founder of HashiCorp) keeps an agent running at all times. His rule: always have an agent doing something.

Before stepping away from the desk, ask yourself: "What slow task could an agent be doing while I am gone?"

Turn off notifications. The agent does not get to interrupt you. You interrupt the agent when you are ready.

Key Insight from The Pragmatic Engineer: "His own rule for himself: always have an agent that does something. He turns off all notifications. The agent does not get to interrupt him. He interrupts the agent when he is ready." --- Mitchell Hashimoto's new way of writing code

Pattern 2: Graduated Automation

Manual task
  --> Identify repeating pattern
    --> Create a skill
      --> Test with Skill Creator evals
        --> Automate with /loop or scheduled task
          --> Move to GitHub Actions for 24/7

Pattern 3: Multi-Model Delegation

Use expensive models for planning, cheap models for execution:

Opus 4.6: Create the plan, do code review
Sonnet 4.6: Execute the plan, run simple tasks
Haiku: Quick lookups, simple transformations

Assign models at the subagent level for maximum cost efficiency.

Chapter Summary

Concept Key Takeaway
/loop Session-based, max 3 days, terminal must stay open
Scheduled Tasks Desktop only, persistent, survives restart, creates new sessions
GitHub Actions Cloud-based, no local machine needed, scoped to GitHub
Agent Teams Multiple Claude instances that communicate and coordinate
Worktrees Isolated Git branches for parallel independent features
Auto-Research Metric + measurement tool + input to change = autonomous optimization
File structure test.md (goal), baseline.md (champion), resource.md (learnings), orchestrator.py
Self-improving skills Combine auto-research + evals for skills that optimize themselves
Background agent Always have an agent doing something; you interrupt it, not vice versa

Chapter 9: RAG and Embeddings

Source Videos: Google's Embedding 2 Is RAG on Steroids (But Everyone is Getting it Wrong), Google's New Model + Claude Code Just Changed RAG Forever

Retrieval Augmented Generation (RAG) lets Claude Code work with your proprietary data -- documents, images, videos, and audio -- by storing it in a searchable vector database and pulling relevant context when needed. With Google's Gemini Embedding 2, we now have truly multimodal RAG that embeds video, images, and audio alongside text in the same vector space. But most implementations get it wrong. This chapter shows you the correct architecture and how to build it with Claude Code.

9.1 Understanding RAG: The Fundamentals

RAG stands for Retrieval Augmented Generation. The concept is simple: your AI agent only knows what is in its training data. When you ask a question about your proprietary information, it needs to retrieve that information to augment the answer it generates.

You ask a question
  --> Claude searches the vector database
    --> Retrieves relevant documents/media
      --> Uses that context to generate a better answer

Key Insight from Nate Herk: "RAG basically is just the concept that your AI agent only knows so much in its training data. So if you ask it a question and it does not have that information, it has to go grab it in order to generate a better answer." --- Google's New Model + Claude Code Just Changed RAG Forever

The Two Sides of RAG

Side 1: Query (the easy part) 1. You ask a question 2. Your question becomes a vector (a point in multi-dimensional space) 3. The system finds the closest vectors in the database 4. Those vectors come paired with their source data 5. The LLM uses that data to answer your question

Side 2: Ingestion (the hard part) 1. You have source data (documents, videos, images) 2. That data goes through an embedding model 3. The embedding model converts it into vectors (numbers representing position in space) 4. Vectors are stored in a vector database 5. Source data is paired alongside the vectors

What is a Vector?

A vector is just a point in space represented by numbers. Think back to geometry: a point on a 2D graph might be (1, 1). In a vector database, each item is represented by 1,526 numbers (for Gemini Embedding 2) that determine its position in high-dimensional space.

Items are positioned based on semantic meaning. A document about World War II battleships will be placed near other vectors about ships and naval history -- not near vectors about bananas and fruit.

Key Insight from Chase AI: "When our document goes through the embedding model, it is turning our document into 1,526 different numbers. It is put inside the vector database based on semantic meaning -- what the document is actually talking about." --- Google's Embedding 2 Is RAG on Steroids

When you ask a question, that question ALSO becomes a vector. The system then finds which stored vectors have numbers closest to your question's numbers. Proximity equals relevance.

9.2 Google Gemini Embedding 2: Natively Multimodal

Google's Gemini Embedding 2 is the first natively multimodal embedding model. Before this, embeddings were essentially limited to text. If you wanted to work with videos or images, you had to use hacky workarounds like describing the content in text and embedding those descriptions.

What Makes It Different

Gemini Embedding 2 can directly embed: - Text (up to 8,192 tokens) - Images (PNG, JPEG; up to 6 per request) - Videos (MP4, MOV; up to 120 seconds per chunk) - Audio - Documents

All modalities exist in the same vector space. This means a search query can find relevant results across text, images, and video simultaneously.

Key Insight from Nate Herk: "This means that you can have completely multimodal databases with text, images, videos, audio, and documents. And it can actually understand the nuanced relationships between these different types of media." --- Google's New Model + Claude Code Just Changed RAG Forever

A Practical Visualization

When testing with a bizarre mix of content -- an image of smiley face potato fries, a video of a dog playing guitar, text files about workflows, and photos of people -- Gemini Embedding 2 placed each item in meaningful locations within the vector space:

Now imagine this with hundreds of images of roof damage, all differentiated by type of damage, severity, and location. That is the real power.

9.3 The Naive RAG Problem (Why Most People Get It Wrong)

Here is where most tutorials, videos, and implementations fail. The expectation when people hear "multimodal embeddings" is:

What people expect:

Upload video --> Ask question --> Get detailed text answer analyzing the video

What actually happens with naive RAG:

Upload video --> Ask question --> Get a 2-minute video clip back
"Answer is in there, brother."

Why This Happens

When a text document is retrieved from the vector database, the LLM can read and analyze the text to generate a thoughtful answer. But when a video is retrieved, the LLM receives an MP4 file. Unless the LLM is specifically equipped to ingest video (like Gemini), it cannot analyze the contents. It just hands you the clip.

Key Insight from Chase AI: "Instead of saying 'Oh yeah, here is A, B, and C, here is what happened,' it would just give me a two-minute clip and be like 'Answer is in there, brother.' That is how most people are showing you how to set this up." --- Google's Embedding 2 Is RAG on Steroids

Even with Gemini, do you really want the model to digest the entire video every time someone asks a question? That is expensive and slow. The answer is to handle this on the ingestion side, not the query side.

The Root Cause

Embedding models turn data into vectors. They are about positioning (where does this belong in semantic space?) and similarity (what is closest?). They are NOT about explanation (what does this content mean in detail?).

Key Insight from Chase AI: "That is not what embedding models do. Embedding models take data and turn it into a vector. It is all about differentiation, similarity, the search side. It is not about the explanation part. It is like the difference between recognizing a face in a crowd and being able to describe who it is." --- Google's Embedding 2 Is RAG on Steroids

9.4 Proper Multimodal RAG Architecture

The solution is to augment each embedded item with a text description at ingestion time, so when the vector is retrieved, the LLM gets both the media AND readable text it can use to generate a real answer.

The Correct Ingestion Pipeline

Source Media (video/image/audio)
       |
       +--> Embedding Model (Gemini Embedding 2)
       |       |
       |       +--> Vector (numbers in space)
       |
       +--> Description Generator (Gemini 3.1 Flash)
               |
               +--> Text description, transcript, metadata

Both get stored together in the vector database.

When someone queries the system: 1. The question becomes a vector 2. The closest vectors are found (works great because the embeddings are multimodal) 3. The system retrieves BOTH the media AND the text description 4. The LLM can now generate a detailed text answer AND provide the media

Before and After Comparison

Without description augmentation (naive):

Q: "How does Playwright test without opening browsers?"
A: "Insufficient information. Here are some source files."
   [raw video clip]

With description augmentation (proper architecture):

Q: "How does Playwright test without opening browsers?"
A: "Playwright supports headless mode, which runs browser
   automation without rendering a visible window. Here is
   how to configure it..."
   [relevant video chunk + matched images + text explanation]

Key Insight from Chase AI: "We do not want to just embed this video as-is as a vector. We want to include a description of the video, a transcript of the video, some sort of text. So when this vector gets pulled, we do not just get the video -- we get the accompanying document as well." --- Google's Embedding 2 Is RAG on Steroids

9.5 Video Chunking Strategy

Just as text documents must be chunked (split into manageable pieces) before embedding, videos must be chunked too. A one-hour video cannot be embedded whole -- the 120-second limit requires splitting.

The Simple Approach: Time-Based Chunking

The proven approach (borrowed from text chunking strategies) is:

Video: |-------- 60 minutes --------|

Chunk 1: [0:00 -------- 2:00]
Chunk 2:       [1:30 -------- 3:30]
Chunk 3:             [3:00 -------- 5:00]
...

The 30-second overlap ensures that content straddling a chunk boundary is captured in at least one chunk.

Why This Is Not Fully Solved

Video chunking is harder than text chunking because: - Topic transitions in video are not as clear as paragraph breaks - A visual demonstration might span multiple chunks - Context from earlier in the video may be needed later - Audio and visual content may convey different information

Key Insight from Chase AI: "The video chunking is going to be a big deal. Just like text chunking is a huge deal even now. I think we are going to have to apply that same logic to video and maybe also add things like re-rankers." --- Google's Embedding 2 Is RAG on Steroids

Future improvements will likely include: - Intelligent chunking based on topic detection - Re-rankers to improve result relevance - Transcript-aware splitting at natural topic boundaries

9.6 Practical Setup: Building a Multimodal RAG System

Prerequisites

You will need: - Python (updated version) - FFmpeg (for video processing) - Supabase CLI or Pine Cone account (vector database) - Gemini API key (for embeddings and descriptions) - Claude Code (for orchestrating the build)

Option 1: Supabase as Vector Database

Supabase is an open-source PostgreSQL-based platform with vector storage capabilities and a generous free tier.

Getting your keys: 1. Create an account at supabase.com (free tier works) 2. Create a project 3. Go to Project Settings > API Keys > Legacy anon role API keys 4. Copy your anon public API key 5. Go to Connect > scroll down > copy your Supabase URL 6. For CLI authentication, you will also need an access token

Claude Code handles all database creation via the Supabase CLI -- no manual SQL required.

Option 2: Pine Cone as Vector Database

Pine Cone is a managed vector database with a free starter plan.

Getting your keys: 1. Create an account at pinecone.io 2. Use the starter plan (free, sufficient for getting started) 3. Go to your dashboard and copy your API key

Key Insight from Nate Herk: "On Pine Cone, you can go ahead and use the starter plan, which is free. This will be more than enough to just get started to see how it works." --- Google's New Model + Claude Code Just Changed RAG Forever

Getting a Gemini API Key

  1. Go to Google AI Studio (aistudio.google.com)
  2. Click "Get API Key"
  3. Create a new API key

Building with Claude Code

The recommended approach is to use Claude Code in plan mode to architect the system:

I want to use Gemini's new Embedding 2 model to build a
multimodal RAG system with a Pine Cone vector database.
It should handle videos, images, and text.

Please build me a plan to set all of this up. Create a .env
file with placeholders and I will drop in my Pine Cone API
key, my Gemini API key, and my OpenRouter API key.

Claude Code will: 1. Create the project structure 2. Set up the embedding pipeline 3. Build the ingestion scripts (with description generation) 4. Create the vector database (via CLI) 5. Build a simple chat web UI for testing 6. Handle all dependency installation

Key Insight from Nate Herk: "I dropped in the PDF right here and I said 'Hey, Claude Code, there is the PDF. I want to be able to chat with this using Google's new embeddings model. Just go build it for me.' And not only did it build it for me, but it built this app where I can actually talk to it." --- Google's New Model + Claude Code Just Changed RAG Forever

9.7 Image RAG: Similarity Search for Visual Content

One of the most practical applications is image-based similarity search. This is transformative for industries that work with visual data.

Example: Roofing Project Matcher

Upload 13 images of past roofing projects, each with metadata (cost, team size, timeline, roof type). Then:

  1. A client uploads a photo of their damaged roof
  2. The system searches across all past project images
  3. Returns the 5 most similar past projects with:
  4. Percent match score
  5. Quote range and averages
  6. Team size trends
  7. Roof type breakdown
Q: [Upload image of damaged roof]
   "Find similar past projects for this roof."

A: 5 similar projects found:
   1. Richmond, VA - 92% match - Shingle replacement - $4,200
   2. Arlington, VA - 87% match - Water damage repair - $6,800
   ...

Key Insight from Nate Herk: "What might be helpful is if you had an app where internally or a client could upload a picture of their roof and you could get a quote or an internal brief about any past work that you have done on a roof that looks like that." --- Google's New Model + Claude Code Just Changed RAG Forever

Why This Matters

Before multimodal embeddings, building image similarity search required: - Manual feature extraction - Custom ML models for image comparison - Complex integration with separate text search

Now it is one unified pipeline. The embedding model understands the visual content natively.

9.8 PDF RAG: Searchable Chat with Extracted Diagrams

PDFs are particularly powerful because they combine text, diagrams, and images. With multimodal RAG, all of these are searchable.

Example: Product Manual Chat

A 68-page vacuum cleaner manual was ingested as a single PDF:

Q: "How do I clean the filter?"
A: "To clean the filter, follow these steps:
   1. Remove the filter assembly...
   2. Rinse under cool water...
   3. Allow to dry completely..."

   [Diagram showing filter removal process]
   [Same diagram in alternate languages]

   Sources: Page 23 (94% match), Page 24 (91% match)

The system returns: - Text instructions extracted from the PDF - Relevant diagrams and images from the PDF pages - Confidence scores for each source page

Key Insight from Nate Herk: "Sometimes when you are trying to troubleshoot things, especially if it is physical, an image is way more valuable than text. What is super cool is at the end I can actually expand the sources and it shows me the different pages that it looked at and the confidence score." --- Google's New Model + Claude Code Just Changed RAG Forever

How PDF Chunking Works

Claude Code handles the PDF chunking automatically. For a 68-page document: - Pages are split into logical chunks - Images and diagrams are extracted separately - Both text and visual elements are embedded - Cross-page context is maintained

9.9 Building the Web UI for Testing

Claude Code can generate a simple chat interface for testing your RAG system. The typical setup includes:

Tips for a Better UI

  1. Use the front-end design skill when building the chat interface
  2. Handle one upload at a time initially (multi-upload can be added later)
  3. Display confidence scores so users know how reliable each result is
  4. Embed media inline -- show images and video players directly in the answer, not just file names
  5. Show source pages/timestamps for traceability

Key Insight from Nate Herk: "Claude Code built this app where I can actually talk to it. I can see the text response, the actual diagrams pulled from the PDF, and expand sources showing different pages and confidence scores." --- Google's New Model + Claude Code Just Changed RAG Forever

9.10 Architecture Considerations for Production

The implementations shown in the source videos are 90% solutions -- functional but not production-hardened. Here are the key areas to address before going live.

Data Cleanup and Updates

What happens when you modify a document that is already in the database? - Do you re-embed the whole thing? - How do you remove stale vectors? - How do you handle versioning?

You need an upsert strategy: check if a document exists, delete old vectors, re-embed the updated version.

Description Quality

The quality of your text descriptions directly impacts answer quality. Generic auto-generated descriptions produce mediocre results. Adding subject matter expertise to descriptions dramatically improves retrieval.

# Generic (weak)
"A video showing a person using a computer"

# Expert-augmented (strong)
"Tutorial demonstrating Playwright CLI headless browser
automation in Claude Code, covering: initialization with
playwright-cli init, running tests with --headless flag,
and the show command for visual dashboard monitoring"

Key Insight from Nate Herk: "The key thing about audio is being able to give it good descriptions so that the AI understands what is actually in that audio file. The importance and value is way more shifting towards being able to communicate clearly, having deep understanding of processes." --- Google's New Model + Claude Code Just Changed RAG Forever

Current Limitations

Limitation Detail
Video length 120 seconds max per chunk (workaround: FFmpeg chunking)
Image formats PNG and JPEG only
Images per request 6 maximum
Video formats MP4 and MOV only
Chunking intelligence Time-based chunking is simplistic; topic-aware chunking is still evolving

Scaling Considerations

Chapter Summary

Concept Key Takeaway
RAG Retrieve proprietary data to augment LLM answers
Gemini Embedding 2 First natively multimodal model: text, image, video, audio in same space
Naive RAG problem Embedding video without descriptions returns clips, not analysis
Proper architecture Embed media + generate text descriptions = LLM can analyze results
Video chunking 2-minute chunks with 30-second overlap via FFmpeg
Supabase Open-source vector DB with free tier, managed via CLI
Pine Cone Managed vector DB with free starter plan
Image RAG Similarity search for visual matching (roofing, products, designs)
PDF RAG Searchable chat with extracted text, diagrams, and images
Build approach Use Claude Code in plan mode; it handles everything from DB creation to UI
Production gaps Data cleanup, description quality, advanced chunking, re-ranking

Chapter 10: Tips and Tricks

Source Videos: 567 Hours of Claude Code Lessons, The ONLY Claude Code Tutorial You'll Ever Need in 2026, Anthropic Just Dropped the Feature Nobody Knew They Needed, Mitchell Hashimoto's new way of writing code

This chapter distills the most impactful practical advice from hundreds of hours of Claude Code usage into actionable tips. From context window management to debugging strategies, from mindset shifts to essential slash commands, these are the lessons that separate productive Claude Code users from those who struggle.

10.1 Context Window Management: The Single Most Important Skill

If you learn only one thing from this entire study guide, let it be this: manage your context window or your output quality will collapse.

The Context Rot Problem

Claude Code has a 200,000 token context window. The problem is not the size -- it is what happens when you fill it. When you hit approximately 50% usage (around 100,000 tokens), output effectiveness begins to nosedive. By 60-70%, you are in the danger zone.

Key Insight from Chase AI: "Context rot tells us that when we hit about 100,000, the halfway mark, or about 120,000 tokens, the effectiveness of our AI system drops drastically. It begins to nosedive." --- 567 Hours of Claude Code Lessons

Monitoring Context Usage

Check your context window at any time:

/context

This gives you a visual breakdown of what is consuming your context: - System prompt - System tools - Custom agents - Memory files - Skills (only loaded ones) - Messages (your conversation history) - Free space remaining

Building a Persistent Status Line

Instead of repeatedly running /context, set up a persistent status line that always shows context percentage:

Build me a status line with context window percentage always
visible, along with the current model and working directory.

This gives you a running tally at the bottom of your terminal:

CC-stuff | Opus 4.6 | Context: 34%

Key Insight from Chase AI: "This does not come out of the box. You can prompt Claude Code and say 'build me a status line with context window percentage always visible' and it will build it for you." --- 567 Hours of Claude Code Lessons

When and How to Clear

When to clear: - Approaching 50-60% context usage - Switching to a completely different task - After completing a major feature - When you notice quality degradation

How to clear:

/clear    # Wipes conversation history entirely, resets token count
/compact  # Keeps a summary in context but frees up space

Do not be afraid of /clear. Unlike web-based AI chat, Claude Code always has context through your project files. It can read your codebase, see what has been built, and pick up where things left off. Clearing conversation history is not the same as losing all context.

Key Insight from Philip Thomas: "After clearing, Claude still has context because it can always look at your files and project. Restarting the conversation is not really a hit." --- Claude Code Tutorial

What NOT to Do

Do not let Claude Code auto-compact by hitting the limit. This happens automatically when you never manually clear and the window fills up. Auto-compaction is a lossy compression of your conversation that you have no control over. Manual clearing at strategic points is always better.

The Skills vs. claude.md Trade-Off

Your claude.md file is loaded fully into context at every session start. Skills are loaded on demand when needed. If you have instructions that are only needed for specific tasks, put them in skills to save context.

Key Insight from Philip Thomas: "The claude.md is always completely loaded into context. Skills are only loaded when needed. So if you have information that is only needed in specific situations, put it in skills to save tokens." --- Claude Code Tutorial

10.2 The /btw Command: Side Questions Without Context Pollution

The /btw (by the way) command is one of the most underappreciated features in Claude Code. It lets you ask a quick question about what Claude is doing without polluting the main conversation history.

The Problem It Solves

When Claude is implementing a feature -- reading files, writing code, running tests -- you might want to ask "why did you use that library?" The old approach was: 1. Press Escape or Ctrl+C to interrupt Claude 2. Ask your question 3. Get an answer that goes into the conversation history 4. Claude resumes, but now the context is polluted with Q&A noise

This is like tapping someone on the shoulder during deep focus. It interrupts their flow and clutters the workspace with information only YOU needed.

Key Insight from Ray Amjad: "If you do this enough, you end up polluting the conversation with a bunch of irrelevant noise. You have less signal overall because you end up having random explanations that the model did not need, but you needed instead." --- Anthropic Just Dropped the Feature Nobody Knew They Needed

How /btw Works

While Claude is working, type:

/btw why did you import and use AVFoundation?

Claude answers your question in an inline overlay. Press Escape, Enter, or Space to dismiss. Meanwhile, the main session continues working behind the scenes.

Key properties of /btw: - Full context visibility -- It can see everything decided and written so far - No context pollution -- Neither the question nor the answer enters conversation history - Non-interrupting -- Claude keeps working while answering - Cost-efficient -- Uses the prompt cache of the main session, so cost is very low

Limitations of /btw

If you need follow-ups or file generation, use /fork instead.

10.3 Forking Sessions for Deep Dives

When /btw is not enough -- you need to explore alternatives, generate artifacts, or have a multi-turn conversation -- use session forking.

Method 1: /fork (Within the Session)

/fork

This moves you to a forked branch of the conversation. You can explore a different approach, test ideas, or ask detailed questions. To resume the original session, copy the session command into a new terminal pane with --fork-session.

Method 2: Split Terminal + Fork

# In a new terminal pane:
claude --continue --fork-session

This creates a copy of the current session in a separate window. Changes in the fork do not affect the main session. When you are done exploring, close the fork pane (Ctrl+W) and continue in the main session.

When to Use Each

Scenario Use
Quick "why did you do X?" question /btw
Multi-turn exploration /fork
Generate a diagram or file for reference --fork-session
Try a completely different approach /fork + worktree

Key Insight from Ray Amjad: "I would personally use /btw as a quick question and then use fork session for any deep dives. That would be for anything that requires reading files, producing artifacts like a mermaid diagram, or exploring a different approach." --- Anthropic Just Dropped the Feature Nobody Knew They Needed

10.4 Using /rewind to Fix Misconceptions

When you discover via /btw that Claude made a fundamentally wrong assumption early in the conversation, do NOT just correct it from the current point. The stale, incorrect context is already polluting 20-30% of the context window.

The Wrong Approach

Claude makes wrong assumption at message 5
  --> You notice at message 25
    --> You say "Actually, I meant X not Y"
      --> Claude tries to reconcile 20 messages of wrong context
        --> Results are messy and inconsistent

The Right Approach

/rewind

This takes you back to a previous point in the conversation AND the code state. Select the point before the wrong assumption was made. Choose "restore code and conversation." Then re-prompt with the correct information.

/rewind
# Select the checkpoint before the bad assumption
# Choose "Restore code and conversation"
# Re-prompt with corrected details

Key Insight from Ray Amjad: "Rather than arguing with stale context where Claude made a bad decision early on and having that stale wrong context polluting 20-30% of the context window, you should /rewind earlier on and then re-prompt with the correct information." --- Anthropic Just Dropped the Feature Nobody Knew They Needed

The /btw + /rewind Workflow

These two commands work together perfectly:

  1. Claude is building a feature
  2. You use /btw to ask about an approach
  3. You realize Claude has a fundamental misconception
  4. You use /rewind to go back before the mistake
  5. You re-prompt with additional detail
  6. Claude proceeds correctly from that point

10.5 Security Review Before Deployment

Before deploying anything Claude has built, always run a security check. This is not optional.

Review this project for security issues.

Claude scans for: - Exposed API keys in source files - Hardcoded credentials or secrets - Vulnerabilities in dependencies - Insecure configurations - Missing environment variable usage (keys that should be in .env but are in code)

Key Insight from Zinho Automates: "Always remember to run a security check before deployment. Type 'review this project for security issues.' Claude scans for exposed keys, vulnerabilities, and risks." --- The ONLY Claude Code Tutorial You'll Ever Need in 2026

Common Security Mistakes with AI-Generated Code

  1. API keys in source code -- Claude may inline keys during development. Always move them to .env files.
  2. Overly permissive CORS -- AI tends to set * for convenience during development.
  3. Missing input validation -- Fast prototyping may skip sanitization.
  4. Debug endpoints left active -- Development routes that expose internal data.
  5. Default credentials -- Database passwords, admin accounts left as defaults.

Make security review a habit, not an afterthought.

10.6 Test-Driven Development with Claude Code

Telling Claude Code to use test-driven development (TDD) dramatically improves output quality. It gives Claude a way to verify its own work.

The Approach

During planning mode, explicitly instruct:

Execute this in a test-driven development manner.
Write the tests first, then implement the features
to pass those tests.

Why This Works

Key Insight from Chase AI: "The third troubleshooting step is to just try to avoid problems altogether. During your plan stage, tell Claude Code to execute this in a test-driven development manner." --- 567 Hours of Claude Code Lessons

Mitchell Hashimoto's Testing Insight

The co-founder of HashiCorp discovered that giving Claude a better test harness makes it dramatically more effective:

Key Insight from The Pragmatic Engineer: "I figured out, oh, if I have a better test harness for it to execute, it does a lot better. And then I recognized, oh, if it makes a mistake and I add that to agents.md, it never makes that mistake again." --- Mitchell Hashimoto's new way of writing code

This is a compounding effect: better tests lead to better code, and documenting mistakes in claude.md or agents.md prevents them from recurring.

10.7 Don't Just Accept -- Ask "Why Did You Do X?"

The biggest trap for Claude Code users -- especially non-technical ones -- is becoming an "accept monkey." You press accept, accept, accept without understanding what is happening. This works for simple projects but collapses for anything complex.

The Mindset Shift

You do not need to know how to code. But you DO need to understand how the building blocks come together. When Claude tells you what it did, and you have no idea what any of it means, you must ask.

Key Insight from Chase AI: "Claude Code is so good that you can get pretty far by just being an accept monkey. But at a certain point, you need to begin to internalize and gain some experience and understanding of what is going on. Or else when you start doing more complicated projects, you are going to fall on your face." --- 567 Hours of Claude Code Lessons

Practical Questions to Ask

When Claude completes a step, consider asking:

What am I not thinking about?
Is this the best way forward?
What would someone who is an expert in [domain] be doing here?
Why did you choose [library/approach/pattern]?
What are the trade-offs of this approach?
What could go wrong with this implementation?

The Expert Consultation Pattern

Rather than blindly trusting Claude, treat it as a colleague you are supervising:

Before you implement this, tell me:
1. What approach are you planning?
2. What alternatives did you consider?
3. What are the risks?

This is especially important when: - You are in unfamiliar technical territory - The project has security or financial implications - You are building something for production use - Multiple valid approaches exist

10.8 File Structure and Organization

How you organize your project directly impacts Claude Code's effectiveness. A logical, well-structured project is easier for Claude to navigate and less likely to produce errors.

Why Structure Matters

Claude Code reads your project files to understand context. If your project is a flat directory of 200 files with inconsistent naming, Claude spends more tokens figuring out what goes where. A clean structure means: - Claude finds relevant files faster - Less context wasted on orientation - Fewer mistakes from putting code in the wrong place - Better understanding of component relationships

Best Practices

  1. Use standard conventions for your framework -- If using React, follow React conventions. If using SvelteKit, follow SvelteKit conventions. Claude knows these patterns.

  2. Put tech stack info in claude.md so Claude does not have to guess: ```markdown # Tech Stack

  3. SvelteKit 2 / Svelte 5
  4. Tailwind CSS 3

  5. DaisyUI 4 ```

  6. Use /init for existing projects -- This analyzes your codebase and generates an appropriate claude.md: /init

  7. Nest claude.md files in subdirectories for folder-specific rules: project/ claude.md # Global project rules tests/ claude.md # Testing conventions components/ claude.md # Component patterns

10.9 Comments and Documentation

Good comments help both humans AND future AI sessions. When Claude starts a new session, it reads your files. Comments provide context that makes future sessions more effective.

Comments as AI Memory

Every time you start a new session, Claude loses the conversation from the previous session. But it can always read your code. Comments bridge this gap.

// IMPORTANT: Using AVFoundation instead of MediaPlayer
// because we need background audio support on iOS.
// See: https://developer.apple.com/documentation/avfoundation
// Decision made 2026-03-10 after testing both approaches.

This comment helps future Claude sessions understand not just WHAT was done, but WHY -- preventing the same exploration and potential wrong decisions.

What to Comment

Asking Claude to Comment

Always add comments to the code explaining the why,
not just the what.

Or add it to your claude.md:

# Code Style
- Always add comments explaining architectural decisions
- Document non-obvious behavior
- Include links to relevant documentation

10.10 Strategic Use of Plan Mode

Plan mode is the most important setting for the start of any project or major feature. It forces Claude to think before acting.

When to Use Plan Mode

Toggle plan mode with Shift+Tab or set it explicitly:

Shift+Tab  (cycle through permission modes)
# Or in the prompt:
Let's work in plan mode. Here is what I want to build...

What Plan Mode Gives You

Instead of immediately writing code, Claude: 1. Asks clarifying questions (brand name, color scheme, features) 2. Creates a detailed plan (file structure, architecture, steps) 3. Shows you the verification approach 4. Presents options: accept, modify, or start over

Key Insight from Chase AI: "Plan mode is one of the most powerful features of Claude Code. It is what you need to be on every single time you start a new project or try to implement a brand new feature." --- 567 Hours of Claude Code Lessons

The "Yes, Clear Context" Pattern

After plan mode produces a solid plan, the typical best response is:

Yes, clear context and bypass permissions.

This tells Claude: execute the plan, start with a fresh context window, and do not ask permission for every file operation. The plan is your agreement; now let it work.

Mitchell Hashimoto's Planning Discovery

The co-founder of HashiCorp independently arrived at the same conclusion as thousands of other users:

Key Insight from The Pragmatic Engineer: "I naturally got to the same point that thousands of other people got to, which is: if I do a separate planning step, it does so much better." --- Mitchell Hashimoto's new way of writing code

10.11 Iterative Refinement

Do not expect perfection on the first pass. The most effective Claude Code workflow is iterative: build, evaluate, refine, repeat.

Image Input for Visual Feedback

Instead of trying to describe visual problems in words, take a screenshot and drag it into Claude Code:

[drag screenshot of broken mobile layout]
Fix this alignment problem. The products are stacking weird
on mobile and the spacing is off.

Claude analyzes the screenshot, identifies the CSS/layout issue, and fixes it. This saves enormous time compared to verbal descriptions.

Key Insight from Zinho Automates: "Instead of trying to explain the problem in words, just show Claude the problem. You do not need to know CSS or media queries. You just show Claude the problem and it fixes it for you. This alone has saved hours of debugging time." --- The ONLY Claude Code Tutorial You'll Ever Need in 2026

Copy-Paste Error Debugging

When errors occur outside Claude Code (in a browser, in a deployment platform, in a test runner), copy the error and paste it directly:

I am getting this error on Vercel:
[paste error output]

The Refinement Loop

1. Build (let Claude implement)
2. Test (run it, look at it, try edge cases)
3. Feedback (screenshot issues, paste errors, describe what is wrong)
4. Fix (Claude addresses the specific issues)
5. Repeat until satisfied

When to Stop Iterating

For skills, use the Skill Creator eval to get a quantitative score. Stop when you hit 9 out of 10 or better. For code, stop when: - All tests pass - The UI matches your vision - Security review is clean - Performance is acceptable

10.12 Essential Slash Commands Reference

Here is a comprehensive reference for the most important slash commands in Claude Code.

Session Management

Command Description
/clear Clear conversation history entirely, reset token count
/compact Summarize conversation and free up context space
/context View current context window usage breakdown
/exit Exit Claude Code
Command Description
/rewind Go back to a previous point in conversation and code state
/fork Create a branch of the current conversation for exploration
/btw Ask a side question without polluting main context

Configuration

Command Description
/model Switch between models (Opus 4.6, Sonnet 4.6, Haiku)
/config View and modify Claude Code configuration
/permissions Manage tool permissions
/memory View and edit Claude's saved memories
/init Generate claude.md from an existing codebase
/usage Check token usage and subscription limits

Extensions

Command Description
/plugin Browse, install, and manage plugins
/mcp Manage MCP server connections
/hooks Create and manage event hooks
/agents Create and manage subagents

Automation

Command Description
/loop Schedule recurring prompts in the current session
/schedule Create persistent scheduled tasks (Desktop only)

Permission Modes (Shift+Tab)

Mode Behavior
Default Prompts for permission on first use of each tool
Accept edits Auto-approves file edits; asks for bash commands
Plan mode Analyze only, no modifications allowed
Bypass permissions Skips all permission prompts (requires --dangerously-skip-permissions flag)

Keyboard Shortcuts

Shortcut Action
Shift+Tab Cycle through permission modes
Escape or Ctrl+C Interrupt Claude mid-task
@filename Scope Claude's edits to a specific file

10.13 The Background Agent Habit

One of the most practical tips from an experienced engineer: always have an agent doing something.

Mitchell Hashimoto's Rule

Before stepping away from your desk -- to get coffee, take a walk, commute, eat lunch -- ask yourself:

"What slow task could an agent be doing while I am gone?"

Examples: - Research edge cases in a codebase - Think deeply about potential issues with an approach - Generate comprehensive documentation - Explore alternative implementations - Analyze a competitor's open-source repo

Practical Implementation

# Before leaving for lunch:
"Look at this vouching system implementation. Think deeply
about what the edge cases might be. What am I missing?
Write up your analysis in edge-cases.md."

Critical Rule: Turn Off Notifications

The agent does not get to interrupt you. You interrupt the agent when YOU are ready.

Key Insight from The Pragmatic Engineer: "He turns off all the agent tool notifications and desktop notifications. He chooses when he interrupts the agent. It does not get to interrupt him." --- Mitchell Hashimoto's new way of writing code

Delegate Non-Thinking Work

Identify tasks that do not require YOUR thinking and delegate them:

Reserve your cognitive energy for the tasks that actually require human judgment and creativity.

Key Insight from The Pragmatic Engineer: "He identifies the tasks that do not require thinking and delegates those to an agent. 'There are a lot of people who say you think less with AI. If you use the tools wrong, you do. But if you view it as a way to choose what you think about, then you do not sacrifice that thinking.'" --- Mitchell Hashimoto's new way of writing code

10.14 The Learning Curve Is Real (And Worth It)

Mitchell Hashimoto's experience mirrors what many experienced developers discover:

  1. Initial skepticism -- "I tried Claude Code when it came out. Was not super impressed."
  2. Fear of falling behind -- "I saw so many positive remarks that I started to get scared I would be behind."
  3. Forced practice -- "I was forcing myself to figure out how to prompt the agent to produce the same quality result. I was working much slower because I was doubling the work."
  4. Breakthrough moments -- "I naturally got to the same point that thousands of others got to: if I do a separate planning step, it does so much better."
  5. Compounding returns -- "If it makes a mistake and I add that to agents.md, it never makes that mistake again."

Key Insight from The Pragmatic Engineer: "It is as if someone tried to adopt Git and they used it for an hour and decided they were not more productive with it. It takes much longer than an hour to get proficient with Git, but you put in the effort and then you reap the rewards later. It is the same thing with AI tools." --- Mitchell Hashimoto's new way of writing code

His Advice for Skeptics

If you do not want AI writing code for you, start with research: - "Consult the oracle" -- have the agent think deeply about edge cases - Build ecosystem graphs of dependencies - Explore unfamiliar codebases - Research best practices before implementation

You do not have to go all-in on AI coding. Find the corners of your work where it adds value and start there.

Chapter Summary

Tip Key Takeaway
Context management Stay below 50% usage; use /context and /clear liberally
/btw Side questions without context pollution; single turn, read-only
/fork Deep dives requiring multi-turn conversation or file generation
/rewind Fix misconceptions by going back to before the wrong assumption
Security review Always scan for exposed keys before deployment
TDD Tell Claude to write tests first; gives it a verification loop
Don't just accept Ask "why" and "what am I not thinking about?"
File structure Logical organization helps Claude navigate your project
Comments Help both humans and future AI sessions understand decisions
Plan mode Always for new projects and major features
Iterative refinement Build, test, screenshot issues, fix, repeat
Background agent Always have an agent working on something; you interrupt it
Learning curve Invest time like you did with Git; returns compound over time

Flashcards

Workflow Cards

Card 1

Q: Which Claude Code command allows you to ask a quick question without adding it to the conversation history?

A: /btw (By The Way)

Card 2

Q: What is the primary drawback of using the /btw command compared to a fork session?

A: It is single-turn only and lacks tool access.

Card 3

Q: Claude Code's /loop command allows users to schedule recurring prompts within the _____.

A: Current session

Card 4

Q: What is the maximum duration a /loop task remains active before expiring?

A: 3 days

Card 5

Q: Which command is used to create a permanent, persistent scheduled task in the Claude Code desktop app?

A: /sched

Card 6

Q: Concept: Context Pollution

A: The degradation of model output caused by adding irrelevant Q&A or tangents to the main conversation history.

Card 7

Q: How does the /rewind command help improve Claude Code's performance on a task?

A: It removes stale or incorrect context by restoring the conversation to a previous state.

Card 8

Q: When choosing between an MCP server and a CLI tool for an AI agent, which is generally preferred?

A: The CLI tool (due to less overhead and better terminal integration).

Card 9

Q: What file extension is used to define a custom skill in Claude Code?

A: .md (skill.md)

Card 10

Q: The _____ skill from Anthropic allows users to measure skill performance and run AB tests.

A: Skill Creator

Card 11

Q: What is a 'Capability Uplift' skill?

A: A prompt-based skill that helps the model perform a specific task better than it would by default.

Card 12

Q: What is an 'Encoded Preference' skill?

A: A skill that enforces a specific, sequential workflow or organizational preference.

Card 13

Q: Term: GSD Framework

A: An orchestration layer for Claude Code that focuses on spec-driven development and context management.

Card 14

Q: How does the GSD framework prevent context window degradation?

A: By ensuring each new portion of a plan is executed with a fresh context window using sub-agents.

Card 15

Q: Which tool allows Claude Code to access Notebook LM's research capabilities without an official API?

A: Notebook LM-PI

Card 16

Q: In a personal assistant context, which tool is recommended for organizing sprawling markdown files created by Claude Code?

A: Obsidian

Card 17

Q: What is the purpose of the Playwright CLI in a Claude Code workflow?

A: Executing browser automations and testing UI design or form submissions.

Card 18

Q: Firecrawl provides four core commands: scrape, crawl, _____, and search.

A: map

Card 19

Q: Why is Firecrawl preferred over standard web search for AI agents?

A: The data it returns is specifically tailor-made for AI ingestion.

Card 20

Q: Which skill allows Claude Code to generate visual charts and diagrams through natural language?

A: Excalidraw Diagram Skill

Card 21

Q: To target a specific file for editing without touching other project files, use the _____ symbol.

A: @ (e.g., @styles.css)

Card 22

Q: Which file, placed in the project root, sets permanent rules that Claude reads at the start of every session?

A: claude.md

Card 23

Q: Term: Model Context Protocol (MCP)

A: An Anthropic-created standard for connecting AI assistants to external data systems and services.

Card 24

Q: What is the function of the 'Skill Trigger Tuning' feature in the Skill Creator?

A: Optimizing skill descriptions to ensure Claude invokes them accurately based on natural language prompts.

Card 25

Q: In skill testing, a _____ is used to detect if a model's performance on a skill has decreased after an update.

A: Regression test

Card 26

Q: Which CLI tool provides Claude Code access to the entire Google Workspace ecosystem (Drive, Gmail, Docs)?

A: GWS CLI

Card 27

Q: How does the GWS CLI differ from standard API calls when creating Google Docs?

A: It uses bash commands to produce properly formatted documents instead of raw markdown.

Card 28

Q: Term: RAG (Retrieval-Augmented Generation)

A: A system where a model retrieves external data to improve the accuracy and context of its generated answers.

Card 29

Q: What is the primary challenge of using video files in a naive RAG system?

A: LLMs often cannot ingest the raw media file to provide a text-based analysis without extra processing.

Card 30

Q: To make video RAG effective, what should be paired with the embedded video vector?

A: A text-based description or transcript of the video content.

Card 31

Q: _____ is a language server protocol that gives Claude Code real-time code intelligence like 'jump to definition'.

A: LSP

Card 32

Q: In Claude Code plugins, which event hook fires immediately after Claude uses a tool like 'write' or 'edit'?

A: post-tool-use

Card 33

Q: Which plugin scope makes a tool available across all projects for a specific user?

A: User scope

Card 34

Q: What directory does Claude Code use to store project-specific rules and learned developer preferences?

A: .clo-memory (or auto-memory directory)

Card 35

Q: The 'By The Way' (/btw) command uses _____ to keep the cost of questions low.

A: Prompt caching

Card 36

Q: Which model is recommended for planning complex architecture and debugging tricky issues in Claude Code?

A: Opus 4.6 (or highest reasoning model)

Card 37

Q: Which model is best for routine edits and simple components due to its speed and lower token cost?

A: Sonnet 4.6

Card 38

Q: Mitchell Hashimoto suggests always keeping an agent running a _____ task in the background while working.

A: Slow (or research-heavy)

Card 39

Q: What is 'Harness Engineering' in the context of AI agents?

A: Building tools or tests that allow an agent to validate its own work and prevent errors.

Card 40

Q: In the Skill Creator, what does an 'eval' (evaluation) typically generate to show performance?

A: A structured report (often HTML) with pass/fail grades and scores.

Card 41

Q: How does Claude Code handle a missed /loop task if the terminal was closed?

A: The task disappears and never runs (unlike scheduled tasks which 'catch up').

Card 42

Q: Which command opens the visual plugin manager in the Claude Code terminal?

A: /plugin

Card 43

Q: Term: libghosty

A: A minimal, zero-dependency library for embedding high-performance terminals into other applications.

Card 44

Q: Why does the GSD framework use sub-agents?

A: To manage complex tasks in parallel and avoid hitting context window limits.

Card 45

Q: What is the purpose of the YAML front matter in a skill.md file?

A: It provides the skill name, description, and instructions for when Claude should trigger it.

Card 46

Q: Which tool is specifically recommended for 'cleaning up' data for AI agents before it enters a vector database?

A: Gemini (e.g., 1.5 Flash)

Card 47

Q: In the Vercel CLI plugin, what can an agent loop be used for?

A: Monitoring deployment statuses automatically after code changes.

Card 48

Q: Which command is used to exit a Claude Code session?

A: /exit

Card 49

Q: Concept: Forking a Session

A: Creating a copy of the current chat to explore a different approach or ask questions without affecting the main thread.

Card 50

Q: What is the benefit of 'local' plugin scope?

A: It keeps the plugin private to a single repository.

Card 51

Q: Which Claude Code feature allows for screenshot-based debugging?

A: Image input (Vision)

Card 52

Q: The _____ command allows you to view and edit what Claude has learned about your project preferences.

A: /memory

Card 53

Q: What is 'Trigger Tuning'?

A: Adjusting a skill's description so the AI invokes it correctly using natural language.

Card 54

Q: Which tool provides 'Multimodal Embedding 2' for RAG systems?

A: Google

Card 55

Q: What is the main advantage of using the Superbase CLI over manual SQL coding in Claude Code?

A: Claude can manage the database and authentication using plain language commands.

Card 56

Q: How does 'planning mode' improve Claude Code's output for new projects?

A: It forces the agent to ask clarifying questions and establish a file structure before writing code.

Card 57

Q: Which specific plugin is designed for managing project tasks in Linear or Asana through Claude Code?

A: External integration plugins

Card 58

Q: In skill development, what is a 'human-in-the-loop' checkpoint?

A: A defined step in the instructions where the agent must stop and ask for user approval.

Card 59

Q: What is the 'ultra mode' or 'max' effort setting in Claude Code?

A: A configuration that allows the model to reason more deeply and work longer on complex tasks.

Card 60

Q: Why should developers use the GitHub CLI instead of manual web actions in Claude Code?

A: It allows pushing code, managing PRs, and checking issues directly from the terminal with natural language.

Card 61

Q: Which Claude Code tool helps developers catch security vulnerabilities before deployment?

A: Security Reviewer agent (or /review command)

Card 62

Q: Term: Cron Jobs (in Claude Code)

A: The underlying scheduling system used to power recurring loops and scheduled tasks.

Card 63

Q: Which file specifies the name, version, and capabilities of a Claude Code plugin?

A: plugin.json

Card 64

Q: What is the 'Notebook LM' value play in Claude Code?

A: Offloading heavy research and deliverable creation (like slide decks) to a free tool.

Card 65

Q: How do 'Hooks' automate workflows in the Claude Code plugin system?

A: By triggering specific shell commands or LLM prompts automatically after defined events like file edits.