# AI Architects — full content dump Source: https://theaiarchitects.com Generated: 2026-08-13T08:38:33.088Z This file concatenates the full markdown of articles and case studies for LLM ingestion. The curated index lives at https://theaiarchitects.com/llms.txt. --- # Articles # Claude Code Plan Mode Checklist Before Production Edits Source: https://theaiarchitects.com/blog/claude-code-plan-mode-checklist Published: 2026-07-05 A practical checklist for using Claude Code Plan Mode before you let an agent edit production code, automations, or business-critical workflows. Plan Mode is where Claude Code becomes useful for serious work. It forces the agent to slow down, inspect the system, and explain the change before it touches files. For non-technical operators, this is the difference between experimenting with AI and safely shipping systems inside a business. ## The checklist - What exact outcome are we trying to create? - Which files, tools, or systems are in scope? - Which systems are explicitly out of scope? - What could break if this change is wrong? - How will we verify the result? - What is the rollback path? ## The prompt I use Before you edit anything, inspect the relevant files and give me a plan. Include the files you expect to touch, the risks, the smallest verification step, and what you will not change. Wait for approval before implementation. ## Where Plan Mode matters most - Revenue pages, checkout flows, and lead forms. - Automations that send email or change CRM records. - Client deliverables where a silent mistake is expensive. - Shared code or scripts that other workflows depend on. ## The operating rule If the work can affect money, customers, or production data, make the agent plan first. The point is not bureaucracy. The point is keeping judgment in the loop while the agent does the mechanical work. > [CTA-BLUEPRINT] ## Related guides - [Claude Code Plan Mode: When and How to Use It in 2026](/blog/claude-code-plan-mode) - [How to Use Claude Code: The 60-Minute Beginner Guide](/blog/how-to-use-claude-code) - [Claude Code Agents Explained: Subagents, Agent View, and Teams](/blog/claude-code-agents) --- # Claude Chrome Extension Permissions: What It Can See Source: https://theaiarchitects.com/blog/claude-chrome-extension-permissions Published: 2026-07-04 A plain-English guide to Claude Chrome extension permissions, what browser agents can access, and the workflow rules non-technical teams should use before trusting it. The useful question with the Claude Chrome extension is not just how to install it. It is what you are comfortable letting it see. Browser agents are powerful because the browser is where your work already happens. That is also why permissions matter. ## What the extension needs access to A browser assistant needs enough context to read the page you are asking about, understand the task, and act inside the browser. That may include page text, selected content, form fields, and the current tab state. That does not mean every workflow is equally safe. Reading a public documentation page is different from working inside a CRM, bank account, health record, or client inbox. ## My practical permission rules - Use it freely on public pages, documentation, research, and low-risk SaaS tools. - Pause before using it on pages with client secrets, payment data, private messages, or sensitive personal information. - Do not let it submit irreversible actions until you have watched the workflow several times. - For teams, write a one-page allowed-sites policy before rollout. ## The team rollout version For a 20 to 200 person company, the extension should start as a supervised tool. Pick two workflows: research and internal documentation. Prove those work. Then expand to customer-facing or operational tools only after you know what data is being exposed. ## The right mindset Treat browser agents like a capable junior operator. Give them access to the pages they need, make them explain what they are about to do, and keep human approval on anything that changes money, customer data, or production systems. > [CTA-BLUEPRINT] ## Related guides - [Claude Chrome Extension: Setup, 8 Use Cases, Privacy](/blog/claude-chrome-extension) - [How to Install the Claude Chrome Extension](/blog/how-to-install-claude-chrome-extension) - [Claude Chrome Extension Not Working? Fixes](/blog/claude-chrome-extension-not-working) - [Is the Claude Chrome Extension Safe?](/blog/is-claude-chrome-extension-safe) --- # Claude Code API Credits: The Real Free Trial Path Source: https://theaiarchitects.com/blog/claude-code-free-trial-api-credits Published: 2026-07-03 How to use Anthropic API credits to test Claude Code without committing to a subscription, what the test proves, and where it gives a false signal. Claude Code does not really have a normal free trial. The closest thing is API credits. That path is useful, but only if you use it for the right test. The API-credit test should answer one question: does Claude Code make sense for the kind of work you actually do? It should not be treated as a month-long production plan. ## What API credits are good for - Installing Claude Code and confirming it runs on your machine. - Testing one small project with real files. - Seeing whether terminal-based agent work feels natural to you. - Learning the difference between chat prompting and project execution. ## What they are bad for - Long build sessions with large codebases. - Testing a full team workflow. - Comparing weekly usage caps against Pro or Max. - Running production automation without spend monitoring. ## The 45-minute test Pick one annoying workflow from your business: a report, a landing page edit, a data cleanup, or a repeated internal task. Put only the relevant files in a small folder. Ask Claude Code to inspect the folder, propose a plan, make one change, and show you how to verify it. If that experience is useful, buy a month of Pro. If it is confusing, the problem is probably not the plan. It is project structure and task framing. > [CTA-BLUEPRINT] ## Related guides - [Claude Code Pricing 2026: Pro, Max, Fable 5 & API](/blog/claude-code-pricing) - [Claude Code Pricing Calculator: Pick Pro, Max, or API](/blog/claude-code-pricing-calculator) - [Claude Code Rate Limits and How to Stop Hitting Them (2026)](/blog/claude-code-rate-limits) - [Claude Code Free Trial: The Honest Path to a Real Test in 2026](/blog/claude-code-free-trial) --- # Claude Code Pricing Calculator: Pick Pro, Max, or API Source: https://theaiarchitects.com/blog/claude-code-pricing-calculator Published: 2026-07-03 A practical decision guide for choosing Claude Code Pro, Max, or API credits based on how often you build, how large your projects are, and whether you need predictable spend. Most Claude Code pricing advice starts with the plan page. That is backwards. The useful question is how many real build sessions you run in a normal week and how painful it is when the meter stops you. This guide is the quick calculator I would use before buying or upgrading. It is built for operators and founders, not engineers trying to optimize every token. ## The short answer - Choose Pro if you are learning, testing, or building one focused workflow at a time. - Choose Max 5x if Claude Code is now part of your normal workday and hitting limits costs you momentum. - Choose Max 20x only if you are running long sessions, large repos, or multiple agent workflows most days. - Choose API credits when you need exact spend controls, automation accounts, or usage separated from your personal subscription. ## A practical rule of thumb If you use Claude Code less than three days a week, start with Pro. If you use it daily and lose time to limits, Max 5x is usually the first serious upgrade. If you are building production systems for clients, API billing belongs in the stack because the cost should be traceable to the work. The mistake is buying the expensive plan before you know what work Claude Code is replacing. The plan should follow the workflow, not the other way around. ## What to measure before upgrading - How many build sessions you run per week. - How often sessions stop because of usage limits. - Whether you are asking Claude Code to read large codebases or small task folders. - Whether the work creates revenue, saves team time, or is still experimentation. ## My recommendation Run one month on Pro with a specific target: ship one workflow you will keep using. If you hit the cap repeatedly while doing valuable work, upgrade. If you do not, stay on Pro and put the money into better project structure, prompts, and review habits. > [CTA-BLUEPRINT] ## Related guides - [Claude Code Pricing 2026: Pro, Max, Fable 5 & API](/blog/claude-code-pricing) - [Claude Code API Credits: The Real Free Trial Path](/blog/claude-code-free-trial-api-credits) - [Claude Code Rate Limits and How to Stop Hitting Them (2026)](/blog/claude-code-rate-limits) --- # GitHub MCP for Claude Code: Setup Checklist Source: https://theaiarchitects.com/blog/github-mcp-claude-code-setup-checklist Published: 2026-07-03 A practical setup checklist for connecting GitHub MCP to Claude Code, including permissions, repo boundaries, review rules, and the first safe workflow. GitHub MCP is powerful because it lets Claude Code work closer to the place your software actually changes. That makes setup discipline more important, not less. The goal is simple: let Claude inspect issues, branches, pull requests, and code context without giving it a blank cheque over your business. ## Before you connect it - Decide which repositories Claude Code should see. - Use least-privilege access where possible. - Keep production secrets out of the repo. - Make branch protection and pull request review non-negotiable. ## The first safe workflow Start with read-heavy work. Ask Claude Code to summarize an issue, inspect the likely files, propose a fix, and draft a pull request description. Do not start with autonomous merges or production deployment. ## What to let it do next - Create small branches for isolated fixes. - Open pull requests with a clear verification note. - Comment on PRs with review findings. - Update documentation from merged implementation details. ## What not to automate yet Do not let a new GitHub MCP setup merge, deploy, rotate secrets, or rewrite shared infrastructure without human review. The mature version can automate more. The first version should make your review faster and better. > [CTA-BLUEPRINT] ## Related guides - [GitHub MCP for Claude Code (my setup)](/blog/github-mcp-claude-code) - [Claude Code MCP: Setup, Scopes & The 4 Servers I Use](/blog/claude-code-mcp) - [Best MCP servers for Claude Code (my stack)](/blog/best-mcp-servers-for-claude-code) --- # Is Claude Down? Check This Before You Debug Claude Code Source: https://theaiarchitects.com/blog/is-claude-down-before-you-debug Published: 2026-07-03 A simple outage checklist for Claude, Claude Code, the API, your network, and local project setup so you do not waste an hour debugging the wrong thing. When Claude Code fails, most people immediately start changing their setup. Sometimes the setup is fine. Claude is slow, the API is degraded, your account is rate limited, or the local command is waiting on a stale process. Use this checklist before you start reinstalling anything. ## 1. Check the visible symptom - If Claude.ai is not loading, treat it as a Claude service issue first. - If Claude Code starts but hangs mid-task, check status and rate limits before touching your repo. - If only one project fails, assume a local project issue until proven otherwise. ## 2. Separate Claude.ai from Claude Code Claude.ai, Claude Code subscription auth, and API-key usage can fail differently. A browser outage does not always mean the CLI is down. An API quota error does not always mean your Pro subscription is broken. ## 3. Check your account and usage - Look for usage-limit or quota messages in the terminal. - Confirm whether you are authenticated with a subscription login or API key. - If using API credits, check the console balance before debugging local files. ## 4. Check the local basics - Restart the terminal session. - Run Claude Code from a small folder, not your entire home directory. - Confirm Node and npm still work if the failure happens during install or command execution. ## When to stop debugging If multiple Claude surfaces are degraded, stop changing your local setup. Wait, or switch to planning work: write the issue, outline the fix, prepare the test cases, and run the implementation when the service is stable. > [CTA-BLUEPRINT] ## Related guides - [Claude Code Rate Limits and How to Stop Hitting Them (2026)](/blog/claude-code-rate-limits) - [How to Update Claude Code (and When You Don't Need To)](/blog/claude-code-update) - [Claude Chrome Extension Not Working? Fixes](/blog/claude-chrome-extension-not-working) --- # Claude Code Tutorial: The Only One You Need Source: https://theaiarchitects.com/blog/claude-code-tutorial Published: 2026-06-28 The Claude Code tutorial that skips the fantasy builds and shows the real mistakes, the real learning timeline, and the setup that makes it actually work. Learning Claude Code in 2026 is one of the most valuable skills you can build. It's also a fast track to burning through tokens and shipping absolutely nothing if you start the wrong way. I've been generating revenue through automation for eight years and using Claude Code on real client work every day since it launched. I've watched dozens of YouTube tutorials on this exact topic. Almost all of them are setting you up to fail. > [CTA-BLUEPRINT] ## What is Claude Code? https://youtu.be/BgXEz4b-fjw Claude Code is not a chatbot. It's a fully autonomous agent with full access to your computer. It can read your files, rewrite them, run commands in your terminal, and modify your database, all without asking permission if you configure it wrong. That distinction matters more than anything else in this tutorial. The regular Claude in your browser responds to prompts. Claude Code acts on your codebase. If you want the full beginner walkthrough, installation, configuration, first project, go read [how to use Claude Code](/blog/how-to-use-claude-code). This tutorial covers what actually breaks down for most people after the first week, and what to do about it. ## The real learning timeline nobody shows you Most Claude Code tutorials skip straight to the fancy commands and the big demo builds. That's how you end up frustrated, confused, and running out of tokens with nothing shipped. Before getting into the steps, here's the timeline you're actually in. Week one feels like a cheat code. You write prompts, code flies across your screen, you ship features faster than anything you've ever used. You're impressed. Week two is when reality arrives. You go back to add a feature to something you built the week before and Claude breaks half of it. You spend hours debugging Claude's own mistakes instead of building anything new. Week three hits your wallet. If you're on the Pro plan, you're probably hitting your weekly limits in two to three days. Max users are running out faster than they expected. Most of those tokens are going toward Claude debugging Claude's own mess. By week four, most people quit or jump to the next tool. The ones who push through are the ones who figured out three specific mistakes everyone makes in those first weeks. Then they stopped making them. ## The Claude Code tutorial walkthrough: fixing what breaks ### 1. Stop treating Claude Code like a chatbot The first mistake is giving Claude Code vague prompts the way you'd talk to ChatGPT. Commands like "fix the bug" or "change the button color" leave Claude guessing. Every guess is a chance to break something that was working yesterday. Treat Claude Code like a junior engineer who needs full context. Tell it the exact file path. Tell it what to do, what not to touch, and what the result should look like when it's done. This is why your [CLAUDE.md file](/blog/how-to-use-claude-code) matters so much. It's a file in your project root that Claude reads automatically at the start of every session. You write your tech stack, your conventions, the files you don't want touched, and you do it once. Claude follows it forever. Something you keep updating as your project evolves. ### 2. Use plan mode before Claude touches anything There's a feature most tutorials haven't shown you yet. It's called plan mode. Hit Shift+Tab inside Claude Code and you flip it into a mode where it cannot touch a single file. It has to plan first. Claude reads your codebase, lays out what it's going to do, shows you the file paths, and waits for your approval before touching anything. That one keystroke would have prevented the majority of the disasters in the comments section of every Claude Code video I've ever watched. If you're treating Claude Code like a chatbot right now, plan mode is your seatbelt. Check the [Claude Code commands reference](/blog/claude-code-commands) for a full breakdown of the keyboard shortcuts worth knowing. ### 3. Push back on the first answer Claude generates 500 lines of code and most people don't even scan it. If you're coming from a non-coding background, you hit accept and move on. That's the trap. Tests passing doesn't mean the code is correct. It just means the tests pass. Those are different things. Claude's first answer is a draft. Treat it like one. Check what files it touched, what it deleted, and ask why. Push back with questions like: what if the user is null here? What if the input is the wrong format? Show me the edge cases you didn't handle. Claude gets sharper every time you challenge it. The back and forth is where quality lives. Most people skip that part entirely. ### 4. Keep sessions focused on one goal Every message you send in a Claude Code session resends the entire conversation history. Your first prompt might be 2,000 tokens. By message 50, every prompt is costing five to ten times what the first one did. That's where your tokens disappear. Claude is rereading the entire history of your chat every single time. The common advice is to run `/compact`, which compresses your session into a summary. It's not the fix it sounds like. Compact replaces your full session with a brief summary, you lose the file paths, the line numbers, the exact decisions you made. Claude actually gets worse output, not lighter context. It's a band-aid for not wanting to start fresh. The real fix is simpler. One goal per session. When you're done with that goal, commit your work, run `/clear`, and start a new session. Fresh sessions are almost free. Bloated sessions cost you tokens and quality. ### 5. Audit your context for ghost tokens This is the one that costs money silently and nobody talks about it. There's a free token optimizer tool on GitHub that audits your Claude Code setup and shows you exactly where your context is leaking. It scans your CLAUDE.md file, your [hooks](/blog/claude-code-hooks), your [skills](/blog/claude-code-skills), your [MCP servers](/blog/claude-code-mcp), your output styles, and surfaces what it calls ghost tokens, the thousands of tokens injected into every prompt before you've typed a single word. I ran it on my own setup and I'm now saving 14% of my context window on every session. Somewhere between 15 and 20 million tokens a month, just from changing default settings. Most people are running a bloated config and have no idea. Combine the token optimizer with one goal per session and your Max subscription suddenly stops feeling like a Pro plan. You can find it linked from the [official Claude Code documentation](https://code.claude.com/docs/en/overview). ### 6. Build context into Claude's memory, not just your prompts The deepest problem with early Claude Code usage is context. When you open a fresh session, Claude knows nothing. It doesn't know your project, your business, your customers, or what you're trying to build. Context isn't a list of preferences in a settings file. It's everything Claude needs to behave like the senior engineer it actually can be: your tech stack, how your files are structured, your customers, your offer, your constraints. Without that spine, Claude behaves the same way for you as it does for every other user. That's not a model problem. That's a setup problem. The CLAUDE.md file is where this lives. Start building it on day one and keep adding to it as your project grows. The [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code) can extend that context even further by connecting Claude to live data sources it can actually use. > [CTA-BLUEPRINT] ## Claude Code tutorial FAQ ### What is Claude Code and how is it different from regular Claude? Claude Code is an autonomous AI agent that runs in your terminal with full access to your computer. Regular Claude in your browser is a conversational tool. Claude Code can read and rewrite files, run terminal commands, and modify databases without asking for confirmation unless you configure it to pause. ### How long does it take to get good at Claude Code? The real timeline is four to six weeks before Claude Code stops feeling unpredictable. Week one feels effortless. Week two and three are where most people struggle with broken builds and high token costs. The people who push through week four are the ones who build real applications with it. ### What is a CLAUDE.md file and why does it matter? A CLAUDE.md file sits in your project root and gets read automatically at the start of every Claude Code session. You put your tech stack, coding conventions, and rules for what Claude should and shouldn't touch. It's the single biggest lever for making Claude behave consistently across sessions. ### What is plan mode in Claude Code? Plan mode is activated with Shift+Tab inside Claude Code. It prevents Claude from editing any files until it has laid out a plan and you've approved it. Claude reads your codebase, lists the files it intends to modify, and waits for your go-ahead. It is one of the most important habits to build early. ### Why am I running out of tokens so fast? Every message in a Claude Code session resends the entire conversation history. By message 50, each prompt costs five to ten times the first one. The fix is one goal per session, running `/clear` when you're done, and running the token optimizer to remove ghost tokens from your setup configuration. ### What is the `/compact` command and should I use it? `/compact` summarizes your session into a compressed version to reduce context size. The problem is you lose file paths, line numbers, and the specific decisions made during the session. Claude's output quality drops. Starting a fresh session with `/clear` after committing your work is almost always the better move. ### Where can I learn Claude Code agents and hooks? The [Claude Code agents guide](/blog/claude-code-agents) covers how to run parallel agents and multi-step workflows. The [Claude Code hooks guide](/blog/claude-code-hooks) covers how to automate triggers before and after Claude actions. Both are worth reading once you've got the basics locked in. ## Sources and citations - [If You Only Watch One Claude Code Video, Make It This](https://youtu.be/BgXEz4b-fjw), Tom Crawshaw - [Claude Code overview, official documentation](https://code.claude.com/docs/en/overview) - [Claude Code common workflows, official documentation](https://code.claude.com/docs/en/common-workflows) ## Ready to set Claude Code up properly from day one? The blueprint I mention in the video is a free interactive course that runs inside Claude Code itself. You install it, open the folder, type "start lesson one," and Claude Code walks you through every step. By the end you have Claude Code installed, configured, and shipping, in under 60 minutes. Get the free blueprint at [/blueprint](/blueprint) and start lesson one tonight. --- # Claude Code Use Cases That Are Actually Insane Source: https://theaiarchitects.com/blog/claude-code-use-case-examples Published: 2026-06-27 Five Claude Code use case examples from a live demo: content repurposing, live dashboards, pre-call briefs, website builds, and invoice handling. The five Claude Code use case examples in this post come straight from a live walkthrough, each one is a real build you can adapt for your own business. I run these workflows myself, and one of my students used the same approach to replace a $30,000-per-year software tool. For the broader picture of what Claude Code can do, the overview post at [/blog/claude-code-use-cases](/blog/claude-code-use-cases) is the right starting point. This post goes one level deeper: here is each example, how the build actually worked, and what you need to replicate it. > [CTA-BLUEPRINT] ## What can you actually build with Claude Code? https://youtu.be/ACM_l3z05do Most people who pick up Claude Code build things that look impressive but do nothing useful in their business. The fix is not a better prompt, it is pointing the tool at real work. The five examples below are all things I either use daily or have watched students build and profit from. If you are still at the orientation stage, read [how to use Claude Code](/blog/how-to-use-claude-code) first, then come back here for the specific builds. This post is the companion to the [Claude Code use cases overview](/blog/claude-code-use-cases): that post gives you the map, this one gives you the worked examples. ## Use case 1: content repurposing pipeline The first example is a full content repurposing run in a single session. The starting point is a YouTube transcript. From that one input, Claude Code produces a LinkedIn carousel (eight slides, exported as a PDF for LinkedIn native upload), an X thread, an Instagram carousel, and short-form scripts for Instagram Reels, TikTok, and YouTube Shorts. The session used three skills in sequence: the content atomizer skill for drafting, an image-generation skill for creating platform-specific cover images, and the Blotato MCP for scheduling everything to go live. The key detail is the voice file. When Claude Code starts, it reads a `voice.md` file that contains my hook frameworks, sentence rhythm, and top-performing post examples. Without that file you get generic output. With it, the content actually sounds like you. The whole run, content, images, and scheduling across LinkedIn, X, and Instagram, took 26 minutes. The content atomizer asks one round of clarifying questions (which platforms, what goal) and then handles the rest. ### How the image skill works The image skill is not just asking the model to invent something. It holds references to my existing images that have performed well, extracts the visual formula from those, and then applies it to the new content. The skill also contains brand guidelines: colors, fonts, typography, layout spacing. The output is on-brand rather than generic. For the content repurposing run, this produced a LinkedIn image, an X thread image, and a carousel cover, all matched to the same post, generated in the same session. ## Use case 2: live business dashboard The second example is a revenue dashboard built inside Claude Code using two data sources: Stripe (via the Stripe CLI) and PostHog (via the PostHog MCP). The dashboard I built tracks workshop buyers, funnel stages (order bumps, upsells), revenue by traffic source using UTM parameters, and a UTM link generator for new campaigns. It also includes an affiliate link creator. The whole thing uses the same brand colors and typography as my website. What makes this useful is that no off-the-shelf analytics tool gives you the exact combination of data you need. PostHog handles web analytics; Stripe handles revenue. Claude Code can query both at the same time and build a single dashboard that shows exactly what you need to see. One of my students, Chris Cole, took this approach further. Chris is a civil engineer in California managing nine-figure government construction contracts. He built a reporting system in Claude Code that completely replaced a Microsoft Access tool his company was paying $30,000 per year for. You can read the full story in his [case study](/case-studies/chris-cole). He has since built similar tools for his own clients. ## Use case 3: automated pre-call briefs for sales The third example is an automation that generates a personalized sales brief for every prospect before a discovery call. The system works like this: when someone submits an application form, the data lands in Airtable. A script runs every couple of hours, scans for new applications, and generates a pre-call brief for each one. The brief is waiting in a folder by the time I sit down to prepare for the call. Each brief contains: - Who they are and a 30-second identity snapshot - What to open with - Discovery questions tailored to what they wrote in the application - Trial close language and offer bridge points - Things to watch for and key phrases that will likely resonate This is not a generic sales script. It is a custom script built from the specific words that person used when they applied. Reading it 10 to 15 minutes before the call puts me in the same position as a salesperson who spent an hour researching the prospect. You can adapt the brief template to your own sales process. The underlying mechanism is the same regardless of what sections you want: a script that watches an Airtable, pulls new rows, runs a prompt, and writes the output to a folder. For building automations like this, the [Claude Code agents](/blog/claude-code-agents) post covers the patterns in more detail. ## Use case 4: a live website from a Google Maps listing The fourth example is one of the most immediately commercial. It takes a Google Maps business listing with no website and turns it into a working HTML and CSS website in a single Claude Code session. The demo used a fish and chip restaurant in the UK that had 473 Google reviews, a 4.4 star average, and no website. The steps were: 1. Copy the Google Maps URL and open a new Claude Code session. 1. Enter plan mode (shift-tab in Claude Code) before starting the build. 1. Voice note the brief: build a local business site from this listing, heritage visual style, generate logo options. 1. Wait for the plan, Claude Code scraped the Google Maps listing using the Firecrawl MCP, pulled the menu items from a linked menu page, extracted photos from the reviews, and outlined the page structure before writing a single line of code. 1. Switch to auto mode and let it build. The output: a working local host site with a hero section using a photo from the listing, a full menu section, a reviews section with actual text from Google, directions, phone number, and a map embed. Claude Code also generated a logo. The plan mode step is the part most people skip, and it is the part that makes the difference in output quality. Jumping straight to build mode gets you something functional but rough. Running plan mode first forces Claude Code to gather all the data and outline the structure before it starts writing code. For businesses that do web development or SEO, this is a prospecting tool. Find a local business with no website, generate a working demo from their Google listing, and show up to the pitch with something live. For the [best MCP servers to pair with Claude Code](/blog/best-mcp-servers-for-claude-code), Firecrawl is one of the highest-leverage ones for builds like this. ## Use case 5: invoice processing and data extraction The fifth example is an invoice handling tool. The problem it solves: invoices arrive by email, you manually upload them into a tool, the tool extracts data, and then you copy it somewhere useful. Most businesses tolerate this because they assume they need dedicated accounting software for it. The demo showed a drag-and-drop web app built in Claude Code. You drop an invoice PDF into the app, it reads and scans the document, extracts the structured data (vendor, amount, date, line items), and writes the record directly to Airtable. The whole extraction takes seconds. The fully automated version goes further. Claude Code can run on a schedule to scan your email inbox every day, identify emails that contain invoice attachments, extract the attachment, scan it, and add the record to your database. No manual upload step, no separate tool subscription. The web app version shown in the demo is the right starting point if you want to stay in control of what gets processed. The fully automated version makes sense once you trust the extraction accuracy. Both are buildable in a single Claude Code session with the Airtable MCP connected. > [CTA-BLUEPRINT] ## Claude Code use cases FAQ ### What Claude Code use cases are best for non-technical users? Content repurposing and pre-call briefs are the two highest-return starting points for non-technical users. Both require minimal setup (a voice file and an Airtable, respectively) and deliver output you can use immediately without building anything complex. ### Can Claude Code actually build a website that looks professional? Yes, with the right inputs. The key is using plan mode before the build, giving Claude Code a visual direction (heritage, modern, minimal, etc.), and connecting the Firecrawl MCP so it can pull real content from the source listing rather than generating placeholder text. ### How does the content repurposing use case handle my writing style? A `voice.md` file in your project directory is what controls this. It holds your hook formulas, sentence patterns, examples of top-performing posts, and a blacklist of phrases to avoid. Claude Code reads it at the start of every session. Without it, you get generic copy. With it, the output matches your voice closely enough to publish with light editing. ### What does the pre-call brief automation actually need to set up? You need an Airtable base receiving your application form data, the Airtable MCP connected to Claude Code, and a prompt template describing what sections you want in the brief. Claude Code writes a Python or shell script that polls the base and generates a brief file for each new row. See [Claude Code commands](/blog/claude-code-commands) for how to run these on a schedule. ### Can I use these examples to build tools for clients? Yes, and this is how several students in the mentorship are making money. Chris Cole, for example, built reporting and workflow tools for his civil engineering clients using the same dashboard approach from use case two. The skills you build for your own business translate directly into client deliverables. ### Is the invoice processing use case accurate enough to rely on? For standard invoice formats, yes. The extraction accuracy depends on the quality of the PDF and how consistently formatted the invoices are. The recommended approach is to start with the manual drag-and-drop version, verify a few batches, then move to full email automation once you trust the output. ### What MCP servers are most useful for these five use cases? Firecrawl for web scraping (use cases 1 and 4), the Airtable MCP for database storage (use cases 3 and 5), the Stripe CLI for payment data (use case 2), and the PostHog MCP for web analytics (use case 2). The [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code) post covers setup for each of these. ## Sources and citations - Video: [Claude Code Use Cases That Are Actually INSANE (free template + tutorial)](https://youtu.be/ACM_l3z05do), Tom Crawshaw, The AI Architects - [Claude Code official documentation](https://code.claude.com/docs/en/overview), Anthropic - [Claude Code common workflows](https://code.claude.com/docs/en/common-workflows), Anthropic - [Chris Cole case study](/case-studies/chris-cole), The AI Architects ## Ready to build your first live agent? The five examples above are all things you can build in Claude Code today. If you want to go from watching to shipping, the [30-day AI Operator Challenge](/challenge) is the fastest path: structured builds, daily output, and a cohort working through the same problems at the same time. If you want the free foundation first, grab the [Claude Code Blueprint](/blueprint), a free interactive course that teaches Claude Code by having you actually use it. Download the files, open the folder, type "start lesson one," and Claude takes it from there. ## Related guides - [Claude Code for SEO: How I Ranked #1 on Google](/blog/claude-code-seo) --- # Claude Code for SEO: How I Ranked #1 on Google Source: https://theaiarchitects.com/blog/claude-code-seo Published: 2026-06-26 How I use Claude Code and the DataForSEO MCP to build a keyword-researched content cluster that ranks on Google, the exact 6-prompt SEO workflow. Yes, Claude Code can do SEO, and it does it better than most agencies charging thousands a month. I've been using Claude Code with the DataForSEO MCP to build a keyword-researched content cluster that's ranking on Google and getting cited by ChatGPT and Perplexity. This is the exact workflow. Six prompts. No guessing, no expensive SEO tools, no outsourcing. > [CTA-BLUEPRINT] ## Can Claude Code do SEO? https://youtu.be/IjEGrZMimdg Claude Code can't pull keyword data on its own, ask it for live search volumes and you'll get hallucinated numbers at best, outdated guesses at worst. But connect it to a real SEO data provider via MCP, and the whole picture changes. What an MCP (Model Context Protocol) does is give Claude Code tools that map directly to API calls. So instead of Claude guessing, it's querying live keyword data, search volumes, and SERP results and building your strategy from actual numbers. That's the unlock. ## The tool stack: Claude Code and DataForSEO MCP The MCP I use for this is from DataForSEO. They provide data for search engine results pages, keyword overviews, keyword ideas, backlink analysis, on-page SEO, domain analytics, and more. It's a well-known data provider in the SEO industry, and their MCP plugs directly into Claude Code. To install it, go to their integrations page and find the DataForSEO MCP. Method two is the recommended path: install it locally via NPM. You'll need your API username and password from their API access page (the username is a short alphanumeric string they email you, not your login email). Paste your credentials into the install command, make sure there are no extra spaces around the equal signs, and run it in your terminal. Once installed, tell Claude Code to add the MCP globally, then restart Claude Code. When it loads back up, you'll have access to the full DataForSEO toolkit: keyword overviews, keyword ideas, keyword suggestions, SERP organic results, on-page optimization, domain analytics, and content analysis. The whole suite is there. One dollar in DataForSEO API credits is hundreds of calls. I ran all my keyword research for the blog without topping up past the initial trial credit. ## The 6-prompt SEO workflow This is the workflow as I ran it. Six prompts in Claude Code, starting from a blank slate and finishing with a validated, competitive, clustered content roadmap. ### 1. Build your keyword research brief Prompt one is about getting clear on what you actually want to rank for. If you already know your niche and target keywords, you can skip this step. If you're starting from scratch, you voice-note or type your answers into Claude Code and it asks follow-up questions to build a brief. What it produces: a keyword research brief with your business described in one sentence, your target buyer described in one sentence, the top three buyer pains, and a set of seed keywords that map to how your buyers are actually searching. Some are problem-aware keywords. Some are solution-aware. ### 2. Expand your seeds into 80-plus keywords Prompt two takes your seed keywords and expands them into a candidate list. The filter is set to surface keywords with search volume above 100 per month for general keyword ideas, and above 200 for related keywords. You also get question-based variants of each seed. Claude Code fires these calls in parallel, spinning up sub-agents to hit the DataForSEO MCP simultaneously. When it came back on my run, it produced 58 keywords (not the 80 to 100 the prompt targets, so I ran a second pass). The second pass asks it to refocus on your specific audience and drop keywords that belong to competitors you can't beat. For my business, the keywords that had the most volume were clustered around Claude Code. That's my audience: people who want to get better at using Claude Code to build things. ### 3. See what AI search engines are actually surfacing Prompt three pulls LLM-era search data for each of your seeds. It also tries to identify the top 15 domains that LLMs cite most often when answering questions about your topic, and the 15 most-cited individual pages. On my run, the LLM-specific volume data was limited. But what it did surface was important: Reddit appeared for every single keyword in my niche. That makes Reddit a massive citation source and a legitimate part of any SEO strategy in this space. The prompt also surfaces four content format preferences for LLMs: Reddit threads, official documentation, Medium one-shot posts, and niche industry blogs. So if you want your content showing up in ChatGPT or Perplexity answers, those are the formats worth mimicking. ### 4. Find the gap and steal it Prompt four is the competitive analysis. It asks Claude Code to identify what your direct competitors are ranking for that you are not. On my run it came back with 275 gap keywords. The keyword difficulty scores on several of these were in single digits, I saw 1, 3, 7, 8, 12. Those are the ones worth targeting first. Low competition, real volume, already being ranked for by sites you can beat. One specific example I flagged: "Is Claude down right now?" gets searched constantly whenever the service has issues. Keyword difficulty was minimal. That kind of informational keyword is easy to rank for and drives consistent traffic. This is the kind of analysis that costs serious money in a traditional SEO tool. Here it ran in a few minutes via Claude Code sub-agents working in parallel. ### 5. Shape the strategy into a cluster Prompt five synthesises everything into an executive summary with a cluster overview table. A cluster is a group of 15 to 20 articles built around interrelated keywords that all support each other, linking internally to boost the authority of the whole group. This is the model I'm building on my blog right now. I started it last week. Every YouTube video I make turns into a full-length blog post on the same topic, then those posts interlink inside a keyword cluster. The cluster I planned out has 15 articles, each targeting specific long-tail keywords from the research. The posts are being written using a content writing skill I built specifically for SEO articles. The CMS is Sanity, hooked up to Claude Code, deployed via Vercel. Each post lands in a draft queue and publishes on a scheduled drip. ### 6. Save the full SEO strategy document The final prompt generates and saves the complete strategy file. It includes the discovery summary, executive summary, the cluster overview table, the gap keywords, the competitive domain analysis, and content priorities. This document is your working brief for writing every article in the cluster. When I ran this the output was saved as "SEO strategy V2" and updated the plan I'd built the week before. The six-prompt workflow takes you from no keywords to a competitive, clustered, data-validated content roadmap. Keyword research is the most important phase of the entire process. Get it wrong and you're writing articles that either can't rank or are too competitive to rank. Get it right and every article you write is targeted at a winnable keyword with real search volume. ## Claude Code SEO FAQ ### Does Claude Code know current keyword search volumes? No. Claude Code's training data has a knowledge cutoff and it does not have live access to search data. To get accurate, current keyword volumes and difficulty scores you need to connect Claude Code to a live SEO data provider via an MCP like the DataForSEO MCP. ### What is the DataForSEO MCP and how does it work? DataForSEO is an SEO data provider that offers an API for keyword data, SERP results, backlink analysis, and on-page SEO. Their MCP connects that API to Claude Code, giving Claude Code tools it can call directly instead of guessing. You install it locally via NPM using your DataForSEO API credentials. ### How much does the DataForSEO MCP cost to use? One dollar in DataForSEO API credits covers hundreds of API calls. I completed my full keyword research workflow for the blog without spending beyond the initial trial credit. For a workflow like this the API cost is negligible, which is the point: the data that used to require an expensive SEO subscription now costs cents. ### What is a content cluster and why does it matter for SEO? A content cluster is a group of blog posts built around interrelated keywords that all link to each other. Instead of writing isolated articles, you build 15 to 20 posts that reinforce each other's authority and signal to Google that your site is a comprehensive resource on a topic. It's the structure behind ranking for multiple keywords at once rather than just one. ### Can Claude Code do the full SEO workflow automatically? Claude Code handles the research and strategy phases well when connected to DataForSEO. It fires parallel sub-agents to run multiple API calls simultaneously, which speeds up keyword expansion and competitive gap analysis significantly. The writing phase is separate and benefits from a dedicated SEO writing skill configured for your voice and blog format. ### Do SEO signals help with ChatGPT and Perplexity citations too? Yes. The same signals that help you rank in Google are what LLMs like ChatGPT and Perplexity pull from when answering questions in your niche. Reddit, official documentation, Medium, and niche industry blogs are the four content formats LLMs prefer to cite. If your content follows the same structure and authority signals, it shows up in AI search answers, not just Google. ### What kind of website setup does this workflow assume? I run a Next.js site with Sanity as the CMS, deployed on Vercel. Sanity is connected to Claude Code so posts can be generated and piped directly into the content management layer. That setup is not required, the keyword research and strategy workflow works regardless of your tech stack. ## Sources and citations - Tom Crawshaw, "Claude Code Helped Me Rank #1 on Google SEO (COPY ME)": https://youtu.be/IjEGrZMimdg - Claude Code overview and documentation: https://code.claude.com/docs/en/overview - Claude Code MCP configuration: https://code.claude.com/docs/en/common-workflows ## Ready to build your own SEO system with Claude Code? If you want to start using Claude Code for tasks like this, the Claude Code Blueprint walks you through the fundamentals from scratch. You install Claude Code, open the folder, and Claude teaches you live inside the tool while you use it. By the end you'll have shipped a real application, learned how to configure your CLAUDE.md file, and run parallel agents inside Claude Code. Get the Blueprint at [/blueprint](/blueprint) and get started today. If you're looking to go deeper on Claude Code's capabilities, these posts cover the adjacent ground: how to [get started with Claude Code end-to-end](/blog/how-to-use-claude-code), the [skills and slash commands system](/blog/claude-code-skills), [custom Claude Code commands](/blog/claude-code-commands), and the [best MCP servers worth adding to your setup](/blog/best-mcp-servers-for-claude-code). If you want to see what else Claude Code can be used for beyond SEO, the [Claude Code use cases rundown](/blog/claude-code-use-cases) covers a range of real applications. --- # How to Learn AI in 2026: My Unfiltered Advice Source: https://theaiarchitects.com/blog/how-to-learn-ai-2026 Published: 2026-06-26 Stop consuming tutorials and start building. Here's my honest advice on how to learn AI in 2026, based on 10 years of building automation systems. Stop consuming and start building. That is the single most important thing I can tell you about how to learn AI in 2026, and most people are getting it exactly backwards. Over the last 10 years I've built automation systems that have generated millions of dollars in revenue for clients. I've also learned guitar, music production, skydiving, content creation, and now AI automations from scratch. Every single one started with months of being terrible at it, and every single one followed the same pattern. This is not a tutorial. It's the advice I wish someone had given me upfront, delivered without the sugar-coating. > [CTA-BLUEPRINT] ## How should you learn AI in 2026? https://youtu.be/y77ds0P70mg Pick one tool, open it, and start building something today. Not after the next tutorial. Not once you feel ready. Today. If you can use [Claude Code](https://www.anthropic.com/claude-code) to build even a basic automation around a problem you actually have, you will learn more in that one session than in five hours of watching someone else do it. The experience you get from breaking things and fixing them is irreplaceable, and AI gives you an on-demand co-pilot for every moment you get stuck. If you're coming from a tech background with API and workflow experience, the leap to building AI automations is a short one. If you're starting from casual ChatGPT use, the curve is steeper but the principle is the same: you need reps, not more content. The people making real progress today are the ones who were willing to start long before they felt ready. ## The real reason you're not seeing results The biggest problem I see in this space is not lack of talent and not lack of motivation. It's a total lack of follow-through. You probably know the pattern. You see something online, you get excited, you buy the course or watch the tutorial, you feel that dopamine hit from starting, and then things get hard. The learning curve shows up, you're not immediately good at it, and that uncomfortable gap between where you are and where you want to be starts to feel like a sign that it's not working. It's not a sign. It's just what learning feels like. The people who actually get good at these tools are the ones who can stay in that uncomfortable zone the longest. They are not more talented. They have just accepted that sucking at something is the price of admission, and they keep showing up anyway. ## Principle 1: Follow-through is the whole game Most people don't fail because they lack ability. They fail because they quit during the period where they haven't yet earned the feedback that would keep them going. You spend two weeks struggling with [Claude Code](https://www.anthropic.com/claude-code) or n8n, you don't see any clients or results, and you decide this probably isn't for you. Then you reset to zero and start over with the next thing. The trap is that every time you quit and restart, you're a beginner again. The compounding you built up vanishes. You end up in a cycle of shiny objects where you know a little bit about a lot of things and aren't useful with any of them. My recommendation: before you start, ask yourself honestly how long you're willing to see no results before you reach your goal. Then multiply whatever number came to mind by three. That's the real timeline. ## Principle 2: Results lag your effort by months This is something I learned the hard way with this YouTube channel and with posting on X. I posted my first video and then spent six months posting into the void before I had a video hit 10,000 views. Same on X. Six months of near silence before I figured out how to write posts that actually spread. I now have millions of views and over 27,000 followers on X, but none of that was visible during those early months of grinding. Every new skill and every market follows this exact delay pattern. You put effort in, and the feedback comes back weeks or months later. Most people are giving up right before the curve turns. And the brutal reality is: if you don't keep going, you never see the fruits of your labor. Take whatever timeline you think learning AI is going to take, and triple it. Think realistically about how much time you're prepared to invest before you see $10,000 a month, or before your automation is running reliably in production, or before your boss stops thinking of you as just an employee and starts thinking of you as the AI person. That extended timeline is not a problem. It's just how learning works. ## Principle 3: 15 minutes a day beats everything Consistency is absolute king. You do not need to cram five hours into a Saturday session to make progress. What you need is to touch the work every single day, even for 15 minutes. The reason this matters is familiarity. If you leave something six days before you come back to it, so much has happened in your brain in the intervening time that you can barely remember where you left off. Your previous session's context is gone. You spend the first half of your next session just re-orienting. Whereas if you open the same project every single day, even briefly, the context stays fresh and you can push things forward immediately. Here is the practical version of this principle: 1. Block 15 minutes in your calendar, the same time every day, labelled "build time." 1. Open the project, not a tutorial, the project. 1. Talk to Claude, describe what you're trying to do, and take the next step. 1. If you hit a wall, ask Claude Code or Claude.ai to help you debug it. 1. Stop when the time is up, even if you're mid-flow, so the habit stays fixed. Small daily actions that compound over weeks and months will give you better results in the long run than sporadic intense sessions. You might not notice the progress day to day, but look back after one month and the improvement will be obvious. One of my students, Cal, spent four months consistently building inside the mentorship. In the early days he wasn't chasing fast results. He accepted that roadblocks were part of the process, he kept showing up, and he came out the other side as a genuinely competent builder. He automated the core process in his job, presented it to management, and they were so impressed they put him on a larger project worth potentially tens of millions of dollars of annual impact. You can read more about how Cal did it in the [case study here](/case-studies/cal-hewitt). ## Principle 4: Keep it simple, pick one thing Right now there are more AI tools than any one person can keep track of. Claude Code, Lovable, Codex, Cursor, n8n, a dozen different image models, video generators, the list adds a new entry every week. If you're deep in the AI space the way I am, it can feel like your job is to test all of them. It is not. The trap is trying to keep up with everything. You end up knowing a little bit about 18 different tools and being genuinely useful with none of them. In my eight to nine years working in the automation space I've watched the specific tools change five, six, seven times. What has not changed is the methodology: identify a problem, choose one tool, build a solution, test it, debug it, put it in production. That process transfers across every generation of tooling. The specific syntax changes. The thinking does not. So here is the instruction: find one problem or create a fictitious scenario, pick one tool with one LLM, and build the simplest possible solution. Do not start with the perfect use case. Do not wait until you have the ideal client or the best workflow idea. If you're just starting out and don't have a real problem to solve yet, make one up. In my [Claude Code 30-day challenge](/challenge), I give students a fictitious company scenario with real processes to automate, because waiting for the perfect real-world use case is just another way of not starting. This is also the key advice for anyone feeling overwhelmed by the pace of AI news: you do not need to be on top of every new tool or feature release. You just need to be doing the work and moving forward. See [Claude Code use cases](/blog/claude-code-use-cases) and [Claude Code tips](/blog/claude-code-tips) for ideas on where to start. ## Principle 5: Ship ugly The creator of one of the fastest-growing open-source AI projects publicly said he ships code he doesn't even read. He builds it, ships it, and moves on. That is a signal worth paying attention to. Your first automation is going to be messy. It will probably break. That is completely fine. An ugly working tool you can actually use is always better than a perfect idea sitting in your head. Nobody cares how many nodes are in your n8n workflow or how many hours you spent debugging it. People care about what it does, what problem it solves, and what the results are. Speed of execution matters more than perfection in a fast-moving space. You learn more from a broken live automation than from a perfect theoretical one. Stop trying to be a perfectionist before you even get started. Build something that works, ship it, and fix it in the next iteration. Perfectionism is just procrastination with better branding. If you try to get things perfect every single time, you will fall behind. Once you're comfortable with the basics of Claude Code, check out [Claude Code agents](/blog/claude-code-agents) and [the best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code) to see how far you can extend what you build. ## Principle 6: The window is open right now, not forever Some people still think AI is a passing fad. It is not. This is the new reality of how businesses operate, and the people who start building now are going to have a compounding advantage over the people who wait. Only 16 to 20 percent of the global population has interacted with generative AI tools. That means the majority of the market, including your clients, your employer, and your competitors, have not yet internalized what these tools can do. That gap is an opportunity. But the window is not going to stay open at this size. The percentage of active AI builders is going to shift massively over the next 12 to 24 months. Six months ago we didn't have Claude Opus 4 or Claude Sonnet 4. Six months in AI is a huge amount of time. Waiting for the right moment means you're already behind. The barrier to entry right now is lower than it has ever been. A Claude subscription costs around $20 a month. You need nothing else to start building real tools that solve real problems. The moment you start building consistently, your sense of what's possible with these tools will expand rapidly. You'll go from "I don't know where to start" to having more ideas than you have time to build. And when that happens, you go through the same process again: simplify, pick one thing, stay consistent. Start with [how to use Claude Code](/blog/how-to-use-claude-code) if you want the foundational guide, and when you're ready to explore more advanced patterns, see [Claude Code agents](/blog/claude-code-agents). ## Six principles for learning AI in 2026 To make this concrete, here is the condensed version of everything above: 1. Stop consuming and start building. Watch one tutorial to get oriented, then close it and build. 1. Accept that the first few weeks will feel frustrating and confusing. That is normal, not a signal to quit. 1. Commit to 15 minutes every single day, not five hours every Saturday. 1. Pick one tool and one problem. Build one simple solution, test it, and ship it. 1. Ship ugly. A working messy tool beats a perfect idea every time. 1. Start now. Waiting for the right moment is a form of procrastination, and AI moves too fast for it to pay off. > [CTA-BLUEPRINT] ## Learning AI in 2026 FAQ ### How long does it take to learn AI in 2026? Expect it to take longer than you think. Results typically lag behind effort by 30 to 90 days, sometimes more. A realistic timeline for going from beginner to useful with tools like Claude Code is three to six months of consistent daily practice. The people who get there faster are usually not smarter, they just started sooner and stayed consistent through the uncomfortable early period. ### Do you need a technical background to learn AI tools? No, but your starting point affects the shape of the learning curve. If you come from a background with APIs, automation tools like Zapier, or email marketing platforms, you'll find tools like n8n and Claude Code feel like a natural extension. If you're starting from casual ChatGPT use, the curve is steeper but still very manageable. The methodology is the same regardless: pick one thing, build it, ship it. ### What is the biggest mistake people make when learning AI? Spending more time consuming content about AI than actually using AI. Tutorials give you a walkthrough you can copy. They do not give you the experience of solving your own problem, hitting a wall, and debugging your way through it. That experience is where the actual learning happens, and it only comes from building. ### Which AI tool should I learn first? Start with Claude Code if you want to build real tools and automations, particularly if you want to work with code and deployable projects. It has the best reasoning capability of any model I've used, and the [Claude Code documentation](https://code.claude.com/docs/en/overview) covers the common workflows clearly. If you want to start with visual workflow automation, n8n is the other tool I'd recommend first. ### How do you stay consistent when you're busy? Block 15 minutes in your calendar and protect it. You do not need an hour. You do not need to dedicate your Saturday mornings to this. Fifteen minutes a day, five days a week, compounds faster than you expect. The key is making it a daily habit rather than a weekly binge. Daily contact keeps the context fresh and lets you push things forward in small increments. ### Is it too late to start learning AI in 2026? No. Only 16 to 20 percent of the global population has interacted with generative AI tools. The majority of businesses, employers, and markets have not yet integrated AI at any meaningful level. The window for early movers is still open. Six months from now the competitive landscape will look different. The best time to start is now. ### What should I build first when learning Claude Code? Build something you actually need, or make up a realistic scenario if you don't have a clear real problem yet. A simple automation that saves you time on a repetitive task is the best starting point. It doesn't need to be impressive. It needs to work well enough that you can use it and see the result of your effort. The [Claude Code use cases](/blog/claude-code-use-cases) post has concrete examples of what's possible at different skill levels. ## Sources and citations - Tom Crawshaw, "My Unfiltered Advice for Anyone Learning AI in 2026" (YouTube): https://youtu.be/y77ds0P70mg - Anthropic Claude Code overview: https://www.anthropic.com/claude-code - Claude Code official documentation: https://code.claude.com/docs/en/overview - Claude Code common workflows: https://code.claude.com/docs/en/common-workflows ## Ready to stop watching and start building? The fastest way to learn AI in 2026 is to get in the work every day, even for 15 minutes, with a specific project and a specific tool. If you want a structured path through that, my [30-day Claude Code challenge](/challenge) gives you real scenarios to build against, weekly calls, and accountability from people going through the same process at the same time. Or if you want the free starting point, the [AI blueprint](/blueprint) covers the framework I use with every student before they write a single line of code. Do the hard thing. Commit. The window is open. ## Related guides - [AI Statistics 2026: Adoption, Agents, and ROI](/blog/ai-statistics-2026) - [How to Succeed in AI Without Grinding 24/7](/blog/succeed-in-ai-without-grinding) --- # Hermes Agent: A Beginner's Guide Source: https://theaiarchitects.com/blog/hermes-agent Published: 2026-06-26 Hermes Agent is an open-source self-hosted AI agent that learns your habits, builds reusable skills, and runs 24/7 on a VPS, here's how to get started. Hermes Agent is an open-source, self-hosted AI agent framework that runs on a VPS or your local machine, connects to your AI model of choice, communicates with you through Telegram, and gets smarter with every session by building reusable skills and persistent memory. I spent the last month using it alongside Claude Code, and the difference compared to OpenClaw, the other open-source agent that got all the hype earlier this year, is real. OpenClaw had a moment. It was one of the fastest-growing GitHub projects for a while, and people were calling it the open-source agent that would change everything. It didn't quite get there. Hermes is what OpenClaw should have been: ten times easier to set up, more secure out of the box, and built around a context system that actually remembers how you work across sessions. If you've been curious about running your own always-on AI agent, this is the one worth trying. > [CTA-BLUEPRINT] ## What is Hermes Agent? https://youtu.be/JQLWy96Ax5c Hermes Agent is an open-source AI agent you install on your own machine or a VPS, connect to a large language model (like OpenAI Codex), and control through Telegram. Unlike a chat interface you open in a browser, Hermes runs continuously in the background. You can text it at midnight from your phone, set it to run reports on a schedule, and wake up to the results, even with your laptop closed. That always-on capability is the whole point. The key features that separate it from a standard coding agent are its persistent memory (it writes down what it learns about you so it never has to ask twice), its `soul.md` personality file (you define the character and context of your agent), and its skill system (it creates reusable workflows from repeated actions over time). It has overtaken OpenClaw in GitHub stars and community interest, and there is an official desktop app available if you prefer not to use the terminal. ## Why Hermes beats OpenClaw OpenClaw required significant VPS hardening to run safely. Hermes is more secure out of the box, the setup process required far less configuration to get to a stable, usable state. The installation is also faster and more guided, with a `hermes setup` command that walks you through API key connection, model selection, communication platform, and browser/image/search tool options in a single flow. The other meaningful difference is how each handles context. People frequently complain that AI agents forget what they know between sessions. Hermes addresses this directly with two mechanisms: a `soul.md` file that stores the agent's personality and baseline context, and a persistent memory system that writes down facts about you as you interact. After a single session, Hermes had my name, my business, my audience size, and the structure of my content folders saved to memory, and it referenced those automatically in the next request without being asked. That is the context engineering fix that most agentic tools still get wrong. ## How to install Hermes Agent Installation works on Mac, Linux, and Windows via a terminal command. If you want a desktop app experience, they released one recently, it is roughly equivalent to having a dedicated interface for your agent rather than running everything through a terminal window. The important decision upfront: do you want Hermes to run 24/7, even when your laptop is closed? If yes, you need a VPS. When your laptop shuts down, so does Hermes. A VPS stays on. ### 1. Install Hermes Run the terminal installation command for your OS (Mac/Linux command or the Windows equivalent). This installs Hermes on your machine or server. If you are deploying to a VPS, the steps are the same as local, you just run them in the VPS terminal rather than your own. ### 2. Run the full setup Type `hermes setup` and choose the full setup option so you can supply your own API keys and configure each component: - **AI model:** Connect your own OpenAI Codex account (or another supported model). Hermes also has an optional plan to use their own hosted API if you prefer not to manage model credentials yourself. - **Communication platform:** Choose Telegram. It is the easiest to configure and means you can talk to your agent from your phone. - **Browser, image, search tools:** You configure these during setup. Brave Search works without an additional API key. Image generation and voice are optional and can be enabled later. ### 3. Set up your Telegram bot Open Telegram, search for BotFather, and create a new bot. Give it whatever name you want. Copy the bot token, then run `hermes gateway setup` in your terminal and paste the token in. You will also need your Telegram user ID, the BotFather can return this via a `get user ID` bot command. Add that ID as an allowed user and set up your home channel. ### 4. Connect Tailscale (optional, but recommended for VPS users) If you want your Hermes agent on a VPS to read and write files on your actual computer, connect the two with Tailscale. You will need a free Tailscale account, an auth key from their admin console, and your machine name and folder path. You can give this information directly to Hermes as a prompt and it will handle the installation and configuration, it ran the Tailscale install on the VPS and connected to my laptop's files through a single prompted request. ### 5. Log in and verify the connection Run `hermes login` to authenticate. Open Telegram, find your bot, and send a test message. If the gateway is not running, ask Hermes directly why Telegram is not connected, it will diagnose and fix the issue on its own. ## Giving your agent a soul and memory Once Hermes is running, the first thing worth doing is defining who your agent is and what it knows about you. Hermes uses a `soul.md` file to store the agent's personality. This is where you set tone, character, and operating instructions, things like "talk to me like a human, not a chatbot" or "when you learn how I work, write it down so you never have to ask twice." After setting the soul file, tell Hermes a bit about yourself and instruct it to save the information to memory. It will store this in a persistent memory file and reference it across future sessions. In the demo session I walked through, Hermes scanned my content folders via Tailscale and automatically indexed key documents, including a `voice.md` style guide, without being asked to do more than "scan this folder." It then suggested building a lightweight index of the whole vault. That kind of proactive context-building is where it starts to feel different from a standard coding tool. ## What Hermes can do in practice Once setup is done and memory is loaded, here is what a working session looks like: **Content creation with file access.** I asked Hermes to scan my YouTube hooks folder, pull the hacks listed there, and write separate X posts for each one with three hook options per post. It accessed the files via Tailscale, read the content, generated the posts, and saved markdown files back to my computer, visible in Obsidian immediately. The hooks it produced were reasonable, though not at the level of a tuned custom skill. The next step would be pointing it at a content creation skill file to run the drafts through. **Parallel sub-agents.** I asked it to spin up three simultaneous research agents: one to find the top Hermes Agent videos on YouTube with view counts, one to pull the latest Anthropic releases from the past 14 days, and one to find what people were saying about Hermes on X. It launched all three, returned results from each, and flagged where data was limited (X without an API key returns little). For the X research gap, it pointed to a "last 30 days" skill available for Hermes that hooks up to the X API. **Scheduled tasks.** I set a recurring schedule: every morning at 9am, pull the top five traction sources from Reddit and Google around Claude, Anthropic, AI agents, Hermes, and Codex, and send me a report on Telegram. Because this runs on a VPS, the schedule fires whether my laptop is on or not. This is the core use case, automated reports, daily briefs, monitoring, delivered to your phone without any manual action. **Importing Claude Code skills.** I asked whether Hermes could pull my existing Claude Code skills from my laptop and install them. It found my skills folder via Tailscale, copied the active skills into Hermes, and even created a new reusable skill based on what it had learned during the session. If you are already running Claude Code and have invested time building custom skills, you can carry those over. This kind of work sits in the same territory as [Claude Code agents](/blog/claude-code-agents) and [Claude Code use cases](/blog/claude-code-use-cases), the difference is Hermes puts the agent on a server that runs when you are not at your desk. ## Where Hermes falls short The content output, without a tuned skill, is competent but not remarkable. The hooks it generated for social posts were described as "reasonable", usable, but not at the level you would get from a purpose-built content workflow like a [custom Claude Code skill](/blog/claude-code-skills). That gap closes as you train the agent with better context and dedicated skill files. The Tailscale setup is the most technically involved part. The video covers it at a high level and defers to Hermes itself for the detailed configuration, which works, but means the setup requires more back-and-forth than a simple install. The transcript also mentions some hiccups during initial configuration (the Telegram gateway not starting, the soul.md file not being written on the first attempt) that required additional prompting to resolve. This is early-stage software and you should expect some friction. Sub-agent results without the right API connections are limited. The X research came back thin without an X API key, and YouTube research returned the hook angle rather than the literal hook text. These are solvable but require additional setup time. For context on how Hermes compares to Claude Code's own approach to agents, [this guide to Claude Code](/blog/how-to-use-claude-code) covers the foundations, and the [MCP servers guide](/blog/claude-code-mcp) covers how Claude Code handles external tool connections in a way Hermes handles natively through its tool setup wizard. ## Verdict: is Hermes Agent worth it? Yes, with the right expectations. If you want an AI agent that works while you sleep, learns your habits over time, and lives in your Telegram DMs, Hermes delivers on that promise better than anything else currently available at this level. The VPS requirement is a real cost and a real setup commitment, but once it is running, the always-on capability is the thing that makes it genuinely different from a chat tool. I will keep using Claude Code as my primary daily driver, it is embedded in my workflow and the skill system is built around how I actually work. But Hermes on a VPS fills a different slot: background research, scheduled reports, tasks you want to fire off from your phone at midnight and find done by morning. Those two tools are not competing for the same use case. The comparison to consider is not Hermes vs. Claude Code, it is Hermes vs. doing nothing while your laptop is closed. On that comparison, Hermes wins easily. > [CTA-BLUEPRINT] ## Hermes Agent FAQ ### What is Hermes Agent? Hermes Agent is an open-source, self-hosted AI agent framework. It connects to a large language model of your choice, communicates with you through Telegram, and runs continuously on a VPS or local machine. It is designed to perform tasks autonomously, learn your habits over time, and build reusable skills from repeated actions. ### How is Hermes Agent different from OpenClaw? Hermes is significantly easier to set up than OpenClaw, requires less VPS hardening for security, and has a more developed context system including persistent memory and a `soul.md` personality file. I switched from OpenClaw to Hermes after finding Hermes more stable and better at maintaining context across sessions. ### Do I need a VPS to use Hermes Agent? You can install Hermes locally without a VPS, but you will lose the always-on capability. When your laptop closes, Hermes stops. A VPS keeps Hermes running 24/7, which is what enables scheduled tasks, overnight reports, and Telegram access from anywhere. Any standard VPS works for this. ### How does Hermes Agent learn and remember things? Hermes uses two systems: a `soul.md` file that stores persistent personality and context, and a memory file that records facts about you across sessions. As you use it, it writes down information you share so it does not need to ask again. Over time, it also creates reusable skill files from repeated workflows. ### Can I use my existing Claude Code skills with Hermes Agent? Yes. If you have existing skill files from Claude Code and your laptop is connected via Tailscale to your Hermes VPS, you can ask Hermes to find and import those skills. In the demo, it located the Claude Code skills folder, copied the active skills into Hermes, and created a new skill from the workflow it had just learned. ### What models can Hermes Agent use? The demo connects Hermes to OpenAI Codex using an OpenAI account. Hermes also offers its own hosted API plan if you prefer not to manage model credentials. The setup wizard lets you choose your model and backend during initial configuration. ### Is Hermes Agent secure? In my testing Hermes required significantly less VPS hardening than OpenClaw, and it felt noticeably more secure out of the box. That said, any self-hosted agent running on a server with access to your files introduces surface area, standard VPS security practices still apply, and you should do your own research before giving it access to sensitive directories. ## Sources and citations - The Ultimate Beginner's Guide to Hermes Agent (Tom's AI Growth Lab, YouTube): https://youtu.be/JQLWy96Ax5c - Claude Code official documentation, overview: https://code.claude.com/docs/en/overview - Claude Code common workflows: https://code.claude.com/docs/en/common-workflows ## Ready to build agents that actually work for your business? Hermes is one way to run an always-on agent, but the foundation underneath it is knowing how to drive a coding agent in the first place. My free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required, so you have the skills to set up and direct tools like Hermes with confidence. Get the [Blueprint](/blueprint) and start building. ## Related guides - [OpenClaw: 95% Cheaper Than Claude Code (Real Setup)](/blog/openclaw-95-percent-cheaper-than-claude) --- # Claude Code Tips: 10 Hacks From 1,000 Hours In Source: https://theaiarchitects.com/blog/claude-code-tips Published: 2026-06-26 10 Claude Code tips from 1,000 hours of real use: auto mode, plan mode, Superpowers plugin, CLAUDE.md, token optimizer, and more. Claude Code tips are the specific settings, tools, and habits that separate people who ship working systems from people who treat it like a chat window. Most users never configure any of this, and it shows in their results. I'm Tom. I've spent close to 1,000 hours inside Claude Code, mentored over 50 students through the build process, and watched the same gaps show up again and again. The people who actually get things done all set Claude Code up the same way. Everyone else just types prompts and hopes. This post covers the 10 hacks I use on every build, starting with the ones you can install in under a minute. > [CTA-BLUEPRINT] ## What are the best Claude Code tips? https://youtu.be/u7efw7JkR8U There are two types of Claude Code users right now. The first type sits there clicking approve on every single permission, one at a time. The second type runs everything on auto mode and lets Claude build while they get on with something else. Six months ago, clicking every permission was normal. Today, there is no reason to work that way. These 10 tips are how you move from the first group to the second. If you are new to Claude Code, start with the [beginner's guide to Claude Code](/blog/how-to-use-claude-code) first. Once you have the basics down, come back here and add these on top. ## The 10 Claude Code tips ### 1. Turn on auto mode Auto mode is the single biggest productivity unlock in Claude Code. When it is on, Claude executes your tasks without stopping to ask permission for every file read or command. You are not giving up safety to get this. Auto mode has specific guardrails built in. Claude cannot execute certain commands, and you can add your own rules to tighten it further. It blocks dangerous operations automatically. To enable it in the terminal, press **Shift+Tab** to cycle through modes. In the Claude Code desktop app, click the dropdown at the bottom of the screen. Once you see auto mode is on, you will never go back to clicking approve one permission at a time. ### 2. Use plan mode before every build Plan mode is accessed the same way as auto mode: press **Shift+Tab** in the terminal to find it. A lot of people skip this, and it is one of the most expensive mistakes you can make with Claude Code. When you give Claude a task and let it run without a plan, it will come back confidently with results. That does not mean those results are right. If Claude builds the wrong thing, you will burn a large number of additional tokens fixing bugs and unwinding work that a two-minute plan would have prevented. In plan mode, Claude cannot build anything. Its only job is to produce a plan and get your approval. Once you review and sign off, Claude gives you the option to execute in auto mode, hands-free. This is the correct workflow: plan first, then build. ### 3. Continue sessions remotely with `/remote-control` Have you ever been in the middle of a Claude Code session and needed to step away? You do not have to lose the context. Type `/remote-control` in the terminal and Claude will generate a link. When you pick up your phone and open the Claude app, you will see a remote control notification connecting directly to the session running on your machine. You can continue the conversation from the back of a taxi or anywhere else. The same command works in the desktop app. ### 4. Install the Superpowers plugin The Superpowers plugin is the best build tool I have come across, and I have tried several. It gives Claude Code 14 skills and one hook out of the box. The ones I use most often are brainstorming, writing plans, subagent-driven development, code review, executing plans, and dispatching parallel agents. The workflow it enables looks like this: 1. Brainstorm the idea (Superpowers asks clarifying questions and builds context) 1. Write an implementation plan based on the brainstorm output 1. Sign off on the plan 1. Superpowers dispatches multiple parallel sub-agents to execute the plan simultaneously 1. A live checklist on screen shows which tasks are in progress and which are done To install it in the desktop app, go to Customize, then Browse Plugins, and search for Superpowers. If it does not appear in search, the terminal fallback is `/plugin install superpowers`. Once installed, you do not need to use the slash command every time. Say "let's brainstorm this" or "create a plan" in any session and Superpowers will pick up the keywords and invoke the right skill automatically. You can read more about building with [Claude Code agents](/blog/claude-code-agents) to understand how the parallel execution works. ### 5. Build a CLAUDE.md file using Karpathy's four rules A CLAUDE.md file is a set of instructions that Claude reads before it does anything inside your project. It is how you bake your standards and context directly into every session, so you are not re-explaining yourself from scratch each time. Andrej Karpathy, one of the founders of OpenAI, published a minimal CLAUDE.md template built around four rules that I now include in every project: 1. **Think before coding.** Do not assume. Surface trade-offs. Flag confusion rather than hiding it. 1. **Simplicity first.** Use the minimum code that actually solves the problem. Nothing speculative. 1. **Surgical changes.** Touch only the files you need to touch. Six months ago, Claude would routinely edit files you never asked it to change. This rule keeps it on task. 1. **Goal-driven execution.** Define the success criteria, then keep iterating until the goal is verified. This connects to Claude Code's `/goal` command, which lets Claude work and keep going until a defined criterion is met. If you already have a CLAUDE.md file and want to add these rules without losing what you have, paste them in and ask Claude to merge them with your existing file. For a deeper look at how to structure this, see the post on [Claude Code memory](/blog/claude-code-memory). ### 6. Turn your repeatable processes into skills Skills are reusable slash commands that encode your own workflow. If you do the same multi-step task repeatedly, there is a skill for it. Instead of manually walking through the same process every time, you invoke the skill and let it run. I have a content-creator skill that takes a YouTube transcript, generates 20 to 30 hook variations using my own hook frameworks, scores each one on four criteria using direct response marketing principles, and then writes body content once I pick a hook. I also have an AI image factory connected to fal.ai with the OpenAI image model. I gave Claude a folder of ads and posts that performed well, had it analyze them, and had it produce image recipes for my social media content. The skill pulls from those recipes and generates five or six image variations per session. There is a built-in skill creator in the desktop app from Anthropic. Ask Claude to use the skill creator skill to help you write your own. Generic skills you download from the internet often get deleted because they lack your personal context. Skills built around your own process are the ones that actually stick. The [Claude Code skills](/blog/claude-code-skills) post covers this in more detail. ### 7. Use WhisperFlow to speak your prompts WhisperFlow is a voice-to-text tool that types at whatever speed you talk. I talk at 108 words per minute, which is faster than most people type. In WhisperFlow I have dictated over 681,000 words. It fixes grammar and spelling as it transcribes. The shortcut is **FN+spacebar** on Mac. A recording bar appears at the bottom of the screen. You talk, you press FN again to stop, you click where you want the text to land, and it appears. Maximum recording length is 6 minutes per clip. If you are in an office and do not want to speak aloud, plug in headphones and whisper into your mic. That is literally why it is called WhisperFlow. You get the productivity gains either way. ### 8. Install the token optimizer When you start installing skills and MCPs, your context window gets heavier. Every session starts with Claude loading all your skills and MCP tools, and then reading your CLAUDE.md file on top of that. Some of my students start sessions at 15% context used before they have typed a single word. I try to clear and create a handoff file around the 35 to 40% mark, because past that point you are burning tokens at a much higher rate without getting better output. The token optimizer is a skill that shows you: - Your total session overhead before you start - Which skills and MCPs you have installed but are not using - A breakdown of what is consuming tokens across your CLAUDE.md, memory, skills, commands, and MCP tools - Estimated cost if you were being billed on raw API usage rather than a flat plan For reference: last 30 days, my token usage would have cost over $2,000 at API pricing. With the max plan, I am paying around 100 pounds per month. The token optimizer helps you understand where that gap comes from and where to trim. The [Claude Code commands reference](/blog/claude-code-commands) has more on managing your session budget. ### 9. Set up self-running scheduled agents Claude Code desktop has a Routines tab. You can create routines that run on a schedule, either locally on your device or hosted remotely. The remote option matters because a local schedule will not run if your laptop is closed. That is why a lot of people use Mac minis for always-on automation. Setting up a routine is as simple as telling Claude: "Run this on a routine at this time." Claude will schedule it inside the Routines tab. You can hook routines up to skills, MCP tools, and automations. A weekly revenue report every Monday at 8am is a one-sentence instruction. This is what turns a skill or workflow into a genuine agent: it runs without you, on a recurring basis, without needing you to trigger it. Learn more about what you can build here in the [Claude Code use cases](/blog/claude-code-use-cases) post. ### 10. Build a persistent memory layer (second brain) This is the one most people skip, and it is the difference between Claude Code starting from scratch in every session and getting smarter the longer you use it. A second brain is not complicated. It is a folder of files on your computer. That is the whole thing. I use Obsidian because it is a file viewer that lets you interlink markdown files, but the underlying asset is just files and folders. Nothing more complex than that. Here is what I keep in mine: a voice profile, a brand spine with colors and fonts and positioning, a CSS design framework that every new page or funnel pulls from so the design stays consistent, previous content pieces I can reference by name, and business context I want Claude to know. The CLAUDE.md file for each project lives here too. When I am in a Claude Code session, I can say "pull the same structure as last week's newsletter" and Claude knows exactly what that means because the file exists. I can drag files in directly, or just reference them by name. The context is always there. For a deeper walkthrough on the MCP side of this, see the post on [Claude Code MCP](/blog/claude-code-mcp). ## Why these Claude Code tips compound over time Each of these tips works on its own. Together, they shift Claude Code from a chatbot you type at into a system that runs. Auto mode and plan mode handle the build quality. The Superpowers plugin and skills handle the repetitive work. WhisperFlow speeds up input. The token optimizer keeps sessions lean. Scheduled agents run things while you sleep. And the second brain makes every session smarter than the last. The setup takes an afternoon. The payoff runs every day after that. > [CTA-BLUEPRINT] ## Claude Code tips FAQ ### What is auto mode in Claude Code? Auto mode lets Claude Code execute tasks without pausing to ask for permission on every action. It is available on the Claude Pro plan and the Max plan, in both the desktop app and the terminal. In the terminal, press Shift+Tab to switch between modes. Auto mode includes built-in guardrails that block dangerous commands, and you can add your own rules to customise its behaviour. ### What is plan mode in Claude Code? Plan mode is a session setting that prevents Claude from writing or modifying any code until you have approved a written plan. Claude's only job in plan mode is to think through the task, surface trade-offs, and produce a structured plan for your review. Once you approve it, you can execute in auto mode. It is the most reliable way to avoid building the wrong thing and wasting tokens fixing it. ### What is a CLAUDE.md file? A CLAUDE.md file is a markdown file that Claude reads at the start of every session before doing anything. It contains instructions, rules, and context specific to your project. You can use it to set coding standards, define what files Claude is allowed to touch, specify your goals, and include any business context Claude needs. Andrej Karpathy's four-rule template (think before coding, simplicity first, surgical changes, goal-driven execution) is a strong starting point. ### How do Claude Code skills work? Claude Code skills are reusable slash commands that encode a multi-step process. You invoke a skill with a `/skill-name` command, and Claude runs through the defined process automatically. Skills can include question gates, generate multiple outputs, score results, and chain into other skills. You can install community skills, or build your own using the skill creator built into the Claude Code desktop app. Building your own with your personal context and process is almost always more effective than importing a generic one. ### What is the token optimizer for Claude Code? The token optimizer is a skill that audits your context window overhead and identifies where tokens are being consumed before you even start a session. It shows your CLAUDE.md size, loaded skills, MCP tools, and memory files, and flags which ones you are not actively using. It estimates how much your usage would cost at API pricing versus a flat plan. Installing it and trimming unused skills and MCPs can recover a meaningful percentage of your session budget. ### How do scheduled agents work in Claude Code? Scheduled agents use the Routines tab in Claude Code desktop to run a skill, automation, or workflow on a timed schedule. You can run them locally on your device or remotely in the cloud. Remote is better for reliability because a local schedule requires your laptop to be open and running at the scheduled time. To create a routine, just tell Claude what you want to run and when, and it will set it up in the Routines tab. ### What is the Claude Code second brain or persistent memory? Persistent memory in Claude Code means keeping a collection of files on your computer that Claude can reference across sessions. It can contain your voice profile, brand guidelines, previous work, business context, and any other files you want Claude to pull from. Tools like Obsidian make it easy to view and interlink these files. When you reference previous work in a Claude Code session, by name or by context, Claude can pull that file and use it. Without this, Claude starts fresh every session with no knowledge of your history or preferences. ## Sources and citations - [Video: I Spent 1,000 Hours in Claude Code, Here Are 10 Hacks I'd Never Skip](https://youtu.be/u7efw7JkR8U) - [Claude Code official documentation](https://code.claude.com/docs/en/overview) - [Claude Code common workflows](https://code.claude.com/docs/en/common-workflows) - [Claude Code sub-agents](https://code.claude.com/docs/en/sub-agents) - [Claude Code hooks](https://code.claude.com/docs/en/hooks) ## Ready to build your own AI-powered system? If you want to go beyond tips and actually map out what to automate in your business, then build it yourself with hands-on support, that is what the blueprint is for. It walks you through the full setup, from your first CLAUDE.md file to running scheduled agents on real business tasks. [Get the free blueprint and start building](/blueprint) --- # Claude Code Status Line: Show Context, Cost and Git Source: https://theaiarchitects.com/blog/claude-code-statusline Published: 2026-06-20 The Claude Code status line is a custom bar showing context usage, cost, and git status. Here's how to set it up with /statusline or a script. The Claude Code status line is a customizable bar at the bottom of the interface that runs a shell script you configure and displays whatever it prints. It receives JSON session data on stdin, so you can show context window usage, session cost, the current model, your git branch, or anything else you want visible at a glance. The fastest way to set one up is the `/statusline` command, which writes the script for you. I'm Tom, and I run a custom status line every day. Mine pipes the session JSON through a Node script so I always see how much context I have left, which on long sessions is the single most useful number on screen. This post covers both ways to set one up, the data you can pull, and a few patterns worth stealing. [CTA-BLUEPRINT] ## What is the Claude Code status line? The status line is a persistent row above Claude Code's built-in footer that shows the output of a script you choose. Claude Code runs your script, pipes session data to it as JSON on stdin, and prints whatever your script returns to stdout. It does not replace the footer badges, it adds a row of your own above them. It is most useful for four things: watching context window usage as you work, tracking session cost, telling multiple sessions apart, and keeping git branch and status always visible. The status line runs locally and does not consume API tokens, so there is no cost to having it on. ## How does the Claude Code status line work? Claude Code runs your script and pipes a JSON object of session data to it on stdin. Your script reads that JSON, extracts the fields it wants, and prints a line. Claude Code displays the result. It re-runs after each assistant message, after `/compact` finishes, when the permission mode changes, and when vim mode toggles, all debounced at 300ms so rapid changes batch together. Your script can print more than plain text. Each separate `echo` renders as its own row, so you can build a multi-line status line. ANSI escape codes give you colour, like `\033[32m` for green, as long as your terminal supports them. And because Claude Code captures the output rather than connecting your script to the terminal directly, you read the terminal width from the `COLUMNS` environment variable that Claude Code sets, not from `tput cols`. ## How to set up a Claude Code status line There are two ways to set one up: let Claude write it, or write it yourself. Both end with a `statusLine` block in your settings. ### 1. Use the /statusline command The fastest path is the `/statusline` command. It takes a plain-English description, generates a script in `~/.claude/`, and updates your settings automatically. This is how most people should start. Describe what you want, and Claude Code builds and wires it up for you. You can refine it later by editing the generated script. ### 2. Configure it manually in settings.json To do it by hand, add a `statusLine` field to your `~/.claude/settings.json`, set `type` to `"command"`, and point `command` at a script or an inline command. Here is the minimal shape: The optional `padding` field adds horizontal spacing. The optional `refreshInterval` re-runs your command every N seconds for time-based data like a clock, which is also handy when background subagents change git state while the main session sits idle. My own config points `command` at a Node script rather than a shell script, which is the same mechanism: any executable that reads stdin and prints a line works. For more on the settings file, see my [Claude Code settings](/blog/claude-code-settings) guide. Here is a minimal script that reads the JSON with [`jq`](https://jqlang.github.io/jq/) and prints the model, folder, and context percentage: Save it to `~/.claude/statusline.sh`, run `chmod +x ~/.claude/statusline.sh` to make it executable, and point your `statusLine` command at it. The `// 0` is a jq fallback so a null field prints `0` instead of breaking the line. ## What data can the status line show? Claude Code sends a rich JSON object to your script, so the question is mostly what you want to surface. The fields I reach for most are the context window and cost numbers, but the full set is broad. - **Model**: `model.id` and `model.display_name` for the current model. - **Directory and git**: `workspace.current_dir`, `workspace.project_dir`, and `workspace.repo.owner` and `workspace.repo.name` parsed from your origin remote. - **Context window**: `context_window.used_percentage` and `context_window.remaining_percentage`, pre-calculated so you do not have to do the math. - **Cost and effort**: `cost.total_cost_usd`, `cost.total_lines_added` and `total_lines_removed`, and `effort.level` for the current reasoning effort. The cost figure is computed client-side and may differ from your actual bill, as the [cost tracking docs](https://code.claude.com/docs/en/costs) note. - **Rate limits**: `rate_limits.five_hour.used_percentage` and `rate_limits.seven_day.used_percentage`. - **Session**: `session_id`, `session_name`, and `version`. That context-window percentage is the one I would not work without. On a long session it is the difference between compacting on purpose and getting surprised. The status line is a sibling to the rest of Claude Code's customization layer, so once you have one, my [Claude Code hooks](/blog/claude-code-hooks) guide and the [how to use Claude Code](/blog/how-to-use-claude-code) walkthrough are the natural next steps. [CTA-BLUEPRINT] ## Claude Code status line FAQ ### How do I add a status line to Claude Code? The quickest way is the `/statusline` command, which takes a plain-English description, generates a script in `~/.claude/`, and updates your settings for you. To do it manually, add a `statusLine` block to your `~/.claude/settings.json` with `type` set to `"command"` and `command` pointing at your script. ### What data can the Claude Code status line display? It can display the model name, working directory, git branch and repo, context window usage percentage, session cost, lines added and removed, reasoning effort level, rate limit usage, and the session name and version. Claude Code sends all of this as JSON to your script on stdin, and you choose which fields to print. ### How do I show context window usage in the status line? Read the `context_window.used_percentage` or `context_window.remaining_percentage` field from the JSON Claude Code pipes to your script. Both are pre-calculated, so you can print them directly or render a progress bar. This is the most useful number to surface on long sessions. ### Can the Claude Code status line use colors? Yes. Print ANSI escape codes from your script, such as `\033[32m` for green, and Claude Code renders them as long as your terminal supports ANSI colors. You can also output multiple lines, since each separate `echo` renders as its own row. ### Does the status line cost API tokens? No. The status line runs locally as a shell script and does not consume API tokens. It only reads session data that Claude Code already has and prints text, so you can keep it on permanently without any usage cost. ### How do I remove the Claude Code status line? Run `/statusline` and ask it to remove or clear your status line, for example `/statusline delete` or `/statusline clear`. You can also manually delete the `statusLine` field from your `settings.json`. Either way removes the custom bar and leaves the built-in footer badges in place. ## Sources and citations - [Customize your status line](https://code.claude.com/docs/en/statusline) — official setup, the full list of JSON data fields, and example scripts. - [Claude Code settings](https://code.claude.com/docs/en/settings) — where the `statusLine` field lives and how settings are loaded. - [Track your costs](https://code.claude.com/docs/en/costs) — how the client-side session cost shown in the status line is computed. - [jq](https://jqlang.github.io/jq/) — the command-line JSON parser used to extract fields from the status line input. ## Ready to make Claude Code yours? A status line is one small piece of shaping Claude Code around how you work. If you want the guided path to a real build, my free Claude Code Blueprint walks you through your first project in about sixty minutes, no coding required. --- # How to Update Claude Code (and When You Don't Need To) Source: https://theaiarchitects.com/blog/claude-code-update Published: 2026-06-19 How to update Claude Code: when it auto-updates, when you run claude update yourself, and how to fix a stuck version. The honest version, by install method. You update Claude Code by running `claude update`, but most people never need to, because the native installer updates itself in the background. The honest answer to "how do I update Claude Code" depends entirely on how you installed it. Native installs auto-update. Homebrew, WinGet, and Linux package managers do not, and need a manual command. I'm Tom, and I run Claude Code all day on a native install that I have never once updated by hand. It just stays current. This post covers how updates actually work, the one command that forces an update now, and how to tell whether you are on the latest version or quietly stuck on an old one. [CTA-BLUEPRINT] ## How do you update Claude Code? You update Claude Code with one command: `claude update`. It applies the newest version immediately instead of waiting for the next background check. That is the manual path, and it works regardless of how you installed Claude Code. The thing most guides skip is that you usually do not need it. If you used the native installer, the recommended method, Claude Code checks for updates on startup and periodically while running, then downloads and installs them in the background. The update takes effect the next time you start Claude Code. So the real question is not "what is the update command," it is "does my install update itself, or do I have to." ## Which Claude Code installs auto-update? Whether Claude Code updates itself comes down to the installer you used. This is the single fact that resolves almost every "my Claude Code is out of date" confusion. The native installer auto-updates in the background, and so does an npm global install on `@latest`. These keep you current with no action. Homebrew, WinGet, and the apt, dnf, and apk Linux package managers do not auto-update through Claude Code. Those arrive through your normal system upgrade workflow instead, so you upgrade them the way you upgrade everything else on that machine. - **Native install**: auto-updates in the background. Nothing to do. - **npm**: run `npm install -g @anthropic-ai/claude-code@latest` to upgrade. Avoid `npm update -g`, which respects the original semver range and may not move you to the newest release. - **Homebrew**: run `brew upgrade claude-code` (or `claude-code@latest` for the latest channel). - **WinGet**: run `winget upgrade Anthropic.ClaudeCode`. - **apt / dnf / apk**: upgrade through your system package manager, the same as any other package. ## How to check your Claude Code version Check your current version with `claude --version`. To see the result of the most recent background update attempt, plus a broader health check of your install, run `claude doctor`. That second command is the one I actually use, because it tells you not just the version but whether anything is blocking an update. If `claude --version` fails with `command not found`, you have an install or PATH problem rather than an update problem, and the fix is in the install troubleshooting docs. If the version simply looks old on a native install, `claude doctor` will usually tell you why the background update has not landed. ## How to force an update right now To apply an update immediately without waiting for the background check, run `claude update`. This is the command to reach for when a new feature shipped and you do not want to wait for the next automatic check, or when you are debugging and want to rule out an outdated version first. On Homebrew or WinGet, you can have Claude Code run the upgrade for you by setting `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` to `1`. It then runs the upgrade in the background when a new version is available and prompts you to restart. This is the closest those package-manager installs get to the native installer's hands-off behaviour. For more of the commands that make up the daily workflow, see my [Claude Code commands](/blog/claude-code-commands) reference and the [how to use Claude Code](/blog/how-to-use-claude-code) guide. ## How to control or stop Claude Code updates You can pin which release channel Claude Code follows with the `autoUpdatesChannel` setting in your `settings.json`. Set it to `"latest"` for new features as soon as they ship, or `"stable"` for a version that is typically about a week old and skips releases with major regressions. I run latest, because I want the new features, and I accept the occasional rough edge as the price. To stop background updates entirely, set `DISABLE_AUTOUPDATER` to `"1"` in the `env` block of your settings. That stops the background check while leaving `claude update` working, so you control exactly when updates land. To block every update path including the manual command, use `DISABLE_UPDATES` instead. Most people should leave auto-updates on. Pinning is for teams that need version consistency, not for individuals. ## How to fix a stuck or outdated Claude Code If Claude Code looks stuck on an old version, the fix is almost always one of three things. Start with `claude doctor`, which reports the result of the most recent update attempt and lists the available fixes for whatever is blocking it. 1. **Wrong install method.** Homebrew, WinGet, and Linux package manager installs do not auto-update through Claude Code. Run that tool's upgrade command rather than expecting a background update. 1. **A non-writable npm global directory.** If an npm global install cannot auto-update because the npm directory is not writable, Claude Code shows a one-time startup notice and `claude doctor` lists the fix. Reinstalling with the native installer sidesteps npm permission issues entirely. 1. **A conflicting second install.** If `claude --version` reports an old number even after updating, you may have two installs or a leftover shell alias. The install troubleshooting guide has a "check for conflicting installations" step that finds and removes the duplicate. Force the newest version with `claude update`, then re-run `claude --version` to confirm it moved. If it still has not, `claude doctor` is the definitive diagnostic. [CTA-BLUEPRINT] ## How to update Claude Code FAQ ### What is the command to update Claude Code? The command is `claude update`. For npm installs, run `npm install -g @anthropic-ai/claude-code@latest`. Homebrew users run `brew upgrade claude-code`, and on Windows, `winget upgrade Anthropic.ClaudeCode`. On a native install you rarely need any of these, because Claude Code auto-updates in the background. ### Does Claude Code update automatically? Native installs and npm installs on `@latest` update automatically in the background, and the update takes effect the next time you start Claude Code. Homebrew, WinGet, and Linux package manager installs do not auto-update through Claude Code, so you upgrade those through your normal system update workflow. ### How do I check what version of Claude Code I have? Run `claude --version` to see your current version. For a fuller picture, including the result of the last background update attempt and any problems blocking it, run `claude doctor`. That second command is the better diagnostic when a version looks stuck. ### Why is my Claude Code not updating? The most common reason is that you installed through Homebrew, WinGet, or a Linux package manager, none of which auto-update through Claude Code. Run that tool's upgrade command. If you are on a native or npm install that should auto-update, run `claude doctor`, which reports what is blocking the background update, such as a non-writable npm global directory. ### How do I stop Claude Code from auto-updating? Set `DISABLE_AUTOUPDATER` to `"1"` in the `env` block of your `settings.json` to stop the background check while keeping `claude update` available. To pin a release channel instead of stopping updates, set `autoUpdatesChannel` to `"stable"`. To block all updates including the manual command, use `DISABLE_UPDATES`. ### What is the difference between the latest and stable update channels? The `latest` channel gives you new features as soon as they ship. The `stable` channel keeps you on a version that is typically about a week old and skips releases with major regressions. Set your choice with the `autoUpdatesChannel` setting, or for Homebrew, by choosing the `claude-code` cask for stable or `claude-code@latest` for latest. ## Sources and citations - [Advanced setup: update Claude Code](https://code.claude.com/docs/en/setup) — official update commands, auto-update behaviour, and release channels by install method. - [Claude Code settings](https://code.claude.com/docs/en/settings) — the `autoUpdatesChannel`, `minimumVersion`, and `DISABLE_AUTOUPDATER` settings. - [Troubleshoot installation and login](https://code.claude.com/docs/en/troubleshoot-install) — fixes for permission errors and conflicting installations that block updates. ## Ready to get more out of Claude Code? Staying current is the easy part. The leverage is in knowing what to point Claude Code at once you are set up. My free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. Start there. ## Related guides - [How to Install Claude Code on Mac, Windows, Linux + WSL](/blog/how-to-install-claude-code) --- # Claude Code Settings: The settings.json Guide Source: https://theaiarchitects.com/blog/claude-code-settings Published: 2026-06-19 Claude Code settings live in settings.json across four levels. Here's the hierarchy, the precedence order, and the keys that actually matter. Claude Code settings live in `settings.json` files, and there are four of them at different levels: user, project, local, and managed. They stack, with the more specific file overriding the more general one, so a project setting beats your personal default and a managed setting beats everything. Knowing which file wins is most of what makes Claude Code configuration click. I'm Tom, and I run a fairly opinionated `settings.json`: model pinned, reasoning effort turned up, session history kept far longer than the default, hooks wired in, and a hard deny rule on reading any `.env` file. This post covers where the files live, the precedence order, and the handful of keys worth setting on day one. [CTA-BLUEPRINT] ## What is the Claude Code settings.json file? The `settings.json` file is where Claude Code reads its configuration: which model to use, what tools it may run, environment variables, hooks, and more. It is plain JSON, and the same keys work in every one of the four settings files. The difference between those files is scope and who they apply to, not syntax. A tip that saves real time: add `"$schema": "https://json.schemastore.org/claude-code-settings.json"` to the top of your file. Your editor then gives you autocomplete and inline validation for every available setting, so you stop guessing at key names. ## The Claude Code settings hierarchy Claude Code reads four settings files, each with a different scope. Understanding the four is the foundation, because a setting that "won't take" is almost always being overridden by a more specific file. - **User** (`~/.claude/settings.json`): your personal preferences across every project. Not shared. - **Project** (`.claude/settings.json`): team settings committed to the repo, so everyone working in it inherits them. - **Local** (`.claude/settings.local.json`): your personal overrides for one project, gitignored so they stay off the team. - **Managed**: deployed by an organization's IT for fleet-wide security and compliance, and it cannot be overridden. ## What is the Claude Code settings precedence order? When the same key is set in more than one file, Claude Code applies them in a fixed order from highest priority to lowest: managed settings, then command-line arguments, then local, then project, then user. So a managed policy wins outright, a `--model` flag beats your files for that session, and your gitignored local file overrides the shared project file, which in turn overrides your global user defaults. The practical rule that follows: put personal defaults in your user file, team agreements in the project file, and your own per-project tweaks in the local file. When a setting is not behaving, check whether a higher-priority file is setting the same key. That one habit resolves most configuration confusion. ## The Claude Code settings that matter You do not need to set most keys. A handful do real work, and these are the ones I actually touch. For the deeper subsystems, each has its own guide. - **`model`**: the default model for Claude Code, overridable per session with `--model`. Read once at startup, so it applies on the next restart. - **`permissions`**: allow, deny, and ask rules for tool execution. I keep a hard `deny` on reading any `.env` file so secrets never reach the model. This is the security-critical one. For the risky end of permissions, see [Claude Code dangerously skip permissions](/blog/claude-code-dangerously-skip-permissions). - **`hooks`**: custom commands that fire at lifecycle events, which is how you automate around the agent. Full detail in my [Claude Code hooks](/blog/claude-code-hooks) guide. - **`env`**: environment variables applied to every session, useful for things like `DISABLE_AUTOUPDATER` or a git bash path on Windows. For what the update settings actually do, see [how to control Claude Code updates](/blog/claude-code-update). - **`cleanupPeriodDays`**: how long session files are kept before deletion. The default is 30. I set mine far higher because I lean on session history and the [Claude Code memory](/blog/claude-code-memory) it feeds. - **`statusLine`**: points at a script for a custom status bar. See my [Claude Code status line](/blog/claude-code-statusline) guide. - **`outputStyle`** and **`attribution`**: adjust the response style and customize git commit and PR bylines respectively. Here is a compact example that sets several of those at once, close to the shape of my own user file: Most settings reload automatically when you change them, including `permissions` and `hooks`. A couple, including `model` and `outputStyle`, are read once at startup and apply on the next restart. You can edit the file directly or use the `/config` command for an interactive interface, including `/config verbose=true` to change a single option without opening the UI. [CTA-BLUEPRINT] ## Claude Code settings FAQ ### Where is the Claude Code settings.json file? There are four. Your personal user settings live at `~/.claude/settings.json`. Project settings shared with your team live at `.claude/settings.json` in the repo. Your gitignored personal overrides for a project live at `.claude/settings.local.json`. Managed settings are deployed by IT at a system path and cannot be overridden. ### What is the precedence order of Claude Code settings? From highest to lowest priority: managed settings, command-line arguments, local settings, project settings, then user settings. A managed policy wins outright, a command-line flag beats your files for that session, and a more specific file overrides a more general one when they set the same key. ### What is the difference between project and local settings? Project settings (`.claude/settings.json`) are committed to the repo and shared with your whole team. Local settings (`.claude/settings.local.json`) are gitignored and apply only to you in that project. Use project settings for team agreements and local settings for your own per-project tweaks that should not be shared. ### How do I change the model in Claude Code settings? Set the `model` key in your `settings.json` to the model you want as the default. You can override it for a single session with the `--model` flag, which takes precedence. The `model` setting is read once at startup, so a change applies the next time you start Claude Code. ### How do I stop Claude Code from reading sensitive files? Add a `permissions` block with a `deny` rule for the file path, such as denying `Read` on any `.env` file. A matching deny rule keeps both the file's contents and, with the IDE integration, the open-file notice from reaching Claude. This is the cleanest way to keep secrets out of the model's context. ### Do Claude Code settings reload without restarting? Most do. Settings like `permissions`, `hooks`, and `apiKeyHelper` reload automatically when changed. A few are read once at startup and apply on the next restart, including `model` and `outputStyle`. Run `claude doctor` if you want to validate that your settings file is being read correctly. ## Sources and citations - [Claude Code settings](https://code.claude.com/docs/en/settings) — official file hierarchy, precedence order, and the full list of available settings. - [Claude Code hooks](https://code.claude.com/docs/en/hooks) — the `hooks` setting and the lifecycle events it fires on. - [Claude Code permissions](https://code.claude.com/docs/en/permissions) — the allow, deny, and ask rules and managed-settings enforcement. ## Ready to make Claude Code work the way you do? Dialing in your settings is the groundwork. The payoff is what you build on top of it. My free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. Start there. --- # Claude Code Checkpoints: How to Rewind a Bad Edit Source: https://theaiarchitects.com/blog/claude-code-checkpoints Published: 2026-06-19 Claude Code checkpoints auto-save your code before each edit so you can rewind. Here's how /rewind works, what it tracks, and the one thing it doesn't. Claude Code checkpoints automatically capture the state of your code before each edit, so you can rewind to a previous state if a task goes sideways. You open the rewind menu with `/rewind`, or by pressing `Esc` twice when the prompt is empty, then pick the point you want to return to. It is a session-level undo for everything Claude changed. I'm Tom, and checkpoints are the reason I let Claude Code take swings at ambitious, wide-scale edits. I know I can always walk it back. This post covers how checkpointing works, the difference between restoring and summarizing, and the one important thing it does not track, which trips people up. [CTA-BLUEPRINT] ## What are Claude Code checkpoints? Claude Code checkpoints are automatic snapshots of your code taken before each of Claude's edits. Every prompt you send creates a new checkpoint, and they persist across sessions, so you can rewind even in a resumed conversation. They are cleaned up along with sessions after 30 days by default, which is configurable. The point is a safety net. When you ask Claude for a big, multi-file change, checkpointing captures where things were before, so a result that breaks something is a quick undo rather than a manual cleanup. Think of it as local undo for the agent, sitting alongside, not replacing, your version control. ## How do Claude Code checkpoints work? Claude Code tracks every change made by its file-editing tools and snapshots the prior state before applying each edit. You do not turn anything on. It happens automatically as you work, and the checkpoints attach to the session so they survive a restart or a resume. To rewind, run `/rewind` or press `Esc` twice on an empty prompt to open the rewind menu. One catch worth knowing: if the prompt has text in it, double `Esc` clears that text instead of opening the menu. The cleared text is saved to your input history, so press `Up` to get it back. The menu then lists every prompt you sent in the session, and you pick the point you want to act on. ## Restore vs summarize: the rewind options The rewind menu gives you two families of action, and they do very different things. The restore options revert state. The summarize options compress conversation without touching your files. Knowing which is which saves you from undoing work you meant to keep. The restore options are the undo. `Restore code and conversation` reverts both back to the chosen point. `Restore conversation` rewinds the chat while keeping your current code. `Restore code` reverts the file changes while keeping the conversation, which is the one I use most when an approach produced bad code but the discussion getting there was still useful. The summarize options are about context, not undo. `Summarize from here` replaces the selected message and everything after it with a summary, keeping earlier context in full. `Summarize up to here` compresses everything before the selected message and leaves recent work intact. Both compress the conversation to free up context window space, similar to `/compact` but targeted at one side of the point you pick. For more on managing context, see my [Claude Code memory](/blog/claude-code-memory) guide. Here is the full menu at a glance: - **Restore code and conversation**: revert both back to the selected point. - **Restore conversation**: rewind the chat, keep current code. - **Restore code**: revert files, keep the conversation. - **Summarize from here**: replace the selected message onward with a summary. - **Summarize up to here**: compress everything before the selected message. - **Never mind**: close the menu with no change. If you want to branch off and try a different approach while keeping the original session fully intact, use a fork instead of a rewind: run `claude --continue --fork-session`. Fork preserves the original session, where summarize compresses it in place. ## How to use checkpoints well Checkpoints earn their keep in four situations: exploring alternatives, recovering from mistakes, iterating on a feature, and freeing context space. The mental model that works for me is to take bigger swings because the floor is protected. If a refactor goes wrong, I am one `/rewind` away from where I started rather than reconstructing it by hand. The workflow pairs naturally with plan mode and the rest of the agent loop. Let Claude attempt the ambitious version, review the diff, and if it is wrong, rewind the code and try a different prompt. The original prompt from the message you select is restored to the input field, so you can edit and re-send it. For the surrounding workflow, my [how to use Claude Code](/blog/how-to-use-claude-code) guide and my [Claude Code commands](/blog/claude-code-commands) reference cover the commands that go with it. [CTA-BLUEPRINT] ## Where checkpoints fall short The single most important limitation: checkpoints do not track files changed by bash commands. If Claude runs `rm`, `mv`, or `cp`, those changes cannot be undone through rewind, because only direct edits through Claude's file-editing tools are tracked. This is the gotcha that bites people who assume rewind is a full undo. It is not. Two more boundaries matter. Checkpoints only track files edited in the current session, so manual changes you make outside Claude Code, or edits from a concurrent session, are usually not captured. And checkpoints are not a replacement for version control. They are session-level recovery, the local undo. Git is still your permanent history, your branches, and your collaboration layer. I treat checkpoints as the fast undo within a session and git as the real safety net, and I commit often regardless. If you want to skip approval prompts during these fast iterations, do it carefully: see [Claude Code dangerously skip permissions](/blog/claude-code-dangerously-skip-permissions). ## Claude Code checkpoints FAQ ### How do I rewind in Claude Code? Run `/rewind`, or press `Esc` twice when the prompt input is empty, to open the rewind menu. Select the prompt you want to return to, then choose to restore code, conversation, or both. If the prompt has text in it, double `Esc` clears the text instead, so clear it first or use the `/rewind` command. ### Are Claude Code checkpoints on by default? Yes. Checkpointing is automatic. Claude Code captures the state of your code before each edit with no setup, creates a checkpoint on every prompt, and persists them across sessions. They are cleaned up with their session after 30 days by default, which you can configure. ### Can I undo bash command changes with checkpoints? No. Checkpoints do not track files modified by bash commands like `rm`, `mv`, or `cp`. Only direct edits made through Claude's file-editing tools are tracked and reversible. For anything a bash command changed, you need version control or a manual fix. ### What is the difference between restore and summarize? Restore reverts state: it undoes code changes, conversation history, or both, depending on which option you pick. Summarize does not touch your files at all. It compresses part of the conversation into a summary to free up context window space, either from the selected message forward or up to it. ### Do checkpoints replace Git? No. Checkpoints are designed for quick, session-level recovery, the local undo within a Claude Code session. Git remains your permanent version history, branching, and collaboration layer. Use both: checkpoints for fast in-session reverts, Git for commits and long-term history. ### Do checkpoints persist after I close Claude Code? Yes. Checkpoints persist across sessions, so you can access them in a resumed conversation. They are automatically cleaned up along with their session after 30 days by default, and that retention period is configurable. ## Sources and citations - [Checkpointing](https://code.claude.com/docs/en/checkpointing) — official guide to automatic tracking, the rewind menu, and the limitations. - [Claude Code commands](https://code.claude.com/docs/en/commands) — the `/rewind` command and related session controls. - [Manage sessions](https://code.claude.com/docs/en/sessions) — forking a session with `--fork-session` to branch instead of rewind. ## Ready to build with Claude Code? Checkpoints are what let you hand Claude Code the big jobs without fear. If you want the guided path from zero to a real build, my free Claude Code Blueprint walks you through your first project in about sixty minutes, no coding required. ## Related guides - [Git Workflow for Claude Code: Solo and Team Guide](/blog/git-workflow-claude-code) --- # Claude vs ChatGPT Chrome Extension: Which Wins? Source: https://theaiarchitects.com/blog/claude-vs-chatgpt-chrome-extension Published: 2026-06-17 I've run both browser extensions in real workflows. Claude wins on browser control and multi-step automation. ChatGPT wins on simplicity. Here's the full breakdown. Claude for Chrome is the better extension for anyone doing multi-step browser tasks, form filling, or competitive research. ChatGPT's browser capability is simpler and more approachable, but it does not give ChatGPT actual control over your browser the way Claude does. I'm Tom. I build AI workflows for business owners and I've been running both extensions in live production work for several months. This post compares them on the five dimensions that actually matter: browser control, autonomy, privacy, pricing, and real task performance. There's a comparison table and a direct verdict at the end. --- > [CTA-BLUEPRINT] --- ## What is the Claude Chrome extension? The [Claude Chrome extension](/blog/claude-chrome-extension) is a browser add-on from Anthropic that gives Claude the ability to read pages, fill forms, click buttons, and chain actions across multiple tabs. You install it from the Chrome Web Store, grant it access site by site, and Claude can then act on your instructions in context rather than waiting for you to copy-paste content into a chat window. Anthropic launched it as a pilot to around 1,000 Max plan users in August 2025, expanded it to all Max subscribers in November 2025, and opened it to Pro, Team, and Enterprise plans on 18 December 2025. It works in Chrome, Edge, Arc, and Brave. Not Firefox or Safari. ## What is the ChatGPT browser extension? ChatGPT's browser capability works differently. OpenAI's ChatGPT Search extension (available in the [Chrome Web Store](https://chromewebstore.google.com/detail/chatgpt-search/ejcknobblikdjfnbccnidpiobacdbemn)) adds a shortcut to open ChatGPT from your browser and enables ChatGPT to read page content when you ask it a question in the sidebar. It also powers the browsing capability inside ChatGPT, which lets the model fetch and read live URLs in the chat. The difference is that ChatGPT's browser tool reads and retrieves. Claude's extension acts. --- ## Browser control depth: Claude takes this by a wide margin Claude for Chrome has what Anthropic calls "computer use" applied to the browser. It can read DOM structure, identify form fields, click specific elements, fill inputs, and submit forms. When I run it on a multi-step task, it navigates through the whole sequence with each action informing the next. ChatGPT can open a URL and read the page content. It can summarize what it finds and report back. What it cannot do is interact with the page: fill a field, click a button, or carry out a sequence of actions that changes the page state. For researching a competitor's pricing page, both tools work. For filling in a supplier onboarding form while you work on something else, only Claude can do it. --- ## Autonomy modes: Claude has two, ChatGPT has one Claude for Chrome runs in two modes. In standard mode, Claude asks for your confirmation before taking high-risk actions like submitting a form or sharing data. In autonomous mode, it chains actions together without a pause. Anthropic keeps additional safeguards on the most sensitive actions even in autonomous mode. In my testing, standard mode is the right starting point until you know exactly what Claude will do on each site you've enabled. ChatGPT has no equivalent of autonomous mode. Every action is in-conversation. You ask, it retrieves, it answers. There is no mode where ChatGPT is working through a series of browser steps without you in the loop. If your goal is to have an AI complete a workflow while you focus on something else, Claude is the only option of the two. If you want a faster answer to a research question in a conversational interface, ChatGPT works fine. --- ## Privacy and permissions: different models, different trade-offs Claude gives you site-by-site access control. You explicitly grant Claude access to each domain in the extension settings. Claude cannot read any site you have not enabled. Team and Enterprise admins can push org-wide allowlists and blocklists. Anthropic published adversarial testing data alongside the launch. With safety mitigations in place, the prompt injection attack success rate sits at 11.2%, down from 23.6% without them. On browser-specific attack scenarios, mitigations reduced the attack success rate from 35.7% to 0%. Those are the numbers I cite when clients ask whether it's safe to use on internal tools. ChatGPT's browsing is session-scoped. Each conversation that uses browsing reads the pages relevant to that conversation. There is no persistent site-by-site toggle to manage. The practical difference: Claude's model is more granular and requires more upfront setup, but gives you finer control. ChatGPT's model is simpler and lower-friction, but you have less visibility into what it's reading and when. Neither tool should be used on pages containing medical records, legal documents under confidentiality, or financial accounts unless you are on an Enterprise plan with a data processing agreement in place. --- ## Pricing and plan gating: nearly identical starting point Claude for Chrome requires a paid Claude plan. The entry point is Claude Pro at $20 per month. Claude Max is $100 per month (the tier Anthropic targets at heavy users and builders) or $200 per month for the higher usage limit. Team and Enterprise add admin controls and data processing agreements. ChatGPT's browsing capability requires ChatGPT Plus at $20 per month, or a Team or Enterprise plan. The ChatGPT Search extension itself is free to install but only useful as a shortcut to open ChatGPT. The starting cost is the same for both. Where they diverge is at the top: Claude Max at $100 per month sits below ChatGPT's Pro tier at $200 per month. For the workflow I use, the Pro tier on either platform is enough. --- ## Real task performance: summarizing pages, filling forms, multi-tab work For page summarization, both tools work. Ask either one to summarize the article you're reading and you'll get a competent summary. ChatGPT's sidebar shortcut is slightly faster to open because of the keyboard shortcut integration. Claude's output tends to be more structured when you specify a format. For form filling, Claude is the only option. I've used it to fill in grant application forms with repeating business information fields, and to complete supplier onboarding portals. Claude works through the fields, populates them, and holds before submitting so I can review. When I ran both on the same task, ChatGPT read the form and described it. Claude filled it in. For multi-tab competitive research, Claude handles this natively. I've had it pull pricing, positioning headlines, and top CTAs from four competitor sites in a single request. It moves through the tabs and compiles a comparison. This used to take 30 to 45 minutes of manual work. ChatGPT cannot coordinate across tabs in the same way. The one category where ChatGPT's browsing sometimes outperforms is when you need live web search built into the answer. ChatGPT's browsing is integrated with its search capability, so it can pull live results and cite them in a structured answer in one step. Claude's browser control is about acting on pages you visit, not searching the web on your behalf. --- ## Where each extension falls short Claude for Chrome has real limitations. Some sites block automated browser access or use DOM structures Claude cannot parse reliably. React and Vue single-page applications sometimes behave unpredictably because the content isn't in a simple static DOM at load time. I've hit this on a few SaaS portals where the page loads JavaScript-rendered content after a delay and Claude reads the loading state instead of the data. Autonomous mode also requires a level of trust that takes time to build. Running a workflow unattended before you fully understand what Claude considers a "safe" action is how you end up with unexpected form submissions. The extension also requires an active paid plan, starting at $20 per month for Claude Pro. There is no way to test browser control features on a free Claude account. ChatGPT's browsing capability falls short on depth. It reads pages and reports back. It cannot interact with them. If your workflow involves anything beyond reading and summarizing, you will hit the ceiling quickly. There is also no persistent permission model to configure. Every session starts fresh, which is simpler but means you have less audit trail for what ChatGPT has read and when. Both extensions are Chrome-only. If your team uses a mix of browsers, neither provides a consistent experience across the board. --- ## Comparison table: Claude vs ChatGPT browser extension - **Browser control depth** — Claude for Chrome: Read, fill, click, navigate. ChatGPT (Plus + browsing): Read and retrieve only. - **Autonomous mode** — Claude for Chrome: Yes (with safeguards). ChatGPT (Plus + browsing): No. - **Multi-tab workflow** — Claude for Chrome: Yes. ChatGPT (Plus + browsing): No. - **Privacy control** — Claude for Chrome: Site-by-site toggle, org policies. ChatGPT (Plus + browsing): Session-scoped, no persistent toggle. - **Plan required** — Claude for Chrome: Pro $20/mo minimum. ChatGPT (Plus + browsing): Plus $20/mo minimum. - **Claude Code integration** — Claude for Chrome: Native. ChatGPT (Plus + browsing): No. - **Live web search** — Claude for Chrome: No (acts on pages you visit). ChatGPT (Plus + browsing): Yes (built-in search). - **Form completion** — Claude for Chrome: Yes. ChatGPT (Plus + browsing): No. - **Available on Firefox/Safari** — Claude for Chrome: No. ChatGPT (Plus + browsing): No. --- > [CTA-BLUEPRINT] --- ## Verdict Claude wins on browser automation. ChatGPT wins on web search integration. **Pick Claude for Chrome if** you do multi-step browser work, form filling, competitive research across tabs, or you are already using Claude Code and want the browser loop closed. The depth of control is not close. **Pick ChatGPT if** your main use case is getting live web search results inside a conversational interface, or you find Claude's site-by-site permission setup too much overhead for your workflow. ChatGPT's browsing is also better integrated into its mobile and desktop apps, which matters if you switch devices constantly. The contrarian verdict: most people installing either extension underuse the capability. The Claude extension is doing real work in my stack, but only because I took the time to configure site access and build specific prompts around it. If you are going to install it and then occasionally ask it to summarize a page, the ChatGPT shortcut is honestly the better fit for that use case because it requires zero configuration. For the full picture on what the Claude extension can do, see my [Claude Chrome extension guide](/blog/claude-chrome-extension). If you are evaluating Claude against its other main rival, the [Claude vs Gemini breakdown](/blog/claude-vs-gemini) covers that comparison in detail. And if you want to understand where Claude Code fits into all of this, the [how to use Claude Code guide](/blog/how-to-use-claude-code) is the place to start. --- ## Claude vs ChatGPT Chrome extension FAQ ### Is the Claude Chrome extension better than ChatGPT's? For browser control, yes. Claude for Chrome can fill forms, click buttons, and chain multi-step actions across tabs. The ChatGPT browser capability reads pages and retrieves information but does not interact with page elements. For live web search built into chat, ChatGPT has the edge. ### Which is safer, Claude or ChatGPT in the browser? Both have safety measures that cut real attack vectors. Claude's site-by-site access model gives you more explicit control over what the AI can see. Anthropic published adversarial testing results showing mitigations reduce prompt injection success rates to 11.2%. ChatGPT's browsing is session-scoped with no persistent site toggle. Neither should be used on confidential documents or financial accounts outside of Enterprise plans with data processing agreements. ### Which is cheaper? Both start at $20 per month (Claude Pro, ChatGPT Plus). The Claude Max plan is $100 per month. ChatGPT's Pro tier is $200 per month. If you only need browser extension access, the entry-level paid tier on either platform gives you what you need. ### Can both control the browser autonomously? Claude has an autonomous mode that chains actions without confirmation prompts, with Anthropic-maintained safeguards on the highest-risk actions. ChatGPT does not have an autonomous mode. Every ChatGPT browser interaction is conversational and in-the-loop. ### Which should I use for summarizing pages? Both summarize pages competently. If page summarization is your only use case, ChatGPT's keyboard shortcut integration is slightly faster to open. If you also need structured extraction, form filling, or multi-tab research, Claude is the better choice because it handles all of those in the same extension. ### Does the ChatGPT Chrome extension do form filling? No. The ChatGPT browser capability reads and retrieves page content but cannot interact with DOM elements, fill form fields, or click buttons. Form completion is a Claude-specific capability in this comparison. ### Do either of these work on Firefox or Safari? No. Both extensions require Chromium-based browsers: Chrome, Edge, Arc, and Brave. Firefox and Safari are not supported by either extension as of June 2026. --- ## Related guides - [Claude Chrome extension: setup, 8 use cases, and privacy](/blog/claude-chrome-extension) - [Claude vs Gemini: which AI should you use in 2026?](/blog/claude-vs-gemini) - [How to use Claude Code](/blog/how-to-use-claude-code) --- ## Sources and citations - Claude AI for Chrome in the Chrome Web Store: [chromewebstore.google.com](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) - ChatGPT Search extension in the Chrome Web Store: [chromewebstore.google.com](https://chromewebstore.google.com/detail/chatgpt-search/ejcknobblikdjfnbccnidpiobacdbemn) - Claude for Chrome announcement: [anthropic.com/news/claude-for-chrome](https://www.anthropic.com/news/claude-for-chrome) - Claude for Chrome documentation: [docs.claude.com](https://docs.claude.com/en/docs/claude-for-chrome) - Claude for Chrome (Anthropic docs): [docs.anthropic.com](https://docs.anthropic.com/en/docs/about-claude/claude-for-chrome) - Getting started with Claude for Chrome: [support.anthropic.com](https://support.anthropic.com/en/articles/12012173-getting-started-with-claude-for-chrome) --- # Claude Chrome Extension Not Working? Fixes Source: https://theaiarchitects.com/blog/claude-chrome-extension-not-working Published: 2026-06-17 If your Claude Chrome extension is not working, the most common cause is a plan mismatch or missing site access, not a broken install. Here are the fixes for every failure mode. The most common reason the Claude Chrome extension stops working is not a broken install. It is that the extension was never granted access to the page you are on, or your account is not on a plan that supports it. Most people reinstall and get the same result because the root cause stays in place. I have hit every one of these failure modes building browser workflows for clients. The fix is almost never reinstalling. It is one specific permission, plan setting, or auth state that needs to be corrected. This post goes through each symptom and the exact fix. A quick note on access: Anthropic launched the extension as a pilot to 1,000 Max plan users in August 2025, expanded it to all Max subscribers in November 2025, then opened it to Pro, Team, and Enterprise on 18 December 2025. Free accounts have never had access. That timeline matters because a lot of the "greyed out" and "upgrade required" reports online date from before December 2025, when Pro users were still locked out. --- > [CTA-BLUEPRINT] --- ## Claude Chrome extension won't load or won't appear in the toolbar If the extension icon is not showing in your Chrome toolbar after installation, the extension is installed but hidden. Open the Extensions menu (the puzzle-piece icon at the top right of Chrome) and look for "Claude AI for Chrome" in the list. Click the pin icon next to it to lock it into the toolbar. Chrome hides newly installed extensions by default. That does not mean the install failed. If the extension does not appear in the Extensions list at all, go to `chrome://extensions` in the address bar and check that the extension is enabled. Toggle it on if it is switched off. If it is missing entirely, reinstall from the [Claude AI for Chrome listing on the Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip). The extension ID in the Chrome Web Store URL is `mmpfdbkbpokgghegejphmpmpnjncehip`, which you can use to verify you're installing the official Anthropic build rather than a clone. One more thing worth checking: Edge, Arc, and Brave all support the extension and run it the same way Chrome does. If you installed it on one Chromium browser and are trying to use it in a different one, you need a separate install for each browser profile. In my setup I run Chrome and Arc, and I keep the extension installed in both because they do not share sessions or permissions. ## Claude says it has no access to the page This is the most common complaint after initial setup, and the fix is one step. The extension does not automatically get permission to read every site. You have to grant access site by site. Open the Claude side panel, click the page access toggle or go into extension settings, and explicitly enable the site you are on. Once you grant access, Claude can read the page content and respond in context. Every time I have seen the no-access message, the install was fine and the site grant was the thing missing. When I see that error in my own browser, I go straight to the extension settings and check the per-domain toggle before I touch anything else. Some sites block browser extension access at the infrastructure level. Financial services sites and a handful of high-risk categories are blocked by Anthropic regardless of your settings. For everything else, if Claude says it cannot access the page, check whether you have toggled on access for that specific domain. The toggle lives in the Claude side panel under Settings, not inside `chrome://extensions`. ## Autonomous mode is greyed out Autonomous mode being greyed out is almost always a plan or settings issue, not a bug. Autonomous mode requires an active Pro, Max, Team, or Enterprise subscription. The Pro plan runs $20 a month. Max runs $100 a month (or $200 a month for the higher tier), and the extension was Max-only from August to November 2025. It opened to Pro, Team, and Enterprise on 18 December 2025. If you are on a free account, the toggle is unavailable. The first time I hit the greyed-out toggle myself, it was because I was signed into a free profile in that browser. Switched to my Pro account and the option appeared immediately. If you are on a paid plan and still seeing it greyed out, open the Claude side panel, go to Settings, and check whether autonomous mode has been enabled at the account level. On Team and Enterprise plans, your admin may have restricted it via org-wide settings. Check with whoever manages your Claude workspace. If your plan supports it and the setting is toggled on, try reloading the extension. Close the side panel, click the extension icon to reopen it, and navigate back to the page. Greyed-out state occasionally persists after a sign-in without a fresh load. ## The extension is stuck in a sign-in loop A sign-in loop where the extension keeps sending you to claude.ai to authenticate but never resolves usually comes down to a cookie conflict or a session that is not being recognised. First, make sure you are signed in to claude.ai in the same browser profile where the extension is installed. If you use multiple Chrome profiles or a guest profile, the extension will not pick up a session from a different profile. I run into this most often when testing workflows in a separate Chrome profile from my main account. If you are signed in and still looping, clear cookies specifically for claude.ai. Go to `chrome://settings/cookies`, search for `claude.ai`, and delete the stored cookies. Then sign in again. This clears any stale or conflicting session state that blocks authentication. On corporate networks or managed devices, IT firewall rules occasionally block the auth handshake. If clearing cookies does not resolve it, test the extension on a personal network or device to confirm whether a network policy is the cause. ## The extension is not working on certain pages Three things can prevent the extension from working on specific pages even when access is enabled. First, browser extension restrictions. Chrome and Chromium block all extensions from running on certain built-in pages: `chrome://` URLs, the Chrome Web Store itself, and the New Tab page. This is a Chrome security policy, not an extension bug. You cannot grant Claude access to these pages. Second, page structure. Some single-page applications built on React or Vue update content dynamically after initial load. Claude reads what is in the DOM at the moment you prompt it. If the page renders content via JavaScript after a delay, Claude may read an incomplete version. Wait for the page to fully load before prompting. Third, PDF files opened directly in Chrome. Claude cannot read PDF content via the browser extension the same way it reads a standard web page. Download the PDF and pass it to Claude via claude.ai instead. If you are on a corporate device, your IT policy may also block specific sites at the network level regardless of what permissions you have set inside the extension. This shows up as Claude reporting no access even when the site is enabled in your settings. The test is whether the same site works on a personal device on a different network. ## The extension is out of date An outdated extension sometimes loses compatibility with the current claude.ai session format, especially after Anthropic ships updates to how the side panel communicates with the backend. Chrome updates extensions automatically, but the cycle can lag. To force an update, go to `chrome://extensions`, enable Developer mode (toggle at the top right), and click Update. This pulls the latest version for all installed extensions immediately. If the extension was working and then broke after a Chrome or macOS update, this is the first thing to check. ## Another extension is conflicting Ad blockers, privacy shields, and content script managers like uBlock Origin, Privacy Badger, and Ghostery occasionally block the extension's communication with claude.ai. Test this by opening a new Chrome window in incognito mode with extensions disabled (hold Shift and click the New Incognito Window option, or go to `chrome://extensions` and disable other extensions temporarily). If the Claude extension works in incognito with no other extensions active, the conflict is with one of your other installed extensions. The usual culprits are ad blockers that have rules aggressive enough to interfere with first-party extension requests. Add claude.ai to the allowlist of any ad blocker you are running and test again. ## You need a paid plan for the Claude Chrome extension The Claude Chrome extension does not work with a free account. Access requires an active paid subscription. The entry point is the Pro plan at $20 a month. Max plans start at $100 a month. Team and Enterprise are priced per seat and add org-wide admin controls on top of everything else. If you are on a paid plan and still seeing an upgrade prompt when you open the extension, sign out of the extension and sign back in. Occasionally the extension caches a stale entitlement check. Signing out and back in forces a fresh plan lookup. If you recently upgraded your plan and the extension is still blocking you, wait a few minutes and reload. Plan changes do not always propagate instantly to the extension session. --- > [CTA-BLUEPRINT] --- ## Claude Chrome extension troubleshooting FAQ ### Why is my Claude Chrome extension not working? The most common causes are that the extension does not have access to the current page, the account is not on a paid plan, or the extension is stuck on a stale auth session. Grant explicit site access in the extension settings, confirm you are on Pro, Max, Team, or Enterprise, and clear cookies for claude.ai if you are stuck in a sign-in loop. ### Why does Claude say it can't access the page? Claude requires explicit per-site access before it can read page content. Open the extension panel and grant access for the domain you are on. If you have already done that and Claude still reports no access, the site may be in a category Anthropic blocks automatically (financial services, for example) or the page is a Chrome-internal URL where extensions cannot run. ### Why is autonomous mode greyed out? Autonomous mode is only available on paid plans. If you are on a free account, it will always be unavailable. On paid plans, the setting must be enabled in the Claude extension's Settings panel. On Team and Enterprise plans, an admin may have restricted it org-wide. ### Why won't the extension sign in? A persistent sign-in loop usually means a cookie conflict. Clear cookies for claude.ai in Chrome settings, then sign in again. Also confirm you are using the same Chrome profile where the extension is installed. The extension does not share sessions across Chrome profiles. ### Do I need a paid plan for the Claude Chrome extension? Yes. The extension requires an active Pro ($20/mo), Max ($100/mo), Team, or Enterprise subscription. Free accounts do not have browser extension access. There is no free trial of the extension separate from a Claude subscription. ### Why did the extension stop working after a Chrome update? Chrome updates occasionally break extension compatibility if the installed version is out of date. Go to `chrome://extensions`, enable Developer mode, and click Update to force the latest version. Most issues after a Chrome update resolve with a forced extension update and a browser restart. ### Can another extension cause the Claude extension to break? Yes. Ad blockers and privacy extensions can block requests between the Claude side panel and claude.ai. Test in incognito with other extensions disabled to isolate the conflict. Add claude.ai to your ad blocker's allowlist if that is the cause. ### Does the Claude Chrome extension work on all websites? It works on most websites you grant explicit access to. Exceptions: `chrome://` internal pages, the Chrome Web Store, and sites Anthropic blocks by policy (financial services, adult content). Dynamic single-page applications sometimes present incomplete DOM content if you prompt before the page finishes loading. --- ## Related guides - [Claude Chrome extension guide](/blog/claude-chrome-extension): setup, use cases, and the privacy trade-off - [How to use Claude Code](/blog/how-to-use-claude-code): the complete beginner guide to working with Claude in the terminal - [Claude Code on the web](/blog/claude-code-web): how Claude Code connects to browser workflows ## Sources and citations - [Claude AI for Chrome on the Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) - [Claude for Chrome: Anthropic documentation](https://docs.anthropic.com/en/docs/about-claude/claude-for-chrome) - [Claude for Chrome documentation (docs.claude.com)](https://docs.claude.com/en/docs/claude-for-chrome) - [Getting started with Claude for Chrome (Anthropic support)](https://support.anthropic.com/en/articles/12012173-getting-started-with-claude-for-chrome) - [Claude for Chrome announcement (Anthropic)](https://www.anthropic.com/news/claude-for-chrome) --- # Best MCP servers for Claude Code (my stack) Source: https://theaiarchitects.com/blog/best-mcp-servers-for-claude-code Published: 2026-06-14 The best MCP servers for Claude Code connect it to the tools you already work in. Here are the ones I run every day, plus how to add them. The best MCP servers for Claude Code are the ones that plug it into the tools you already work in: your database, your browser, your repo, your docs, your analytics. An MCP server is a small connector that gives Claude Code a set of real actions inside an outside system, so instead of guessing it can read a live Airtable record, drive a real browser, or open a pull request for you. I run more than twenty MCP servers in Claude Code across my own business and my mentorship cohort. Some I use every single day. Most of the ones people install never get touched again. This post is the working list: the servers worth your time, the exact stack I run, and how to add one in about two minutes. > [CTA-BLUEPRINT] ## What is an MCP server in Claude Code? An MCP server is a connector that exposes a specific tool or service to Claude Code through the Model Context Protocol. MCP is an open standard Anthropic released in late 2024, and it does for AI tools what USB-C did for hardware. One protocol, any number of connectors, no custom glue code per integration. In plain terms, a server hands Claude Code a menu of actions. The GitHub server gives it "list pull requests," "create issue," "read file." The Playwright server gives it "open page," "click," "screenshot." Claude decides which action to call, the server runs it against the real system, and the result comes back into the conversation. The model stops describing what you could do and starts doing it. If you want the deeper mechanics of the protocol itself, I covered that in my [Claude Code MCP guide](/blog/claude-code-mcp). This post is about which servers actually earn a slot. ## How do MCP servers work in Claude Code? MCP servers run as separate processes that Claude Code talks to over one of two transports. Local servers run on your machine and connect over stdio, which is standard input and output. Remote servers run somewhere else and connect over HTTP. You do not need to know the difference to use them, but it explains why some servers need a command on your machine and others just need a URL and a token. Claude Code reads its server list from a config file. Project servers live in a `.mcp.json` file at the root of the repo, so everyone on the team gets the same stack. User servers live in your global config and follow you across every project. When Claude Code starts, it launches each server, asks what tools it offers, and adds those tools to the session. The practical takeaway is that adding a server does not change Claude. It changes what Claude can reach. ## The MCP servers I actually run in Claude Code My daily stack is built around the systems my business runs on, not a generic "top 10" list. Here is the project-scoped block from my `.mcp.json`, with the secrets pulled out into environment variables so nothing sensitive sits in the file: The Airtable server is the one I would lose sleep over. My sales pipeline and application briefs live in Airtable, and a couple of times an hour Claude Code pulls new applications into pre-call briefs without me touching the base. The PostHog server reads product analytics for the apps I run, so I can ask "which onboarding step are people dropping at" and get a real answer from real events. The Obsidian server points at my entire operating system, more than four thousand markdown notes, so Claude can search and edit the business itself. GitHub handles pull requests and issues across every repo. That is the proprietary angle nobody else can copy. The best MCP stack is not a leaderboard. It is a mirror of the tools your work already lives in. ## The best MCP servers for Claude Code These are the servers I recommend most people install first, in rough order of how often they earn their keep. Each one is a clean, single-purpose connector with an official or well-maintained source. ### 1. Context7 (live documentation) Context7 pulls current, version-specific documentation into Claude Code so it stops writing code against APIs that changed a year ago. It is the single highest-leverage server for anyone writing real code, because it kills the most common failure mode: confident, outdated answers. I wrote a full walkthrough in my [Context7 MCP guide](/blog/context7-mcp). ### 2. Playwright (browser control and testing) The Playwright server lets Claude Code drive a real browser: open pages, click, fill forms, take screenshots, and run end-to-end tests. It is the most-searched MCP integration in the Claude Code niche right now, and for good reason. You can hand Claude a failing UI and it can actually look at the page instead of guessing. Microsoft maintains it, and the install is a single command. Full walkthrough in my [Playwright MCP for Claude Code](/blog/playwright-mcp-claude-code) guide. ### 3. GitHub (repos, pull requests, issues) The GitHub server connects Claude Code to your repositories so it can read code across branches, open and review pull requests, file issues, and check CI status without you leaving the terminal. GitHub ships an official server, which is exactly the kind of primary-source connector you want over a random community fork. I broke down the full setup in my [GitHub MCP for Claude Code](/blog/github-mcp-claude-code) guide. ### 4. Filesystem (controlled local file access) The Filesystem server gives Claude scoped read and write access to directories you choose. It is the quiet workhorse for anyone working across files outside the current repo, like a notes folder, a downloads directory, or a separate assets project. You decide the boundaries, and Claude stays inside them. ### 5. Supabase (database and backend) The Supabase server lets Claude Code query your database, inspect your schema, and manage your backend directly. If you are vibe-coding a real app, this turns "write me a migration" into "write and check the migration against my actual schema." Supabase maintains it officially. Full setup and the tools it exposes are in my [Supabase MCP for Claude Code](/blog/supabase-mcp-claude-code) guide. ### 6. Figma (design to code) The Figma server reads your design files so Claude Code can turn a frame into real, matching front-end code. It is the cleanest bridge I have used between a designer's file and a working component. Figma ships the official Dev Mode server. ### 7. Your business systems (the ones that pay off) The servers that compounded for me are the boring ones wired into my actual operation: Airtable for the pipeline, PostHog for analytics, Stripe for revenue questions, Gmail and Google Drive for the back office. None of these will show up on a generic "best MCP" list, and that is the point. The best MCP server for you is the one connected to the system you check twenty times a day. One of my mentorship clients, Keven, rebuilt a seven-year-old content workflow into a system that runs in minutes, and MCP servers were part of how he wired the pieces together. The full breakdown is in his [case study](/case-studies/keven). ## How to add an MCP server to Claude Code Adding a server takes one command. The fastest path is the `claude mcp add` command, which writes the config for you. ### 1. Add a local server Run `claude mcp add` with a name and the command that starts the server. For example, a filesystem server looks like this: The double dash separates the Claude Code flags from the command Claude should run. Everything after it is the server's own startup command. ### 2. Add a remote server For an HTTP server, pass the transport and the URL. Many hosted servers also need an auth header: ### 3. Choose the scope By default a server is added for you only. Add `--scope project` to write it into the repo's `.mcp.json` so your whole team inherits it, or `--scope user` to make it follow you across every project. Project scope is what you want for anything the team shares. ### 4. Confirm it connected Run `claude mcp list` to see every server and its health. A green check means Claude Code can reach it. A "needs authentication" flag means the server loaded but you still have to log in, which you do with `claude mcp` auth prompts or the server's own flow. > [CTA-BLUEPRINT] ## How to configure MCP servers in .mcp.json You can skip the commands and edit `.mcp.json` directly, which is what I do once a stack settles. The file lives at the repo root and holds one entry per server under `mcpServers`. Local servers take a `command` and `args`. Remote servers take a `type` of `http` and a `url`. Never paste a raw API key into the file. Use the `${VAR}` syntax shown in my stack above and keep the real values in your shell environment or a gitignored `.env`. This keeps secrets out of version control, which matters the moment a repo goes anywhere near public. Claude Code expands those variables at launch. ## Where MCP servers fall short MCP servers are not free in the way that matters most: context. Every server you load injects its tool definitions into the model's context window, so a machine stuffed with thirty servers spends tokens describing tools Claude will never call in that session. I run a large stack, but I prune it per project, and I keep noisy servers in user scope so they are not forced on every repo. The other real cost is trust. An MCP server can run commands and touch live systems, so you are extending real permissions to it. Install official or well-known servers, read what actions a server exposes before you wire it into a project, and never give a server credentials it does not need. A server with write access to your production database is convenient right up until it is not. Authentication churn is the last papercut. Remote servers expire tokens and drop connections, and you will see "needs authentication" in `claude mcp list` more often than you would like. It is a minor tax, not a dealbreaker. ## Best MCP servers for Claude Code: my verdict If you are starting from zero, install three: Context7 so Claude writes code against current docs, Playwright so it can see and test the browser, and GitHub so it can work your repo. That covers the writing, testing, and shipping loop, and it is enough to feel the difference immediately. After that, stop chasing the leaderboard and wire in the systems your work actually runs on. The Airtable, PostHog, and Stripe servers do more for my day than any "top MCP servers" list ever could, because they are connected to the business instead of a demo. Add servers when a real task needs one, not because a post told you to. > [CTA-BLUEPRINT] ## Claude Code MCP FAQ ### What is the best MCP server for Claude Code? For most people the best first MCP server is Context7, because it keeps Claude Code writing code against current documentation instead of outdated training data. Playwright and the official GitHub server are the next two to add. The best long-term server is whichever one connects to the system you use most. ### How many MCP servers should I run in Claude Code? Run as few as you actively use per project. Each server adds its tool definitions to the context window, so a bloated stack wastes tokens and can slow Claude down. I keep shared servers in project scope and personal ones in user scope, and I prune anything I have not called in weeks. ### Are MCP servers free? Most MCP servers are free and open source, including Playwright, Filesystem, and the official GitHub and Supabase servers. You pay only for the underlying service if it charges, such as a paid API tier. The server itself is just a connector. ### Where are MCP servers configured in Claude Code? Project servers are configured in a `.mcp.json` file at the root of the repo, which is shared with your team. User servers live in your global Claude Code config and follow you across projects. You can edit either file directly or use the `claude mcp add` command to write the entry for you. ### What is the difference between a local and a remote MCP server? A local server runs as a process on your machine and connects over stdio, so it needs a command like `npx`. A remote server runs elsewhere and connects over HTTP, so it needs a URL and usually an auth token. Local servers suit tools that touch your filesystem, and remote servers suit hosted services. ### Can MCP servers slow down Claude Code? Yes. Every loaded server injects its tool list into the context window, so running many servers at once consumes tokens and can make responses slower. Keep your active stack lean per project and the overhead stays small. ### How do I remove an MCP server from Claude Code? Run `claude mcp remove ` to delete a server, or delete its entry from `.mcp.json` by hand. Run `claude mcp list` afterward to confirm it is gone. Removing a server you are not using is the simplest way to reclaim context. ### Do MCP servers work in Claude Desktop too? Yes. MCP is the same open standard across Claude Code, Claude Desktop, and other MCP-aware clients, so most servers work in all of them. The config location differs per app, but the servers themselves are interchangeable. ## Sources and citations - [Model Context Protocol](https://modelcontextprotocol.io) — the open standard MCP servers are built on. - [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) — official setup and scope reference. - [GitHub MCP server](https://github.com/github/github-mcp-server) — the official GitHub connector. - [Playwright](https://playwright.dev) — Microsoft's browser automation framework behind the Playwright MCP server. ## Ready to put Claude Code to work? You do not need twenty MCP servers to get value out of Claude Code. You need the three that cover writing, testing, and shipping, plus one wired into the system your work actually runs on. Start there, add servers when a real task demands one, and let the stack grow around how you work instead of a list. If you want the guided version, my free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. ## Related guides - [Blender MCP: Control Blender With Claude (Setup + Real Examples)](/blog/blender-mcp) --- # Claude Code vs Codex: When I Use Each (Honest Take) Source: https://theaiarchitects.com/blog/claude-code-vs-codex Published: 2026-06-14 Claude Code vs Codex from someone who runs both. The real differences, when I reach for Codex, and why Claude Code stays my default driver. Claude Code and Codex are both terminal-first AI coding agents that read your files, write code, run commands, and work across a whole project instead of handing you a snippet. Claude Code is Anthropic's agent. Codex is OpenAI's. They overlap heavily, and the honest answer to "which is better" is that I run both, Claude Code is my default, and Codex is the tool I reach for when I want a second opinion. To be clear about names: Codex here means OpenAI's current coding agent, not the old 2021 Codex model that powered early Copilot. I'm Tom, I run Claude Code all day and keep Codex wired in as a rescue. This is the comparison from actually using them, not a spec-sheet readout. [CTA-BLUEPRINT] ## What is the difference between Claude Code and Codex? The core difference is the company and the model behind the agent, not the shape of the tool. Claude Code is Anthropic's coding agent and runs on Claude models. Codex is OpenAI's coding agent and runs on OpenAI's models. Both live in your terminal, both can plan and edit across files, and both run commands and tests on your behalf. If you have used one, the other will feel familiar fast. Where they diverge is the surrounding ecosystem and the defaults. Claude Code leans hard into a deep extension layer: skills, hooks, subagents, slash commands, and MCP servers that let you shape the agent around your exact workflow. Codex comes bundled with a ChatGPT subscription and leans into multiple surfaces, including a CLI, an IDE extension, and a desktop app. The agent loop is similar. The thing built around the loop is where each shows its personality. ## How does Codex work? Codex is OpenAI's coding agent, and it is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans rather than sold as a separate product. That bundling matters: if you already pay for ChatGPT, you already have Codex. It can write code that matches your project structure, explain unfamiliar codebases, review code for bugs, debug failures, and automate refactors and migrations. Codex ships in three main forms. There is a CLI for working in the terminal, an IDE extension for working inside your editor, and a desktop app with its own local environment and review features. You point it at a task, it plans and edits, and you approve the changes. The workflow will feel immediately recognisable to anyone who has used Claude Code, because the agentic loop of plan, edit, run, review is the shared foundation of this whole category. ## How I actually use Claude Code and Codex together I do not pick one and abandon the other. I run Claude Code as my primary driver and keep Codex as a second opinion, and that split is deliberate. When Claude Code gets stuck on a gnarly bug, or I want a different model's take on an approach before I commit to it, I hand the same problem to Codex and compare. Two strong agents from two different labs rarely fail in the same place, so the disagreement itself is useful information. This is easier than it sounds because I can trigger Codex from inside Claude Code through a plugin, so the second opinion is one command away rather than a context switch into another tool. The pattern is simple: Claude Code does the building, and Codex is the rescue I call when the first pass stalls or the stakes are high enough to want a sanity check. Most days I barely touch it. On the hard days it earns its place. If you want the broader picture of how I run Claude Code day to day, my [how to use Claude Code](/blog/how-to-use-claude-code) guide covers the core workflow. ## Claude Code vs Codex: the comparison that matters On raw capability the two are close, so the decision comes down to ecosystem, pricing model, and which model you trust on hard problems. Here is the split as I see it after running both. - **Model**: Claude Code runs on Anthropic's Claude models. Codex runs on OpenAI's models. On genuinely hard problems, a second model is worth having, which is the whole reason I keep both. - **Pricing**: Claude Code comes with a paid Claude subscription. Codex is included with a ChatGPT subscription. If you already pay for one of those, that agent is effectively free to you. - **Extensibility**: Claude Code has the deeper customization layer I rely on, with skills, hooks, subagents, and MCP servers. This is the single biggest reason it is my default. - **Surfaces**: Codex spreads across a CLI, an IDE extension, and a desktop app. Claude Code is CLI-first with a strong VS Code and Cursor integration. - **Role in my workflow**: Claude Code is the everyday driver. Codex is the situational second opinion. For how Claude Code stacks up against the other tools in this space, I compared it directly in [Claude Code vs Cursor](/blog/claude-code-vs-cursor) and [Claude Code vs Copilot](/blog/claude-code-vs-copilot). ## When should you use Codex over Claude Code? Use Codex over Claude Code when you want a second model's take on a hard problem, when Claude Code has stalled on a bug after a couple of passes, or when you already pay for ChatGPT and not for Claude. Those are the three honest cases. A different lab's model genuinely fails differently, so a stubborn problem that beats one agent will sometimes fall to the other on the first try. Use Claude Code as your default for everything else, especially if you lean on customization. The skills, hooks, subagents, and MCP ecosystem are what turn a general coding agent into a system shaped around your work, and that is where Claude Code pulls ahead for how I operate. The right answer for a lot of people is not one or the other. It is one as the driver and the other as the backup. ## Where each one falls short Claude Code's weak spot is that its depth has a learning curve. The extension layer that makes it powerful, the skills and hooks and subagents, is also more to learn than a tool that just answers prompts. If you only want quick inline help, that depth is overhead you will not use. It also requires a paid Claude plan, which is a second subscription if you already live in ChatGPT. Codex's weak spot, for me, is exactly the mirror image: a thinner customization story than Claude Code's. It is an excellent agent, but I do not get the same deep hooks-and-skills control over how it behaves, which is why it stays my second opinion rather than my driver. Your mileage flips if you are already deep in the OpenAI ecosystem and value the bundling with ChatGPT more than the extension layer. Neither tool is bad. They are tuned for slightly different operators. [CTA-BLUEPRINT] ## Claude Code vs Codex FAQ ### Is Claude Code or Codex better? Neither is strictly better. Claude Code has the deeper customization layer with skills, hooks, subagents, and MCP servers, while Codex comes bundled with a ChatGPT subscription and spreads across a CLI, IDE extension, and desktop app. I run Claude Code as my default and use Codex as a second opinion on hard problems. ### Can you use Claude Code and Codex together? Yes, and it is a strong setup. I run Claude Code as my primary agent and hand the same problem to Codex when I want a second model's take or when Claude Code has stalled. Two agents from different labs rarely fail in the same place, so comparing their answers is genuinely useful. ### Is Codex free? Codex is included with ChatGPT Plus, Pro, Business, Edu, and Enterprise plans rather than sold separately, so if you already pay for ChatGPT you already have it. Claude Code similarly comes with a paid Claude subscription. In both cases you are paying for the subscription, and the coding agent is bundled in. ### What model does Codex use? Codex runs on OpenAI's models, the same way Claude Code runs on Anthropic's Claude models. The practical takeaway is that they are built on different model families, which is exactly why running both gives you two genuinely different perspectives on a hard problem. ### When should I use Codex instead of Claude Code? Reach for Codex when you want a second opinion on a tough problem, when Claude Code has been stuck for a couple of passes, or when you pay for ChatGPT but not for Claude. For everyday driving, especially if you use customization like skills and hooks, Claude Code is the stronger default. ### Does Codex work in the terminal like Claude Code? Yes. Codex ships a CLI that works in the terminal much like Claude Code, alongside an IDE extension and a desktop app. The core agentic loop of plan, edit, run, and review is shared across both tools, so the terminal experience will feel familiar if you move between them. ## Sources and citations - [OpenAI Codex](https://developers.openai.com/codex/) — what Codex is, its plan access, and its CLI, IDE, and app surfaces. - [Anthropic: Claude Code](https://www.anthropic.com/claude-code) — Anthropic's coding agent and positioning. - [Claude Code overview](https://code.claude.com/docs/en/overview) — how the Claude Code agent operates. ## Ready to get more out of your coding agent? Whichever agent you drive, the leverage is in knowing what to point it at and how to shape it around your work. My free Claude Code Blueprint walks you through your first real build in about sixty minutes, and the Challenge is where operators turn it into a system. Start with the Blueprint. --- # Supabase MCP for Claude Code: Setup and What It Does Source: https://theaiarchitects.com/blog/supabase-mcp-claude-code Published: 2026-06-14 The Supabase MCP server lets Claude Code query your database, run migrations, and read logs. Here's how I add it and what I actually use it for. The Supabase MCP server connects Claude Code directly to your Supabase project so it can query your database, inspect and change your schema, run migrations, read logs, and generate types, all from the terminal. It turns "write me a migration" into "write the migration, run it against my real schema, and check it worked." I run the official Supabase MCP server in Claude Code, added in one command, and I use the full surface of it: querying data, managing schema and migrations, building app features, and pulling logs when something breaks. I'm Tom, and this is the setup I use plus the honest version of what the integration is good and bad at. If you want the wider picture first, this is one server in my [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code) stack. [CTA-BLUEPRINT] ## What is the Supabase MCP server? The Supabase MCP server is an official connector that exposes your Supabase project to AI tools through the Model Context Protocol. Supabase maintains it, and it runs as a remote server hosted by Supabase rather than something you install locally. Once it is wired into Claude Code, the agent gets a menu of real actions against your project: list tables, run SQL, apply a migration, fetch logs, generate TypeScript types, and more. In plain terms, it is the difference between Claude guessing about your database and Claude reading it. Without the server, Claude writes a migration against the schema it imagines you have. With it, Claude lists your actual tables, writes the migration against what is really there, and can run it and confirm the result. For the underlying protocol mechanics, my [Claude Code MCP guide](/blog/claude-code-mcp) covers how MCP works in general. ## How does the Supabase MCP work in Claude Code? The Supabase MCP is a remote HTTP server. Claude Code connects to it over a URL at `mcp.supabase.com`, and you authenticate with a Supabase personal access token passed as a bearer header. You scope it to a single project with a `project_ref` parameter, so the agent only ever sees the project you point it at. This is different from a local server like Filesystem, which runs as a process on your machine. The Supabase server runs on Supabase's side, and Claude Code just talks to it. Two parameters shape how safe and focused it is. The `project_ref=` parameter locks the connection to one project. The `read_only=true` parameter forces every query to run as a read-only Postgres user, so the agent can look but not change anything. You bolt these onto the server URL, and they are the difference between a tightly scoped helper and a wide-open connection. ## How to add the Supabase MCP to Claude Code Adding the Supabase MCP takes four steps. This is the official server, and the whole thing is a couple of minutes. ### 1. Create a Supabase personal access token Go to your Supabase access tokens page and create a personal access token. This is what authenticates Claude Code to your account. Treat it like a password and keep it out of any file that goes near version control. Store it in your shell environment as something like `SUPABASE_ACCESS_TOKEN`. ### 2. Add the server with claude mcp add Run `claude mcp add` with the HTTP transport, the Supabase URL scoped to your project, and the token as an auth header: Swap `YOUR_PROJECT_REF` for your project's reference id. The command writes the entry into your config so you do not have to edit JSON by hand. ### 3. Decide on read-only and scope Keep `read_only=true` in the URL whenever the agent is touching real data you care about. Drop it only when you actually want Claude to write, such as applying migrations against a development project. The `project_ref` parameter should always be set, so the connection can never wander into another project by accident. ### 4. Confirm it connected Run `claude mcp list` to check the server's health. A green check means Claude Code reached it. If it shows "needs authentication," complete the auth flow and re-run the check. Once it is green, ask Claude something simple like "list my tables" to confirm the tools are live. ## What I use the Supabase MCP for I use the Supabase MCP across the full lifecycle of building on Supabase, not just one trick. Four jobs come up constantly. The first is querying and inspecting the database, where I ask Claude to pull real rows or describe a table instead of opening the dashboard. The second is schema and migrations, where Claude writes a migration against my actual tables and applies it, then I confirm the change landed. The third is building app features end to end, where the agent reads the schema, writes the data layer, and generates matching TypeScript types so the front end and the database stay in sync. The fourth is debugging, where I have Claude pull logs and run the advisors to find what is slow or misconfigured. That last one is the quiet winner. Asking "check the logs and tell me why this query is failing" and getting a real answer from the real project beats guessing every time. ## Supabase MCP tools The server groups its tools by job, and knowing the groups helps you reason about what you are granting access to. The main ones are worth knowing before you wire it in. - **Database**: `list_tables`, `list_extensions`, `list_migrations`, `apply_migration`, and `execute_sql` for reading and changing the database. - **Debugging**: `get_logs` and `get_advisors` for diagnosing issues and surfacing security or performance warnings. - **Development**: `get_project_url`, `get_publishable_keys`, and `generate_typescript_types` for wiring an app to the project. - **Edge Functions**: list, read, and deploy Supabase Edge Functions. - **Branching** (paid plans): create and manage database branches for safe testing. Storage tools are disabled by default, and you can use the `features` parameter to enable only the tool groups you actually need, which keeps the surface small. ## Where the Supabase MCP falls short The biggest caveat is not a flaw in the server, it is a rule you have to follow: do not point it at production. Supabase says it plainly, and so do I. Use the MCP server with a development project, keep `read_only=true` on whenever it touches real data, and use a database branch to test anything risky. An agent with write access to your production database is convenient right up until a bad migration runs against live customer data. The other cost is the usual MCP tax. Every tool the server exposes adds its definition to Claude's context window, so enabling every feature group on a project you barely touch is wasted context. Scope it with `project_ref`, trim the feature groups you do not use, and keep it lean. For more on that trade-off, and the rest of my stack, see [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code), and for two more official connectors worth adding, my [GitHub MCP](/blog/github-mcp-claude-code) and [Playwright MCP](/blog/playwright-mcp-claude-code) guides. [CTA-BLUEPRINT] ## Supabase MCP FAQ ### How do I add the Supabase MCP to Claude Code? Create a Supabase personal access token, then run `claude mcp add --transport http supabase` with the `mcp.supabase.com` URL scoped to your `project_ref` and the token as a bearer Authorization header. Run `claude mcp list` to confirm it connected. The whole setup takes a couple of minutes because it is a hosted server, not a local install. ### Is the Supabase MCP server official? Yes. Supabase maintains the Supabase MCP server officially and hosts it as a remote server at `mcp.supabase.com`. Using the official server is safer than a community fork because you know exactly who maintains it and what actions it exposes. ### What can the Supabase MCP do in Claude Code? It lets Claude Code list and query tables, run SQL, apply migrations, read logs, run security and performance advisors, generate TypeScript types, and manage Edge Functions. In practice that covers inspecting your data, changing your schema, building app features against the real project, and debugging issues. ### Is the Supabase MCP safe to use? It is safe when scoped correctly. Keep `read_only=true` on for real data, always set `project_ref` to lock it to one project, and never connect it to production. Supabase recommends using a development project and database branches for anything risky. The token authenticates full account access, so treat it like a password. ### Do I need a personal access token for the Supabase MCP? You need a personal access token to authenticate in a setup like Claude Code's, where you pass it as a bearer header. Create it on your Supabase access tokens page and store it in your shell environment rather than in any committed file. The token is what lets the hosted server act on your account. ### Can the Supabase MCP run migrations? Yes. The `apply_migration` tool lets Claude Code write and run a migration against your project, and `list_migrations` shows what has already run. Do this against a development project with write access enabled, not production, and confirm the change afterward. Pairing it with database branching keeps risky migrations isolated. ## Sources and citations - [Supabase MCP server](https://supabase.com/docs/guides/getting-started/mcp) — official setup, tool list, and security guidance. - [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) — how to add and scope MCP servers in Claude Code. - [Model Context Protocol](https://modelcontextprotocol.io) — the open standard the Supabase server is built on. ## Ready to build on Supabase with Claude Code? Wiring the Supabase MCP into Claude Code is the moment the agent stops guessing about your backend and starts working against the real thing. If you want the guided path from zero to a working build, my free Claude Code Blueprint walks you through your first real project in about sixty minutes, no coding required. --- # Claude Code in Cursor: How I Run It (and Skip Cursor AI) Source: https://theaiarchitects.com/blog/claude-code-in-cursor Published: 2026-06-13 How to run Claude Code in Cursor: the integrated-terminal CLI setup, the extension panel, IDE diff viewing, and why I use Cursor as just an editor. You run Claude Code in Cursor by opening Cursor's integrated terminal and running the `claude` command, or by installing the Claude Code extension for a graphical panel. Cursor is a fork of VS Code, so the same Claude Code tooling that works in VS Code works in Cursor with no extra steps. This is not a comparison post. If you want Claude Code versus Cursor head to head, I wrote that separately in [Claude Code vs Cursor](/blog/claude-code-vs-cursor). This is the how-to for people who already use Cursor and want Claude Code running inside it. I'm Tom, and here is the honest version: I run Claude Code in Cursor's integrated terminal all day, and I barely touch Cursor's own AI. Cursor is my editor. Claude Code is the brain. Here is the exact setup and why I run it that way. [CTA-BLUEPRINT] ## What does running Claude Code in Cursor mean? Running Claude Code in Cursor means using Anthropic's agent inside the Cursor editor instead of, or alongside, Cursor's built-in AI features. There are two ways to do it. The first is the command-line interface in Cursor's integrated terminal, where you type `claude` and work in the CLI. The second is the Claude Code extension, which adds a graphical chat panel to Cursor. Both run in Cursor because it is a VS Code fork. The Claude Code extension installs in VS Code forks like Cursor, Devin Desktop, and Kiro, and the CLI runs in any terminal, including Cursor's. The two share the same conversation history and the same settings file, so you can start in one and continue in the other. I use the terminal path, which I will come back to, but I will cover both so you can pick. ## How do you run Claude Code in Cursor? Getting Claude Code running in Cursor takes four steps for the terminal path. This is the setup I actually use. ### 1. Install the standalone Claude Code CLI The Claude Code extension bundles its own private copy of the CLI for its chat panel, but that copy is not on your shell PATH. To type `claude` in Cursor's terminal, you need the [standalone CLI install](https://code.claude.com/docs/en/setup). Install it once and the command works in any terminal. If `claude` is still not found afterwards, check your PATH. After that, [keep Claude Code up to date](/blog/claude-code-update) so the Cursor integration gets fixes early. ### 2. Open Cursor's integrated terminal and run claude Open the integrated terminal with `Cmd+` backtick on Mac or `Ctrl+` backtick on Windows and Linux, then type `claude` and hit enter. Sign in with your Claude account on first run. No API key is needed for a paid Claude subscription. You are now in a full Claude Code session inside Cursor. ### 3. Run terminal-setup so Shift+Enter works Cursor needs one command to fix multi-line input and a couple of editor quirks. Run `/terminal-setup` once inside Cursor. It writes the Shift+Enter keybinding so you can add newlines without sending, sets `terminal.integrated.gpuAcceleration` to off to stop garbled text, and adjusts scroll sensitivity. Existing keybindings are left in place. ### 4. Let the IDE integration connect When you run the CLI in Cursor's integrated terminal, Claude Code automatically connects to the editor. That connection is what opens its file edits in Cursor's native side-by-side diff viewer and lets it read your current selection and the language-server errors from the Problems panel. If you are running Claude Code in an external terminal instead, run `/ide` inside the session to connect it to Cursor manually. ### Or install the extension for a graphical panel If you prefer a graphical chat panel over the CLI, install the extension. Open the Extensions view with `Cmd+Shift+X` or `Ctrl+Shift+X`, search for "Claude Code", and install, or install from the Open VSX registry. The Spark icon then appears in the editor toolbar when a file is open. The panel gives you plan review, click-to-accept diffs, @-mentions, and conversation history in a sidebar. ## Why I use Cursor as just an editor I run Claude Code in the integrated terminal and let Cursor be a plain editor, and I do almost nothing with Cursor's own AI. This sounds wasteful given what Cursor charges for, and I have thought about it. The reason is simple: Claude Code is a more capable agent for the way I work, and I would rather have one tool driving everything than split my attention between two AI systems with different memories and different habits. Cursor still earns its place. Its diff viewer, file tree, git panel, and extensions are a comfortable shell to read and review Claude's work in. The IDE integration means every edit Claude proposes shows up in Cursor's native diff view, so I get the agent of Claude Code with the review experience of a real editor. That combination is the whole point. The CLI does the thinking, Cursor shows me the result in a window I trust. ## Claude Code CLI vs the Cursor extension panel The CLI and the extension share history and settings, but they are not feature-identical. The CLI is the complete product. The extension is a graphical subset with a few editor-native extras of its own. Here is the split that matters. The CLI has the full set of commands and skills, the `!` bash shortcut for running a shell command inline, and tab completion. The extension exposes only a subset of commands, has no `!` bash shortcut, and has no tab completion. What the extension adds is graphical: plan review as an editable markdown document, click-to-accept diffs, the `Option+K` shortcut to insert an `@file#5-10` reference from your selection, checkpoints to rewind Claude's edits, and a sidebar of past conversations. If you need a CLI-only feature while living in the panel, just open the integrated terminal and run `claude` there. They stay in sync. ## Claude Code in Cursor vs Cursor's own AI If you are deciding whether to run Claude Code in Cursor or lean on Cursor's native AI, the honest answer is that it depends on the size of the job. Cursor's Tab autocomplete and inline edits are fast and excellent for small, local changes while you type. Claude Code is the stronger choice for multi-file, agentic work where you describe an outcome and let it plan, edit across the codebase, and run commands. My verdict, for how I work, is that Claude Code is the main driver and Cursor's AI is the part I skip. I am not telling you to cancel Cursor. I am telling you that if you already pay for it, you can run a more capable agent inside it and use Cursor for what it is genuinely great at, which is being a fast, familiar editor. For the full side-by-side, see [Claude Code vs Cursor](/blog/claude-code-vs-cursor), and if you are weighing other assistants, [Claude Code vs Copilot](/blog/claude-code-vs-copilot) covers that pairing. ## Where running Claude Code in Cursor falls short The setup has rough edges worth knowing before you commit. The biggest is that installing the extension does not put `claude` on your PATH, so people assume the terminal command is broken when they just need the standalone CLI install. The extension panel is also a subset of the CLI, so power users miss the `!` bash shortcut and tab completion until they drop into the terminal. Background process visibility is weaker in the panel than in the CLI, so long-running commands are easier to track in the terminal. And on macOS Tahoe and later, the system Game Overlay binds `Cmd+Esc`, which intercepts the extension's focus shortcut until you clear it in System Settings under Keyboard, Keyboard Shortcuts, Game Controllers. None of these are dealbreakers, but they are the friction points that send people to a troubleshooting page. To go deeper on the CLI itself, my [Claude Code commands](/blog/claude-code-commands) reference and the [how to use Claude Code](/blog/how-to-use-claude-code) guide cover the workflow once you are set up. [CTA-BLUEPRINT] ## Claude Code in Cursor FAQ ### How do I use Claude Code in Cursor? Install the standalone Claude Code CLI, open Cursor's integrated terminal with `Cmd+` backtick or `Ctrl+` backtick, and run `claude`. Sign in on first launch. For a graphical panel instead, install the Claude Code extension from the Extensions view or the Open VSX registry. Both work because Cursor is a VS Code fork. ### Does the Claude Code extension work in Cursor? Yes. The Claude Code extension installs in VS Code forks including Cursor. Open the Extensions view with `Cmd+Shift+X` or `Ctrl+Shift+X`, search for "Claude Code", and install, or install from the Open VSX registry. After installing, the Spark icon appears in the editor toolbar when a file is open. ### Do I need an API key to run Claude Code in Cursor? No. Any paid Claude subscription such as Pro, Max, Team, or Enterprise works, and you sign in with that account on first launch. No API key is required unless you access Claude through a third-party provider like Amazon Bedrock or Google Vertex AI. ### Why does typing claude in Cursor's terminal say command not found? The extension bundles a private copy of the CLI for its chat panel, but it does not add `claude` to your shell PATH. Install the standalone Claude Code CLI once and the command works in Cursor's terminal and any other terminal. If it is still not found, verify your PATH. ### Can Claude Code show diffs inside Cursor? Yes. When you run the CLI in Cursor's integrated terminal, Claude Code connects to the editor automatically and opens its proposed edits in Cursor's native side-by-side diff viewer. If you run Claude Code in an external terminal, run `/ide` inside the session to connect it to Cursor. ### Should I use Claude Code or Cursor's own AI? Use Cursor's Tab and inline edits for small, fast changes as you type, and use Claude Code for multi-file, agentic work where you describe an outcome and let it run. They are complementary. I run Claude Code as my main driver and use Cursor mostly as the editor, but both approaches are valid. ### Do Claude Code and the Cursor extension share history? Yes. The CLI and the extension share the same conversation history and the same `~/.claude/settings.json` settings file. You can start a conversation in the panel and continue it in the terminal with `claude --resume`, or the other way around. ## Sources and citations - [Use Claude Code in VS Code](https://code.claude.com/docs/en/ide-integrations) — the extension, integrated-terminal CLI, IDE diff viewing, and the CLI-versus-extension feature split. - [Configure your terminal for Claude Code](https://code.claude.com/docs/en/terminal-config) — the `/terminal-setup` command and Cursor-specific keybinding fixes. - [Set up Claude Code](https://code.claude.com/docs/en/setup) — the standalone CLI install that puts `claude` on your PATH. ## Ready to get more out of Claude Code? Running Claude Code in Cursor is the easy part. The leverage comes from knowing what to point it at. The free Blueprint walks you through your first real Claude Code build in 60 minutes, and the Challenge is where operators turn it into a system. Start with the Blueprint. --- # Git Workflow for Claude Code: Solo and Team Guide Source: https://theaiarchitects.com/blog/git-workflow-claude-code Published: 2026-06-12 I ran feature branches on a one-person project for months. Here's the git system that actually works for solo Claude Code operators and teams. The right git workflow for Claude Code depends on one thing: whether you're building alone or with a team. I ran three feature branches on a one-person project for months and pushed almost none of them to GitHub. The worst one, `chore/scrub-mcp-secrets`, sat unmerged long enough to accumulate 191 files across accounting scripts, session logs, agent state, and a dozen other areas that had nothing to do with scrubbing secrets. I'm Tom. I build AI systems professionally and teach Claude Code to solo operators and teams. I was using git and GitHub wrong for months. This is the system I switched to. > [CTA-BLUEPRINT] ## What is the right git workflow for Claude Code? Git's entire branching model was designed to protect developers from each other. On a team, branches keep one person's unfinished work from breaking another person's day. That's the whole job. When you're the only developer in the codebase, that problem doesn't exist. There's no one to protect the code from except past-you. Solo operators don't need branches as a workflow. They need a backup system, and the two things look similar on the surface while working completely differently underneath. For solo operators: stay on master, commit after every Claude Code session, push to GitHub at natural checkpoints. For teams: one branch per task, kept short-lived, with Claude handling the commit message and PR description. Merge it and delete it immediately. ## How does git work with Claude Code? Claude Code runs git commands directly through natural language. You don't write the commands yourself. Tell Claude what you want, it stages the files, writes a commit message from the actual diff, and runs the push. This works in both the terminal version and the Desktop app. If you're new to Claude Code and haven't set it up yet, the [beginner's guide to Claude Code](/blog/how-to-use-claude-code) covers installation and your first session before you worry about git. ### Committing with Claude Code in the terminal At the end of a session, say: "commit and push all the changes with a descriptive message." Claude stages the modified files, reads the diff, writes a commit message in conventional format, and pushes to origin. The whole operation takes about ten seconds and you never write a git command. ### Committing with Claude Code on desktop The Desktop Claude Code app works identically for git. Type the same instruction in the chat panel. Claude sees the same working tree and runs the same operations. The only difference is the interface, not the behavior. ### How Claude Code attributes commits By default, Claude Code adds a `Co-Authored-By` trailer to every commit it creates. GitHub reads this format and lists Claude as a co-author on that commit. To disable it, add one line to your CLAUDE.md: "Do not add Co-Authored-By attribution to commits." ## The solo operator git system Stay on master. Work directly on the main branch, commit at the end of every session, and push to GitHub when something meaningful is done. GitHub, for a solo operator, is a backup drive. A safety net, not a ceremony. Push when you've shipped something worth keeping. That's the purpose. The mistake most solo Claude Code operators make is copying team git workflows. They create a branch for every task, open a PR with no reviewer, and watch it sit for weeks until it's accumulated enough unrelated work to become a cleanup chore. That's exactly how a `chore/scrub-mcp-secrets` branch turns into 191 files. ### What to tell Claude Code at the end of every session Say: "commit and push everything with a descriptive message." Claude handles staging, writes the message from the diff, and pushes. For more context: "commit the API integration work and push — describe what was built and why." Claude reads what changed and writes accordingly. You can also add a standing instruction to CLAUDE.md: "At the end of every session where meaningful work happened, commit and push all changes with a descriptive message." Claude reads this at session start and applies it automatically. ### The one time solo operators should create a branch Create a branch when you're doing something you might want to roll back without losing other work. A risky refactor. An experiment you're not confident about. A significant architectural change where you want a clean escape route. That's the signal: uncertainty, not organisation. If you're confident the work is going in, do it on master. ## The team git system For teams, the right system is different but not complicated. One task gets one branch. The branch lives for hours or days, never weeks. Claude names it, commits on it, and drafts the PR description when the work is done. Merge it and delete it immediately. The key is keeping branches short-lived. A branch open for more than a few days has accumulated too much context to review cleanly. Merge fast, delete immediately, and start fresh on the next task. ### How to name branches when working with Claude Code Ask Claude to name the branch based on the work: "create a branch for the payment webhook changes." Claude picks a name like `feat/payment-webhooks`, creates it, and checks it out. For team consistency, put your naming convention in CLAUDE.md: "branches follow the format `feat/` or `fix/`." Claude reads it at session start and follows it from that point on. ### Can Claude Code create pull requests? Yes. Claude Code uses the `gh` CLI to create PRs directly from the terminal. Tell it: "create a PR for this branch with a summary of the changes." Claude reads all the commits on the branch, generates a title and description covering what changed and why, and opens the PR against your base branch. The `gh` CLI needs to be installed separately: `brew install gh` on Mac, then `gh auth login` to connect it to your GitHub account. Once it's set up, Claude handles PR creation without you touching the GitHub interface. ### How to stop branches piling up on a team Merge and delete on the same day the work ships. As soon as a PR merges, tell Claude: "delete this branch locally and on origin." One instruction. To enforce this as a team habit, add it to your CLAUDE.md: "after merging a PR, always delete the branch locally and on origin." ## My before and after Before: four open branches, the oldest three months old. When I dealt with it this morning, the catch-up commit was 191 files across 15 different areas of the project. Accounting scripts, session logs, agent state, call recording notes, a new copywriting wiki, all mixed together in a single branch that started as a two-hour secrets scrub. It took 20 minutes of cleanup before I could start anything new. After: on master. Claude commits after every session. GitHub is a backup. Zero overhead. The before state happened because I was following team-style git habits on a solo project. The fix was understanding that git's job changes entirely when you're the only person in the repo. > [CTA-BLUEPRINT] ## How to set up git for Claude Code ### 1. Make sure git and gh CLI are installed Git comes pre-installed on most Macs. Verify with `git --version` in your terminal. For PR creation, install the `gh` CLI: `brew install gh`, then `gh auth login` to connect it to your GitHub account. ### 2. Set your commit conventions in CLAUDE.md Add this to your project's CLAUDE.md: Claude reads CLAUDE.md at the start of every session. The conventions apply automatically from that point. ### 3. Decide: solo or team workflow If you're solo, add to CLAUDE.md: "Work on master directly. Commit and push at the end of every session where meaningful changes were made." If you're on a team, add: "One branch per task. Naming format: `feat/` or `fix/`. Delete the branch locally and on origin immediately after the PR merges." ### 4. Connect to GitHub as a backup Create a remote repo with `gh repo create` or through the GitHub interface. Push your master branch once. After that, Claude's end-of-session commits push automatically to your remote, and your work is backed up with every session. If you want a step-by-step walkthrough of the full Claude Code setup, the [Blueprint](/blueprint) covers the complete system including CLAUDE.md configuration, workflow patterns, and the folder structure I use for every project. ## Common git mistakes with Claude Code The most common one is copying team git workflows when you're solo. Branches and PRs exist to solve coordination problems between multiple developers. When you're the only person in the repo, adding them creates overhead without solving anything. Not committing between sessions is the second issue. Claude Code sessions are stateless. The next session doesn't know what the previous one built unless it's committed to the git history. Uncommitted work means lost context if something goes wrong. Commit at the end of every session, without exception. Treating GitHub as a deployment pipeline rather than a backup catches people too. For solo operators, GitHub is where the code lives safely offsite. It becomes a pipeline only if you deliberately set one up. Adding that complexity by default creates ceremony with no payoff. The fourth is letting branches go stale. A branch open for more than a few days has accumulated too much to review cleanly. Merge it or close it. Dead branches create cleanup overhead and nothing else. ## Sources and citations - [Claude Code common workflows](https://code.claude.com/docs/en/common-workflows) — Anthropic's official documentation on git operations in Claude Code - [Claude Code GitHub repository](https://github.com/anthropics/claude-code) — source and full documentation for the Claude Code CLI > [CTA-BLUEPRINT] ## Git workflow for Claude Code FAQ ### Does Claude Code automatically commit my changes? No, not by default. Claude Code commits when you ask it to. Say "commit and push everything with a descriptive message" at the end of a session and it handles staging, the message, and the push. You can add a standing instruction to your CLAUDE.md to make this happen at the end of every session automatically. ### Should I use branches with Claude Code as a solo developer? Generally, no. Solo operators don't need branches for day-to-day work. Stay on master, commit after every session, and use GitHub as a backup. Create a branch only when you're doing something you might want to roll back without affecting the rest of your work — a risky refactor, an experiment, a major structural change. ### How do I push to GitHub from Claude Code? Tell Claude: "commit and push all changes with a descriptive message." It stages the files, writes a commit message from the diff, and runs the push. If you haven't set an upstream branch yet, Claude handles that step too. The `gh` CLI isn't needed for basic pushes. ### Does Claude Code work with GitHub? Yes. Claude Code works with any git hosting provider, including GitHub. For standard git operations — commits, pushes, branches — it uses the `git` CLI directly. For GitHub-specific features like creating pull requests and managing issues, it uses the `gh` CLI, which needs to be installed separately. ### What is the best git workflow for Claude Code teams? One task per branch, kept short-lived. Ask Claude to name the branch, commit on it, and draft the PR description when the work is done. Merge and delete the branch immediately after the PR merges. Branches that stay open longer than a few days accumulate too much context to review cleanly. ### Can Claude Code resolve merge conflicts? Yes. Claude Code can read conflicting code and suggest resolutions based on what each side was trying to do. Tell it "help me resolve the merge conflicts in this file" and it walks through each conflict and proposes the right merge. You review and accept or adjust. ### Do I need a GitHub account to use git with Claude Code? No. Git is local and works without any remote hosting. GitHub is optional. It becomes useful as a backup and for team collaboration. For a solo project where local git is enough, you don't need a GitHub account. ## Ready to build with a cleaner setup? Git is supposed to serve the work. When Claude Code is handling the commits, the messages, and the pushes, the only question left is whether you're backed up. Answer yes, and get back to building. If you want the complete Claude Code system — CLAUDE.md setup, session workflow, the folder structure I use across every project — it's all in the [Blueprint](/blueprint). ## Related guides - [Claude Code Checkpoints: How to Rewind a Bad Edit](/blog/claude-code-checkpoints) - [Claude Code GitHub Integration: Actions, MCP, Auto-Review in 2026](/blog/claude-code-github) --- # Claude in the Browser: The Build-and-Verify Loop Source: https://theaiarchitects.com/blog/claude-browser Published: 2026-06-12 Using Claude in the browser means Claude can read, click, and verify in Chrome while you build in the terminal. Here's how the developer loop actually works. Using Claude in the browser means giving Claude the ability to read what's on screen, navigate pages, and verify real application state inside Chrome while you build in the terminal, closing a feedback loop that previously required you to manually check every change. I'm Tom. I run AI workflows for business owners and have been using Claude Code as my primary build environment since early 2026. The part most guides skip over is what happens after you write the code: how do you verify it worked? For months I was alt-tabbing between the terminal and Chrome, reading console errors, copying DOM state back into Claude, and then manually describing what I saw. The build-and-verify loop fixes that. Claude goes into the browser, reads what's actually there, and tells you whether the thing you just built is behaving as expected. --- > [CTA-BLUEPRINT] --- ## What is Claude browser use? Claude browser use is Anthropic's umbrella term for the capabilities that let Claude perceive and act inside a web browser. Two things fall under it that people often conflate. The first is the Claude browser agent running inside Claude Code, which autonomously navigates URLs, reads DOM state, clicks buttons, and fills forms as part of an agentic task. The second is the Claude Chrome extension, which sits in your toolbar and gives Claude access to the page you are currently viewing. Same underlying computer-use capability. Different deployment entirely. The computer-use API, which powers both, was launched in public beta in October 2024. It lets Claude models take screenshots of a display, move the cursor, click, type, and scroll. When scoped to a browser, that turns into page navigation, DOM inspection, and form interaction that Claude can chain together across a multi-step workflow. --- ## What is the Claude browser agent? The Claude browser agent is the agentic mode of browser use, where Claude plans and executes a sequence of browser actions to complete a goal rather than responding to a single prompt. You give it an objective ("open the staging URL, submit the contact form with test data, and confirm the success state"), and it runs the steps autonomously, reporting back when it's done or when it hits a decision point that requires your input. In Claude Code, you invoke browser agent behavior by giving Claude a task that requires browser verification as part of the plan. Claude handles the sequencing. You can also run it through the computer-use API directly if you are building a custom pipeline. The browser agent is most powerful when paired with a deployment. You build locally, push the change, hand off verification to Claude, and move on to the next task while it checks. --- ## How does the Claude build-and-verify loop work? The build-and-verify loop is the workflow pattern I use on every frontend change. It has four steps. **1. Build in Claude Code (terminal)** You describe the change to Claude Code, it edits the files, and your dev server reflects the update. Claude stays in the terminal context and knows what changed. **2. Run the change** The local dev server rebuilds (or you push to a staging URL if you want a real environment check). The change is live somewhere Claude can read it. **3. Open in Chrome, Claude reads the page** Claude navigates to the URL, loads the page, and reads DOM state, visible text, error states, and console output. With the Chrome extension installed, it can also read the active tab directly. Without it, Claude Code can use computer-use to take a screenshot and read what it sees. **4. Claude verifies and reports** Claude tells you whether the component rendered, whether the form submitted correctly, whether the error message appears in the right place, and whether there are console errors worth fixing. If something is wrong, it feeds that information straight back into the next build iteration. This cuts the feedback loop from "build, manually check, describe what you saw, fix" to "build, let Claude check." On a heavy build day, that saves me an hour or more of context-switching. --- ## Does Claude have a browser extension? Yes. The Claude Chrome extension is a browser add-on available from the Chrome Web Store that gives Claude direct access to the active tab. It works on Chrome, Edge, Arc, and Brave, but not Firefox or Safari. You authenticate with your Claude account (Pro, Max, Team, or Enterprise plan required), grant access to specific sites, and Claude can read and act on those pages from inside a Claude conversation. For the build-and-verify loop, the extension is the cleanest integration. Claude can read the page you have open without you screenshotting or copying anything. For a full walkthrough of setup, the eight business use cases, and the privacy trade-off, read the [Claude Chrome extension guide](/blog/claude-chrome-extension). This post focuses on the developer and operator workflow, not the extension setup itself. --- ## Can Claude Code control the browser? Claude Code can control the browser through two routes. The first is the computer-use API, where Claude Code takes screenshots of your screen (or a sandboxed display) and issues mouse and keyboard commands to navigate and interact with the browser. This works without any extension installed. The second route is via the Chrome extension: when you have the extension active on a tab, Claude Code can read that tab's DOM and visible state directly. The computer-use route is more powerful but slower. It treats the browser as a visual surface and infers structure from screenshots. The extension route is faster and more precise because Claude is reading the parsed DOM, not inferring from pixels. For debugging and verification tasks in a build loop, I use the extension route because the precision matters more than the raw capability. The [Claude Code on the web guide](/blog/claude-code-web) covers the computer-use API in more depth if you are building pipelines outside the build-and-verify loop. --- ## Claude browser agent vs Chrome extension: which to use? - ****What Claude sees**** — Claude browser agent: Screenshots + DOM via computer-use. Claude Chrome extension: Live DOM and page content directly. - ****Best for**** — Claude browser agent: Agentic multi-step workflows, external pipelines. Claude Chrome extension: In-browser assistance, build verification. - ****Setup**** — Claude browser agent: Claude Code or API, no extension needed. Claude Chrome extension: Requires Chrome extension install + site grant. - ****Speed**** — Claude browser agent: Slower (screenshot-based vision). Claude Chrome extension: Faster (direct DOM access). - ****Integration**** — Claude browser agent: Claude Code native. Claude Chrome extension: claude.ai sidebar. - ****Autonomous mode**** — Claude browser agent: Yes, via Claude Code agent. Claude Chrome extension: Yes, with Anthropic safeguards. - ****Developer use case**** — Claude browser agent: E2E test automation, scraping pipelines. Claude Chrome extension: Build-and-verify loop, debugging. The browser agent approach is the right call when you want Claude to run an automated workflow without you being present. The Chrome extension is better when you are at the keyboard and want Claude to augment what you are actively doing. For the build-and-verify loop specifically, the extension wins. You're already in the browser with the tab open. It's the lowest-friction path to getting Claude's eyes on the result. --- ## Is using Claude in the browser safe? Using Claude in the browser is safe for most developer and business workflows with standard precautions. The main risks are prompt injection and unintended actions in autonomous mode. Prompt injection is when a malicious actor embeds instructions in a web page designed to hijack Claude's behavior. Anthropic's published adversarial testing found that safety mitigations reduce browser-specific attack success rates from 35.7% to 0% on the targeted scenarios they tested. The general prompt injection rate dropped from 23.6% to 11.2%. Not zero, but significantly mitigated. The practical defense: keep autonomous mode off when browsing sites you do not control, and review what Claude is about to do before it does it. For developer use, the risk profile is low. You are pointing Claude at your own staging URLs or local dev server. The data is yours and you are watching it happen. Sensitive production data and client records belong behind an Enterprise plan with a data processing agreement, not in a browser extension workflow. The [Claude computer use documentation on Anthropic's docs](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) covers the full security guidance and safe usage patterns. --- ## What I actually use the browser loop for My real workflow is messier than the four-step version above. I am building in Claude Code in the terminal. A component breaks. Instead of opening Chrome, reading the error, copying the stack trace, and pasting it back into Claude, I just ask Claude to check the staging URL. It goes there, reads the error state, and tells me exactly what is wrong. Then we fix it in the terminal and it checks again. The part that changed my build habits is not the dramatic autonomous browsing case. It is the small loops. Check if that button is rendering. Is the spacing right? Did the form submit and redirect? These feel trivial but each one used to be a context-switch. Now they are not. I also use it for competitive research on deployed sites. When I am building a new page, I will ask Claude to read two or three reference sites and summarise the UI patterns they use. That feeds directly into the build conversation without me opening separate tabs and manually describing what I see. --- ## How does browser use work with Claude Code specifically? Claude Code treats the browser as a tool it can call when it needs to verify something in the real world. In practice, this happens in two ways. First, you can explicitly ask Claude Code to navigate to a URL and report what it finds. Claude uses computer-use to take a screenshot of the rendered page, read visible text and console output, and bring that information back into the active conversation. Second, Claude Code can use the Chrome extension's DOM access if you have it installed and the target site is granted access. This is the faster path for local development because the extension reads live DOM state rather than inferring from a screenshot. For developer teams, the practical setup is: Claude Code in the terminal, Chrome extension installed, local dev server running. You build a feature in the terminal, ask Claude to verify it on the local URL, and the loop runs without you touching the browser. Read the [complete Claude Code guide](/blog/how-to-use-claude-code) if you are new to Claude Code and want to understand the full picture before layering in browser integration. --- > [CTA-BLUEPRINT] --- ## Claude in the browser FAQ ### What is Claude browser use? Claude browser use refers to the capabilities that let Claude perceive and act inside a web browser, either through the computer-use API (where Claude takes screenshots and issues mouse and keyboard commands) or through the Chrome extension (where Claude reads live DOM content from the active tab). Both are available today on paid Claude plans. ### Does Claude have a browser extension? Yes. The Claude Chrome extension is available from the Chrome Web Store and works on Chrome, Edge, Arc, and Brave. It requires a paid Claude plan (Pro, Max, Team, or Enterprise) and grants Claude access to specific sites you enable in the settings. It is not available on Firefox or Safari. ### Can Claude Code control the browser? Yes. Claude Code can navigate to URLs, read page content, take screenshots via computer-use, and interact with DOM elements. With the Chrome extension installed, it can also read the live DOM of your active tab directly. This is how the build-and-verify loop works: Claude builds in the terminal and checks the result in the browser without you switching context. ### What is the Claude browser agent? The Claude browser agent is the agentic mode of Claude's browser use capability, where Claude plans and executes a sequence of browser actions to complete a goal autonomously. You give it an objective, and it navigates, clicks, reads, and reports back. It runs inside Claude Code or via the computer-use API. It is the right tool for multi-step automated workflows. The Chrome extension is better for in-session developer verification. ### Is using Claude in the browser safe? For developers pointing Claude at their own staging or local URLs, the risk is low. Anthropic's safeguards reduced browser-specific prompt injection attack success to 0% on the targeted scenarios they tested. The other risk is unintended actions in autonomous mode. Keep autonomous mode off on untrusted sites. Do not grant extension access to pages containing sensitive client data unless you are on an Enterprise plan with a data processing agreement. ### How is Claude browser use different from the ChatGPT browser plugin? Both let an AI model read web content, but Claude browser use allows direct browser control: form filling, multi-step navigation, and live DOM reading. ChatGPT's browser tool is built for in-chat research, not agentic workflows that chain actions together. ### Does Claude browser use work without the Chrome extension? Yes. Claude can use the computer-use API to take screenshots of the browser and interact with it visually without the extension installed. This is slower because it works from screenshots rather than the parsed DOM. The extension gives a more precise, faster integration for the build-and-verify loop. For fully automated pipelines where you are not at the keyboard, the computer-use API route is more self-contained. --- ## Related guides - [Claude Chrome extension: setup, 8 use cases, and the privacy trade-off](/blog/claude-chrome-extension) - [How to use Claude Code: the 60-minute beginner guide](/blog/how-to-use-claude-code) - [Claude Code on the web](/blog/claude-code-web) --- ## Sources and citations - Anthropic computer use documentation: [https://docs.anthropic.com/en/docs/build-with-claude/computer-use](https://docs.anthropic.com/en/docs/build-with-claude/computer-use) - Anthropic agents and tools reference: [https://docs.anthropic.com/en/docs/agents-and-tools/computer-use](https://docs.anthropic.com/en/docs/agents-and-tools/computer-use) --- # Claude Code Use Cases: What I Actually Build With It Source: https://theaiarchitects.com/blog/claude-code-use-cases Published: 2026-06-11 Claude Code use cases go far past writing code. Here are the real ones I ship with it: content pipelines, lead-gen sites, agents and back-office automation. Claude Code use cases run far past writing code. It is a command-line agent that reads and edits files, runs commands, and chains multi-step jobs, which means it can build software, automate content, run business operations, and stand up internal tools. Most people meet it as a coding assistant. I use it as the engine my whole business runs on. I'm Tom. I run a mentorship and content business almost entirely through Claude Code, from the blog you are reading to the lead-gen sites, the marketing agents, and the back-office plumbing nobody sees. This post is the honest list of what I actually build with it, not a generic feature tour. Every example below is something running in production right now. [CTA-BLUEPRINT] ## What are the main Claude Code use cases? The main Claude Code use cases fall into five buckets: shipping production code, automating content, building internal tools and dashboards, running operational workflows like data sync and reporting, and standing up autonomous agents that run on a loop. The first is the obvious one. The other four are where the real leverage sits, because they let one person operate like a team. The reason it stretches that far is simple. Claude Code is not a chat window that hands you a snippet. It is an agent with hands. It can open your files, write new ones, run a script, read the output, and decide what to do next. Any task that lives in files and commands is a candidate. That covers a lot more than a codebase. ## How do developers use Claude Code? Developers use Claude Code to build features, fix bugs, refactor across many files, and understand unfamiliar codebases without reading every line. You point it at a repository, describe the change, and it plans the edits, makes them, and runs the tests. The official [common workflows guide](https://code.claude.com/docs/en/common-workflows) covers the core coding patterns: fixing a bug from a stack trace, adding a feature, and onboarding to a new code base. This is the use case Anthropic built it for, and it is genuinely strong. But if you stop here, you are using maybe a fifth of what it can do. The same agent that edits a React component can just as easily run your Tuesday reporting job. Here are the use cases that changed how I work. ## 1. Automating content production I produce the AI Architects blog through a Claude Code pipeline, end to end. I drop in a video URL or a topic, and a custom skill pulls keyword data, writes a 2,000-word post in my brand format, generates a branded cover image, builds an in-body diagram, and imports the whole thing to my CMS as a draft. A second job publishes one post a day on a drip. The point is not that Claude wrote some words. The point is that the research, the formatting, the image generation, and the publishing are all one orchestrated run. That is a use case a chat assistant cannot touch, because it needs an agent that can run scripts and touch a CMS, not just generate text. ## 2. Building faceless lead-generation sites I built a faceless local lead-gen site with Claude Code, from the Next.js front end to the content cluster to the deploy. It generates comparison guides backed by real local pricing data, follows a strict on-page SEO contract, and ships to production with one command. No founder face, no personal brand, just a clean publisher that answers buyer questions. This works because Claude Code holds the whole project at once. It writes the page component, follows the SEO checklist, generates the guide content, and runs the deploy, all inside one repository it understands. For a solo operator, spinning up a fresh revenue site is a weekend, not a quarter. ## 3. Running autonomous marketing agents I run marketing agents that loop on a schedule. One drafts replies to relevant Reddit threads into a queue, re-scores them for traction, and sends me an approval digest three times a day. Another does the same for PR opportunities. I approve or reject from my phone, and only approved items go out, one at a time, never in a burst. These are not one-shot prompts. They are long-running jobs with state, gating, and human approval baked in. Claude Code is the right tool because the loop reads a queue file, scores entries, writes back, and pings me, which is exactly the file-plus-command pattern it excels at. A real client, Doug Loud, used the same idea to build a one-click dashboard that hides Claude, n8n, and Qdrant behind a simple web button for his non-technical team. The full breakdown is in his [case study](/case-studies/doug-loud). ## 4. Automating back-office operations I have used Claude Code to wire up the boring, high-value plumbing: syncing transactions between a bank, a payment processor, and a database, generating monthly reports, and pulling new applications into pre-call briefs on a timer. These are the jobs that quietly eat a founder's week, and they are perfect for an agent because they are repetitive, rule-based, and live entirely in data and scripts. This is where the leverage compounds. One of my mentorship clients, Chris Cole, cut a two-day document workflow down to under two minutes with this style of automation. Read how in his [case study](/case-studies/chris-cole). The pattern is always the same: find the manual data shuffle, describe it once, and let the agent run it forever. ## 5. Building internal tools and dashboards Claude Code is excellent at the throwaway internal tool you would never pay a developer to build. A script that audits your content for quality issues. A dashboard that shows project status. A one-off data cleanup. Because the cost of building one is now minutes, you build the tools you used to live without. I have a fleet of small scripts and skills that exist purely because asking for them was cheaper than doing the task by hand twice. That is a mindset shift more than a feature. When tooling is nearly free, you tool everything. [CTA-BLUEPRINT] ## How do I extend Claude Code for my own use cases? You extend Claude Code with three building blocks: slash commands, skills, and agents. Slash commands package a repeatable prompt. Skills give Claude a reusable capability it loads on demand. Agents and subagents let you run work in parallel or on a schedule. Together they turn a general assistant into a system shaped around your exact workflow. I lean on all three daily. My [Claude Code commands reference](/blog/claude-code-commands) covers the command layer, my guide to the [best Claude Code skills](/blog/best-claude-code-skills) covers the skill layer, and my walkthrough of [Claude Code agents](/blog/claude-code-agents) covers running work autonomously. If you are brand new, start with [how to use Claude Code](/blog/how-to-use-claude-code) and build from there. ## Where Claude Code use cases fall short Claude Code is not the right tool for everything. Real-time, low-latency systems, anything needing a polished consumer UI built by hand, and workflows that demand a human's judgment at every single step are poor fits. It is an agent, so it shines where a task can be described and then run, and it struggles where the value is in continuous human taste or sub-second response. It also is not magic on a messy foundation. If your data is chaos or your process is undefined, automating it just makes the chaos run faster. The use cases that pay off are the ones where the process is already clear enough to describe in plain English. Get the process right first, then hand it to the agent. ## Verdict: who should be using Claude Code beyond code? If you are a solo operator, a small team, or a founder doing the work of five people, Claude Code is the highest-leverage tool you can learn this year, and the coding use case is the least interesting part. The operators who win with it are the ones who stop seeing a code assistant and start seeing an agent that can run any process they can describe. If you only ever want help writing functions, it is still excellent, but you are leaving most of the value on the table. The whole game is realising that content, ops, lead-gen, and internal tooling are all just files and commands, and Claude Code does files and commands. [CTA-BLUEPRINT] ## Claude Code use cases FAQ ### What can you use Claude Code for besides coding? You can use Claude Code for content production, marketing automation, building lead-gen websites, syncing and reporting on business data, and running autonomous agents on a schedule. Any task that lives in files and commands is a candidate, because Claude Code is an agent that can read files, edit them, and run scripts, not just a chat assistant. ### Is Claude Code only for developers? No. Developers get the most obvious value, but non-developers run real businesses on it. The work is in describing a process clearly, not in writing code by hand, so an operator who understands their own workflow can build automations without a traditional engineering background. ### What is the best use case for Claude Code for a small business? The best first use case for most small businesses is automating a repetitive data or content task that already eats hours each week. Reporting, data sync between tools, and content production are common wins because they are rule-based and live in scripts. Start with one painful weekly job and automate that before reaching for anything ambitious. ### Can Claude Code automate marketing? Yes. Claude Code can draft, queue, score, and schedule marketing content, and it can run those jobs on a loop with human approval gates. I run Reddit and PR outreach agents that draft replies, re-score them for traction, and send me an approval digest before anything goes live. ### Can Claude Code build a whole website? Yes. Claude Code can scaffold a site, write the pages, generate the content, follow an SEO contract, and deploy it to production from one repository. I have built faceless lead-gen sites this way, front end to deploy, without leaving the CLI. ### Do I need to know how to code to use Claude Code? You do not need to write code by hand, but you do need to be able to describe what you want clearly and check the result. Knowing the basics of how files, commands, and your own tools fit together helps a lot. The skill that matters most is process thinking, not syntax. ## Sources and citations - [Claude Code common workflows](https://code.claude.com/docs/en/common-workflows) — official guide to the core coding use cases. - [Claude Code overview](https://code.claude.com/docs/en/overview) — what Claude Code is and how the agent operates. - [Anthropic: Claude Code](https://www.anthropic.com/claude-code) — the product page and positioning from Anthropic. ## Ready to build your own Claude Code use case? The fastest way to go from reading about this to running your own automation is to build one with guidance. The free Blueprint walks you through your first Claude Code build in 60 minutes, and the Challenge is where operators turn these use cases into a real system. Pick the one that fits where you are. ## Related guides - [Claude Code Use Cases That Are Actually Insane](/blog/claude-code-use-case-examples) --- # Claude Code Notifications: Get Alerted When It's Done Source: https://theaiarchitects.com/blog/claude-code-notifications Published: 2026-06-11 Claude Code notifications alert you when a task finishes or needs permission. Enable the terminal bell, desktop alerts, or a custom sound hook. Claude Code notifications are alerts Claude Code fires when a task finishes or when it pauses to ask for permission, so you can step away during a long run and get pinged the moment it needs you. They show up as a desktop notification, a terminal bell, or a custom sound you wire up yourself. I'm Tom. I run Claude Code most of the day, with agent push notifications switched on and hooks wired into my own settings file. The problem this solves is real: you kick off a big refactor, tab away to do something useful, and then lose ten minutes because you forgot Claude was sitting there waiting for a yes or no. This post covers every way to get notified, which one fits which terminal, and the single setting that fixes it for almost everyone. [CTA-BLUEPRINT] ## What are Claude Code notifications? Claude Code notifications are the alerts the CLI sends when it finishes a task or stops to wait for your input. The trigger is an internal notification event. Claude fires it at two main moments: when a long task completes, and when a permission prompt appears and needs you to approve or deny an action. By default the behaviour depends entirely on your terminal. Claude Code sends a real desktop notification only in Ghostty, Kitty, and iTerm2. In every other terminal, including the VS Code integrated terminal and Warp, the default does nothing at all. That single fact explains most of the "my notifications don't work" confusion. You are not broken, your terminal just is not on the default list. ## How do Claude Code notifications work? Claude Code fires one notification event, and you choose how that event reaches you. There are three delivery channels: a desktop notification, the terminal bell, and a custom Notification hook. They are not mutually exclusive. A hook runs alongside the built-in notification rather than replacing it. The desktop notification also travels over SSH, so a session running on a remote box can still alert your local machine. Ghostty and Kitty forward it to your operating system's notification centre with no extra setup. iTerm2 needs one box ticked first, which I cover below. ### The notification event The event has no power to block or change what Claude does. It exists purely for side effects: ring a bell, pop a desktop alert, play a sound, write a log line. Under the hood it carries a `message` field describing what happened, for example `Permission required: Read file 'config.json'`. That message is what a custom hook can read and surface however you like. ### The setting that controls it One setting governs the built-in behaviour: `preferredNotifChannel`. It lives in `~/.claude/settings.json` and also appears in `/config` as **Notifications**. The accepted values are `auto`, `terminal_bell`, `iterm2`, `iterm2_with_bell`, `kitty`, `ghostty`, and `notifications_disabled`. The default is `auto`, which sends a desktop notification in iTerm2, Ghostty, and Kitty and does nothing everywhere else. ## How to enable Claude Code notifications Getting notified takes one of four moves depending on your terminal. Work down this list in order and stop at the first one that fits your setup. ### 1. Check your terminal's default first If you use Ghostty, Kitty, or iTerm2, you may already be done. Run a task, tab away, and see whether a desktop notification lands. Ghostty and Kitty work out of the box. iTerm2 needs the forwarding step in section 3. If a notification arrives, you have nothing left to configure. ### 2. Set preferredNotifChannel to terminal_bell For any other terminal, the fastest universal fix is the terminal bell. Add this to `~/.claude/settings.json`: This rings the bell character in any terminal when Claude finishes or needs input. Most terminals turn that bell into either an audible beep or a visual flash, depending on your terminal's own bell settings. It is the one change that works almost everywhere, which is why it is the answer I give most people. ### 3. Turn on iTerm2 notification forwarding iTerm2 can show real desktop notifications, but it ignores the escape sequence until you allow it. Open Settings, then Profiles, then Terminal. Check **Notification Center Alerts**, click **Filter Alerts**, and enable **Send escape sequence-generated alerts**. Once that is on, iTerm2 forwards Claude Code's notifications to the macOS Notification Center like Ghostty and Kitty do. ### 4. Fix notifications inside tmux If you run Claude Code inside tmux, notifications never reach the outer terminal by default. tmux swallows them. Add this line to `~/.tmux.conf`, then run `tmux source-file ~/.tmux.conf` to apply it: The passthrough setting lets notifications and progress updates pass through tmux to the terminal that can actually display them. Without it, no channel will reach you while you are inside a tmux session. ## How to play a custom sound with a Notification hook A Notification hook lets you run any command when Claude needs your attention, in any terminal, regardless of `preferredNotifChannel`. This is the most flexible option and the one worth learning if you live in the CLI. On macOS the simplest version plays a system sound: That plays the Glass sound every time Claude fires a notification. Swap in any file from `/System/Library/Sounds/` to change the tone. Because hooks run alongside the built-in notification, a sound hook is how terminals that get no desktop alert, like Warp or the VS Code integrated terminal, still ping you. You can also narrow when the hook fires with a matcher. The Notification event supports matchers including `permission_prompt` (a permission dialog appeared), `idle_prompt` (Claude has gone idle), and `auth_success` (authentication succeeded). To only play a sound when Claude is waiting on a permission decision, match on `permission_prompt`: If you want a full desktop popup instead of a sound, the hook can emit a terminal escape sequence through a `terminalSequence` field, which supports notification sequences for iTerm2, Kitty, Ghostty, and Warp. The official [hooks guide](https://code.claude.com/docs/en/hooks) has ready-made commands for macOS, Linux, and Windows. For a deeper walk through every hook event, read my guide to [Claude Code hooks](/blog/claude-code-hooks). ## Why are my Claude Code notifications not working? The most common reason is that your terminal is not on the default desktop-notification list. Claude Code only sends desktop notifications in Ghostty, Kitty, and iTerm2 out of the box. In VS Code, Warp, Apple Terminal, and most others, nothing happens until you set `preferredNotifChannel` to `terminal_bell` or add a Notification hook. The next most common cause is iTerm2 without forwarding turned on, which section 3 fixes. After that, check that your terminal app actually has notification permission in your operating system's settings, since macOS silently drops alerts from apps that were never granted permission. If you are inside tmux, the passthrough line in section 4 is almost always the missing piece. Work through those four and one of them will be your problem. ## What I actually run My own setup leans on two things, and neither is the terminal bell. The first is `agentPushNotifEnabled`, which I keep set to `true` in my settings file. That sends a push notification when an agent or a teammate run needs my attention, which matters far more to me than a beep, because the runs I walk away from are the long ones. If you run [agents and agent teams](/blog/claude-code-agents), this is the setting that pings you when one of them is blocked. The second is hooks. I already run `Stop` hooks in my settings, mine sync each session to my notes and feed my token tracker, so the hook surface is something I touch every day rather than a feature I read about once. That hands-on familiarity is why I push people toward the Notification hook over fiddling with bell settings. Here is my honest verdict: most guides send you down the terminal-bell path because it is the universal answer, and it is fine. But if you are serious about stepping away from long runs, a Notification hook plus push notifications is the combination that actually changes how you work. The bell tells you something happened. The hook can tell you exactly what, and route it wherever you already pay attention. For the rest of the commands and settings that make this workflow tick, my [Claude Code commands reference](/blog/claude-code-commands) and the [how to use Claude Code](/blog/how-to-use-claude-code) guide cover the surrounding setup. [CTA-BLUEPRINT] ## Claude Code notifications FAQ ### How do I enable notifications in Claude Code? If you use Ghostty or Kitty, desktop notifications work by default. For any other terminal, set `preferredNotifChannel` to `terminal_bell` in `~/.claude/settings.json`, or add a Notification hook for a custom sound. iTerm2 also needs Notification Center forwarding turned on under Settings, Profiles, Terminal. ### Why does Claude Code not notify me when it is done? Your terminal is probably not one of the three that get desktop notifications by default, which are Ghostty, Kitty, and iTerm2. Set `preferredNotifChannel` to `terminal_bell` or configure a Notification hook. Inside tmux, you also need `set -g allow-passthrough on` in your tmux config. ### How do I make Claude Code play a sound? Add a Notification hook that runs a sound command. On macOS, `afplay /System/Library/Sounds/Glass.aiff` plays a system sound whenever Claude fires a notification. The hook runs in any terminal, so it works even where desktop notifications do not. ### Can I get Claude Code notifications over SSH? Yes. The desktop notification reaches your local machine over an SSH connection, so a Claude Code session running on a remote server can still alert the terminal in front of you. Ghostty and Kitty forward it automatically, and iTerm2 forwards it once you enable escape-sequence alerts. ### Do Claude Code notifications work in VS Code or Warp? Not by default. Neither the VS Code integrated terminal nor Warp receives the built-in desktop notification. Set `preferredNotifChannel` to `terminal_bell`, or add a Notification hook with a sound or a desktop-notification command, and both will alert you. ### How do I turn off Claude Code notifications? Set `preferredNotifChannel` to `notifications_disabled` in `~/.claude/settings.json`, or change it in `/config` under Notifications. That stops both the task-complete and permission-prompt notifications. ### What is the difference between the terminal bell and the Notification hook? The terminal bell is a single built-in beep or flash you switch on with one setting. The Notification hook runs a command you choose, so it can play a specific sound, fire a desktop popup, or log the event, and it can filter by matcher to fire only on permission prompts. The bell is the fast universal option. The hook is the flexible one. ## Sources and citations - [Configure your terminal for Claude Code](https://code.claude.com/docs/en/terminal-config) — official terminal-bell and notification setup, iTerm2 forwarding, tmux passthrough. - [Claude Code hooks](https://code.claude.com/docs/en/hooks) — the Notification hook event, matchers, and desktop-notification examples for macOS, Linux, and Windows. - [Claude Code settings](https://code.claude.com/docs/en/settings) — the `preferredNotifChannel` setting and its accepted values. ## Ready to build with Claude Code? Notifications are a small thing that quietly changes how you work, because they let you trust Claude with the long jobs and walk away. If you want the full picture of how to set Claude Code up and actually ship with it, start with the free Blueprint. --- # GitHub MCP for Claude Code (my setup) Source: https://theaiarchitects.com/blog/github-mcp-claude-code Published: 2026-06-10 The GitHub MCP server lets Claude Code work your repos: pull requests, reviews, issues, code search, and CI. Here's how to set it up and what it's for. The GitHub MCP server lets Claude Code work directly with your GitHub repositories: open and review pull requests, file and triage issues, read code across branches and repos, and check CI status, all from the terminal. It is GitHub's official Model Context Protocol server, and it turns Claude from something that writes code into something that can also move it through your workflow. This is one of the servers I actually run in my own `.mcp.json`, every day, across every repo. Below is the real setup, what I use it for, how it differs from the Claude Code GitHub Action, and where it falls short. > [CTA-BLUEPRINT] ## What is the GitHub MCP server? The GitHub MCP server is the official connector that exposes GitHub's API to Claude Code as a set of callable tools. It hands Claude actions like "list pull requests," "create issue," "get file contents," and "check workflow runs," so Claude can read and act on your repositories without you copying anything back and forth. One quick disambiguation, because two GitHub integrations get confused. The GitHub MCP server runs inside your Claude Code session and lets Claude reach into GitHub while you work. That is different from the [Claude Code GitHub Action](/blog/claude-code-github), which runs Claude inside GitHub's CI to review pull requests automatically. This post is about the MCP server. It is part of the wider [MCP server stack](/blog/best-mcp-servers-for-claude-code) as the repo-and-workflow piece. ## How does GitHub MCP work with Claude Code? The GitHub MCP server works by connecting Claude Code to GitHub's API over an authenticated HTTP connection. You point Claude at GitHub's hosted server URL and pass a token, and Claude gains a menu of GitHub actions it can call during a session. GitHub offers it as a remote server, which means there is nothing to install on your machine. You add the URL and an authorization header, and the server runs on GitHub's side. Claude calls a tool, the server runs it against your real repositories with your token's permissions, and the result comes straight back into the conversation. Because it uses your token, Claude can only do what you are allowed to do, which keeps the blast radius scoped to your access. ## What I use GitHub MCP for I keep the GitHub server loaded because it covers the whole second half of a build, the part after the code is written. Four jobs earn it a permanent slot in my stack. Pull requests and reviews are the big one. Claude can open a pull request, read the diff, and walk through a review without me leaving the terminal. Issues are the second, Claude files and triages them while we work, so a "we should fix this later" becomes a real tracked issue instead of a lost thought. Third is reading code across repos, pulling file contents and searching branches when a change spans more than the repo I happen to be in. Fourth is CI and commits, checking workflow status and recent commits so Claude knows whether the last push is green before it builds on it. Here is the project-scoped entry from my `.mcp.json`, with the token kept in an environment variable so nothing sensitive sits in the file: ## How to add GitHub MCP to Claude Code Adding the GitHub server takes one command plus a token. It is a remote server, so there is nothing to install locally. ### 1. Create a GitHub token Generate a GitHub personal access token with the scopes the server needs, repo access for code and pull requests, and any extra scopes for issues or actions you want Claude to reach. Give it the least access that covers your use, since Claude inherits exactly those permissions. ### 2. Add the server Run `claude mcp add` with the HTTP transport, GitHub's server URL, and your token in the authorization header: Keep the real token in your shell environment or a gitignored `.env` and reference it as `${GITHUB_MCP_TOKEN}` in `.mcp.json`, rather than pasting it into a file that could land in version control. ### 3. Choose the scope Add `--scope project` to write the server into the repo's `.mcp.json` so your whole team inherits it, or `--scope user` to make it follow you across every project. I run GitHub in user scope because nearly every repo benefits from it. ### 4. Confirm it connected Run `claude mcp list` and look for a green check next to `github`. A "needs authentication" flag means the server loaded but the token did not take, so re-check the header. Once it is green, ask Claude something like "list the open pull requests on this repo" to see it work. > [CTA-BLUEPRINT] ## GitHub MCP server vs the Claude Code GitHub Action These two GitHub integrations do different jobs, and picking the right one comes down to where Claude runs. The GitHub MCP server runs in your local Claude Code session and lets you drive GitHub interactively while you build. The GitHub Action runs Claude inside GitHub's CI and reacts to events like a new pull request, automatically and without you present. Use the MCP server when you want Claude working your repos alongside you, opening pull requests, triaging issues, searching code. Use the [GitHub Action](/blog/claude-code-github) when you want hands-off automation, like an auto-review that comments on every pull request. They stack well together: the MCP server for the interactive build loop, the Action for the always-on guardrail. ## Is GitHub MCP free? Yes. The GitHub MCP server is free and open source, and GitHub hosts the remote version at no cost. You authenticate with your own GitHub account and token, so you are working within whatever GitHub plan you already have. The only running cost is the Claude Code tokens spent calling its tools, which is part of your normal Claude usage. ## Where GitHub MCP falls short The GitHub server is only as safe as the token you give it. A broad token means Claude can touch anything that token can, so an over-scoped credential is the real risk here. Scope the token tightly, prefer fine-grained tokens limited to the repos you want, and never hand it write access it does not need. The other cost is context. The GitHub server exposes a large tool set, which is exactly why it is useful, but it also means it adds real weight to the context window. On a project that never touches GitHub, that is wasted overhead, so scope it where it earns its place. And like any remote server, it occasionally drops its connection or needs a token refresh, which shows up as a "needs authentication" flag in `claude mcp list`. ## Verdict: is the GitHub MCP server worth it? Yes, for anyone who ships code through GitHub with Claude Code. It closes the loop between writing code and moving it, pull requests, issues, reviews, and CI, without leaving the terminal. It is one of the first three servers I would install, next to Context7 and the Playwright server, and it is the one I would keep if I could only keep one. It is not worth loading on a project that never touches GitHub, where it is just context overhead. Scope the token tightly, run it in user scope so it follows you, and let it own the half of the work that starts once the code is written. > [CTA-BLUEPRINT] ## GitHub MCP FAQ ### What is the GitHub MCP server? The GitHub MCP server is GitHub's official Model Context Protocol connector. It exposes GitHub actions, pull requests, issues, code search, and CI, as tools that an AI client like Claude Code can call, so Claude can read and act on your repositories directly. ### How do I add the GitHub MCP server to Claude Code? Run `claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_TOKEN"`, using a GitHub personal access token scoped to what you want Claude to reach. Then run `claude mcp list` to confirm it shows a green check. ### Is the GitHub MCP server free? Yes. The server is free and open source, and GitHub hosts the remote version at no cost. You use your own GitHub account and token, so you operate within your existing GitHub plan. The only extra cost is the Claude Code tokens spent calling its tools. ### What is the difference between the GitHub MCP server and the Claude Code GitHub Action? The GitHub MCP server runs in your local Claude Code session and lets you work GitHub interactively. The Claude Code GitHub Action runs Claude inside GitHub's CI to react to events like new pull requests automatically. One is interactive, the other is hands-off automation, and they work well together. ### What permissions does the GitHub MCP server need? It uses a GitHub personal access token, and it can do exactly what that token allows. Give it the least access that covers your use, repo scope for code and pull requests, plus issues or actions scopes only if you want Claude to reach those. Fine-grained tokens limited to specific repos are the safest option. ### Why does my GitHub MCP server say it needs authentication? A "needs authentication" flag in `claude mcp list` usually means the token is missing, expired, or not passed correctly in the authorization header. Re-check the header value, confirm the token has the right scopes, and re-add the server if needed. ## Sources and citations - [GitHub MCP server](https://github.com/github/github-mcp-server) — GitHub's official MCP server and documentation. - [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) — official setup and scope reference. - [Model Context Protocol](https://modelcontextprotocol.io) — the open standard the server is built on. ## Ready to build with Claude Code? The GitHub server is one piece of a stack. The real win is wiring Claude Code into the tools your work runs on, your repo, your browser, your database, then letting it do the work while you direct. Start with the [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code) and add the GitHub server the moment your work ships through GitHub. If you want the guided version, my free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. ## Related guides - [Claude Code MCP: Setup, Scopes & The 4 Servers I Use](/blog/claude-code-mcp) - [GitHub MCP for Claude Code: Setup Checklist](/blog/github-mcp-claude-code-setup-checklist) --- # Playwright MCP for Claude Code (setup + verdict) Source: https://theaiarchitects.com/blog/playwright-mcp-claude-code Published: 2026-06-10 Playwright MCP lets Claude Code drive a real browser: click, fill, screenshot, and test. Here's how to install it and when it actually earns its slot. Playwright MCP is a server that lets Claude Code drive a real web browser: open pages, click buttons, fill forms, take screenshots, and run end-to-end tests. Instead of guessing what your UI does, Claude can actually open it, look at the page, and act on what is really there. It is built on Microsoft's Playwright framework and connects to Claude Code through the Model Context Protocol. I run Playwright MCP in my own Claude Code setup, and it is the server I reach for the moment a problem moves from "reason about code" to "see what the page is doing." This is the full setup, how it differs from the Playwright CLI, where it falls short, and whether it deserves a slot in your stack. > [CTA-BLUEPRINT] ## What is Playwright MCP? Playwright MCP is the official Model Context Protocol server for Playwright, maintained by Microsoft. It exposes browser actions as tools Claude Code can call, so the model can navigate, interact with, and inspect web pages on your behalf. It is the most-searched MCP integration in the Claude Code niche, and it sits inside the wider [MCP server stack](/blog/best-mcp-servers-for-claude-code) as the browser-control piece. One thing to clear up early, because the names collide. Playwright MCP is not the same as the Playwright test runner you may already use. The test runner is a CLI you script against. Playwright MCP is a live connector that hands the browser to Claude as a set of callable actions. They share the same underlying engine, but you use them in completely different ways. ## How does Playwright MCP work with Claude Code? Playwright MCP works by exposing browser actions to Claude Code as a tool menu over the Model Context Protocol. When you load the server, Claude gains tools like "navigate," "click," "type," "take screenshot," and "snapshot the page." Claude decides which action to call, the server runs it in a real Chromium browser, and the result comes back into the conversation. The detail that makes it powerful is the accessibility snapshot. Rather than feed Claude raw pixels, Playwright MCP can hand back a structured snapshot of the page, the buttons, inputs, and links with their roles and labels. Claude reads that snapshot, decides what to click, and acts. It is closer to how a screen reader sees a page than how a screenshot does, which is exactly why it is reliable. The practical effect is that Claude stops describing what your UI might do and starts operating it. You can hand it a broken form and it can fill the fields, submit, and report what actually happened. ## What I use Playwright MCP for I keep Playwright MCP loaded for the work that no amount of code-reading can solve: seeing the running app. When a page behaves wrong in a way the source does not explain, I let Claude open it, walk the flow, and screenshot the failure. That turns a vague "the button does nothing" into Claude reporting the exact element and state it found. The second job is end-to-end checks. After a front-end change, Claude can drive the real user path, sign in, click through, fill a form, and confirm the screen ends up where it should. It is not a replacement for a proper test suite, but it catches the obvious breakage before I do. The honest pattern I have settled on: I load it when a task is about the browser, and I leave it out when it is not. A browser server burns context describing tools Claude will not call on a backend task, so it lives in my stack as a per-project decision, not an always-on default. ## How to install Playwright MCP in Claude Code Installing Playwright MCP takes one command. The official Microsoft package is `@playwright/mcp`, and Claude Code can add it for you. ### 1. Add the server Run the `claude mcp add` command with the official package: The double dash separates the Claude Code flags from the command the server runs. Everything after it starts Playwright MCP through `npx`, so there is nothing to install globally. ### 2. Choose the scope By default the server is added for you only. Add `--scope project` to write it into the repo's `.mcp.json` so your team inherits it, or `--scope user` to make it follow you across every project. For a browser server I tend to use user scope, because I want it available everywhere but not forced onto backend repos. ### 3. Confirm it connected Run `claude mcp list` and look for a green check next to `playwright`. That means Claude Code launched the server and can reach its tools. The first time it drives a page, Playwright downloads the Chromium browser it needs, which takes a moment but only happens once. ### 4. Use it Ask Claude to do something that needs the browser. A prompt like "open localhost:3000, click the sign-up button, and tell me what happens" is enough. Claude calls the navigate and click tools, runs them in the real browser, and reports back. > [CTA-BLUEPRINT] ## Playwright MCP vs Playwright CLI Playwright MCP and the Playwright CLI solve different problems, and the "playwright cli vs mcp" question comes down to who is driving. The CLI is for tests you write and run yourself. The MCP server is for letting Claude operate the browser interactively. Use the Playwright CLI when you want a deterministic, version-controlled test suite that runs in CI. You write the test once, it runs the same way forever, and it fails loudly when something breaks. That is the right tool for regression coverage. Use Playwright MCP when you want Claude to explore, debug, or check something live without you writing a script first. It shines in the loop where you are building and want a second pair of eyes on the running UI. The two are complements, not rivals. I use the CLI for the suite and the MCP server for the messy, exploratory middle of a build. ## Is Playwright MCP free? Yes. Playwright MCP is free and open source under Microsoft's Playwright project, and so is the Chromium browser it drives. You pay nothing for the server itself. The only cost is the usual one, the tokens Claude Code spends calling its tools, which is part of your normal Claude usage rather than a separate Playwright charge. ## Where Playwright MCP falls short Playwright MCP is not free in context terms. It loads a broad set of browser tools into the model's context window, so keeping it on for a backend or pure-writing task wastes tokens on actions Claude will never call. This is the main reason I scope it per project instead of running it everywhere. The other limit is that a live browser session is stateful and occasionally fragile. Pages hang, logins expire, and a flow that worked yesterday can need a nudge today. It is excellent for interactive debugging and quick checks, but it is not the thing you lean on for rock-solid, repeatable regression testing. That is what the CLI suite is for. There is also a trust dimension. You are giving Claude control of a real browser that can submit forms and trigger actions on live sites. Point it at local or staging environments while you are exploring, and be deliberate before you let it act against anything in production. ## Verdict: is Playwright MCP worth it? Yes, for anyone who builds or debugs web UIs with Claude Code. It is the cleanest way to give Claude eyes on the running app, and the install is a single command with no global setup. If your work touches the browser, it is one of the first three MCP servers I would add, alongside Context7 and the GitHub server. It is not worth loading if your work never leaves the backend or the terminal. A browser server on a pure-API project is just context overhead. Add it when a task is about the browser, scope it so it is not forced onto repos that do not need it, and keep your deterministic regression tests in the Playwright CLI where they belong. > [CTA-BLUEPRINT] ## Playwright MCP FAQ ### What is the difference between Playwright MCP and Playwright? Playwright is Microsoft's browser automation framework, used mainly through a CLI and test runner you script yourself. Playwright MCP is a Model Context Protocol server built on that framework that exposes browser actions as tools an AI like Claude Code can call directly. Same engine, different driver. ### How do I add Playwright MCP to Claude Code? Run `claude mcp add playwright -- npx -y @playwright/mcp@latest`, then run `claude mcp list` to confirm it connected. The first browser action downloads Chromium automatically. No global install is required because it runs through `npx`. ### Is Playwright MCP free? Yes. Both the Playwright MCP server and the Chromium browser it controls are free and open source. The only cost is the Claude Code tokens spent calling its tools during a session. ### What can Claude Code do with Playwright MCP? With Playwright MCP, Claude Code can open web pages, click elements, fill and submit forms, take screenshots, and read a structured snapshot of the page to decide what to do next. That makes it useful for interactive debugging and for walking through end-to-end user flows. ### Playwright MCP vs Playwright CLI: which should I use? Use the Playwright CLI for deterministic, version-controlled tests that run in CI. Use Playwright MCP when you want Claude to explore or debug the running UI interactively without writing a script first. Most teams benefit from both, the CLI for the suite and the MCP server for exploratory work. ### Does Playwright MCP work in other MCP clients? Yes. Because it follows the open Model Context Protocol, Playwright MCP works in Claude Code, Claude Desktop, and other MCP-aware clients. The configuration location differs per app, but the server itself is the same. ### Why is my Playwright MCP server not connecting? The most common causes are a missing Chromium download on first run, a server that needs a moment to launch, or a scope mismatch where the server was added in a different project. Run `claude mcp list` to check its health, and re-add it with the correct `--scope` if it is missing from the project you are in. ## Sources and citations - [Playwright MCP](https://github.com/microsoft/playwright-mcp) — Microsoft's official Playwright MCP server and documentation. - [Playwright](https://playwright.dev) — the underlying browser automation framework. - [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) — official setup and scope reference. - [Model Context Protocol](https://modelcontextprotocol.io) — the open standard Playwright MCP is built on. ## Ready to build with Claude Code? Playwright MCP is one piece of a stack. The real win is wiring Claude Code into the few tools your work actually runs on, then letting it do the clicking, testing, and shipping while you direct. Start with the [best MCP servers for Claude Code](/blog/best-mcp-servers-for-claude-code), add Playwright when your work touches the browser, and grow the stack around real tasks. If you want the guided version, my free Claude Code Blueprint walks you through your first real build in about sixty minutes, no coding required. ## Related guides - [Claude Code MCP: Setup, Scopes & The 4 Servers I Use](/blog/claude-code-mcp) - [Claude in the Browser: The Build-and-Verify Loop](/blog/claude-browser) --- # Claude Agent Mode: Background Sessions You Monitor From One Screen Source: https://theaiarchitects.com/blog/claude-agent-mode Published: 2026-06-09 Claude agent mode (agent view) lets you dispatch multiple background Claude sessions and monitor them all from one screen with the claude agents command. Here is how it works. Claude agent mode is what Anthropic calls [agent view](https://code.claude.com/docs/en/agent-view): a full-screen monitor you open with `claude agents` that shows every background Claude session you have running, which ones need your input, and which ones are done. You dispatch tasks from it, watch them run without being attached, and step in only when one needs you. It is a research preview as of May 2026. It requires Claude Code v2.1.139 or later. Check your version with `claude --version`. I'm Tom. I teach Claude Code operators how to run real production workflows, and agent view is one of the most underused features in the current Claude Code release. > [CTA-BLUEPRINT] ## What agent mode actually is When most people hear "agent mode" in Claude context, they think of a setting that makes Claude act more autonomously in a single session. Claude agent mode in Claude Code is something more specific: a separate process manager for background sessions. Each background session is a full Claude Code conversation that keeps running without a terminal attached. You can dispatch it, close the terminal, go do other work, and check back when you are ready. The session keeps working. Agent view is the interface for managing those sessions. It shows you what every background session is doing and which ones need your input. You can reply to a session from agent view without opening the full conversation. ## How to open agent mode Run this in your shell: Agent view takes over the full terminal. It shows a session list grouped by state at the top and a dispatch input at the bottom. Press `Esc` at any time to return to your shell. Your sessions keep running while you are away. ## Dispatching a task Type a task description in the input at the bottom and press `Enter`. A new background session starts and appears as a row in the list. Every prompt you enter in agent view starts its own new session. Typing another prompt and pressing Enter launches a second session alongside the first rather than sending a follow-up to the current one. That is the intended behaviour. Agent view is for managing multiple independent tasks, not continuing a single conversation. ## Reading session state Each row shows a state icon. The icon animates while the session is actively working. It turns yellow when the session is waiting on input from you. It dims when the session is idle. It turns green when the task is done. Red means it ended in an error. Row summaries are generated by a Haiku-class model and refresh every 15 seconds while a session works, plus once when each turn ends. The summary tells you what the session is currently doing without you needing to open the full transcript. ## Peeking and replying without attaching Press `Space` on a selected row to open the peek panel. It shows the session's most recent output or the question it is waiting on. You can type a reply in the peek panel and press `Enter` to send it without leaving agent view. This is the most efficient way to handle sessions that need input. You do not need to open the full conversation, you see exactly what it needs, you reply, and you go back to the list. ## Attaching to a full session Press `Enter` or the right arrow key on a row to attach to it. Agent view is replaced by the full interactive session, exactly as if you had run `claude` in that directory. Press the left arrow on an empty prompt to detach and return to agent view. Detaching never stops the session. It keeps running in the background. ## File isolation with worktrees Before a background session edits files, Claude automatically moves it into an isolated git worktree under `.claude/worktrees/`. This means parallel background sessions can each edit files without overwriting each other's changes. You do not need to configure this. It happens automatically. The session works in its own isolated checkout. When you delete the session from agent view, the worktree is cleaned up. ## The supervisor process Background sessions are kept alive by a supervisor process that is separate from your terminal. It starts automatically the first time you dispatch a background session. Sessions survive terminal closes, agent view closes, and sleep. They do not survive a full machine shutdown. Idle sessions that have been sitting unattached for about an hour are stopped by the supervisor to free resources, but their state stays on disk. The next time you peek, reply to, or attach to a stopped session, the supervisor restarts it from where it left off. ## Keyboard shortcuts worth knowing - **`Space`** — Open or close the peek panel for the selected row - **`Enter` or `→`** — Attach to the selected session - **`←`** — Detach and return to agent view - **`Ctrl+T`** — Pin a session to keep its process running while idle - **`Ctrl+R`** — Rename a session - **`Ctrl+X`** — Stop a session (press twice to delete it) - **`?`** — Show all shortcuts ## Agent mode vs agent teams vs subagents These three things are related but different. Agent view (agent mode) is a monitor for background sessions that each run independently. The sessions do not communicate with each other. You coordinate them. [Agent teams](https://code.claude.com/docs/en/agent-teams) are multiple coordinated sessions with a shared task list and messaging. The sessions communicate directly with each other. This is experimental and disabled by default. Subagents are workers spawned inside a single session. They do a side task and return a summary. They are not visible in agent view. For a complete breakdown of when to use each, read [Claude Code Agents Explained](/blog/claude-code-agents). ## Agent mode FAQ ### What Claude Code version do I need for agent mode? Agent view requires Claude Code v2.1.139 or later. Check your version with `claude --version`. Run `claude update` to install the latest version. ### Is agent mode the same as auto mode? No. Auto mode (or auto-accept mode) is a permission setting that lets Claude run without stopping for each edit approval. Agent mode (agent view) is a separate process manager for background sessions. They are different features. ### Can I use agent mode on Claude for the web? No. Agent view is a Claude Code feature that runs locally. It is not available in the Claude.ai web interface. For cloud-hosted sessions, look at Claude Code on the web. ### Do background sessions use my subscription quota? Yes. Each background session uses quota the same as an interactive session. Running many background sessions in parallel multiplies your usage proportionally. ### What happens to my sessions if I restart my computer? Sessions that were running when the machine shut down show as failed when you next open agent view. Attach, peek, or reply to any of them and the session restarts from where it left off. Sleep alone preserves sessions and the supervisor reconnects on wake. ## Use agent mode to stop watching Claude work The biggest productivity gain from agent view is simple. Stop watching Claude work in real time. Dispatch a task, check back when it is done, spend that time on something else. That is the shift most operators have not made yet. They sit and watch Claude Code run because they feel they need to be present. Agent view lets you be present only when it matters. For more on the full agent capability in Claude Code, read [Claude Code Agents Explained](/blog/claude-code-agents). For the multi-agent patterns that make heavy use of agent view, read [Claude Code Multi-Agent Orchestration](/blog/claude-code-multi-agent). Start with the [free Claude Code Blueprint](/blueprint) to build the foundations, then join the [30-day challenge](/challenge) to put agent mode into a real production workflow. ## Related guides - [Claude Agent Teams: How to Run Multiple AI Agents at Once](/blog/claude-agent-teams) --- # Vibe Coding Tools: What They Are and Which to Use in 2026 Source: https://theaiarchitects.com/blog/vibe-coding-tools Published: 2026-06-09 Vibe coding tools let you build apps and scripts by describing what you want in plain English. Here is the landscape in 2026, what each tool is actually for, and how to choose. Vibe coding tools let you describe what you want and get working code back without reading every line yourself. The category exploded in 2025 when Andrej Karpathy coined the term, and by 2026 there are more tools in this space than most people realise, each built for a different kind of builder and a different kind of work. The tool you want depends on who you are, what you are building, and how much control you need over the output. I'm Tom. I teach operators and developers how to build with Claude Code, and I went through the main vibe coding tools in active use to give you a clear breakdown by use case. > [CTA-BLUEPRINT] ## What makes something a vibe coding tool A vibe coding tool generates code from natural language descriptions. The minimal version is a chat interface where you describe a script and get code back. The more capable version is an agent that plans, implements, tests, and iterates across an entire codebase without you switching between files manually. What separates a basic AI code generator from a vibe coding tool is whether it can act across a project, not just a single prompt. The tools worth knowing in 2026 all do something agentic, not just completion. ## Claude Code: the serious builder's pick Claude Code is a terminal-based AI coding agent with full access to your machine, your file system, and your shell. You run it from the command line, describe what you want to build or change, and it plans the work and implements it. The differentiators are the guardrails. Plan mode shows you the full implementation plan before any code runs. Hooks let you define automated checks that fire at set points. CLAUDE.md gives Claude persistent context about your codebase, your conventions, and what not to touch. Subagents let you delegate side tasks to separate context windows without cluttering the main session. These features are not designed for quick throwaway scripts. They are designed for operators and developers building real systems they will maintain. Claude Code is best for: developers and technical operators building production-grade software, running complex multi-step automations, and maintaining large codebases with specific conventions and architecture. Claude Code is not ideal for: non-developers who want to avoid the command line, or people who just need to prototype a simple front-end quickly. ## Cursor: the IDE for AI-first developers Cursor is an IDE built around AI from the ground up. It starts from VS Code's interface and adds deep AI integration: tab-complete that predicts your next edit, a Composer mode for describing larger changes, and agent mode for multi-step implementation across files. Cursor's strength is in the developer workflow. You stay in a familiar IDE, and the AI integrates into how you already work rather than asking you to switch tools. It supports most of the same languages and extensions as VS Code. Cursor is best for: developers who want AI deep in their development workflow but prefer an IDE to a terminal, and teams where everyone is already using a VS Code-compatible editor. ## GitHub Copilot: inline completions at scale Copilot is the most widely used AI coding assistant in the world, embedded directly in VS Code, JetBrains, and other editors. Its core capability is inline completion: as you type, Copilot suggests the next line or next block. The newer Copilot Workspace feature adds more agentic capability: describe a task, get a plan, implement it. But Copilot's core is still inline completion, and that is where it is strongest. It is less suited to the "describe a whole feature" mode that the newer agents handle better. Copilot is best for: developers who want AI assistance as they code, completing patterns faster, and staying in their existing editor without changing their workflow. ## v0 by Vercel: UI from a description [v0 by Vercel](https://v0.dev) generates React UI components and pages from text descriptions and screenshots. You describe a layout or paste a screenshot, and v0 produces production-ready JSX using Tailwind and shadcn/ui. It is purpose-built for front-end scaffolding. It is not a general-purpose code generator. If you want a data table, a pricing page, a form, or a dashboard layout, v0 produces solid, usable output fast. It cannot replace the engineering work needed to wire that UI into a real back-end. v0 is best for: designers and front-end developers who want to prototype UI fast, and product teams who need a working visual starting point before engineering picks it up. ## Bolt.new: browser-based full-stack apps [Bolt.new](https://bolt.new) is StackBlitz's browser-based full-stack builder. You describe an app, Bolt generates the code, runs it in a browser sandbox, and lets you iterate in plain English. No local setup. No terminal. The key differentiator is that it runs in the browser. There is no install. You go to bolt.new, describe what you want, and you are building. For small to medium apps where getting something running fast matters more than long-term maintainability, Bolt works well. Bolt is best for: non-developers and early-stage founders who want to build a working app prototype without any local setup, and anyone building demos, MVPs, or internal tools that do not need production-grade architecture. ## Replit: AI coding in the cloud Replit is a browser-based coding environment with AI built in. You can write code in your browser, run it there, deploy it from there, and use AI to help write and debug it all within one interface. Replit's agent feature lets you describe apps and have them built and deployed without touching local tooling. Its biggest advantage is the complete cloud environment: you do not need a development machine, just a browser. Its limitation is that for serious projects, the cloud environment is more constrained than a local machine with Claude Code. Replit is best for: beginners and students learning to code, quick experiments that need to run and be shared immediately, and anyone who needs to code without a development machine. ## How to choose Start with your role, not with the tools. If you are a technical operator or developer building production systems: Claude Code. If you are a developer who wants AI embedded in an IDE workflow: Cursor or Copilot. If you need UI fast from a description: v0. If you want a working app without local setup: Bolt or Replit. Most people doing serious work end up using more than one. v0 for the front-end scaffold, Claude Code for the implementation logic, Copilot or Cursor for the daily editing workflow. The tools are not mutually exclusive. ## Vibe coding tools FAQ ### What is the best vibe coding tool for beginners? Bolt.new and Replit both require no local setup and are the lowest barrier to entry. For beginners who want to understand what they are building, not just generate it, Replit includes a learning-oriented environment. ### Can vibe coding tools replace developers? No. They eliminate a large portion of mechanical coding work. They do not replace the engineering judgment needed to design architecture, handle edge cases, debug complex problems, or build secure systems. Senior developers who use these tools well ship faster. They are not replaced by them. ### Is Claude Code free? Claude Code requires a Claude paid plan. The entry point is Claude Pro at $20 per month. A separate free trial of Claude Code is available. Read the full pricing breakdown at [Claude Code Pricing Explained](/blog/claude-code-pricing). ### Which vibe coding tools work without an internet connection? None of the AI-powered tools in this list work offline. They all send prompts to AI APIs. GitHub Copilot, Cursor, and Claude Code have local editors, but the AI features require an internet connection. ### What is vibe coding search volume telling us about adoption? The keyword "vibe coding tools" has 3,600 searches per month and growing. "Best vibe coding tools" has 1,900 searches per month. The category is actively growing in developer search behaviour as more people discover these tools. ## Pick the right tool for where you are The mistake most people make is trying to use one tool for everything. Each of these tools is optimised for a specific type of builder and a specific kind of work. The operators getting the best results pick the right tool for the job rather than forcing one tool to cover all cases. For a focused look at which tools are ranked best overall, read [The Best Vibe Coding Tools in 2026](/blog/best-vibe-coding-tools). Grab the [free Claude Code Blueprint](/blueprint) if you want to understand how Claude Code fits into a real production workflow, then join the [30-day challenge](/challenge) to build your first system with it. ## Related guides - [Claude Vibe Coding: What It Is, When It Works, When It Doesn't](/blog/claude-vibe-coding) --- # The Best Vibe Coding Tools in 2026: Tested and Ranked Source: https://theaiarchitects.com/blog/best-vibe-coding-tools Published: 2026-06-08 The best vibe coding tool depends on what you are building. Claude Code for production systems, Cursor for IDE workflow, v0 for UI, Bolt for no-setup prototyping. Here is the honest ranking. The best vibe coding tool is Claude Code for serious builders. It is the only one in the category that gives you an agentic coding workflow with plan mode, memory, hooks, and multi-agent orchestration built in. Every other tool in the category is better at specific things, worse at others. This is the honest ranking based on what each tool actually does well, not a list of features with no clear verdict. I'm Tom. I build production systems with Claude Code and teach operators how to do the same. I went through the main tools in this category to give you a clear picture of where each one belongs in a serious builder's workflow. > [CTA-BLUEPRINT] ## 1. Claude Code: Best for Serious Builders Claude Code is the strongest option for operators and developers building production-grade systems. You run it from the terminal, describe what you want, and it plans and implements across your entire codebase. What separates it from the rest of the category is the guardrail system. Plan mode shows you the full implementation before anything runs. Hooks automate checks at defined points. CLAUDE.md gives Claude persistent memory about your codebase. Subagents and agent teams handle parallel work. These are not features you get anywhere else in the vibe coding category. The honest limitation: it requires a terminal. Non-developers find the command-line interface unfamiliar. If you are not comfortable in a terminal, the setup friction is real. That said, the actual coding you ask it to do requires no technical knowledge. The terminal is just where you type to it. **Best for:** technical operators and developers building things they will maintain. **Entry point:** Claude Pro at $20/month. ## 2. Cursor: Best for IDE-First Developers [Cursor](https://www.cursor.com) is VS Code rebuilt with AI at the core. Tab completions, Composer for file-spanning changes, and an agent mode that can plan and implement across your project. It integrates into the IDE workflow so there is no context switch between writing code and asking for help. The advantage over Claude Code for some developers is familiarity. If you spend your day in an IDE, Cursor keeps you there. The disadvantage is that its agentic capabilities are not as deep as Claude Code's. For complex multi-step tasks that need real orchestration, Claude Code pulls ahead. **Best for:** developers who want AI deeply integrated into an IDE workflow. **Entry point:** Free tier available, Pro plan at $20/month. ## 3. GitHub Copilot: Best for Inline Completion Copilot is the most used AI coding tool on the planet. That is not because it is the most capable agent. It is because it is in the editor where most developers already work, and its tab-complete for the next line or block is genuinely useful every day. Copilot Workspace adds more agentic features, but Copilot's core strength is completion, not orchestration. For daily coding tasks where you want AI finishing your thoughts rather than planning whole features, Copilot is the right fit. **Best for:** developers who want AI inline completion in their existing editor. **Entry point:** Free tier available for individuals. ## 4. v0 by Vercel: Best for UI From a Description [v0](https://v0.dev) is purpose-built for one thing: generating React UI components and layouts from text descriptions or screenshots. You describe a data table or a pricing page, and v0 outputs clean JSX using Tailwind and shadcn/ui that you can drop into your project. It is not a general coding tool. It does not handle back-end logic, data wiring, or architecture decisions. But for getting a UI skeleton that looks right in minutes rather than hours, nothing in the category touches it. **Best for:** front-end developers and product teams who need UI scaffolding fast. **Entry point:** Free tier available. ## 5. Bolt.new: Best for No-Setup Full-Stack Prototypes Bolt generates and runs full-stack apps in a browser sandbox. No install. No terminal. No local environment. Describe an app, get a working prototype, iterate in plain English. For non-developers and early-stage founders who need to see something working fast, Bolt removes every setup friction point that normally slows down prototyping. The trade-off is that the browser environment has constraints that make complex, production-grade apps harder to build there than with local tooling. **Best for:** non-developers, founders, and anyone who needs a working prototype without local setup. **Entry point:** Free tier available. ## 6. Replit: Best for Beginners and Cloud-First Coding Replit is a complete cloud coding environment with AI built in. You write, run, and deploy code from a browser. The AI helps you write and debug. For people learning to code or people who need to code without a development machine, it is the most complete environment. For serious production work, the constraints of the cloud environment become limiting quickly. Most experienced developers outgrow Replit's model as their projects scale. It excels at education, quick experiments, and accessible first experiences with AI coding tools. **Best for:** beginners, students, and anyone coding without a local development setup. **Entry point:** Free tier available. ## Honest verdict If you are building systems you plan to run, maintain, and grow: **Claude Code**. If you are a developer who lives in an IDE and wants AI deeply integrated there: **Cursor**. If you want AI tab-complete while you write: **GitHub Copilot**. If you need UI components from a description: **v0**. If you want to prototype a full-stack app in a browser with no setup: **Bolt**. If you are learning or need cloud-based coding: **Replit**. Most serious operators end up using two or three of these. Claude Code as the primary engineering agent, v0 for front-end scaffolding, and Copilot as the daily inline assistant. They are not mutually exclusive, and the strongest builders do not limit themselves to one. ## Best vibe coding tools FAQ ### Is there a free vibe coding tool? GitHub Copilot, v0, Bolt.new, and Replit all have free tiers. Claude Code has a free trial. Cursor has a free tier. Paid plans unlock higher usage limits and more capable features across all of them. ### What is the easiest vibe coding tool to start with? Bolt.new requires no setup and works in a browser. Type a description, get a working app, iterate. It is the lowest barrier to entry in the category. If you want something more capable with a slightly higher setup curve, Replit is the next step. ### How is vibe coding different from traditional coding? Traditional coding means writing every line yourself. Vibe coding means describing what you want in plain English and letting AI generate the implementation. The practical difference is speed: vibe coding is much faster for building first versions and standard patterns. The limitation is that you need some understanding of what you are building to catch errors and iterate effectively. ### Will vibe coding tools replace programming jobs? They will change what programming looks like rather than eliminate it. Mechanical implementation work decreases. Architectural judgment, system design, and debugging complex failures remain human work. The developers and operators who learn to use these tools well will be more productive, not replaced. ### What is the best vibe coding tool for building an AI agent? Claude Code with the Agent SDK knowledge is the strongest option for building production AI agents. The Agent SDK walkthrough is at [Claude Agent SDK: Build Your First Production Agent](/blog/claude-agent-sdk). ## Start with the right tool for the work The operators who waste time are the ones who use a prototyping tool for production code, or use a production tool for a quick throwaway script. Match the tool to the task. For production systems: Claude Code. Read the full beginner guide at [How to Use Claude Code](/blog/how-to-use-claude-code) and grab the [free Claude Code Blueprint](/blueprint). Ready to build real systems? The [30-day challenge](/challenge) is where operators go from setup to shipping in 30 days. ## Related guides - [Vibe Coding Tools: What They Are and Which to Use in 2026](/blog/vibe-coding-tools) --- # Claude Code Multi-Agent: Orchestration Patterns That Work in 2026 Source: https://theaiarchitects.com/blog/claude-code-multi-agent Published: 2026-06-07 Multi-agent orchestration in Claude Code means splitting work across coordinated Claude sessions. Here are the three patterns that work and the one decision that determines which to use. Multi-agent orchestration in Claude Code means running more than one Claude session on the same goal, with each session handling a piece of the work. Done right, it cuts hours off complex tasks. Done wrong, you get sessions stepping on each other, duplicate work, and conflicts that are harder to debug than the original problem. There are three patterns worth knowing: subagents for context isolation, agent teams for inter-agent coordination, and `/batch` for mechanical parallelism at scale. The right pattern depends on one question. I'm Tom. I teach Claude Code operators how to build production workflows, and I spent time with the [Anthropic multi-agent documentation](https://code.claude.com/docs/en/agents) to pull out what actually determines which pattern to reach for. > [CTA-BLUEPRINT] ## The one question that determines your approach Do the workers need to talk to each other? If no, use subagents or `/batch`. Each worker runs independently, returns a result, and does not need to know what the others did. If yes, use agent teams. Agent teams give each worker a shared task list and a direct messaging channel to other workers in the team. They can coordinate without routing everything through you. That is the core decision. The rest is detail. ## Pattern 1: Subagents for context isolation A subagent runs in its own context window, does a task, and returns a summary. The main session stays clean. No search results, no file reads, no debugging output from the side task bleeding into your main conversation. This matters more than it seems. A context window that fills with research and exploration gets expensive and starts producing lower-quality responses as Claude tries to reason across too much noise. Subagents prevent that by keeping side work in a separate window. Use subagents when the tasks are independent and the results can be collected and used in the main session. Research tasks, test runs, file processing, and linting checks are all natural subagent work. You can also control costs at the subagent level. Route a cheap, mechanical task to Haiku instead of Opus in the subagent's frontmatter. The main session uses Opus for reasoning while the subagent uses a faster, cheaper model for volume work. For the full picture on custom subagents, read [Claude Code Agents Explained](/blog/claude-code-agents). ## Pattern 2: Agent teams for coordinated work [Agent teams](https://code.claude.com/docs/en/agent-teams) go further than subagents. A lead agent creates a team, creates a shared task list, and spawns teammates. Each teammate claims tasks from the list, marks them done, and messages other teammates directly when it needs to coordinate. Cole Medin, who has published real agent team demos, describes the difference clearly. Subagents only report back to the conversation that spawned them. Agent teams let workers talk to each other. The practical use case is work that has interdependencies. If you are building a feature that needs a back-end change, a front-end change, and tests, those three pieces are related. The front-end worker needs to know what the back-end worker built. Agent teams handle that handoff. Subagents do not. Agent teams are experimental and disabled by default. Enable them by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your settings.json `env` block. You need Claude Code v2.1.32 or later. One critical constraint: agent teams do not isolate workers in separate worktrees. If two teammates edit the same file at the same time, they will conflict. Partition the work so each teammate owns a clearly separate set of files before you start. For setup and real examples, read [Claude Agent Teams: How to Run Multiple AI Agents at Once](/blog/claude-agent-teams). ## Pattern 3: /batch for mechanical parallelism `/batch` is a Claude Code command that splits a large mechanical change into 5 to 30 worktree-isolated subagents, each of which makes the change in its own isolated git checkout and opens a pull request. This is the right tool for repo-wide migrations: renaming a function across 40 files, updating a deprecated API pattern throughout a codebase, or applying a consistent structural change to every module. The key feature is isolation. Each subagent gets its own worktree so they cannot interfere with each other's changes. Each opens its own PR so you can review and merge the pieces independently. `/batch` is not for creative or reasoning-heavy work. It is for describing a mechanical change in one instruction and letting 5 to 30 workers execute it in parallel. The workers do not need to coordinate. They each do the same thing in a different part of the codebase. ## Worktrees: the underlying isolation mechanism Subagents, agent teams, and `/batch` all rely on worktrees for file isolation. A worktree is a separate git checkout in its own directory. Parallel sessions can each work in their own checkout without touching each other's files. Agent view (the background session monitor you open with `claude agents`) creates worktrees automatically before background sessions edit files. For manual parallel work, you can create worktrees yourself with `git worktree add`. The most common multi-agent mistake is running parallel sessions without worktrees on a codebase where they edit overlapping files. The second session overwrites the first session's changes. Use worktrees any time parallel sessions might touch the same files. ## What multi-agent does not solve Multi-agent makes parallel work faster. It does not make bad architecture faster to debug. If you split work into agents before understanding the problem, you get multiple agents heading in the wrong direction at once. Plan mode first, agents second. Run the task in plan mode, review what Claude intends to do, confirm the approach makes sense, then delegate to agents. The planning step is where wrong assumptions surface cheaply rather than after parallel sessions have run in four different wrong directions. ## Multi-agent cost reality Every session in a multi-agent setup multiplies your token usage. Running 10 subagents in parallel uses quota roughly 10 times as fast as a single session. Manage this deliberately. Route mechanical subagent tasks to Haiku. Keep agent teams small: 3 to 4 workers is enough for most tasks. Use `/batch` for scale when the work is truly mechanical. Do not spin up 15 agents because more feels like more. ## Claude Code multi-agent FAQ ### How many agents can I run at once in Claude Code? There is no hard limit on the number of agents. Practical limits come from rate limits and subscription quota. Running many agents simultaneously multiplies your token usage proportionally. ### Do I need a paid plan for multi-agent? Yes. Multi-agent features, including subagents, agent view, and agent teams, require a paid Claude plan. Agent teams specifically require Claude Code v2.1.32 or later. ### Can subagents use different models? Yes. Set the model in a custom subagent's frontmatter. This lets you run a main session on Opus while subagents doing cheaper work run on Haiku. ### Is `/batch` the same as agent teams? No. `/batch` splits a single mechanical change into isolated, non-communicating parallel workers. Agent teams create coordinated workers that share a task list and message each other. Use `/batch` for mechanical changes, agent teams for work that requires coordination. ### How do I prevent agents from overwriting each other's work? Use worktrees. Each agent gets its own isolated git checkout. Changes in one worktree cannot affect another. Agent view creates worktrees automatically. For manual parallel sessions, create them with `git worktree add`. ## Ship faster without the chaos Multi-agent is about speed with structure, not just running more Claude sessions at once. The structure is what keeps it from becoming a debugging problem bigger than the original task. Subagents for isolated side work. Agent teams when workers need to coordinate. `/batch` for repo-wide mechanical changes. Worktrees everywhere parallel sessions touch the same files. Start with the [free Claude Code Blueprint](/blueprint) to build the foundations, then join the [30-day challenge](/challenge) to run real multi-agent workflows in your business. ## Related guides - [Claude Code Subagents vs Skills: When to Use Each](/blog/claude-code-subagents-vs-skills) --- # Claude Vibe Coding: What It Is, When It Works, When It Doesn't Source: https://theaiarchitects.com/blog/claude-vibe-coding Published: 2026-06-06 Vibe coding with Claude means describing what you want and letting AI write the code. Here is the honest version of when that works, when it fails, and why Claude Code is the serious builder's pick. Vibe coding means describing what you want and letting AI write the code without reading or understanding it yourself. Andrej Karpathy [coined the term](https://en.wikipedia.org/wiki/Vibe_coding) in early 2025 to describe a new mode of programming: you are the product manager, the AI is the engineer, and you mostly just vibe with the output until it works. It is real, it is useful, and it is also genuinely dangerous if you apply it in the wrong places. I'm Tom. I teach Claude Code operators how to build real production systems. I have watched operators save hours with vibe coding and I have watched them ship broken software because they trusted a vibe instead of understanding what Claude built. Here is the honest version. > [CTA-BLUEPRINT] ## What vibe coding actually is Karpathy's original framing was specific. You describe what you want, let the AI implement it, and if something breaks you paste the error back in and ask it to fix. You are not reading the code line by line. You are not reasoning through the implementation. You are vibing with the result. That framing matters because it defines the honest use case. Vibe coding is best when the code is low-stakes, short-lived, or where you just need something that runs once. A quick script to rename 200 files. A one-page data dashboard for a meeting. A prototype you will throw away after a demo. It is not best when the code will handle money, user data, security logic, or anything you need to maintain over time. You cannot maintain code you do not understand. ## Where Claude vibe coding works well **Personal scripts and automation.** Renaming files, converting formats, parsing a CSV, scraping a table from a website. These are low-risk, often used once, and the cost of getting it slightly wrong is low. Claude produces working scripts for this class of task reliably. **Prototypes and demos.** When you need something functional enough to show a concept, vibe coding gets you there in minutes. A quick Next.js page, a simple API route, a working form. The prototype is not the product, so the implementation details matter less. **Throwaway data tools.** Analysts and operators build one-off dashboards and data transforms constantly. If you are cleaning a dataset for a one-time import, vibing with Claude until the transform is right is a completely legitimate approach. **Front-end scaffolding.** UI components, basic layouts, and styling from a description work well with Claude. Especially with Claude Code's ability to see screenshots and iterate on visual output. ## Where it falls apart **Security-critical code.** Authentication, authorisation, payment flows, and anything that handles sensitive user data require someone who understands what the code does. Vibing with a session token implementation and shipping it to production is how data breaches happen. **Large codebases you will maintain.** Code you do not understand becomes technical debt immediately. When it breaks in three months, you cannot debug it. When requirements change, you cannot adapt it. Vibe coding in a system you plan to maintain long-term is borrowing against yourself. **Anything with edge cases that matter.** Claude produces code that handles the happy path well. Edge cases, unusual input, and failure modes require deliberate thought about what could go wrong. Vibing past the obvious cases leaves bugs that only appear in production. **Regulated or auditable systems.** If your code needs to be reviewed by a compliance team or audited for legal purposes, you need to understand and be able to explain every line. ## Why Claude Code is the serious builder's pick Vibe coding tools are not all equal. The difference comes down to what guardrails the tool gives you and how much of the system you can inspect. [Claude Code](https://www.anthropic.com/claude-code) gives you plan mode, which shows you what changes will be made before any code runs. You can review, reject, or redirect. It gives you hooks, which let you run checks or tests automatically at defined points. It gives you CLAUDE.md, which sets persistent instructions about how the codebase should be built. These are not features for someone who wants to vibe past understanding. They are features for builders who want to move fast on implementation but maintain control over direction and standards. The operators I work with who get the most from Claude Code are not the ones who turn off their judgment. They are the ones who delegate well. Claude writes the code. They review what it does. They use plan mode when they want to stay in the loop and auto mode when they trust the task. That is a better model than pure vibe coding. You still get the speed. You do not lose the understanding. ## Vibe coding vs agentic coding There is a real distinction worth drawing. Vibe coding is typically reactive: describe, generate, accept or retry. Agentic coding with Claude Code is proactive: give Claude a goal, let it plan a multi-step implementation, review the plan, and let it execute. Agentic coding gives Claude more autonomy but with checkpoints. It is faster than vibe coding for complex work because Claude can break the problem into parts and handle each one. It is safer than pure vibe coding because you can catch wrong assumptions at the planning stage before any code runs. If you are using Claude primarily in the reactive vibe mode, try shifting to plan mode for anything non-trivial. The planning step surfaces decisions that would otherwise happen invisibly. ## The honest performance picture Vibe coding works better for some types of code than others. Self-contained scripts perform very well. Integrated components that depend on your existing architecture perform less well, because Claude does not have full context about the system it is plugging into. CLAUDE.md is how you close that context gap. If you give Claude persistent instructions about your architecture, your conventions, and your constraints, its output becomes much more relevant to your actual codebase rather than a generic implementation. The operators who maintain a good CLAUDE.md get substantially better results from Claude Code than those who do not. For a deep look at CLAUDE.md and Claude Code memory, read [Claude Code Memory: CLAUDE.md, Auto Memory, and Path Rules](/blog/claude-code-memory). ## Claude vibe coding FAQ ### Who is vibe coding for? Vibe coding is most useful for non-developers who need one-off scripts and prototypes, and for developers who want to move faster on low-stakes implementation tasks. It is not a good fit for production systems or security-critical code where understanding the implementation matters. ### Can you vibe code an entire app? Yes, but the results depend heavily on the app's complexity and how long you plan to maintain it. Simple, self-contained apps with no external dependencies or security requirements work well. Apps with user data, payment flows, or complex state are much harder to build this way safely. ### Is Claude Code the best vibe coding tool? For serious operators who want to move fast without giving up control, Claude Code's guardrails, plan mode, and CLAUDE.md memory make it the strongest choice. For quick one-off scripts without a development workflow, Claude in the chat interface or Cowork is often faster. ### How do you get better results vibe coding with Claude? Be specific about what you want. Include the constraints and edge cases upfront rather than discovering them through errors. Use plan mode to see what Claude intends before it runs. And maintain a CLAUDE.md that tells Claude about your stack, conventions, and what not to touch. ## Build with intention, not just vibes Vibe coding is a legitimate tool. It is not the only tool, and it is not always the right one. The operators building real businesses with Claude Code are not vibing through production systems. They are using Claude to handle implementation while they maintain direction, standards, and understanding. That combination is faster than vibe coding and safer than traditional development. Start with the [free Claude Code Blueprint](/blueprint) to build the right foundations. The [30-day challenge](/challenge) is where you install real working systems, not one-off vibes. ## Related guides - [The Best Vibe Coding Tools in 2026: Tested and Ranked](/blog/best-vibe-coding-tools) - [Vibe Coding Tools: What They Are and Which to Use in 2026](/blog/vibe-coding-tools) --- # Claude Cowork Plugins: Connectors, Skills, and What Ships Free Source: https://theaiarchitects.com/blog/claude-cowork-plugins Published: 2026-06-05 Claude Cowork plugins bundle connectors and skills together. Anthropic ships three free plugin packs. Here is what each one includes and how to extend Cowork beyond the built-ins. Claude Cowork plugins bundle connectors and skills together into one install. A connector gives Cowork access to an external service like Gmail or Notion. A skill gives it a reusable instruction set for a specific kind of task. A plugin packages both so you install one thing and get the whole capability. Anthropic ships three plugin packs for free: Productivity, Customer Support, and Finance. Beyond those, there is a connector marketplace you can extend manually, and a Zapier MCP connector that bridges apps not yet in the marketplace. I'm Tom. I teach operators how to build with Claude, and I went through the full Cowork connector setup to give you a clear picture of what you actually get. > [CTA-BLUEPRINT] ## The difference between connectors, skills, and plugins These three words get used interchangeably in conversations about Cowork. They are not the same thing. A **connector** is access to an external service. The Gmail connector lets Cowork read and send emails. The Google Drive connector lets it read and write files in your Drive. The Notion connector lets it read and update your Notion workspace. Connectors are the integration layer. A **skill** is a reusable instruction set. It tells Cowork how to handle a specific kind of task, like "when you summarise emails, format them this way and flag items that need a response within 24 hours." Skills make consistent behaviour replicable without re-prompting every time. A **plugin** bundles connectors and skills together. Install a plugin and you get both the service access and the instructions for how to use it productively. That is why installing the Productivity plugin gets you further than just connecting Gmail manually. ## The three free plugin packs from Anthropic Anthropic ships three plugin packs that are available at no extra charge on paid Claude plans. **Productivity** covers the core day-to-day tools: email, calendar, and document work. It includes connectors for Gmail, Google Calendar, and Google Drive, with skills for inbox triage, meeting prep, and document summarisation. **Customer Support** is built for teams handling customer communication. It includes skills for ticket summarisation, response drafting, and escalation flagging. The connectors in this pack depend on which support tools are in the marketplace. **Finance** handles financial documents and reporting. Skills for reading invoices, extracting line items, reconciling data, and producing summaries. This is the pack most useful for solo operators doing their own bookkeeping with AI support. All three packs are installed from the Cowork plugins or integrations section in the desktop app. Select a pack, click install, and grant the OAuth permissions for each connector inside it. ## The connector marketplace Beyond the three plugin packs, Cowork has a connector marketplace where you can add integrations individually. The confirmed connectors as of May 2026 include Gmail, Google Calendar, Google Drive, and Notion. The marketplace does not yet include CRM platforms like Salesforce or HubSpot. It does not yet include ecommerce platforms. If your workflow depends on those tools, you are working around a gap. The workaround most operators use is the [Zapier MCP](https://zapier.com/mcp) connector. Zapier connects to thousands of apps, and if you bridge Zapier into Cowork via MCP, you can route actions through Zapier to apps that have no direct connector yet. It is more setup than a native connector, but it extends your reach considerably. ## Projects: folders with their own connector context Projects in Cowork wrap a folder with its own instructions, connectors, and memory. Each project can have different integrations active. Your client work project might have a specific Notion workspace connected. Your personal project might have only Google Drive. This separation matters when you have connectors that touch sensitive data. Instead of one global connector context that bleeds across tasks, projects keep each area of your work scoped and separate. ## What Cowork plugins cannot do yet Cowork connectors work within a sandbox. Cowork cannot access services you have not explicitly connected. It cannot reach tools that are not in the marketplace or bridged through Zapier MCP. The sandbox is intentional. It keeps Cowork safe for non-technical users who do not want Claude touching things they did not explicitly grant. But it does mean the ceiling is lower than Claude Code, which has full machine access. For work that needs custom APIs, webhooks, or connections to tools that have no Zapier integration, you are outside what Cowork plugins can handle. That work belongs in Claude Code with a custom [MCP server](https://code.claude.com/docs/en/mcp) setup. For a look at how MCP servers work in Claude Code, read [Claude Code MCP: Setup, Scopes and the 4 Servers I Use](/blog/claude-code-mcp). ## Cowork plugins vs Claude Code MCP servers They solve the same problem from different angles: giving Claude access to tools outside itself. Cowork plugins are one-click installs through a marketplace UI. They work inside the sandbox. They are designed for non-technical operators who want integrations without config files. Claude Code MCP servers are configured in JSON, can connect to any API or service with an MCP implementation, and have no sandbox restriction. They require more setup and more technical comfort. If you start with Cowork and hit the ceiling of what the marketplace offers, that is when you move toward Claude Code and MCP. If you never hit that ceiling, Cowork plugins handle everything you need. ## Cowork plugins FAQ ### Are the Anthropic plugin packs really free? Yes. The Productivity, Customer Support, and Finance plugin packs from Anthropic are included with paid Claude plans at no extra charge. You need Claude Pro ($20/month), Max, or Team. ### Can I build my own Cowork plugin? As of May 2026, custom plugin creation is not publicly documented. Anthropic controls the plugin marketplace. For custom integrations, use a Zapier MCP bridge or move to Claude Code MCP servers. ### Does the Gmail connector read all my emails? The Gmail connector requests access during the OAuth flow. You grant it the permissions it asks for. Cowork can only access what you explicitly authorised. Review the permission request carefully before clicking approve. ### What happens if I revoke a connector's access? Cowork can no longer reach that service. Tasks that depend on the connector will fail or skip that integration. You can reconnect it at any time through the integrations panel. ### Can Cowork write to my Google Drive? Yes, with the Google Drive connector installed and write permissions granted. Cowork can create, update, and organise files in the folders you have given it access to. ## Extend Cowork to what you actually need The three free plugin packs cover most operators' day-to-day needs. Email, calendar, documents, basic reporting. Start there, see where the gaps are, and bridge with Zapier MCP for anything the marketplace does not cover yet. For a wider look at what Cowork can do day to day, read [10 Real Claude Cowork Use Cases That Save You Hours](/blog/claude-cowork-use-cases). For how Cowork compares to building with Claude Code directly, read [Claude Cowork vs Claude Code](/blog/claude-cowork-vs-claude-code). Grab the [free Claude Code Blueprint](/blueprint) to understand the full Claude ecosystem, then join the [30-day challenge](/challenge) to start building real systems. --- # Claude Cowork on Windows: Install and First Task (2026) Source: https://theaiarchitects.com/blog/claude-cowork-windows Published: 2026-06-04 Claude Cowork works on Windows through the Claude desktop app. Here is the exact install path, what you need, and how to run your first task in under 10 minutes. Claude Cowork works on Windows. You install it through the Claude desktop app, sign in, click the Cowork tab, and you are running. The same features available on Mac are available on Windows. Linux is not supported as of May 2026. This is the install path from zero to first task. No terminal. No config files. The whole setup takes under 10 minutes if you have a Claude account already. I'm Tom. I teach operators how to build with Claude, and I put together this guide from the official Anthropic setup flow and feedback from operators who went through the Windows install. > [CTA-BLUEPRINT] ## What you need before installing A paid Claude plan is required. Cowork is not available on the free tier. The [Claude Pro plan](https://claude.com/pricing) at $20 per month is the entry point. Max and Team plans include Cowork as well. You also need Windows 10 or Windows 11. Older versions of Windows are not officially supported. Your computer needs to stay on and awake for scheduled tasks to run. If you use Cowork for scheduled inbox triage or recurring reports, the machine has to be running when the task fires. A laptop that sleeps overnight will miss scheduled runs. ## Installing Claude Cowork on Windows **Step 1: Download the Claude desktop app** Go to [claude.com/download](https://claude.com/download) and download the Windows installer. It is a standard `.exe` file. Run it and follow the prompts. The install takes about 2 minutes. **Step 2: Sign in** Open the Claude desktop app and sign in with the account attached to your paid plan. If you already use Claude on the web, use the same account. **Step 3: Open the Cowork tab** Once signed in, you see three tabs at the top of the app: Chat, Code, and Cowork. Click Cowork. This is where everything happens. **Step 4: Grant folder access** Cowork works by giving Claude access to a specific folder on your computer. Click the folder icon or the setup prompt to choose which folder you want Cowork to be able to read and write. Start with one folder, such as your Documents folder or a project-specific folder. You can add more later. Cowork only touches the folders you explicitly grant. It cannot access the rest of your machine without your permission. **Step 5: Run your first task** Type a task in plain English in the Cowork input. Something like "summarise the files in this folder and list any action items" is a good starting point. Cowork will read the files, complete the task, and return a finished result. ## Connecting integrations on Windows Cowork has a connector marketplace that works the same on Windows as on Mac. The available connectors include Gmail, Google Calendar, Google Drive, and Notion, along with others. To connect an integration, click the Integrations or Connectors section in the Cowork sidebar. Choose the service you want to connect, click through the OAuth flow, and grant the permissions. Once connected, Cowork can read and act on that service's data as part of your tasks. Anthropic ships three free plugin bundles: Productivity, Customer Support, and Finance. Each one packages a set of connectors and skills for that use case. You can install a bundle to get a useful starting set without configuring each connector individually. If you need a service that is not in the marketplace, some operators bridge it through a Zapier MCP connector. That is a manual setup, but it extends Cowork's reach to hundreds of additional apps. ## Scheduled tasks on Windows Cowork can run tasks on a schedule you set in plain language. "Every weekday morning, summarise my inbox and create a priority list" is the kind of prompt that becomes a scheduled task. For scheduled tasks to run on Windows, the Claude desktop app needs to be open and your computer needs to be awake. Tasks do not run if the app is closed or the machine is asleep. If you need reliable scheduled automation that runs without a machine being on, that is a job for a server-based tool rather than Cowork. ## How Cowork on Windows differs from Claude Code Claude Code runs in a terminal and has full access to your entire machine, including file system operations and shell commands. It is built for software development. Cowork runs in the desktop app in a sandboxed environment. It can only access the folders you explicitly grant it. It is built for knowledge work: documents, emails, reports, and files. If you are not a developer and you want Claude handling your documents and email, Cowork is the right tool. If you are building software or automations that need full machine access, Claude Code is the right tool. For an honest side-by-side, read [Claude Cowork vs Claude Code](/blog/claude-cowork-vs-claude-code). ## Troubleshooting Windows-specific issues **The app does not open after install:** Try right-clicking the icon and selecting "Run as administrator" on first launch. Some Windows security settings block new apps from running normally on the first attempt. **Scheduled tasks are not running:** Check that the Claude desktop app is open and not minimised to the system tray in a paused state. Windows battery saver and sleep settings can prevent tasks from firing. Keep the machine plugged in and set it to stay awake during scheduled task windows. **Connector OAuth is not completing:** If the browser redirects to the right page but the connection does not register in Cowork, try closing and reopening the Claude desktop app after completing the OAuth flow. **Cowork tab is not visible:** This usually means your account is not on a paid plan. Cowork requires Claude Pro, Max, or Team. Check your subscription at `claude.ai/settings`. ## Claude Cowork Windows FAQ ### Does Claude Cowork work on Windows 10? Yes. Cowork is supported on Windows 10 and Windows 11 through the Claude desktop app. Older versions of Windows are not officially supported. ### Is Cowork the same on Windows and Mac? The features are the same. The interface is the same. The install path is different because Windows uses an `.exe` installer rather than a `.dmg`. Everything else works identically. ### Can I use Cowork without an internet connection? No. Cowork requires an internet connection to communicate with Anthropic's servers. The AI processing happens remotely, not on your machine. ### Does Cowork run when my computer is off? No. Cowork runs on your local machine, so your computer has to be on for it to work. This applies to scheduled tasks too. If your machine is asleep or off, scheduled tasks will not fire. ### How much does Claude Cowork cost on Windows? Cowork is included in Claude paid plans. The entry point is Claude Pro at $20 per month. There is no separate charge for using Cowork on Windows. ## Start building with Cowork The install is the easy part. The real value comes from building workflows that run on a schedule and handle work while you are doing something else. For a full tour of what Cowork can do, read [10 Real Claude Cowork Use Cases That Save You Hours](/blog/claude-cowork-use-cases). For the step-by-step setup of your first real task, read [How to Use Claude Cowork](/blog/how-to-use-claude-cowork). Grab the [free Claude Code Blueprint](/blueprint) if you want to go deeper with the full Claude ecosystem, then join the [30-day challenge](/challenge) to build real systems in your business. --- # Is the Claude Chrome Extension Safe? Source: https://theaiarchitects.com/blog/is-claude-chrome-extension-safe Published: 2026-06-04 The Claude Chrome extension is safe for everyday business tasks, with real limits you need to know. Here's what Claude can see, what it can't, and when to keep it off. The Claude Chrome extension is safe to use on everyday business sites, and that verdict comes with two conditions you should understand before clicking install. It is not a blank-check surveillance tool, and it is not a zero-risk sandbox either. What Claude can see is narrow and under your control. The safety trade-off depends on which sites you grant access to and whether you understand what autonomous mode actually does. I've been running the extension on Pro and Team plans since it opened to those tiers on 18 December 2025, across client research workflows, CRM reading, and email drafting. Pro is $20/month. Max runs at $100/month or $200/month depending on the tier. Neither price tier changes what the extension can access, because the permissions model works the same across all paid plans. Most of the coverage I've read either exaggerates the risk or waves it away. Neither is useful if you handle client data or work in a regulated space. This post gives you the actual picture. --- > [CTA-BLUEPRINT] --- ## What is the Claude Chrome extension? The [Claude Chrome extension](/blog/claude-chrome-extension) is a browser add-on from Anthropic that lets Claude read the content of pages you're on, fill in forms, click buttons, and chain actions across tabs. It connects your active browser session to your Claude conversations so Claude can act on what it sees, rather than waiting for you to copy-paste content manually. Anthropic launched it as a pilot to roughly 1,000 Max plan users in August 2025, expanded to all Max subscribers in November 2025, and opened it to Pro, Team, and Enterprise plans on 18 December 2025. It installs from the [Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) and authenticates against your existing Claude account. It works on Chrome and any Chromium-based browser: Edge, Brave, and Arc are all supported. It is worth being clear about what it is not. It is not a passive sidebar assistant that reads everything you visit. It is not spyware. It does not activate until you ask it to act on a page, and it only has eyes on pages you have explicitly enabled in the settings panel. That distinction matters a lot for the safety question. --- ## What data can the Claude Chrome extension access? The extension can read text content, form fields, and page structure on sites you explicitly grant it access to. That is the full scope. It reads pages you approve, one at a time, in the extension settings panel. It cannot read sites you haven't granted. It cannot read your passwords, stored payment details, or browser history. Anthropic also blocks specific categories automatically, regardless of what you enable: financial services sites, adult content, and pirated content are off-limits at the platform level. When Claude reads a page, that page content travels to Anthropic's servers for processing. This is how the AI works. The content is handled under [Anthropic's privacy policy](https://www.anthropic.com/privacy) the same way any message you send to claude.ai is handled. You are not in a local sandbox. If the page content is sensitive, treat granting access to that site the same as you'd treat typing that content into claude.ai directly. The privacy question most business owners actually need to answer is this: does the content on this page contain anything I'd be uncomfortable sending to Anthropic via the regular chat interface? If yes, don't enable that site. If no, the extension adds no meaningful risk beyond what you've already accepted by using Claude at all. There is one more nuance for people on paid plans. Pro and Max plan users are on Anthropic's standard terms. Enterprise plan users can negotiate a data processing addendum, which governs how Anthropic handles your data under frameworks like GDPR or HIPAA. If you operate in a regulated industry, the Enterprise DPA is the right configuration before the extension touches any client-facing data. --- ## Standard mode vs autonomous mode: the safety difference that matters Most people install the extension and never change the default mode. That default is standard mode, and the distinction is important. - ****Who triggers actions**** — Standard mode: You confirm each action step. Autonomous mode: Claude chains actions without confirmation. - ****Form submissions**** — Standard mode: Asks before submitting. Autonomous mode: Can submit without prompt. - ****High-risk actions**** — Standard mode: Confirmation required. Autonomous mode: Anthropic safeguards apply, but no pause. - ****Multi-step tasks**** — Standard mode: Step-by-step with review. Autonomous mode: Full chain without interruption. - ****Good for**** — Standard mode: Research, drafting, summarising. Autonomous mode: Repeatable workflows you've reviewed. - ****Risk level**** — Standard mode: Low for most use cases. Autonomous mode: Moderate until you've vetted the workflow. Standard mode is the right starting point. Claude asks for confirmation before submitting forms, making purchases, or sharing data. Autonomous mode is for workflows you've already tested and trust, not for exploration on new sites. Even in autonomous mode, Anthropic maintains additional safeguards on the most sensitive actions. That means Claude will still pause on certain high-risk steps, but you should not rely on that as your only check. Review any autonomous workflow before you run it unattended. The practical framing I use with clients: start every new workflow in standard mode. Watch what Claude does at each step. When you've run it five or six times and understand exactly what it touches, switching to autonomous mode is a reasonable call. Flipping to autonomous on day one, on a site you've never granted access to before, is the mistake. In my own setup I keep autonomous mode off by default for any site that handles client financial pages or contracts, regardless of how familiar the workflow is. That is where things go wrong, and not because the extension is unsafe, but because you haven't built enough context to know what "safe" means for that specific workflow. --- ## The prompt injection risk Anthropic flagged, and what it actually means Anthropic published adversarial testing data alongside the [Claude for Chrome announcement](https://www.anthropic.com/news/claude-for-chrome). Prompt injection is the attack where a malicious actor embeds hidden instructions in a web page designed to trick Claude into taking unintended actions, like exfiltrating data from the page or clicking something you didn't ask it to click. Here is what the numbers actually show. Without safety mitigations, adversarial testing achieved a 23.6% success rate on prompt injection attacks. With Anthropic's current mitigations in place, that number dropped to 11.2%. On browser-specific attack scenarios specifically, mitigations reduced success rates from 35.7% to 0%. Most of the coverage I've seen treats the 11.2% figure as alarming. When I tested the extension across my standard client research sites (HubSpot pages, supplier portals, editorial sites), I didn't encounter a single injection attempt in normal use. That framing is wrong in context. The adversarial tests are designed by researchers specifically trying to break the system, on pages engineered to contain malicious instructions. That is not your CRM, your email inbox, or the supplier sites you use every day. For everyday business use on your own tools and trusted sites, the residual injection risk is a non-issue. Where it becomes relevant is autonomous mode, pointed at an unfamiliar page, without you reviewing what the workflow does. That is the specific combination that creates real risk. Standard mode on a trusted site, combined with Anthropic's mitigations dropping browser-specific attack rates from 35.7% to 0%, makes the exposure minimal. The lesson is not that the extension is unsafe. The lesson is that you should use it on sites you trust. A corporate intranet you control is lower risk than a scraped content aggregator you've never visited. The fix for the injection risk is the same as the fix for everything else: grant access deliberately, start in standard mode, and expand from there. --- ## Can I limit which sites Claude can see? You have complete control over site access, and the controls are immediate. In the extension settings panel, you grant or revoke access per domain. Claude cannot see any site you haven't explicitly enabled, and revoking access to a site takes effect instantly. For Team and Enterprise accounts, admins can enforce org-wide allowlists and blocklists. That is the right configuration if you're rolling this out to a team, because it removes the decision from individual users and sets a consistent policy. The practical approach: start with three or four sites you use daily and trust completely. Test simple tasks on each. Expand from there as you get comfortable with what Claude does in context. --- ## Should businesses use the Claude Chrome extension? For most business use cases, yes. The email reply drafting, competitive research across tabs, and CRM page reading are all genuinely useful and operate well within the safe zone: sites you control or trust, standard mode, no sensitive client data. These are the workflows that save 20 to 30 minutes a day and compound fast. I use it daily across Chrome and Arc, and the setup took me less than five minutes from install to first working task. There are two categories where you should be more careful. If your work involves legal documents, medical records, or data covered by a confidentiality agreement, keep those sites off the enabled list unless you're on an Enterprise plan with the right data processing agreements in place. Anthropic's standard privacy policy covers standard plan usage, and for regulated industries that is not sufficient without Enterprise-level DPA coverage. The second category is autonomous mode at scale. If you're building a workflow that runs unattended and touches forms or submissions, test it manually a few times first. Autonomous mode is powerful and the safeguards are solid, but "solid" and "zero-error" are different things. The comparison that frames this most clearly: granting Claude access to your HubSpot contact page is no more sensitive than screen-sharing that page in a Zoom call. Granting access to a page full of client financial data is a different decision, and you should treat it as such. For developers, the extension closes a workflow loop that previously required manual copy-paste between the terminal and the browser. If you're already working through [how to use Claude Code](/blog/how-to-use-claude-code), the browser integration is a natural next step. The two tools are designed to complement each other. --- > [CTA-BLUEPRINT] --- ## Claude Chrome extension safety FAQ ### Is the Claude Chrome extension safe? The Claude Chrome extension is safe for everyday business tasks on trusted sites with default standard mode settings. Anthropic automatically blocks financial services and other high-risk site categories. Prompt injection mitigations reduce adversarial attack success rates significantly on browser-specific scenarios. The main condition is: do not enable it on pages containing confidential client data, medical records, or financial accounts unless you have an Enterprise plan with appropriate data agreements. ### What data can the Claude Chrome extension access? Claude can access text content, form fields, and page structure on sites you explicitly grant it access to in the extension settings. It cannot read your password manager, browser history, payment details, or any site you haven't enabled. Anthropic also blocks financial services sites and other sensitive categories at the platform level regardless of your settings. ### What is prompt injection and does it affect the Claude extension? Prompt injection is an attack where hidden instructions embedded in a web page try to trick Claude into taking unintended actions. Anthropic published adversarial testing data showing their mitigations reduced prompt injection success rates from 35.7% to 0% on browser-specific scenarios. The risk is real but managed, and using the extension on sites you trust eliminates it for practical purposes. ### Is autonomous mode safe to use? Autonomous mode is safe for workflows you've tested and verified. In standard mode, Claude asks for confirmation before high-risk actions. In autonomous mode, it chains steps without pausing, though Anthropic still applies safeguards on the most sensitive actions. The right approach is to run a new workflow in standard mode first, review what Claude does at each step, and switch to autonomous only once you're confident in the workflow. ### Can I limit which sites Claude can see? Yes. Access is granted site by site in the extension settings panel, and you can revoke any site instantly. Claude has no visibility into sites you haven't explicitly enabled. Team and Enterprise admins can also set org-wide allowlists and blocklists to enforce consistent policy across a team. ### Should businesses use the Claude Chrome extension? Yes, for the core use cases: drafting email replies in context, competitive research across tabs, CRM page reading, and form completion on known sites. These are all within the safe zone of standard mode on trusted sites. Businesses handling regulated data should stay on Enterprise plans with appropriate data processing agreements before granting access to any pages containing that data. ### What are the biggest safety risks with the extension? The two practical risks are: using autonomous mode on untrusted or unfamiliar sites before reviewing what the workflow does, and enabling the extension on pages containing data covered by confidentiality agreements or regulated by HIPAA, GDPR, or similar frameworks without the right Enterprise data agreements in place. Both risks are avoidable with deliberate setup. ### Does the Claude Chrome extension track my browsing? Claude can only read pages on sites you've explicitly granted access to in the settings panel. It does not run in the background reading every site you visit. Nothing is processed until you actively use Claude on an enabled site. Anthropic handles the processed content under their standard privacy policy, which is the same policy that applies to everything you send to claude.ai. --- ## Related guides - [Claude Chrome extension: setup, 8 use cases, privacy](/blog/claude-chrome-extension) - [How to use Claude Code](/blog/how-to-use-claude-code) - [Claude for Excel](/blog/claude-for-excel) --- ## Sources and citations - [Claude for Chrome announcement (Anthropic)](https://www.anthropic.com/news/claude-for-chrome) - [Anthropic privacy policy](https://www.anthropic.com/privacy) - [Claude AI for Chrome (Chrome Web Store)](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) - [Claude for Chrome documentation (docs.claude.com)](https://docs.claude.com/en/docs/claude-for-chrome) --- # How to Install the Claude Chrome Extension Source: https://theaiarchitects.com/blog/how-to-install-claude-chrome-extension Published: 2026-06-03 Install the Claude Chrome extension in four steps: open the Web Store, click Add to Chrome, sign in with your paid plan, and grant site access. To install the Claude Chrome extension, open the [Claude AI for Chrome listing on the Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip), click Add to Chrome, and sign in with your paid Claude account. I'm Tom. I build AI systems for business owners and have been testing Claude for Chrome since it expanded to Pro, Team, and Enterprise plans on 18 December 2025. The install itself takes under two minutes. The part that trips most people up is the permissions prompt and the site-access step after that, so this walkthrough covers both in detail. --- > [CTA-BLUEPRINT] --- ## Which Claude plans include the Chrome extension? The Claude Chrome extension is available on Pro ($20/mo), Max ($100/mo), Team, and Enterprise plans. Free accounts do not have access to the browser extension. Anthropic launched it as a limited pilot to 1,000 Max plan users in August 2025, expanded it to all Max subscribers in November 2025, and opened it to Pro, Team, and Enterprise on 18 December 2025. If you are on a paid Claude plan today, you have access. Check your plan at [anthropic.com/pricing](https://www.anthropic.com/pricing) if you are not sure which tier you are on. --- ## Where do I download the Claude Chrome extension? The official download is the [Claude AI for Chrome listing on the Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip), published by Anthropic. That is the only legitimate source. Do not install Claude extensions from third-party sites or unofficial listings. The extension works in any Chromium-based browser: Chrome, Edge, Arc, and Brave all work. Firefox and Safari are not supported. --- ## How to install the Claude Chrome extension The full installation takes four steps. Each one is covered below with exactly what you will see on screen. ### 1. Open the Chrome Web Store listing Navigate to the [Claude AI for Chrome page](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) in the Chrome Web Store. Confirm the publisher is Anthropic before you proceed. You are looking for the verified Anthropic badge on the listing. Alternatively, open [claude.ai/download](https://claude.ai/download) and follow the browser extension link from there. That page links directly to the correct Store listing and is the route Anthropic recommends in their own documentation. ### 2. Click "Add to Chrome" and accept the permissions prompt Click the blue Add to Chrome button. Chrome will show a permissions dialog listing what the extension can access. The dialog covers reading and changing data on websites you visit, which is what gives Claude the ability to see the active page. Click Add extension to confirm. The extension installs in a few seconds and the puzzle-piece icon appears in your browser toolbar. ### 3. Sign in with your Claude account Click the Claude extension icon in the toolbar. A sign-in panel opens inside the browser. Log in with the same email and password you use at claude.ai. If you are on a Team or Enterprise plan and your organisation uses SSO, sign in through your organisation's SSO flow rather than directly. The extension inherits your session from claude.ai, so if you are already signed in there, clicking the icon may authenticate you automatically. ### 4. Grant site access and set your preferred mode After signing in, open the extension settings panel. This is where you control which sites Claude can read. Access is off by default for every site. Add the sites you want Claude to be able to see. A sensible starting point is one or two sites you use for research or daily work: a CRM, a news site, a competitor's pricing page. You can revoke access at any time by removing the site from the list. You will also see an option to choose between standard mode and autonomous mode. Standard mode asks for confirmation before Claude takes high-risk actions like submitting a form or clicking a purchase button. Autonomous mode lets Claude chain actions without a confirmation step, but Anthropic keeps additional safeguards active for the most sensitive action types even in that mode. Leave it on standard mode until you are familiar with what Claude does in your specific workflow. --- ## How do I use the Claude Chrome extension after installing it? Once the extension is installed and you have granted access to a site, navigate to a page on that site and open a new Claude conversation at claude.ai. Claude will confirm it can see the page content. From there, you give it instructions in plain language: summarise this article, extract the pricing tiers from this table, draft a reply to this email thread. The [Claude Chrome extension guide](/blog/claude-chrome-extension) covers the eight business use cases in detail, including competitive research across multiple tabs and form completion workflows. That post is the right next read once installation is done. --- ## First-run permission: what the dialog actually says The permissions prompt is the step where most people hesitate. Chrome lists the extension's access as "read and change all your data on websites you visit," which sounds broader than it is. In practice, the extension reads the content of pages you have explicitly enabled in the settings. Anthropic also maintains a category blocklist that prevents the extension from reading financial services sites, adult content, and pirated content regardless of your settings. The "all websites" phrasing in Chrome's generic prompt is Chrome's default language, not a description of what Claude actually touches. For Team and Enterprise users, admins can configure org-wide allowlists and blocklists from the admin panel. That is the recommended setup before rolling the extension out to a team. --- ## Standard mode vs autonomous mode: which should you use? Standard mode is the right choice for most users. Claude asks for confirmation before taking any action that could be difficult to reverse: form submissions, button clicks, purchases. You see what it is about to do before it does it. Autonomous mode is useful for repetitive multi-step workflows you have already tested and understand. Before switching to autonomous mode for any workflow, run it in standard mode at least once to see the full action chain. Anthropic's adversarial testing found that safety mitigations in standard mode block the significant majority of prompt injection attempts that would otherwise redirect Claude's actions. Do not run autonomous mode on pages containing client data or confidential documents unless you are on an Enterprise plan with appropriate data processing agreements in place. Read the [Claude Code on the web](/blog/claude-code-web) post for how autonomous mode fits into larger developer workflows where Claude is acting across the terminal and the browser simultaneously. --- ## Troubleshooting the Claude Chrome extension install A few things that commonly go wrong on first install. The extension icon appears in the toolbar but does not respond. This usually means you are not signed in to claude.ai in the same browser profile. Sign in at claude.ai first, then click the extension icon again. Claude says it cannot see the page. Check the extension settings panel and confirm the site is on your access list. Claude cannot read a site that is not explicitly enabled, even if the extension is installed and you are signed in. The permissions prompt did not appear. Some organisations run Chrome policies that block extension permissions prompts. Check with your IT team about installing browser extensions under a managed Chrome policy. The extension is not available in the Chrome Web Store. Some regions have restricted access to the Claude extension during staged rollouts. Check [anthropic.com/pricing](https://www.anthropic.com/pricing) to confirm the extension is available on your plan in your region. --- ## Is the Claude Chrome extension free? The extension itself is free to download from the Chrome Web Store. Using it requires an active paid Claude subscription. The lowest-cost access is the Pro plan at $20 a month. There is no free trial of the browser extension that is separate from a Claude subscription. Team and Enterprise plans add org-wide configuration controls, admin allowlists and blocklists, and data processing agreements for regulated industries. If you handle client data or operate under any compliance framework, those plan tiers are the ones worth evaluating before granting the extension access to sensitive sites. --- ## How do I uninstall the Claude Chrome extension? Right-click the Claude icon in the Chrome toolbar and select Remove from Chrome. Chrome asks for confirmation and removes the extension completely. All site access permissions are cleared when you uninstall. If you want to pause access without uninstalling, you can disable the extension from Chrome's extension management page at `chrome://extensions`. Disabling removes Claude's ability to read any page until you re-enable it. The site access list you configured is preserved while the extension is disabled. --- > [CTA-BLUEPRINT] --- ## Claude Chrome extension FAQ ### How do I install the Claude Chrome extension? Open the [Claude AI for Chrome listing](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) in the Chrome Web Store, click Add to Chrome, and accept the permissions prompt. After installation, click the extension icon and sign in with your paid Claude account. Then open the extension settings and add the sites you want Claude to be able to read. ### Which Claude plans include the Chrome extension? Pro, Max, Team, and Enterprise plans all support the Chrome extension as of 18 December 2025. Free accounts do not have access. Pro starts at $20 a month. Team and Enterprise plans add admin controls and data processing agreements for organisations that need them. ### Where do I download the Claude Chrome extension? The only official download is the [Claude AI for Chrome listing](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) on the Chrome Web Store, published by Anthropic. You can also reach it via [claude.ai/download](https://claude.ai/download). Do not install Claude browser extensions from any other source. ### How do I use the Claude Chrome extension after installing it? After installing and signing in, grant access to the sites you want Claude to read in the extension settings panel. Navigate to one of those sites, open a new conversation at claude.ai, and give Claude instructions in plain language. Claude reads the active page and responds based on the content it can see. The full walkthrough of use cases is in the [Claude Chrome extension guide](/blog/claude-chrome-extension). ### Is the Claude Chrome extension free? The extension is free to download. Using it requires an active paid Claude subscription starting at $20 a month for Pro. There is no separate free tier for the browser extension. ### How do I uninstall the Claude Chrome extension? Right-click the Claude icon in the Chrome toolbar and select Remove from Chrome, then confirm. All site access permissions are cleared on removal. To pause without uninstalling, disable the extension at `chrome://extensions`. ### What browsers does the Claude Chrome extension support? The extension works in Chrome and other Chromium-based browsers: Edge, Arc, and Brave. Firefox and Safari are not supported at launch. If your team uses a mix of browsers, only users on Chromium-based browsers can use the extension. ### Why can Claude not see the page after I install the extension? Claude can only read pages you have explicitly added to the access list in the extension settings panel. Every site is off by default. Open the settings panel, add the site URL, and navigate back to the page. If Claude still cannot read it, confirm you are signed in to the same Claude account in the same browser profile. --- ## Related guides - [Claude Chrome extension: 8 use cases, setup, and the privacy trade-off](/blog/claude-chrome-extension): the full picture of what the extension does and where it earns its place in a business workflow. - [How to use Claude Code](/blog/how-to-use-claude-code): the complete beginner guide to Claude Code, Anthropic's terminal-based AI coding tool. - [Claude Code on the web](/blog/claude-code-web): how developers use Claude Code alongside the browser extension for terminal-to-browser debugging loops. --- ## Sources and citations - [Claude AI for Chrome on the Chrome Web Store](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) (Anthropic, verified publisher) - [Claude pricing page](https://www.anthropic.com/pricing): plan comparison including browser extension access - [claude.ai/download](https://claude.ai/download): Anthropic's official download page for Claude apps and extensions --- # Blender MCP: Control Blender With Claude (Setup + Real Examples) Source: https://theaiarchitects.com/blog/blender-mcp Published: 2026-06-03 Blender MCP connects Blender 3D to Claude via the Model Context Protocol. You describe what you want in plain English and Claude creates, modifies, and scripts objects in Blender directly. Blender MCP connects Blender 3D to Claude through the [Model Context Protocol](https://modelcontextprotocol.io). You describe a scene in plain English and Claude creates the objects, applies the materials, and runs the Python directly inside Blender. No separate script file. No copy-pasting into the Python console. The project is by Ahuja Siddharth and lives on GitHub at [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp). It works with Claude Desktop, Cursor, and VS Code. I'm Tom. I teach operators how to build with Claude Code, and Blender MCP is one of the more impressive demonstrations of what MCP servers make possible with creative tools. > [CTA-BLUEPRINT] ## How Blender MCP works The system has two components. A Blender addon (`addon.py`) creates a socket-based server inside Blender and listens for commands. An MCP server implements the Model Context Protocol and connects to that socket. Claude talks to the MCP server, which relays instructions to Blender. Communication uses JSON over TCP sockets. You install the addon into Blender, start the socket server from the addon panel, then connect Claude to the MCP server. Once connected, Claude can query the scene and send commands directly. ## What you need before installing Before you install anything, check these requirements: - Blender 3.0 or later - Python 3.10 or later (for the MCP server) - The `uv` package manager The `uv` requirement catches people off guard. It is a fast Python package manager that you install separately. If you already have it for other Python work, you are ready. If not, install it first before running the MCP server. ## Installation steps **Step 1:** Download `addon.py` from the GitHub repository at `ahujasid/blender-mcp`. **Step 2:** Open Blender. Go to Edit, then Preferences, then Add-ons. Click Install and select the `addon.py` file you downloaded. **Step 3:** Enable the addon in the list. A panel called BlenderMCP appears in the sidebar (press N to open the sidebar if it is hidden). **Step 4:** Click Start MCP Server in the BlenderMCP panel. Blender now listens for commands on a local TCP socket. **Step 5:** Add the MCP server to your Claude configuration. The GitHub README has the exact JSON block for Claude Desktop. The server connects via the socket Blender just opened. Once connected, tell Claude what you want in plain English and it starts working. ## What Claude can do inside Blender The MCP server exposes several capabilities to Claude. Claude can create, modify, and delete 3D objects. You can ask it to add a sphere, resize a cube, move an object to a specific coordinate, or delete the selected mesh. Claude can apply and modify materials. Describe a colour or material property and Claude sets it programmatically. Claude can inspect the current scene. It can tell you what objects exist, their positions, their materials, and their relationships before deciding what to change. Claude can execute arbitrary Python code inside Blender via the `execute_blender_code` tool. The project documentation is direct about this: use it with caution. Arbitrary Python execution is powerful, but it can also crash Blender or corrupt your scene. Save before executing anything non-trivial. Claude can download assets from Poly Haven, the open-source 3D asset library, and integrate them into your scene. The project notes that Poly Haven integration can be erratic. Treat it as a useful but unreliable extra rather than a core workflow. Claude can also generate 3D models through Hyper3D and bring them into the scene. ## Real examples from the community The examples that circulate most in the 3D community show the range of what is possible. Someone asked for a low-poly dungeon scene with a dragon guarding treasure. Claude created the geometry, placed the elements, and applied simple materials for the whole scene. Beach scenes using HDRIs and environmental assets have been recreated with simple descriptions, including HDR sky lighting pulled from Poly Haven. Architectural walkthroughs and product visualisation mockups have been built by describing the space or product and letting Claude generate the scene structure. These are impressive demonstrations. They are also the cleaner end of what you will get. Complex, precise work still benefits from reviewing what Claude produced and iterating. ## What to keep in mind The `execute_blender_code` tool is the most powerful and the most dangerous. Claude uses it for operations the specific MCP tools do not cover. Save your work before any complex operation. If Claude runs code that crashes Blender, your unsaved changes are gone. The Poly Haven integration works inconsistently. Sometimes Claude loads assets cleanly. Sometimes the request fails. Build workflows that can handle that gracefully. Complex operations work better in smaller steps. Instead of asking for a fully detailed scene in one prompt, build it in stages. Claude tends to produce cleaner results when it can inspect what it just created and iterate. ## Blender MCP FAQ ### Does Blender MCP work with Claude Code? The project is primarily designed for Claude Desktop, Cursor, and VS Code. Claude Code can connect to any MCP server, so it is possible to wire up Blender MCP through your `.mcp.json`, but the standard setup targets the Desktop app. Check the GitHub README for the current recommended configuration. ### Do I need programming knowledge to use Blender MCP? You need to be comfortable installing a Blender addon and editing a JSON config file. After that, you describe what you want in plain English. The Python execution happens on Claude's side, not yours. ### Is Blender MCP free? The MCP server and addon are open-source and free. Your Claude usage costs what it normally costs. There are no additional fees for Blender MCP itself. ### Can Claude MCP replace a 3D artist? No. Claude MCP speeds up the structural and scripting side of 3D work. Detailed modelling, UV unwrapping, rigging, and animation still need a skilled artist. Use it to prototype fast, generate base meshes, and automate repetitive Python tasks, not as a replacement for craft. ### Where is the GitHub repository? The repository is at `github.com/ahujasid/blender-mcp`. The README has the full installation guide and configuration JSON for each supported client. ## Build faster with Claude and your tools Blender MCP is one of several MCP servers that plug real creative and developer tools directly into Claude. For the ones I use in my Claude Code workflow, read [Claude Code MCP: Setup, Scopes and the 4 Servers I Use](/blog/claude-code-mcp). For a broader look at how MCP extends Claude, read [Claude Plugins Explained](/blog/claude-plugins). The [free Claude Code Blueprint](/blueprint) covers the MCP setup process end to end. The [30-day challenge](/challenge) is where you build working systems with it. ## Related guides - [Best MCP servers for Claude Code (my stack)](/blog/best-mcp-servers-for-claude-code) --- # Context7 MCP: Up-to-Date Docs Inside Claude Code (2026) Source: https://theaiarchitects.com/blog/context7-mcp Published: 2026-06-02 Context7 is an MCP server that pulls current library documentation into Claude Code at query time, stopping the hallucinated APIs and outdated code examples. Context7 is an MCP server that pulls current, version-specific library documentation directly into Claude Code when you ask about a package. Without it, Claude answers from training data that can be months or years out of date. With it, Claude has the right docs in its context window before it writes a single line. It has [56,300 stars on GitHub](https://github.com/upstash/context7). That number tells you how many developers have hit the same problem: outdated code examples, hallucinated APIs, and generic answers that break on the version you are actually running. I'm Tom. I teach Claude Code operators how to build real production systems, and Context7 is one of the first MCP servers I install on a new machine. > [CTA-BLUEPRINT] ## What problem does Context7 solve? Claude Code is trained on a snapshot of the internet. That snapshot has a cutoff. When you ask about a package that has shipped major updates since training, Claude answers from old data. The result is code that looks right but does not work. An API method that no longer exists. A config option that was renamed. A pattern that the library deprecated two versions ago. You debug for 20 minutes before realising Claude was working from the wrong docs. Context7 fixes this by pulling documentation at query time, not training time. When you ask Claude about a library, Context7 fetches the current official docs and injects them into the context window. Claude then answers from what is actually true right now. ## How Context7 works inside Claude Code Context7 exposes two tools to Claude Code. The first is `resolve-library-id`. It takes a plain library name and converts it to a Context7-compatible ID. If you ask about React or Tailwind or Drizzle, Claude starts here to get the canonical identifier before fetching anything. The second is `query-docs`. It takes a library ID and a query and returns the relevant documentation. Claude uses this to pull exactly the section it needs, not the entire docs for a library. Both tools run in the background. From your side, you just ask Claude about a library and it handles the rest. You see more accurate answers without changing your workflow. ## Installing Context7 in Claude Code The fastest path is a single command: This authenticates via OAuth, generates an API key, and registers the [MCP server](https://code.claude.com/docs/en/mcp) with Claude Code. If you want to target Claude Code specifically, add the `--claude` flag. For manual configuration, the MCP server URL is `https://mcp.context7.com/mcp`. Add it to your `.mcp.json` with your `CONTEXT7_API_KEY` passed as a header. The setup command handles all of this automatically. After installation, restart Claude Code and you are done. No extra prompts needed in your workflow. ## What you get in practice The difference is most visible when you are working with fast-moving libraries. Next.js ships breaking changes regularly. Drizzle ORM added new patterns in recent versions. The Claude Code MCP ecosystem itself updates constantly. Before Context7, Claude would give you the pattern from its training snapshot. That might be two or three major versions behind. After Context7, Claude pulls from the current docs and gives you the pattern that actually works today. You can also specify a version in your prompt. If your project pins a specific version of a library, tell Claude which one and Context7 will match the documentation to that version rather than the latest. ## Context7 vs just pasting docs manually Some operators paste docs or README excerpts directly into the context window. That works for small files. It breaks down quickly once a library's API surface is large, or when you need accurate answers across several libraries in the same session. Context7 is surgical. It fetches only the section relevant to your query, not the whole docs. Your context window stays clean. And it does it automatically, so you do not spend time hunting for the right page and copying it in. The 56,300 stars on GitHub are not from developers who paste docs manually. ## MCP server scope options Context7 works at the user level (available across all your projects) or at the project level (scoped to one codebase). If you install it globally with `npx ctx7 setup`, it is available everywhere. If you prefer to keep it project-specific, add the MCP config to your project's `.mcp.json` instead of your user config. For a full walkthrough of how MCP server scopes work in Claude Code, read [Claude Code MCP: Setup, Scopes and the 4 Servers I Use](/blog/claude-code-mcp). ## Context7 FAQ ### Is Context7 free? Context7 has a free tier for personal use. Commercial use and higher query volumes require a paid plan. The `npx ctx7 setup` flow walks you through the options during authentication. ### Does Context7 work with other AI coding tools? Yes. Context7 also works with Cursor, Copilot in VS Code, and other MCP-compatible tools. The Claude Code setup just targets Claude Code specifically. The `npx ctx7 setup --claude` flag writes the configuration to the right place for Claude. ### What libraries does Context7 support? Context7 supports most major JavaScript, TypeScript, and Python libraries, plus a growing list of others. Coverage is driven by the open-source community. If a library you need is missing, you can contribute documentation to the Context7 index. ### Will Context7 slow down Claude Code? The `query-docs` tool adds one fetch step before Claude answers library questions. In practice the delay is not noticeable in a normal coding session. Claude does not call Context7 on every response, only when it is fetching library-specific information. ## Stop debugging outdated answers The most expensive debugging sessions are the ones where the code Claude wrote was technically correct for a library version from 18 months ago. Context7 eliminates that class of error. Install it once. It runs every session. You stop hitting outdated patterns and start shipping code that matches the library you are actually using. Start with the [free Claude Code Blueprint](/blueprint) for the foundations, then join the [30-day challenge](/challenge) to build real production systems. ## Related guides - [Best MCP servers for Claude Code (my stack)](/blog/best-mcp-servers-for-claude-code) - [Playwright MCP for Claude Code (setup + verdict)](/blog/playwright-mcp-claude-code) --- # Claude Opus 4.8: The Model That Stopped Guessing Source: https://theaiarchitects.com/blog/claude-opus-4-8 Published: 2026-05-29 Claude Opus 4.8 is Anthropic's new flagship model, and the real upgrade isn't speed. It's honesty: around 4x less likely to let its own code flaws slip. Claude Opus 4.8 is Anthropic's new flagship model, released on May 28, 2026, as a direct upgrade to Opus 4.7 at the same price. It improves across coding, agentic, and reasoning benchmarks, but the change that actually matters for daily work is honesty. The model is around four times less likely to let a flaw in its own code pass without flagging it. I'm Tom. I run AI Architects and I've shipped real work on every Opus version since 4.5. I read the announcement and the system card the morning it dropped, then ran it on live projects. Here's what changed, what shipped alongside it, and whether it's worth switching. > [CTA-BLUEPRINT] ## What is Claude Opus 4.8? Claude Opus 4.8 is the latest version of Anthropic's most capable model, built for coding, agentic tasks, and knowledge work. It replaces Opus 4.7 as the default Opus tier and costs exactly the same to run. Anthropic describes it as a modest but tangible improvement on its predecessor, and a more reliable collaborator on long tasks. The headline number is reliability. On Anthropic's own evaluations, Opus 4.8 is roughly four times less likely than Opus 4.7 to let a flaw in code it wrote pass unremarked. In plain terms, it catches more of its own mistakes before handing the work back to you. ## What actually changed in Opus 4.8 The biggest upgrade in Opus 4.8 is that it stopped pretending the code works when it doesn't. If you have built anything with an AI model, you know the pattern. It writes a fix, tells you it's done, sounds completely sure of itself, and then you run it and nothing works. I have watched that happen more times than I can count. The model was never lying on purpose. It just jumped to "I fixed it" before the evidence was actually there. Anthropic trains its models to be honest, but every model has had a habit of claiming progress on thin evidence. Opus 4.8 is the first version where that mostly stopped. Early testers reported it flags uncertainty about its own work and makes fewer claims it can't support. That tracks with what I saw: it tells you when it isn't sure instead of bluffing past the gap. That one change does more for real work than another point on a coding benchmark. Most of the time I lose with AI was never the writing itself. It was trusting a confident answer that turned out to be wrong, then spending an hour finding out why. ## How does the Opus 4.8 honesty improvement work? The honesty gain comes from training the model to avoid unsupported claims and surface its own uncertainty. Anthropic measured this directly: Opus 4.8 is about four times less likely to let flaws in its code go unflagged compared to Opus 4.7. The improvement shows up most in long agentic tasks, where older models tended to declare victory early. Anthropic also ran a full alignment assessment before release. Its Alignment team reported that Opus 4.8 reaches new highs on prosocial traits like supporting user autonomy, and shows rates of misaligned behavior substantially lower than Opus 4.7. The detail sits in the official system card. ## What else shipped with Opus 4.8 Opus 4.8 launched alongside four updates worth knowing, not just a model swap. Each one targets a real friction point in how people use Claude day to day. ### 1. Dynamic workflows in Claude Code Dynamic workflows let Claude take on much larger jobs inside Claude Code. The feature, in research preview, lets Claude plan the work, run hundreds of parallel subagents in a single session, then verify its outputs before reporting back. Anthropic's stated example is a codebase-scale migration across hundreds of thousands of lines from kickoff to merge, with the existing test suite as the bar. This is the same direction my mentorship clients have been pushing toward with agent fleets. One of them, Cal Hewitt, used agentic dispatch patterns to build automated work order routing for a Toronto maintenance contractor, cutting acknowledgement time from up to 48 hours down to minutes. The full breakdown is in his [case study](/case-studies/cal-hewitt). Dynamic workflows make that class of build easier to reach inside Claude Code itself. It's available on Team, Enterprise, and Max plans. ### 2. Effort control Effort control lets you choose how hard Claude works on a response. A new control sits next to the model selector in claude.ai and Cowork. On higher effort, Claude thinks more often and more deeply for better answers. On lower effort, it responds faster and burns through your rate limits more slowly. Opus 4.8 defaults to high effort, which Anthropic judges the best balance of quality and speed. You can push it to "extra" (called `xhigh` in Claude Code) or "max" for difficult, long-running tasks. The control is available on all plans. ### 3. A cheaper, faster fast mode Fast mode runs Opus 4.8 at 2.5 times the normal speed, and it now costs three times less than it did on previous models. That makes the speed tier actually worth using for iterative work, where waiting on a slow response breaks your flow. ### 4. Mid-task system messages in the API The Messages API now accepts system entries inside the messages array. Developers can update Claude's instructions partway through a task without breaking the prompt cache or routing the change through a user turn. If you build agents, this matters more than it sounds: you can adjust permissions, token budgets, or environment context while an agent is running. > [CTA-BLUEPRINT] ## Claude Opus 4.8 vs 4.7: what's different? Opus 4.8 beats Opus 4.7 on benchmarks across coding, agentic skills, and reasoning, but the meaningful gap is reliability. The standout difference is that 4.8 is around four times less likely to let its own code flaws slip past unflagged, and it flags uncertainty instead of overclaiming. Cost is identical, so there's no reason to stay on 4.7 for budget. On coding tasks, 4.8 at its default high effort spends a similar number of tokens to 4.7's default, but returns better results for that spend. Alignment metrics also improved, with misaligned behavior rates substantially below 4.7. ## Claude Opus 4.8 pricing: is it free? Claude Opus 4.8 is not free, but it is available on Anthropic's free and paid plans with usage limits, and effort control now lets free users stretch those limits further. For developers, API pricing is unchanged from Opus 4.7: 5 dollars per million input tokens and 25 dollars per million output tokens. Fast mode runs at 10 dollars per million input and 50 dollars per million output. The practical takeaway is that the better model costs the same as the one it replaced. There is no upgrade tax for the improved judgement. ## How to use Opus 4.8 in Claude Code You use Opus 4.8 in Claude Code by selecting it as your model, the same way you ran 4.7. If you are new to the tool, my [full Claude Code guide](/blog/how-to-use-claude-code) walks through setup from scratch. Once you're in, pick the effort level that fits the job: default high for most work, `xhigh` for hard problems, and lower effort for quick edits that don't need deep thinking. For large jobs, dynamic workflows are where Opus 4.8 pulls ahead. If you want to understand the subagent model that powers them, my breakdown of [Claude Code multi-agent setups](/blog/claude-code-multi-agent) covers how parallel agents divide and verify work. ## Verdict: is Claude Opus 4.8 worth it? Yes, and the switch is a no-brainer because it costs the same as Opus 4.7. If you write code with Claude, the honesty improvement alone pays for itself the first time it flags a fix it isn't sure about instead of sending you down a dead end. The reliability gain is the kind of upgrade you feel on real work, not just in a benchmark table. It's worth being honest about the ceiling. Anthropic itself calls this a modest improvement, not a leap, and hints that a bigger jump is coming with a higher-intelligence model class. If you were hoping for a dramatic capability jump, this isn't it. For everyone shipping daily work, a model that stops guessing is worth more than one that scores two points higher and still bluffs. ## Claude Opus 4.8 FAQ ### When was Claude Opus 4.8 released? Claude Opus 4.8 was released on May 28, 2026. It became available everywhere on launch day across claude.ai, Claude Code, Cowork, and the API. ### Is Claude Opus 4.8 better than Opus 4.7? Yes. Opus 4.8 improves on Opus 4.7 across coding, agentic, and reasoning benchmarks, and it is around four times less likely to let a flaw in its own code pass unflagged. It also scores better on alignment metrics, at the same price. ### How much does Claude Opus 4.8 cost? API pricing is 5 dollars per million input tokens and 25 dollars per million output tokens, unchanged from Opus 4.7. Fast mode costs 10 dollars per million input and 50 dollars per million output. Subscription access is included on Claude's paid plans. ### What are dynamic workflows in Claude Code? Dynamic workflows are a research-preview feature that lets Claude plan a large task, run hundreds of parallel subagents in one session, and verify its outputs before reporting back. They are built for big jobs like codebase-scale migrations and are available on Team, Enterprise, and Max plans. ### What is effort control in Claude? Effort control is a setting next to the model selector that lets you choose how hard Claude works on a response. Higher effort means deeper thinking and better answers, while lower effort means faster responses that use your rate limits more slowly. It is available on all plans. ### Can I use Opus 4.8 for free? You can use Opus 4.8 on Claude's free plan within usage limits, and effort control helps free users stretch those limits. Heavy or professional use needs a paid plan or API access. ## Sources and citations - [Introducing Claude Opus 4.8](https://www.anthropic.com/news/claude-opus-4-8) — Anthropic's official announcement and pricing - [Claude Opus 4.8 System Card](https://www.anthropic.com/claude-opus-4-8-system-card) — evaluations, honesty metrics, and the alignment assessment - [Claude models overview](https://platform.claude.com/docs/en/about-claude/models/overview) — API model IDs and current pricing ## Ready to build with Claude Code? A better model is only useful if you know how to put it to work. The Claude Code Blueprint shows you how to go from zero to a working build in 60 minutes, no coding required. If you want to go further with a cohort, the [30-day challenge](/challenge) takes you from setup to a shipped agent. ## Related guides - [Claude 4 models (Opus, Sonnet, Haiku): which for which job](/blog/claude-4-models) --- # Claude Code Agents Explained: Subagents, Agent View, and Teams Source: https://theaiarchitects.com/blog/claude-code-agents Published: 2026-05-28 Claude Code has four ways to run agents in parallel. Subagents, agent view, agent teams, and worktrees each do something different. Here is how to choose. Claude Code has four ways to run agents in parallel: subagents, agent view, agent teams, and worktrees. Each one handles a different coordination problem. Subagents offload a side task and return a summary. Agent view runs background sessions you monitor from one screen. Agent teams let multiple agents share a task list and message each other. Worktrees isolate parallel sessions so they never overwrite each other's files. The right one depends on three questions: who coordinates the work, do the workers need to talk to each other, and do the tasks touch the same files. I'm Tom. I teach Claude Code operators how to run production workflows, and I went through the full [Anthropic agent documentation](https://code.claude.com/docs/en/agents) to give you the clean version without the noise. > [CTA-BLUEPRINT] ## What is an agent in Claude Code? In Claude Code, an agent is a Claude session with its own context window, its own set of tools, and its own instructions. When Claude delegates work to an agent, that agent runs the task independently and returns only a result, not its entire working context. That is the key difference from asking Claude to do something in your main session. An agent's context stays separate. Your main conversation does not fill up with search results or file reads the agent needed to do its job. ## The four approaches side by side Anthropic's documentation lays out the trade-offs in a single table, and it is worth understanding before you reach for any specific approach. **Subagents** are delegated workers inside one session. They do a side task in their own context and return a summary. Use them when a task would flood your main conversation with content you will not reference again. **Agent view** is one screen for dispatching and monitoring background sessions. You open it with `claude agents`. Each background session runs without a terminal attached, so you can close agent view and the sessions keep working. This is a research preview and requires Claude Code v2.1.139 or later. **Agent teams** are multiple coordinated sessions with a shared task list and inter-agent messaging. Agents can message each other directly without routing everything through you. This is experimental and disabled by default. **Worktrees** are isolated git checkouts. Parallel sessions each get their own copy of the repository so they can edit without touching each other's files. Agent view creates worktrees automatically for background sessions that edit files. There is also `/batch`, which splits a large mechanical change into 5 to 30 worktree-isolated subagents, each of which opens its own pull request. It is the right tool for repo-wide migrations or mechanical refactors you can describe in one instruction. ## How to choose The decision comes down to three questions. **Who coordinates the work?** If you want Claude to delegate and collect results inside one conversation, use subagents. If you are handing off independent tasks and checking back on them, use agent view. If you want Claude to plan, assign, and supervise a group of workers that coordinate among themselves, use agent teams. **Do the workers need to talk to each other?** Subagents report results back to the conversation that spawned them. Agent view sessions report only to you. Teammates in an agent team share a task list and message each other directly. **Do the tasks touch the same files?** If yes, use worktrees. Agent view does this automatically for background sessions. Subagents and sessions you run yourself can each get their own worktree too. ## Subagents: the starting point for most operators Subagents are the most mature and most used approach. Each one runs with a custom system prompt, specific tool access, and independent permissions. You can also control costs by routing subagent tasks to a faster, cheaper model like Haiku instead of Opus. [Custom subagents](https://code.claude.com/docs/en/sub-agents) live in your user config or in a project's `.claude/` directory. Claude uses each subagent's description to decide when to delegate. Write a clear description and Claude starts routing tasks automatically. The `/agents` command (inside a session) opens a panel showing your running subagents and lets you create or edit custom ones. This is separate from `claude agents`, which opens agent view. Both use the word "agents" but they do different things. To track in-session background tasks, use `/tasks`. ## Agent view: background work you can monitor Agent view is the right tool when you have several independent tasks that Claude can run without you watching every step. Open it with `claude agents` in your shell, dispatch a task from the bottom input, and each task becomes a row showing its state. Sessions stay alive even when agent view is closed. A background supervisor process keeps them running, so you can dispatch work, close the terminal, and check back when you are ready. Sessions survive sleep but not shutdown. Row summaries are generated by a Haiku-class model. They refresh every 15 seconds while a session works, and once when each turn ends. ## Agent teams: experimental coordination Agent teams let agents message each other and share a task list instead of reporting everything through you. A lead agent creates the team, creates tasks, and spawns teammates. Teammates claim tasks, message each other when they need to coordinate, and mark work done. This is experimental and disabled by default. Enable it by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your settings.json `env` block. You need v2.1.32 or later. Agent teams do not isolate teammates in worktrees, so partition the work so each teammate owns a different set of files. Otherwise two agents editing the same file will conflict. For more on agent teams setup and real examples, read [Claude Agent Teams: How to Run Multiple AI Agents at Once](/blog/claude-agent-teams). ## Worktrees: file isolation for parallel work Worktrees give each parallel session its own git checkout under `.claude/worktrees/`. Sessions can read the same codebase but each writes to its own copy. You do not always need to manage this yourself. Agent view creates a worktree automatically before a background session edits files. For manual parallel work, you can create worktrees yourself and start Claude sessions in each one. ## What about the Claude Agent SDK? The Agent SDK is for building agents that run outside Claude Code, via the Anthropic API. If you are building a production agent you will deploy as a service, that is the right tool. For agents that run inside your Claude Code workflow, subagents and agent teams are the right abstraction. The SDK and Claude Code agents serve different audiences. For a deep look at the SDK, read [Claude Agent SDK: Build Your First Production Agent](/blog/claude-agent-sdk). ## Claude Code agents FAQ ### What is the difference between a subagent and a background agent? Subagents run inside your current session and return a result when done. Background agents (started through agent view or `claude --bg`) are separate sessions that keep running without your terminal attached. You can check on them from agent view and attach whenever you want. ### Do subagents cost extra? No extra charge, but they multiply token usage. Each subagent has its own context window, and running several at once burns through your quota faster than a single session would. You can reduce the cost by assigning subagent tasks to Haiku instead of Opus in the subagent's frontmatter. ### How many agents can I run at once? There is no hard limit, but rate limits apply. Running many background sessions in parallel uses your subscription quota proportionally. Anthropic's documentation notes that ten sessions in parallel uses quota roughly ten times as fast as one. ### Is agent view production-ready? Agent view is in research preview as of May 2026. It requires Claude Code v2.1.139 or later. The interface and keyboard shortcuts may change. Agent teams are even earlier, still experimental and off by default. ### Where do I start if I have never used agents? Start with subagents. They are the most stable, most documented, and easiest to reason about. Once you are comfortable delegating tasks to subagents, move to agent view for background monitoring, then consider agent teams only when you need agents to coordinate with each other. ## Build with agents, not around them The operators who get the most from Claude Code are not the ones who run the longest single sessions. They are the ones who delegate well, keep their main context clean, and let agents handle the work that would otherwise flood the conversation. Subagents are where most people should start. Agent view is where you go when you want to stop watching. Agent teams are where you go when the work itself needs coordination. Grab the [free Claude Code Blueprint](/blueprint) for the foundations, or join the [30-day challenge](/challenge) to build real systems with agents in your business. ## Related guides - [Claude Code Multi-Agent: Orchestration Patterns That Work in 2026](/blog/claude-code-multi-agent) - [Claude Agent Mode: Background Sessions You Monitor From One Screen](/blog/claude-agent-mode) - [Hermes Agent: A Beginner's Guide](/blog/hermes-agent) --- # What Is Claude Cowork? The AI That Does Your Work For You Source: https://theaiarchitects.com/blog/claude-cowork Published: 2026-05-28 Claude Cowork is Anthropic's desktop AI that does the work for you. What it is, how it works, what people build with it, and where it falls short. Claude Cowork is Anthropic's desktop AI that completes whole tasks for you instead of handing back instructions. You give it a goal, it works across your local files and apps, and it returns a finished deliverable. Anthropic's own line is blunt: "Give it a goal and Claude works on your computer, local files, and applications to return a finished deliverable." This is not a coworking app or an office booking tool. Cowork is a mode inside the Claude desktop app, sitting next to Chat and Code. I'm Tom. I teach operators to build with Claude, and I went through every major Cowork walkthrough from launch month, the ones from Jeff Su, Tina Huang, and Paul Lipsky included, to separate what actually works from launch hype. Here is the honest version. > [CTA-BLUEPRINT] ## What is Claude Cowork? Claude Cowork is a local AI agent that lives inside the Claude desktop app and does work on your actual computer. It reads, edits, and creates files in folders you choose. It plans a task, executes it step by step, and asks before anything significant happens. Tina Huang puts the category simply. "A local AI agent is an AI that lives on your actual computer that can autonomously do things with your files, your apps, and your tools." The difference from Claude Chat is the part that matters. Chat gives you text to copy and paste. Cowork gives you the finished file. ## Who is Claude Cowork for? Cowork is built for anyone whose workday is full of tasks that eat time but need no special skill. Anthropic names researchers, analysts, operations teams, finance teams, and legal professionals as the core users. The common thread is documents, data, and files. If your week involves sorting them, pulling numbers out of them, or turning them into reports, Cowork is aimed squarely at you. It is not built for developers shipping software. That is what Claude Code is for, and the two split cleanly along that line. ## How does Claude Cowork work? You describe an outcome, Cowork makes a plan, and it works through that plan while looping you in. Most creators converge on the same setup, so the mechanics are predictable once you see them once. ### The desktop tab and folder access Cowork is a tab in the Claude desktop app on Mac and Windows. There is no web or mobile version that runs the work itself, though you can fire off a task from your phone and let the desktop finish it. You point Cowork at a folder and grant access. Everyone who teaches it repeats the same rule. Make one dedicated parent folder so the rest of your machine stays untouched, then grant access to that. ### Skills, plugins, and projects Skills are reusable instruction sets saved as markdown. The reliable way to build one, per Jeff Su and Paul Lipsky, is to do the task manually with Claude first, then tell Cowork to turn that workflow into a skill. Plugins bundle skills and connectors together. Anthropic ships free ones for Productivity, Customer Support, and Finance. Projects wrap a folder with its own instructions, memory, and connections, so each area of your work stays separate. ### Scheduled tasks Cowork can run tasks on a cadence. A 6am inbox triage, a weekly Slack digest, a daily metrics pull. You define the schedule once and it repeats. There is a catch worth knowing before you rely on it. Paul Lipsky found that "in order for scheduled tasks to actually work, your computer needs to be on and Cowork needs to be open." He runs a second computer just for this. ## What people are actually building with it The demos are where Cowork stops sounding abstract. These are real runs from named creators, not my numbers. Jeff Su dropped over 100 receipts, a mix of PDFs and photos, into a folder and had Cowork extract every date, vendor, and amount into a formatted Excel file, flagging the blurry ones for review. That task is impossible in Claude Chat, which caps you at 20 files. Tina Huang pointed it at a desktop with 376 files and had it propose a clean folder structure. It also spotted an API key sitting exposed in a text file on her desktop. She then fed it 24 months of credit card statements and got an interactive spending dashboard that surfaced over 4,000 dollars in active subscriptions. Paul Lipsky had it read two weeks of Gmail to build a mini contact list and a brand-voice file, then draft replies directly inside Gmail rather than in the chat. He went further and built what he calls a "Cowork OS," a folder hierarchy where each project area has its own instructions and memory file. Tina Huang built an investment "mission control" dashboard that tracks her positions, researches opportunities, and sends a daily digest matched to her stated investing rules. Brock Mesarich runs a 7am morning briefing that pulls his calendar, urgent emails, and top priorities into one dashboard before he sits down. The pattern across all of them is the same. The value is in the setup, not the one-off prompt. ## Claude Cowork vs Claude Code vs Claude Chat Chat is for conversation and analysis. Code is for building software in a terminal with access to your whole machine. Cowork is for everyday knowledge work in selected folders, with approval gates. Brock Mesarich draws the cleanest line. "Cowork is basically your assistant, whereas Claude Code is your entire engineer." The technical version is that Cowork runs in a sandbox limited to the folders you grant, while Claude Code can touch your entire computer. I broke the full comparison down in [Claude Cowork vs Claude Code](/blog/claude-cowork-vs-claude-code). If you already live in the terminal, also read [how to use Claude Code](/blog/how-to-use-claude-code). ## Where Claude Cowork falls short Cowork is a research preview, and it shows in a few places. This is the part the hype videos skip. The browser extension is the weak point. Jeff Su was direct: "I simply can't recommend the extension right now. It's slow, it's unreliable, and it burns through your usage because it overthinks every step." It also still invents the occasional number. No Code MBA caught it reporting a subscriber count of 25,000 when the real figure was 36,000. Human review stays mandatory for anything high stakes. Linux is unsupported, and EU data residency is Enterprise only as of May 2026. > [CTA-BLUEPRINT] ## How to get Claude Cowork and what it costs Cowork ships inside the Claude desktop app and is available on all paid plans, per Anthropic. That means Pro at 20 dollars a month, Team at 25 dollars per seat, or Enterprise with custom pricing. There is no separate Cowork subscription. It launched as a research preview for Max subscribers, then widened to the lower tiers. Power users on heavy daily tasks will feel the usage limits faster, especially when running the slower, more meticulous Opus model. ## Verdict: is Claude Cowork worth it? Yes, if your day is full of repeatable file and document work and you are willing to spend an hour on setup. The operators getting real value treat it like an assistant they onboard, not a chatbot they query. No, if you want it to run unattended on a laptop you close at night, or you need it to touch a CRM like Salesforce or HubSpot, which it does not connect to yet. Jeff Su has made AI videos for three years and said he has "never felt this way about a single tool." That enthusiasm is real. So is the setup tax. ## Claude Cowork FAQ ### Is Claude Cowork free? No. Cowork is included on Anthropic's paid plans, starting with Claude Pro at 20 dollars a month. There is no free standalone version, though you do not pay extra for Cowork on top of your plan. ### Is Claude Cowork the same as Claude Code? No. Cowork is a sandboxed assistant for knowledge work in selected folders. Claude Code is a developer tool with full access to your machine and terminal. They share a CLAUDE.md file and can work on the same folder. ### What can Claude Cowork actually do? It organizes files, extracts data from receipts and statements, builds spreadsheets and reports, drafts emails inside Gmail, and runs scheduled tasks like a daily inbox triage. It works on your local files and returns finished deliverables. ### Does Claude Cowork work on Windows? Yes. Cowork runs on both Mac and Windows through the Claude desktop app. Linux is not supported as of May 2026. ### Is Claude Cowork safe to use on my files? It only accesses folders you explicitly grant, and it asks before significant actions like deleting or overwriting. Best practice is to point it at one dedicated folder, not your whole drive, and keep human review on important outputs. ### What apps can Claude Cowork connect to? Cowork has a connector marketplace covering Gmail, Google Calendar, Google Drive, Notion, and more. It does not yet connect to CRMs like Salesforce or HubSpot, or to ecommerce platforms. For unsupported apps, some users bridge them through a Zapier MCP connector. ### Can I use Claude Cowork on my phone? You can send a task from your phone and have Claude continue it on your desktop, but the work itself runs on the desktop app. There is no mobile version that executes tasks on its own, so your computer needs to be on for anything to run. ## Ready to build your own AI systems? Cowork is one piece of a bigger shift: operators who build their own tools instead of waiting for software to catch up. If you want the fastest path in, start with the [free Claude Code Blueprint](/blueprint), then join the [30-day challenge](/challenge) to install real systems in your business. ## Related guides - [How to Use Claude Cowork (Step-by-Step for Operators)](/blog/how-to-use-claude-cowork) - [Claude Cowork Plugins: Connectors, Skills, and What Ships Free](/blog/claude-cowork-plugins) --- # Claude Agent Teams: How to Run Multiple AI Agents at Once Source: https://theaiarchitects.com/blog/claude-agent-teams Published: 2026-05-28 Claude agent teams let multiple Claude Code agents talk to each other and share a task list. How they work, setup, and whether they beat subagents. Claude agent teams are a Claude Code feature that spawns multiple agents which share a task list and message each other directly. A lead agent breaks the work into tasks, each teammate claims tasks and works in its own context window, and they coordinate peer to peer instead of reporting everything back up the chain. This is the feature that shipped alongside Opus 4.6, and it goes further than the subagents people already know. I'm Tom. I teach Claude Code for a living, and I went through the deep demos from Cole Medin, IndyDevDan, Shaw Talebi, and Bart Slodyczka to pull what works from what is still an experimental rough edge. > [CTA-BLUEPRINT] ## What are Claude code agent teams? Agent teams are a coordinated group of Claude Code agents working the same goal at the same time. The old subagent model spawned isolated workers that returned a summary and nothing else. Agent teams let those workers talk. Cole Medin describes the leap. "This goes way beyond subagents. These agents actually talk to each other like, let me complete this before you work on this." Shaw Talebi frames the architecture cleanly. Subagents are centralized, a hub with spokes. Agent teams are a hybrid, a lead agent plus teammates that message each other directly. ## How do agent teams work? A lead agent creates a team, creates a shared task list, and spawns teammates with specific roles. Each teammate has its own session and context window. They claim tasks, mark them done, and send messages without routing through the lead every time. IndyDevDan lays out the full lifecycle in one line. "Create the team, create the tasks, spawn the agents, work in parallel, shut them all down, delete the team." Under the hood there are three families of tools. Team management to create and delete the team. Task management to create, list, and update the shared board. And a send message tool, which IndyDevDan calls "the most important one of all." Deleting the team at the end is good hygiene, because it resets the context you no longer need. ## Agent teams vs subagents Use subagents when the work does not need agents talking to each other. Use agent teams when it does, and when the task is complex enough to justify the extra tokens. Mark Kashef gives the decision rule directly. "Do you need agents to speak to each other? If the answer is no, then you can use subagents. Is the task complex enough to justify the overhead of tokens? If yes, then use agent teams." Cole Medin pipelines them. Subagents for research, because context isolation keeps the main thread clean. Agent teams for the actual build, where coordination pays off. If you are new to the distinction, start with [Claude Code subagents vs skills](/blog/claude-code-subagents-vs-skills). ## How to set up Claude code agent teams Agent teams are experimental and disabled by default, so the feature sits behind a setting you turn on yourself. You need Claude Code v2.1.32 or later, so update first and check with `claude --version`. Enable it by adding `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to your settings.json `env` block: That setting comes straight from Anthropic's orchestration docs, not a transcript, so it is the real key. You can set it globally in `~/.claude` or per project in `.claude/settings.json`. By default teammates run in-process, all inside your main terminal, which works anywhere. For split panes you need tmux or iTerm2, set through the `teammateMode` setting. Bart Slodyczka flags the order that trips people up. Start the tmux session first, then launch Claude, not the other way around. Split panes do not work in VS Code's terminal or Windows Terminal. Then invoke it with the words Anthropic uses in its own examples, like "create an agent team." Bart and Mark both warn that vague prompts make Claude hallucinate weird teams or fall back to plain subagents. ## What people built with agent teams The demos show both the ceiling and the current reality. These are real runs from named builders. Cole Medin ran four agents at once on a live code review, splitting security, code quality, and documentation across the team in tmux panes. The lead agent decided the team composition from a short prompt and built the shared task list itself. IndyDevDan pushed it hardest. He one-shotted 8 full-stack apps, then used a Haiku team under an Opus lead to investigate all 8 codebases, leaving his primary agent at only 31 percent context because the work was offloaded. Then there is the contrarian data point. Shaw Talebi ran the only real A/B test, subagents versus agent teams on identical tasks. Teams were faster. But "the subagents consistently produce better outputs than the teams," and he concluded he would "stick to subagents for actually getting stuff done." ## Where agent teams fall short The honest summary is that agent teams are powerful and not yet reliable. Plan around three things. Token cost is the big one. Cole saw two to four times the usage of a single agent. Mark Kashef was blunter. "It swallows up tokens like a vacuum. You could spend anywhere between 100 to 300,000 tokens just spinning up and executing an agent team." The feature is also not great at using itself yet. Cole found it hallucinates teams without precise prompts, and Mark watched the lead agent start coding instead of delegating, "stepping on the toes of its sub-employees." Output quality still trails subagents for now, which is Shaw's whole point. > [CTA-BLUEPRINT] ## Verdict: should you use agent teams? Use them today for parallel research, code review across a large codebase, and experiments where speed matters more than polish. They genuinely shine when the work splits cleanly into independent lanes. Skip them for tasks that must run in sequence, or where output quality is the priority, where subagents still win. Treat agent teams the way Mark frames it, like a bootstrapped founder hiring staff. You only spawn a team when the job is big enough to justify the payroll. ## Claude agent teams FAQ ### What is the difference between agent teams and subagents? Subagents are isolated workers that return only a summary, with no agent-to-agent communication. Agent teams share a task list and message each other directly. Subagents are better for clean research and quality output today. Agent teams are better for parallel, coordinated work. ### Are Claude agent teams free to use? The feature is free inside Claude Code, but it consumes API tokens fast, often two to four times a single agent. On usage-capped plans you can hit limits mid-run, so budget for the extra token cost. ### Do I need a special terminal for agent teams? For split-pane visibility, yes. Claude Code supports tmux and iTerm2 for showing each agent in its own pane. It does not work inside VS Code or Cursor, and Windows needs WSL. ### How many agents can a team have? There is no hard cap, but Mark Kashef found diminishing returns past roughly five or six agents. More agents means more token burn and more chances for them to overwrite each other's work. ### Are agent teams the same as the Claude Agent SDK? No. Agent teams are a built-in Claude Code feature for orchestrating multiple agents in the terminal. The [Claude Agent SDK](/blog/claude-agent-sdk) is a separate toolkit for building your own agents in code. ## Ready to build with Claude Code? Agent teams are an advanced move on top of solid Claude Code fundamentals. If you want those fundamentals fast, grab the [free Claude Code Blueprint](/blueprint), then install real working systems in the [30-day challenge](/challenge). ## Related guides - [Claude Code Agents Explained: Subagents, Agent View, and Teams](/blog/claude-code-agents) --- # Claude Cowork vs Claude Code: Which One Should You Use? Source: https://theaiarchitects.com/blog/claude-cowork-vs-claude-code Published: 2026-05-28 Claude Cowork vs Claude Code, explained simply. Cowork is your assistant, Code is your engineer. How they differ and which to use for what. Claude Cowork is your assistant and Claude Code is your engineer. Cowork handles knowledge work in folders you choose, with approval gates. Claude Code builds software with full access to your machine and terminal. Use Cowork for files, documents, and email. Use Code for actual development. Both ship from Anthropic, both live in the Claude ecosystem, and they share the same CLAUDE.md instructions file. The confusion is fair, so here is the clean split. I'm Tom. I teach Claude Code for a living, and the sharpest breakdown of this comparison came from Brock Mesarich, who built real workflows in both. I have pulled his distinctions together with what Tina Huang and No Code MBA found. > [CTA-BLUEPRINT] ## What is the difference between Claude Cowork and Claude Code? The core difference is access and audience. Brock Mesarich says it best. "Cowork is basically your assistant, whereas Claude Code is your entire engineer." Cowork runs in a sandbox. Brock describes it as a sealed bubble that can only touch the folders you grant it. Claude Code has no such bubble. It has access to your entire machine and your terminal. That one difference drives everything else. The sandbox makes Cowork safe for non-technical people. The full access makes Code powerful for developers. ## How Claude Cowork and Claude Code work differently They feel different the moment you open them, and the gaps are practical, not cosmetic. ### Where they live Cowork is a tab in the Claude desktop app, next to Chat and Code. You click into it. Claude Code lives in a terminal, which Brock calls "mighty scary if you are not a developer." You may not even recognize the core terminology in Code. ### How they connect to your tools Cowork has a one-click connector marketplace for Gmail, Drive, Notion, and more. Claude Code is manual. As Brock puts it, in Claude Code "you have to set up an MCP through config files." More control, more friction. ### How they handle scheduled work Cowork has built-in scheduled tasks you set in plain language. Claude Code uses cron jobs you configure yourself in the terminal. Same outcome, very different skill floor. ## Claude Cowork vs Claude Code at a glance A quick side-by-side on the points that decide it: - Audience: Cowork for operators and non-technical users, Code for developers. - Access: Cowork is sandboxed to chosen folders, Code reaches your whole machine. - Interface: Cowork is a desktop tab, Code is a terminal. - Connectors: Cowork uses a one-click marketplace, Code uses manual MCP config. - Scheduling: Cowork has built-in tasks, Code uses cron. - Best at: Cowork for documents and file work, Code for building software. ## Which one should you use? If your work is files, documents, email, and reports, use Cowork. The sandbox keeps you safe and the outcome-first prompts mean you never touch a terminal. If you are building software, use Claude Code. Tina Huang is clear that "as amazing as Cowork is, it is not specialized as an AI coding agent." For real coding, Code unlocks far more. If you are weighing Code against other dev tools, read [Claude Code vs Cursor](/blog/claude-code-vs-cursor) next. ## Can you use Claude Cowork and Claude Code together? Yes, and this is the part most comparisons miss. They share a CLAUDE.md file, so you can point both at the same folder and they use the exact same context. Brock hit a real case for this. Cowork's sandbox blocked an image-generation API he needed, so he used Claude Code in the same folder to generate 8 infographics, then had Cowork stitch them into slides. One folder, two tools, each doing what it is best at. ## Will Claude Cowork replace Claude Code? The builders disagree, and the disagreement is useful. Brock runs an 80/20 split, 80 percent Cowork, and predicts "the gap between these two tools is shrinking every single week," to the point most people may never need Code. Tina takes the other side. Code stays better for real coding as projects scale, and that gap is structural, not temporary. My read sits between them. Cowork will absorb more everyday work, but anyone building software will keep reaching for Code. > [CTA-BLUEPRINT] ## Verdict: Cowork or Code? For most operators, start with Cowork. It is the faster path to value and you will never see a terminal. The receipts, the file cleanup, the scheduled reports all happen in a tab. Move to Claude Code when you start building tools and apps, not just running tasks. And if you do both, point them at the same folder and let each play its position. That is the setup the sharpest builders are already running. ## Claude Cowork vs Claude Code FAQ ### Is Claude Cowork better than Claude Code? Neither is better, they do different jobs. Cowork is better for knowledge work like files, documents, and email. Claude Code is better for building software. Most operators want Cowork, most developers want Code. ### Do Claude Cowork and Claude Code cost the same? They are both available on Anthropic's paid plans, starting with Claude Pro at 20 dollars a month. You do not pay separately for each. Heavy use of either burns through usage limits faster. ### Can Claude Cowork write code? It can produce simple scripts and HTML, but it is not specialized for development. For real coding, larger projects, and full machine access, Claude Code is the right tool. ### Do Cowork and Claude Code share settings? Yes. They share the CLAUDE.md instructions file, so you can point both at the same folder and they work from identical context. This lets them hand work back and forth. ### Should a non-technical person use Cowork or Code? Cowork. It runs in the desktop app with a sandbox and plain-language prompts, no terminal required. Claude Code assumes comfort with a command line and developer concepts. ## Ready to build with Claude? Whether you start with Cowork or Code, the win is building your own systems instead of waiting for software to do it for you. Grab the [free Claude Code Blueprint](/blueprint) for the foundations, then join the [30-day challenge](/challenge) to install real working systems in your business. ## Related guides - [What Is Claude Cowork? The AI That Does Your Work For You](/blog/claude-cowork) - [How to Use Claude Cowork (Step-by-Step for Operators)](/blog/how-to-use-claude-cowork) --- # 10 Real Claude Cowork Use Cases That Save You Hours Source: https://theaiarchitects.com/blog/claude-cowork-use-cases Published: 2026-05-28 10 real Claude Cowork use cases pulled from actual demos, with the numbers. Receipts, file cleanup, inbox triage, reports, and scheduled work. The best Claude Cowork use cases are the repeatable file, document, and email jobs that eat your week but need no real skill. Cowork works on your local files and delivers a finished result, so the wins show up fastest on the boring, high-volume stuff you keep putting off. These are not hypothetical ideas. Every example below is a real run from a named creator, with the numbers they reported. I'm Tom. I teach operators to build with Claude, and I pulled these from the launch-month demos by Jeff Su, Tina Huang, Paul Lipsky, and Brock Mesarich. > [CTA-BLUEPRINT] ## What is Claude Cowork good for? Cowork is good for work that is high effort and low complexity. Sorting files, extracting data, drafting from a template, running the same report every Monday. It is not built for deep coding or anything touching a CRM it cannot connect to yet. Keep that line in mind as you read the list. ## 10 real Claude Cowork use cases ### 1. Turn a pile of receipts into an expense report Jeff Su dropped over 100 receipts, a mix of PDFs and phone photos, into a folder. Cowork extracted the date, vendor, category, and amount from each one and built a formatted Excel file, flagging blurry receipts as "verify." That task is impossible in Claude Chat, which caps you at 20 files. This is the single clearest reason to use Cowork over Chat. ### 2. Clean up a folder that has gotten out of control Tina Huang pointed Cowork at a desktop holding 376 files and had it propose and build a clean folder structure. It even spotted an API key sitting exposed in a text file and flagged it. In a separate run, Cowork sorted 186 chaotic downloads into 11 subfolders and detected 27 duplicates by hashing the files. The kind of cleanup you never get around to, done in one prompt. ### 3. Build a spending dashboard from your statements Tina fed Cowork 24 months of credit card statements as CSV exports and got back an interactive spending dashboard. It surfaced over 4,000 dollars in active subscriptions and flagged the fees and interest she was paying. This is the second job Chat physically cannot do. Twenty four documents is past its limit. ### 4. Run a daily inbox triage on a schedule Jeff Su set a 6am scheduled task that reads his inbox and produces a report plus draft replies before he wakes up. He is honest that it took "the first week or so" of corrections before it ran clean. Brock Mesarich runs a 7am morning briefing instead, a dashboard of his calendar, urgent emails, AI news, and top priorities for the day. ### 5. Draft email replies inside Gmail, in your voice Paul Lipsky had Cowork read two weeks of his Gmail to build a brand-voice file and a list of frequent contacts. Then it drafted replies directly inside Gmail, not as text in the chat for him to copy. That last detail is the difference. The reply lands where you actually send from. ### 6. Split and convert big batches of documents Jeff Su had Cowork split a 400-plus megabyte PDF into one file per chapter, each with a descriptive name. In a DataCamp demo, Cowork converted 21 Word docs to PDF, compressed 40 PDFs to save 63 megabytes, and converted 35 images to PNG. This is the work that used to mean bouncing between three different websites. Now it is one prompt. ### 7. Extract a brand book and reuse it Tina Huang gave Cowork screenshots of her logo and website and had it generate a brand book as a PDF. Then she turned that into a reusable "apply brand" skill, so every future deliverable comes out on-brand by default. The skill is the leverage. Build the brand reference once, apply it forever. ### 8. Cross-check meeting notes against the transcript Jeff Su had Cowork compare a meeting transcript stored in Google Drive against his Notion meeting notes. It surfaced the commitments that got made in the meeting but never made it into the written notes. This is the kind of synthesis across two tools that is tedious by hand and easy to forget. ### 9. Run a weekly competitor report automatically Brock Mesarich built a scheduled task that runs daily at 11am, scrapes his YouTube competitors, and updates a dashboard. He set it up once and it keeps feeding him fresh data. Any recurring research job fits this shape. Define the cadence, point it at the source, let it run. ### 10. Spin up a planning doc, growth plan, or lead magnet On launch day, No Code MBA described his business to Cowork and had it research the web, then build a Q1 growth plan with lead magnets and an email sequence, a mockup landing page in HTML, and a PDF lead magnet. All saved into the folder as finished files. It is not perfect first-pass work. But it is a fast, editable starting draft instead of a blank page. ## Which use cases are actually worth it? Start with the high-volume file jobs in points 1, 2, and 6. They prove the value in minutes and carry no real risk. Hold off on anything high stakes until you trust it, because Cowork still invents the occasional number. No Code MBA caught it reporting 25,000 subscribers when the real figure was 36,000. Use it on the boring work first, keep human review on the important work. > [CTA-BLUEPRINT] ## Claude Cowork use cases FAQ ### What is the best first task for Claude Cowork? Organizing a messy folder or building an expense report from receipts. Both are low risk, high volume, and impossible to mess up badly, so they prove the value fast. ### Can Claude Cowork manage my email? Yes. It can run a scheduled inbox triage, summarize your inbox, and draft replies directly inside Gmail using a brand-voice file it builds from your past emails. It needs the Gmail connector and your computer on for scheduled runs. ### Can Claude Cowork build reports and dashboards? Yes. Creators have built spending dashboards from 24 months of statements, expense reports from 100-plus receipts, and competitor research dashboards on a daily schedule. It outputs finished spreadsheets, PDFs, and HTML dashboards. ### Is Claude Cowork good for non-technical people? Yes. It is aimed at people whose work is time-consuming but not technically complex, and it requires no coding. The only real skill is setting up folders and writing clear outcome-first prompts. ### What can Claude Cowork not do well yet? It cannot connect to CRMs like Salesforce or HubSpot, its browser extension is slow and unreliable, and it occasionally invents numbers. Keep it on file and document work and review high-stakes output. ## Ready to put AI to work in your business? Every use case above is a system you could install once and reuse for months. If you want the fastest path to building your own, grab the [free Claude Code Blueprint](/blueprint), then join the [30-day challenge](/challenge) and build real systems alongside other operators. ## Related guides - [What Is Claude Cowork? The AI That Does Your Work For You](/blog/claude-cowork) - [How to Use Claude Cowork (Step-by-Step for Operators)](/blog/how-to-use-claude-cowork) - [Claude Cowork vs Claude Code: Which One Should You Use?](/blog/claude-cowork-vs-claude-code) --- # How to Use Claude Cowork (Step-by-Step for Operators) Source: https://theaiarchitects.com/blog/how-to-use-claude-cowork Published: 2026-05-28 How to use Claude Cowork the right way. Folder setup, guardrails, connectors, outcome-first prompts, skills, and scheduled tasks, in 7 steps. To use Claude Cowork, open the Cowork tab in the Claude desktop app, point it at a dedicated folder, then describe the outcome you want instead of the steps. Claude makes a plan, works through your files, and asks before anything significant happens. The tool is easy to open and easy to misuse. The operators getting real value spend an hour on setup first, and that is the part most people skip. I'm Tom. I teach operators to build with Claude, and this guide is the setup pattern that Jeff Su, Tina Huang, and Paul Lipsky all landed on independently, stripped down to the steps that matter. > [CTA-BLUEPRINT] ## What is Claude Cowork? Claude Cowork is Anthropic's desktop AI that completes tasks on your computer rather than handing back instructions. It reads and edits your local files, runs multi-step work, and delivers finished deliverables. If you want the full breakdown of what it is and where it falls short, read [what is Claude Cowork](/blog/claude-cowork) first. This guide is about getting it working. ## How to use Claude Cowork step by step ### Step 1: Install the desktop app and open the Cowork tab Download the Claude desktop app for Mac or Windows. Open it and select the Cowork tab, which sits alongside Chat and Code. There is no web version that runs the work, so the desktop app is the whole game. ### Step 2: Set up one dedicated folder Make a single parent folder before you grant any access. Jeff Su calls his "Cowork Playground." Paul Lipsky calls his "Cowork OS." The reason is safety. When you grant Cowork access to a folder, that is its sandbox. Point it at one folder you control, not your entire drive, and the rest of your machine stays untouched. ### Step 3: Add guardrails in the instructions Open the Cowork settings and add global instructions that apply only to Cowork. This is where you set the rules before it touches anything. Jeff Su's go-to guardrail is worth copying. Tell it that before deleting, overwriting, or renaming any existing file, it must show you what will change and wait for confirmation. He calls these instructions "training wheels on a bicycle." Keep them until you trust the workflow. ### Step 4: Connect your tools Go to Customize, then Connectors, and add the integrations you actually use. The common starting set is Gmail, Google Calendar, Google Drive, and Notion. If an app you need is not in the marketplace, Brock Mesarich shows a Zapier MCP workaround to bridge it. Start with two or three connectors, not ten. ### Step 5: Give it an outcome, not a task This is the prompt shift that separates Cowork from Chat. Jeff Su puts it well. "With Cowork, we use outcome-first language, where we define the end result, the constraints, and the quality bar." In Chat you tell it the steps. In Cowork you tell it the destination and let it plan the route. "Build me a clean expense report from these receipts, flag anything blurry" beats a list of ten manual instructions. ### Step 6: Turn repeat work into a skill A skill is a reusable instruction set Cowork can run again. The reliable way to build one, per Jeff Su and Paul Lipsky, is to do the task manually with Cowork first, get it right, then say "turn that into a skill." Jeff Su warns against the shortcut button that creates a skill from scratch. Run the real workflow first, then reverse engineer the skill at the end. It works far better. ### Step 7: Schedule the work that repeats Once a workflow runs clean, put it on a schedule. A 6am inbox triage, a Monday metrics pull, a weekly digest. You define the cadence once. One hard limit to plan around. Paul Lipsky found that "your computer needs to be on and Cowork needs to be open" for scheduled tasks to fire. If you close your laptop at night, the morning task will not run. ## A first task worth trying Start with something low stakes that proves the value. A messy downloads folder is perfect. Tina Huang pointed Cowork at a desktop of 376 files and had it propose a clean structure, then sort and rename. Jeff Su ran 100-plus receipts into a single Excel expense report. Pick a pile of files you have been avoiding and let it earn your trust on that first. ## Mistakes to avoid Do not grant access to your whole drive. One dedicated folder, always. Do not lean on the browser extension yet. Jeff Su could not recommend it, calling it slow, unreliable, and a usage hog that "overthinks every step." And do not trust numbers blindly, since Cowork still invents the occasional stat. Keep human review on anything that matters. > [CTA-BLUEPRINT] ## How to use Claude Cowork FAQ ### Do I need a paid plan to use Claude Cowork? Yes. Cowork is available on Anthropic's paid plans, starting with Claude Pro at 20 dollars a month. There is no free standalone version. ### Can Claude Cowork access all my files? Only the folders you explicitly grant. Files outside the granted folder will not be read, even if you drag them in. Point it at one dedicated folder for safety. ### How do I give Claude Cowork a task? Type a plain-language description of the outcome you want, not a list of steps. Define the end result, the constraints, and the quality bar, then approve its plan before it runs. ### Why are my Claude Cowork scheduled tasks not running? The most common cause is a closed laptop. Scheduled tasks only fire when your computer is on and Cowork is open. Some users run a dedicated machine to keep them alive. ### What is the difference between using Cowork and Claude Code? Cowork is a sandboxed assistant for everyday file and document work. [Claude Code](/blog/how-to-use-claude-code) is a developer tool with full machine access. Cowork uses outcome-first prompts, Code lives in your terminal. ## Ready to build your own systems? Cowork is a fast on-ramp to building real automations without code. Start with the [free Claude Code Blueprint](/blueprint) for the foundations, then join the [30-day challenge](/challenge) to install systems that run your business while you sleep. ## Related guides - [10 Real Claude Cowork Use Cases That Save You Hours](/blog/claude-cowork-use-cases) - [Claude Cowork on Windows: Install and First Task (2026)](/blog/claude-cowork-windows) --- # AI Statistics 2026: Adoption, Agents, and ROI Source: https://theaiarchitects.com/blog/ai-statistics-2026 Published: 2026-05-27 The AI statistics that matter in 2026: adoption rates, AI agent deployment, ROI, barriers, and jobs, pulled from McKinsey, Stanford HAI, and Gartner. AI statistics in 2026 tell a split story: adoption is now near-universal, but real financial return is still rare. As of 2025, 88% of organizations report regular AI use in at least one business function, yet only 39% can point to any measurable impact on earnings. That gap between using AI and profiting from it is the single most important number on this page. I'm Tom Crawshaw. I run The AI Architects, and I spend my days helping founders and operators build their own AI automations with Claude Code. I pulled every statistic below from primary sources, McKinsey, Stanford HAI, Gartner, the US Federal Reserve, Anthropic, PwC, and Google, and linked each one so you can check it yourself. No aggregator listicles, no recycled numbers. > [CTA-BLUEPRINT] ## AI statistics 2026: the headline numbers These are the figures journalists and analysts lead with in 2026. Each is drawn from a named primary source published in 2025 or 2026. - 88% of organizations report regular AI use in at least one business function, up from 78% a year earlier (McKinsey, 2025). - Generative AI reached 53% population adoption within three years, faster than the personal computer or the internet (Stanford HAI AI Index, 2026). - Global corporate AI investment hit $581.7 billion in 2025, up 130% year over year (Stanford HAI, 2026). - 62% of organizations are at least experimenting with AI agents, and 23% are already scaling one (McKinsey, 2025). - Over 40% of agentic AI projects will be canceled by the end of 2027, due to cost, unclear value, or weak risk controls (Gartner, 2025). - Only 39% of organizations attribute any EBIT impact to AI, and most of those say it is under 5% of EBIT (McKinsey, 2025). - Jobs requiring AI skills carry a 56% average wage premium, up from 25% the prior year (PwC, 2025). - 90% of software professionals now use AI at work, a median of two hours a day (Google DORA, 2025). ## How many businesses use AI in 2026? Most organizations now use AI, but most have not scaled it. McKinsey's 2025 State of AI survey of 1,993 respondents across 105 countries found 88% report regular AI use in at least one business function, up from 78% in 2024. Stanford's [2026 AI Index](https://hai.stanford.edu/ai-index/2026-ai-index-report/economy) puts organizational adoption at the same 88% level, with generative AI specifically used in at least one function at 70% of organizations. Scaling is where the picture thins out. Roughly one-third of organizations have begun to scale AI across the enterprise, and nearly two-thirds have not. More than two-thirds now use AI in more than one function, and half use it in three or more. Company size is the clearest divide: nearly half of companies with over $5 billion in revenue have reached the scaling phase, versus 29% of those under $100 million. The official US numbers run lower than the survey numbers because they count firms, not enthusiasm. The [US Federal Reserve](https://www.federalreserve.gov/econres/notes/feds-notes/monitoring-ai-adoption-in-the-u-s-economy-20260403.html) reported about 18% of US firms had adopted AI by year-end 2025, while 78% of the labor force works at a firm that has adopted AI. Over 20% of US firms expect to use AI in the first half of 2026. ### AI adoption in small business Small firms are closing the gap on large ones. US Census Bureau data, relayed through the SBA Office of Advocacy, shows small businesses under 250 employees using AI rose to 8.8% of firms, up from 6.3% six months earlier, against 11.1% for large firms. The size gap narrowed from a factor of 1.8. Oddly, businesses with fewer than five employees use AI more than other small firms, producing a U-shaped curve where the smallest and largest companies lead. There is a catch in the small business data. About half of small firms using AI reported no investment in it at all, no training, no capital, no process change, versus 40% of large businesses. Adoption without investment is exactly the pattern that produces the ROI gap this page keeps returning to. ## How fast is AI adoption growing? AI is being adopted faster than any prior general-purpose technology. Stanford HAI's [2026 AI Index](https://hai.stanford.edu/news/inside-the-ai-index-12-takeaways-from-the-2026-report) found generative AI reached 53% population adoption within three years, outpacing both the personal computer and the internet at the same stage. Adoption correlates strongly with GDP per capita, so the curve is steepest in wealthy economies. Country-level numbers show the spread. Generative AI adoption reaches 61% in Singapore and 54% in the United Arab Emirates, while the US ranks 24th at 28.3%. China and Europe posted the highest year-over-year increases in business use. On investment, the US dwarfs everyone: US private AI investment of $285.9 billion in 2025 was 23.1 times China's $12.4 billion. The money tells the same growth story as the usage data. Corporate AI investment of $581.7 billion in 2025 represents a 130% jump in a single year. The estimated value of generative AI tools to US consumers reached $172 billion annually by early 2026, with median value per user tripling between 2025 and 2026. ## Are businesses actually deploying AI agents? AI agents are widely tested and rarely scaled. McKinsey found 62% of organizations are at least experimenting with AI agents, with 23% scaling an agentic system in at least one function and another 39% experimenting. In any single business function, though, no more than 10% of organizations report scaling agents. Stanford HAI confirms agent deployment sat in the single digits across nearly every function in 2025. The forecasts are aggressive and the failure rate is high at the same time. [Gartner predicts](https://www.gartner.com/en/newsroom/press-releases/2025-08-26-gartner-predicts-40-percent-of-enterprise-apps-will-feature-task-specific-ai-agents-by-2026-up-from-less-than-5-percent-in-2025) that 40% of enterprise applications will include task-specific AI agents by the end of 2026, up from under 5% in 2025. Gartner also predicts that over 40% of agentic AI projects will be canceled by the end of 2027. In a January 2025 Gartner poll of 3,412 attendees, only 19% had made significant agentic investments. Gartner estimates just 130 of the thousands of self-described agentic vendors are real, calling the rest "agent washing." Real usage data backs the build-versus-experiment split. Anthropic's [Economic Index](https://www.anthropic.com/research/anthropic-economic-index-september-2025-report) found 77% of business API usage follows an automation pattern, versus about 50% for consumer Claude.ai users. Conversations where users delegate a complete task to the model jumped from 27% to 39% over the report period. IBM reported 61% of CEOs are actively adopting AI agents and preparing to scale them. ## What is the ROI of AI automation? Return on AI is concentrated in a small group of companies. McKinsey found only 39% of organizations attribute any EBIT impact to AI, and most of those put it under 5% of EBIT. A roughly 6% slice McKinsey calls "AI high performers" attribute at least 5% of EBIT to AI and are more than three times as likely to pursue transformative change. IBM's CEO study found only 25% of AI initiatives delivered the expected ROI in recent years, and just 16% scaled enterprise-wide. The macro productivity data is more encouraging than the boardroom data. PwC's Global AI Jobs Barometer found productivity growth nearly quadrupled in the industries most exposed to AI, rising from 7% over 2018 to 2022 to 27% over 2018 to 2024. Those same industries saw three times higher growth in revenue per employee. Anthropic found college-level tasks run on Claude show an average 12x speedup. Where the value lands depends on the function. McKinsey reports cost benefits show up most in software engineering, manufacturing, and IT, while revenue benefits cluster in marketing and sales, strategy and corporate finance, and product development. The 95% of pilots that fail and the 5% that succeed, a finding from MIT's NANDA report as reported by Fortune, come down to this: buying from specialized vendors succeeds about 67% of the time, while internal builds succeed about a third as often. ## What are the biggest barriers to AI adoption? The barriers to AI value are operational, not technical. These are the failure modes the 2026 data points to, in order of how often they appear. 1. **No measurable business value.** Over 40% of agentic projects will be canceled by 2027 for cost, unclear value, or weak risk controls (Gartner). Only 5% of enterprise generative AI pilots reach rapid revenue acceleration (MIT NANDA via Fortune). 1. **Inaccuracy and hallucination.** 51% of organizations using AI have experienced at least one negative consequence, and nearly a third report problems from AI inaccuracy (McKinsey). Inaccuracy and explainability are the most commonly mitigated risks. 1. **Security exposure.** Gartner predicts that by 2028, 25% of enterprise generative AI applications will experience at least five minor security incidents per year. 1. **Lack of trust.** 28% of executives rank lack of trust as a top challenge to value from AI agents (PwC). 30% of tech professionals report little or no trust in AI-generated code (Google DORA). 1. **Adoption without investment.** Organizations now mitigate an average of four AI-related risks, up from two in 2022 (McKinsey), yet half of small firms using AI invest nothing in it (US Census). A reliability note matters here. AI agents handling real-world tasks improved to a 77.3% success rate on Terminal-Bench, up from 20% the year before (Stanford HAI). That is real progress and still well short of the reliability a business needs to hand over a critical workflow unattended. ## How is AI changing jobs and skills? AI is reshaping which skills get paid, more than it is eliminating jobs. PwC found jobs requiring AI skills carry a 56% average wage premium, up from 25% the prior year, and AI-skill job postings grew 7.5% even as total postings fell 11.3%. The skills employers want are changing 66% faster in AI-exposed occupations. Degree requirements are falling fastest in those same roles. The workforce reductions are real but smaller than the headlines suggest. McKinsey found 32% of organizations expect headcount to fall by at least 3% from AI in the next year, while 43% expect no change and 13% expect increases. Across functions, a median 17% of organizations saw AI-driven workforce declines last year, rising to a median 30% expecting declines next year. The sharpest signal is at the entry level: Stanford HAI found employment among software developers aged 22 to 25 has fallen nearly 20% since 2024, even as headcount for older developers grew. Leadership is the quiet variable in the data. McKinsey found AI high performers have senior leaders who are three times more likely to show strong ownership of AI initiatives. Gartner predicts that by 2029, at least half of knowledge workers will develop new skills to work with, govern, or create AI agents. The people who learn to build and direct automations are the ones the wage data rewards. That is the entire premise behind the [Claude Code skills](/blog/how-to-use-claude-code) I teach. ## AI automation by business function in 2026 AI automation shows up unevenly across business functions. Here is where the 2026 data concentrates, by function. - **Software development:** 90% of tech professionals use AI at work, up 14 points year over year, and more than 80% say it raised their productivity (Google DORA). On Claude, coding is the single largest use category at 36% of all usage (Anthropic). - **Marketing and sales:** revenue increases from AI are most commonly reported here (McKinsey). Gartner predicts that by 2028, 60% of brands will use agentic AI for one-to-one customer interactions, and AI agents will outnumber sellers by 10 to 1. - **Customer service:** contact-center and customer-service automation is among the most-reported use cases (McKinsey). - **IT and knowledge management:** AI agent use is most common in these two functions (McKinsey). - **Operations and government:** Gartner predicts that by 2028, at least 80% of governments will deploy AI agents to automate routine decision-making. - **Healthcare:** physicians using AI clinical-note tools reported up to 83% less time spent writing notes (Stanford HAI). ## What the AI automation numbers mean if you are building The data says the same thing I see in the field every week: tools are not the bottleneck, building is. Adoption is at 88% and ROI is at 39% because most companies bought access to AI and never built anything specific with it. The 5% of pilots that pay off, and the 6% of firms McKinsey calls high performers, are the ones who treated AI as something to build with, not subscribe to. I have watched this play out client by client. One of my mentorship clients, Cal Hewitt, used Claude Code and n8n to build agentic work-order dispatch for a maintenance contractor. Acknowledgement time dropped from up to 48 hours down to minutes, and four months later he was introduced as the company's head of AI at a quarterly town hall. The full breakdown is in his [case study](/case-studies/cal-hewitt). He is the 5%, not because he had better tools, but because he built a specific automation around a specific bottleneck. That is the gap the statistics keep pointing at. If you want to be on the right side of the ROI number, the move is to build one real automation around one real problem, then expand. I wrote a [step-by-step guide to Claude Code](/blog/how-to-use-claude-code) for exactly that, and if you are weighing your stack, my take on [whether n8n is still worth it in 2026](/blog/is-n8n-dead-in-2026) covers where automation tools fit alongside AI agents. > [CTA-BLUEPRINT] ## Frequently asked questions ### How many companies use AI in 2026? 88% of organizations report regular AI use in at least one business function as of 2025, according to McKinsey, up from 78% a year earlier. Official US firm-level data from the Federal Reserve is lower, at about 18% of firms, because it counts formal adoption rather than any use. ### What percentage of AI projects fail? Roughly 95% of enterprise generative AI pilots show little or no measurable profit-and-loss impact, per MIT's NANDA report. Separately, Gartner predicts over 40% of agentic AI projects will be canceled by the end of 2027 due to cost, unclear value, or weak risk controls. ### What is the ROI of AI automation? Only 39% of organizations attribute any EBIT impact to AI, and most of those say it is under 5%, according to McKinsey. Returns concentrate in a small group: the 6% of firms McKinsey calls high performers attribute at least 5% of EBIT to AI. ### Are AI agents being used by businesses? Yes, but mostly at the experimental stage. McKinsey found 62% of organizations are experimenting with AI agents and 23% are scaling at least one, while no more than 10% have scaled agents in any single function. Gartner expects 40% of enterprise apps to include task-specific agents by the end of 2026. ### Which country leads in AI adoption? Singapore leads on generative AI adoption at 61%, followed by the United Arab Emirates at 54%, per Stanford HAI's 2026 AI Index. The US ranks 24th at 28.3% but dominates investment, with $285.9 billion in private AI investment in 2025. ### Is AI replacing jobs in 2026? AI is reshaping pay more than cutting headcount overall. McKinsey found 32% of organizations expect at least a 3% headcount reduction from AI next year, while jobs requiring AI skills carry a 56% wage premium, per PwC. The clearest decline is among entry-level software developers aged 22 to 25, down nearly 20% since 2024. ### How fast is AI being adopted compared to past technology? Generative AI reached 53% population adoption within three years, faster than the personal computer or the internet at the same stage, according to Stanford HAI's 2026 AI Index. ## Sources and citations - [The state of AI in 2025: Agents, innovation, and transformation](https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai) (McKinsey, 2025) Adoption, scaling, ROI, agents, risks, workforce. - [The 2026 AI Index Report: Economy](https://hai.stanford.edu/ai-index/2026-ai-index-report/economy) and [12 Takeaways from the 2026 Report](https://hai.stanford.edu/news/inside-the-ai-index-12-takeaways-from-the-2026-report) (Stanford HAI, 2026) Adoption speed, investment, country data. - [Gartner Predicts Over 40% of Agentic AI Projects Will Be Canceled by End of 2027](https://www.gartner.com/en/newsroom/press-releases/2025-06-25-gartner-predicts-over-40-percent-of-agentic-ai-projects-will-be-canceled-by-end-of-2027) and [40% of Enterprise Apps Will Feature Task-Specific AI Agents by 2026](https://www.gartner.com/en/newsroom/press-releases/2025-08-26-gartner-predicts-40-percent-of-enterprise-apps-will-feature-task-specific-ai-agents-by-2026-up-from-less-than-5-percent-in-2025) (Gartner, 2025). - [Monitoring AI Adoption in the U.S. Economy](https://www.federalreserve.gov/econres/notes/feds-notes/monitoring-ai-adoption-in-the-u-s-economy-20260403.html) (US Federal Reserve, 2026) Firm-level and employment-weighted adoption. - [AI in Business: Small Firms Closing In](https://advocacy.sba.gov/wp-content/uploads/2025/09/Research-Spotlight-AI-in-Business-Small-Firms-Closing-In_-092425.pdf) (US Census Bureau via SBA Office of Advocacy, 2025) Small business adoption. - [Anthropic Economic Index, September 2025](https://www.anthropic.com/research/anthropic-economic-index-september-2025-report) Automation patterns, geographic usage, task speedups. - [AI linked to a fourfold increase in productivity growth](https://www.pwc.com/gx/en/news-room/press-releases/2025/ai-linked-to-a-fourfold-increase-in-productivity-growth.html) (PwC Global AI Jobs Barometer, 2025) Wage premium, productivity, skills. - [Announcing the 2025 DORA Report](https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report) (Google, 2025) Software developer AI use. - [IBM study: CEOs double down on AI](https://newsroom.ibm.com/2025-05-06-ibm-study-ceos-double-down-on-ai-while-navigating-enterprise-hurdles) (IBM Institute for Business Value, 2025) CEO ROI and agent adoption. - [MIT report: 95% of generative AI pilots are failing](https://fortune.com/2025/08/18/mit-report-95-percent-generative-ai-pilots-at-companies-failing-cfo/) (MIT NANDA via Fortune, 2025). ## Ready to build your own AI automation? The statistics make the path obvious. The companies getting return are the ones building specific automations, not buying generic access. If you want to join them, my free [Claude Code Blueprint](/blueprint) walks you through your first build in 60 minutes with no coding, and the [30-day challenge](/challenge) takes you from there to a working operator stack. ## Related guides - [How to Learn AI in 2026: My Unfiltered Advice](/blog/how-to-learn-ai-2026) --- # How to Install Claude Code on Windows in 2026 (PowerShell, WSL, and the Path Gotcha) Source: https://theaiarchitects.com/blog/claude-code-windows-install Published: 2026-05-20 How to install Claude Code on Windows step-by-step. The two install methods (PowerShell vs WSL), the path issue that breaks half of new setups, and how to verify. Installing Claude Code on Windows takes about 5 minutes if you pick the right method and about 45 minutes if you don't. There are two real options: PowerShell with Node.js (the fastest path for most people) and WSL2 with Ubuntu (better if you already live in a Linux terminal). A third option, Git Bash, exists but creates more problems than it solves. I'm Tom. I've installed Claude Code on Windows 11, Windows 10, and WSL on three different machines. Here's the path that actually works without the usual permission and PATH errors. > [CTA-BLUEPRINT] ## Can you install Claude Code on Windows? Yes. Claude Code runs on Windows natively via PowerShell and Node.js, and it also runs inside WSL2 (Windows Subsystem for Linux 2). Both methods are officially supported. You need a Claude Pro account ($20/month) or Anthropic API credits to authenticate after install. ## The two ways to install Claude Code on Windows The PowerShell method installs Claude Code directly onto your Windows machine using Node.js. The WSL2 method runs Claude Code inside a Linux environment that lives on your Windows machine. Both produce a working Claude Code setup. The difference is how much Linux tooling you want alongside it. **My recommendation:** Use PowerShell if you just want Claude Code working today. Use WSL2 if you're already running Docker, Node, or other Linux tools there so everything stays in one environment. - **PowerShell + Node.js** — Best for: Most users, simplest path. Setup time: 5 min. Catches: Need Node 20+, PATH issues on first install. - **WSL2 + Ubuntu** — Best for: Devs already using Linux tools. Setup time: 15 min. Catches: Path translation between Windows and Linux filesystems. - **Git Bash** — Best for: Niche, NOT recommended. Setup time: 10 min. Catches: Symlink issues, npm bin PATH quirks. ## How to install Claude Code on Windows with PowerShell ### 1. Install Node.js 20 or newer Claude Code requires Node.js 20 or higher. Go to [nodejs.org](https://nodejs.org) and download the LTS installer. Run it with the defaults. When it's done, confirm the version: You should see `v20.x.x` or higher. If you see anything below v20, download the current LTS version and reinstall. ### 2. Open PowerShell as administrator Right-click the Start menu and choose "Windows PowerShell (Admin)" or "Terminal (Admin)". You need admin rights for npm to write to the global bin directory. Without this, the install will fail silently or write to a location that isn't in your PATH. ### 3. Run npm install This downloads and installs Claude Code globally. It takes 30 to 60 seconds depending on your connection. If you see permission errors, confirm you opened PowerShell as administrator. ### 4. Verify the install You should see a version number. If you see `command not found` or a PATH error, skip to the path gotcha section below before going further. ### 5. Authenticate with your Claude account Claude Code opens an interactive prompt asking you to log in with your Anthropic account. You need a Claude Pro plan ($20/month) or API credits. Follow the browser authentication flow and return to the terminal when done. ## How to install Claude Code on Windows with WSL ### 1. Enable WSL2 Open PowerShell as administrator and run: On Windows 11 this is already available. On Windows 10 you may need to enable the Virtual Machine Platform feature first. Restart your machine after this step. ### 2. Install Ubuntu WSL2 defaults to Ubuntu. After the restart, open the Microsoft Store, search "Ubuntu", install the latest LTS version, and launch it to set up a username and password. ### 3. Install Node inside WSL Inside the Ubuntu terminal, install Node Version Manager (nvm) for clean control over Node versions: Confirm you're on Node 20 or higher before moving on. ### 4. Install Claude Code inside WSL Authenticate the same way as the PowerShell method. Claude Code is now running inside your Linux environment. ### 5. Run from your Windows project folder Your Windows files live at `/mnt/c/` inside WSL. To work on a Windows project folder, navigate to it like this: Keep your project files on the Windows filesystem (`/mnt/c/`) rather than inside WSL's Linux filesystem. Mixing filesystems mid-project causes slow reads and occasional permission confusion. > [CTA-HOSTINGER] ## The Windows path gotcha most installs hit After a successful `npm install -g @anthropic-ai/claude-code`, many Windows users type `claude --version` and see nothing. The binary is on disk, but Windows can't find it because the npm global bin directory isn't in the system PATH. On Windows, npm installs global binaries to `%AppData%\npm`. To find the exact path on your machine: Copy the output. Now add it to your PATH: 1. Search "Environment Variables" in the Start menu and open it. 1. Under "System variables", click "Path" and then "Edit". 1. Click "New" and paste the path you copied from the npm command above. 1. Click OK, close all the dialogs, and restart your terminal. After restarting the terminal, run `claude --version` again. If it still doesn't resolve, confirm the path you added ends in `\npm` and that you fully closed and reopened the terminal rather than opening a new tab. ## How to verify Claude Code installed correctly on Windows Run both of these checks: A working install returns a version number on the first command and help text on the second. If `claude --version` works but `claude --help` throws an error, your Node.js version is likely below 20. Recheck with `node --version`. To confirm Claude Code can actually run, open a project directory and type `claude`. It launches the interactive session and prompts for authentication if you haven't logged in yet. ## Claude Code Windows install FAQ ### Does Claude Code work on Windows 11? Yes. Claude Code works on Windows 11 via PowerShell with Node.js 20+ or inside WSL2. Windows 11 ships with WSL2 support built in, so either method is available without additional setup. ### Do I need WSL to use Claude Code on Windows? No. WSL is optional. The PowerShell method installs Claude Code natively on Windows without any Linux subsystem. WSL2 is a good choice if you already use it for development, but it's not required. ### Why does my Claude Code install fail on Windows? The two most common causes are Node.js being below version 20, and the npm global bin directory not being in the system PATH. Check your Node version with `node --version` and follow the path fix steps in the section above if `claude` isn't resolving after install. ### Can I use Claude Code in PowerShell? Yes. PowerShell is the recommended terminal for the native Windows install. Open it as administrator for the install step, then use it normally for day-to-day Claude Code sessions. ### Does Claude Code work in Git Bash? Technically yes, but it's not recommended. Git Bash on Windows has known issues with npm global symlinks and PATH resolution that can cause unexpected errors. Stick with PowerShell or use WSL2 with a proper Linux shell. ### Is Claude Code free on Windows? The install itself is free. To actually use Claude Code, you need either a Claude Pro account ($20/month) or Anthropic API credits. Without valid credentials, the CLI installs but authentication fails and you can't run sessions. ### How do I update Claude Code on Windows? Run the same install command you used originally: npm overwrites the existing version with the latest. Check the updated version with `claude --version` afterward. ### What Node version do I need for Claude Code on Windows? Node.js 20 or higher. Older Node versions will fail at install or throw runtime errors. Use `node --version` to confirm before running the install command. ## Related guides If you're just getting started or need setup guidance across other platforms, these cover the next steps: - [How to use Claude Code: 60-minute beginner guide](/blog/how-to-use-claude-code) - [How to install Claude Code (all platforms)](/blog/how-to-install-claude-code) - [Claude Code pricing explained](/blog/claude-code-pricing) ## Sources and official documentation Commands and requirements in this guide come from Anthropic's official documentation and the Claude Code GitHub repo: - [Claude Code installation docs](https://docs.claude.com/en/docs/claude-code/setup) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) - [Anthropic Claude Code documentation](https://docs.claude.com/en/docs/claude-code) ## Ready to ship something real with Claude Code? Getting Claude Code installed is step one. The bigger unlock is knowing how to use it to build and automate, not just run one-off prompts. The blueprint below is where to start. > [CTA-BLUEPRINT] ## Frequently Asked Questions ### Can you install Claude Code on Windows? Yes. Claude Code runs natively on Windows via PowerShell with Node.js, and it also runs inside WSL2 with Ubuntu. Both methods are officially supported. PowerShell is the fastest path for most people (5 minutes). WSL2 is better if you already live in a Linux terminal for other tools (15 minutes). Git Bash technically works but creates more problems than it solves. ### How do I install Claude Code on Windows with PowerShell? Five steps. Install Node.js 20 or newer from nodejs.org. Open PowerShell as administrator. Run npm install -g @anthropic-ai/claude-code. Verify with claude --version. Authenticate by running claude and following the browser login flow. Admin rights matter for npm to write to the global bin directory cleanly. ### Do I need WSL to use Claude Code on Windows? No. WSL is optional. The PowerShell method installs Claude Code natively on Windows without any Linux subsystem. WSL2 is a good choice if you already use it for Docker, Node, or other Linux tools and want everything in one environment. For a clean single-purpose install, PowerShell is simpler. ### Why does claude --version say command not found after install? Your npm global bin directory is not in your Windows PATH. Run npm config get prefix to find the npm prefix. Open Environment Variables in the Start menu, edit System Path, click New, and paste the path (ending in \npm). Close all dialogs, fully restart your terminal (not just open a new tab), and try claude --version again. ### Does Claude Code work in Git Bash on Windows? Technically yes, but not recommended. Git Bash on Windows has known issues with npm global symlinks and PATH resolution that cause unexpected errors. Stick with PowerShell for the native Windows install or use WSL2 with a proper Linux shell. The time you save in setup gets eaten by the time you spend debugging symlink quirks. ### Is Claude Code free on Windows? The install is free. To actually use it you need either a Claude Pro account ($20 a month) or Anthropic API credits. Without valid credentials, the CLI installs but authentication fails and you cannot run sessions. New API accounts get $5 in trial credits, which is enough for two to ten sessions before you need to add a payment method. ### Should I keep my project files inside WSL or on the Windows filesystem? Keep project files on the Windows filesystem at /mnt/c/ when running Claude Code from WSL. Mixing filesystems mid-project causes slow reads and occasional permission confusion. Navigate from WSL with cd /mnt/c/Users/YourName/Projects/my-project and run claude from there. This gives you Linux tooling without the I/O penalty. --- # Claude Code on the Web: Coding From Your Phone in 2026 Source: https://theaiarchitects.com/blog/claude-code-web Published: 2026-05-20 Claude Code on the web, mobile, desktop, and terminal. Multi-surface async coding, Routines, Channels, and the iOS app workflow that changed mine. Claude Code on the web is Anthropic's browser-hosted, asynchronous version of its coding agent. It runs in a cloud sandbox, clones your GitHub repo on the fly, and lets you fire off tasks from any device with a browser. No local install. No terminal. Just a URL and a prompt box. I'm Tom. I now run Claude Code across four surfaces (terminal, desktop, web, iOS) and I've shipped over 40 production features this way in the last six weeks, including the publishing pipeline behind this blog. This post is the field guide I wish I'd had when web launched. > [CTA-BLUEPRINT] ## What is Claude Code on the web? Claude Code on the web is the browser-based version of Anthropic's coding agent, announced on November 12, 2025. You log in at claude.com/code, point it at a GitHub repository, and it spins up an isolated cloud sandbox running the same Claude Code engine that lives in the terminal. The whole point is asynchronicity. You queue a task, close the laptop, and come back to a pull request waiting for review. The agent does the work in the cloud while you do something else with your day. ## How does Claude Code on the web work? When you start a session, the web app clones your repo into a fresh cloud sandbox attached to a single Anthropic-hosted container. Claude then plans, edits files, runs tests, and opens a PR back to your branch. Your laptop is not involved. Because the work runs on Anthropic's infrastructure, you can have multiple sessions going at once across different repos. I usually have three or four active in different browser tabs. One refactor, one bug fix, one experimental feature, one docs pass. The web surface also exposes new primitives that the terminal CLI doesn't have natively. Routines for scheduling. Channels for inbound events. Dispatch for phone-triggered runs. I'll cover those further down. Under the hood, each sandbox gets a fresh Linux container with your repo checked out, Anthropic's tool-use runtime, and a scoped GitHub token that can only see the repos you've authorised. When the task finishes, Claude pushes a branch and opens the PR through the GitHub API. Read the official [web quickstart docs](https://code.claude.com/docs/en/web-quickstart) for the full security model. ## The four Claude Code surfaces (and when to use each) ### Terminal CLI The original. Install via `npm install -g @anthropic-ai/claude-code`, run `claude` in any repo, and you get full local control. It can read your filesystem, run your dev server, hot-reload your code, and watch files in real time. I use the terminal for anything where I want to see the work happen line by line. Debugging. Reading logs. Pairing with the agent on tricky migrations. If you're new to all this, start with my [60-minute beginner guide](/blog/how-to-use-claude-code) before touching the web app. ### Desktop app The desktop app is Claude Code with a graphical chrome wrapper around the same engine. Same machine, same filesystem, same git, just with a clickable UI instead of a TUI. It runs locally like the CLI does. This is the surface I recommend to non-developers in the AI Architects cohort. The drag-and-drop file context and the visual diff viewer make it dramatically easier to onboard. If you've ever fought with `vim` keybindings, the desktop app is your friend. ### Web The browser-hosted, cloud-sandboxed version. No install, no local dependencies, no Node version mismatch. You can use it from a Chromebook, a friend's laptop, or a hotel business centre. As long as you can sign in to claude.com, you can ship code. The async nature is what makes it different. The web surface assumes you'll fire and forget, and the entire UI is built around managing multiple parallel runs instead of one synchronous chat. ### iOS app The phone app. Push a task from your iPhone, the work runs in the cloud, and you get a notification when the PR is ready. I review diffs from the back of a London cab. The iOS app shines for two things specifically. Capturing ideas the moment they hit (instead of letting them die in a Notes file) and reviewing agent work during the dead time you'd otherwise scroll Instagram. It is genuinely the highest-leverage app on my phone right now. The diff viewer on mobile is better than I expected. Syntax highlighting, file tree on the left, swipe-to-approve on the right. I can read a 400-line PR on a 6.1-inch screen without squinting. Push notifications respect Focus modes, so it doesn't bother me during deep work. ## My actual cross-surface workflow A normal Tuesday looks like this. At my desk by 7am, I open the terminal, start a complex refactor that needs me watching the test output, and pair with Claude on it until 9am. That work is too gnarly for async. I want eyeballs on every diff. Around 9am I switch to the web app and queue three smaller tasks across two repos. A copy update on the marketing site. A new field on the student-os Airtable sync. A docs refresh on the Claude Code course repo. I close the laptop and go to a coaching call. By the time the call ends at 11am, two of the three PRs are ready. I review them on my iPhone using the iOS app while walking to lunch and merge the easy one straight from the phone. The third needs a tweak, so I leave a comment and let the agent take another pass. After lunch I'm back on the desktop app to do the final review and ship. Four hours, four surfaces, six features shipped. The trick is matching the task to the surface, not jamming everything into one tool. Watch-the-diff work goes in the terminal. Async batchable work goes on the web. Mobile review goes on iOS. That is the entire system. Before web launched, my throughput was capped at how fast I could read diffs in one terminal window. Now the bottleneck is my own attention, not the agent's speed. Six weeks in, I've stopped scheduling "coding blocks" on my calendar entirely. Coding fits in the gaps between meetings instead of needing its own dedicated time. ## What's new: Routines, Channels, Dispatch, and `claude --teleport` ### Routines Routines are scheduled cloud cron jobs that run Claude Code on a timer. Cron-style syntax, hosted by Anthropic, no server to maintain. I have one that runs every Monday at 6am, pulls the week's analytics from PostHog, and drafts a summary PR for the team channel. You can think of them as the lightweight Vercel cron equivalent for repo-level work. Anything you'd ask Claude to do every Monday or every hour can become a Routine in about ninety seconds. ### Channels Channels let external systems push events into a live Claude session. Slack messages, Telegram threads, GitHub webhooks, Linear comments, all of it. The agent listens and responds. I have a Channel wired to my support inbox. When a customer files a bug report with a reproducible link, the Channel pushes the payload into a Claude Code session that opens a draft PR with the fix. I review and merge. Support-to-shipped in under an hour on a good day. ### Dispatch Dispatch is the feature behind the iOS app's main button. You type a task into your phone, hit send, and the work executes on cloud infrastructure. The phone is purely a remote. I use Dispatch most when I'm out walking and an idea hits. Instead of writing a Notion ticket I'll never read again, I dispatch the task directly to the repo and let Claude scaffold it. Half the time the PR is good enough to merge as-is. The other half is at least 80% of the way there. ### `claude --teleport` `claude --teleport` is the CLI flag that ships your local terminal session to the cloud so you can resume on another surface. Halfway through a refactor on your laptop and need to leave? Run `claude --teleport`, close the lid, open the web app, and pick up exactly where you stopped. The state, the context, the open files, the planning notes, all of it transfers. This is the connective tissue between the four surfaces and the reason the whole system actually works as one tool instead of four separate ones. ## Where Claude Code on the web falls short It isn't all upside. The cloud sandbox can't watch files in real time the way the local CLI does, which means tasks that depend on hot-reload or live dev server output are awkward. I still do those on the terminal. Latency on long sessions is real. A two-hour async run sometimes ends with the sandbox having to re-clone or re-warm, and the final five minutes feel sluggish compared to local execution. Not a dealbreaker, but worth knowing before you push a marathon job at 4pm on a Friday. And the pricing. Web access is gated to Claude Pro and Max users, with stricter rate limits than the terminal CLI. If you're on the free plan, the web app will show you the door fast. Full breakdown is in my [Claude Code pricing](/blog/claude-code-pricing) post. > [CTA-BLUEPRINT] ## Claude Code on the web FAQ ### What is Claude Code on the web? Claude Code on the web is the browser version of Anthropic's coding agent, launched on [November 12, 2025](https://www.anthropic.com/news/claude-code-on-the-web). It runs in a cloud sandbox, connects to your GitHub repos, and executes coding tasks asynchronously without any local install. ### How do I use Claude Code on my iPhone? Download the Claude app from the iOS App Store and sign in with the same account you use for claude.com. Tap the code icon, pick a connected repo, and type your task. The work runs in the cloud and a notification lands when the PR is ready for review. ### Is Claude Code on the web free? No. Claude Code on the web is gated to paid plans (Pro and Max). The free plan gives you the chat interface but not the coding agent. If you want the agent across all four surfaces, you need at least a Pro subscription. ### Can I run Claude Code on multiple repos at once? Yes. The web app is built around parallel sessions, and I commonly have three or four sandboxes running across different repos at the same time. Each session is isolated, so a long task on Repo A won't block a quick PR on Repo B. ### What's the difference between Claude Code desktop and web? The desktop app runs locally on your machine and has full filesystem access. The web app runs in an Anthropic-hosted cloud sandbox and clones your repo from GitHub. Desktop is better for live debugging. Web is better for async batch work and for using on devices where you can't or don't want to install anything. For a deeper comparison of agent tools generally, see my Claude Code [vs Cursor](/blog/claude-code-vs-cursor) post or the official [web quickstart docs](https://code.claude.com/docs/en/web-quickstart). ## Ready to try Claude Code on the web? The four-surface workflow took me from one feature a day to six. The web app alone won't get you there, but combining web with terminal, desktop, and iOS will. The whole point is matching the right surface to the right task and letting the agent run while you do something else. If you want the full playbook I run with my mentorship cohort, including the exact Routines and Channels setups, grab the [Blueprint](/blueprint) and I'll walk you through it. It covers the surface-matching framework, the three Routines I run every week, and the Channels wiring that turns Slack into a shipping queue. ## Frequently Asked Questions ### What is Claude Code on the web? Claude Code on the web is the browser-hosted version of Anthropic's coding agent, launched November 12, 2025. You log in at claude.com/code, point it at a GitHub repo, and it spins up an isolated cloud sandbox running the same engine as the terminal CLI. No local install. You queue a task, close the laptop, come back to a PR waiting for review. ### How do I use Claude Code on my iPhone? Download the Claude app from the iOS App Store and sign in with the same account you use for claude.com. Tap the code icon, pick a connected repo, and type your task. The work runs in the cloud on Anthropic infrastructure and a notification lands when the PR is ready. I review 400-line diffs from the back of a London cab without squinting. ### Is Claude Code on the web free? No. Web access is gated to paid plans (Pro at $20 a month and Max at $200 a month). The free Claude.ai plan gives you the chat interface but not the coding agent. If you want the agent across all four surfaces, Pro is the minimum entry point. ### What are Routines, Channels, and Dispatch? Routines are scheduled cloud cron jobs that run Claude Code on a timer with no server to maintain. Channels let external systems push events (Slack, GitHub webhooks, Linear comments) into a live session that responds. Dispatch is the iOS app feature that fires a task from your phone to the cloud. All three are web-only primitives the terminal CLI does not have natively. ### Can I run Claude Code on multiple repos at once? Yes. The web app is built around parallel sessions. I usually have three or four sandboxes running across different repos at the same time. Each session is isolated, so a long task on Repo A does not block a quick PR on Repo B. This is the property that took my throughput from one feature a day to six. ### What's the difference between Claude Code desktop and web? The desktop app runs locally on your machine with full filesystem access. The web app runs in an Anthropic-hosted cloud sandbox and clones your repo from GitHub. Desktop is better for live debugging with hot-reload and watching files in real time. Web is better for async batch work and for devices where you cannot install anything. ### Where does Claude Code on the web fall short? Three places. The cloud sandbox cannot watch files in real time the way the local CLI does, so hot-reload work stays on terminal. Latency on long sessions is real, with two-hour async runs sometimes feeling sluggish at the end. And the web app is paid-only, so the free plan shows you the door fast. --- # Claude Code Rate Limits and How to Stop Hitting Them (2026) Source: https://theaiarchitects.com/blog/claude-code-rate-limits Published: 2026-05-20 Claude Code rate limits, how to check your usage, the 5-hour and weekly caps explained, plus 9 ways to cut token usage by 80% without changing what you ship. Claude Code rate limits are usage caps that throttle or block your session when you cross either a 5-hour rolling window or a weekly threshold on your plan. The fastest way to stop hitting them is to switch your default model to Sonnet, compact every 20-30 messages, scope subagents through plan mode, and install the token-optimizer skill. I'm Tom. I run Claude Code 4-8 hours a day across multiple projects and I rarely hit a limit. This post is what I actually do. > [CTA-BLUEPRINT] ## What are the Claude Code rate limits? Claude Code rate limits are tied to your Claude plan, not to Claude Code as a separate product. The free tier gives you a small daily allotment of messages. Pro gives you roughly 5x the free tier in a rolling 5-hour window. Max gives you 20x. Every plan also has a weekly ceiling that resets on a fixed day, and Opus burns through that ceiling faster than Sonnet. You will hit one of three caps in practice. The 5-hour rolling cap throttles you mid-session when you push hard on Opus. The weekly cap stops the bleeding for the rest of the week if you spent all five days on long agentic loops. The output cap on individual responses can clip a long file rewrite without warning. The full pricing breakdown is on the [Claude Code pricing](/blog/claude-code-pricing) post. ## How do I check my Claude Code usage? Three checks, in order: 1. **Inside Claude Code itself.** Run `/cost` in the CLI. You get the current session's token spend, model mix, and approximate dollar equivalent. Fastest signal when you suspect a session has gone heavy. 1. **The Claude desktop app.** This is the one most people miss. Almost everyone running Claude Code is on a Pro or Max subscription, not the API. So open the Claude desktop app, go to Settings, and you can see your usage against your plan's 5-hour and weekly caps right there. This is the canonical source for subscription users, and it is the check I run first. 1. **The token-optimizer dashboard.** If you have [token-optimizer](https://github.com/alexgreensh/token-optimizer) installed, `/token-optimizer` opens an interactive dashboard with cost per session, model mix, cache hit rate, and subagent spending. More detail than the app, scoped to your local sessions. The Anthropic console at [console.anthropic.com](https://console.anthropic.com) is the fourth check, but only if you run Claude Code against your own API key. Open Usage there for per-day token consumption by model. If you are on the standard Pro or Max plan, the console will not show your Claude Code usage, the desktop app will. For serious users who want their own tracker: pipe `/cost` output to a log file via a Stop hook and roll a weekly rollup. Five lines of bash. The [Claude Code hooks](/blog/claude-code-hooks) post covers the hook setup. ## Why did Claude Code say "limit reached"? Four causes, in order of frequency: 1. **You hit the 5-hour rolling cap.** Long Opus sessions are the usual culprit. The cap resets automatically 5 hours after your first message in the current window, not on the hour. 1. **You hit the weekly cap.** Resets on the day of the week tied to your billing cycle. The console shows the exact reset time. Switching to Sonnet temporarily extends your runway but does not reset the cap. 1. **Output cap on a single response.** Claude Code defaults to a generous output cap, but you can hit it on long file generation or massive refactor diffs. The fix is to break the task into smaller asks. 1. **A model-specific cap.** Opus has its own ceiling distinct from Sonnet on Max plans. You can run out of Opus while Sonnet is still available. Switch with `/model sonnet` to keep working. Two of these caps can be raised without changing plans. The other two require either a plan upgrade or an architectural change to how you use the tool. The next sections cover both paths. ## How do I extend Claude Code rate limits? First, the honest framing. Most people reading this do not want to leave their Claude Code subscription. You are paying a flat monthly rate and you want to get more out of it, not start paying per token again. So treat the first two levers as the exception. The real win for almost everyone is the efficiency section right after this one. You have three levers, in escalating cost order: **Lever 1: Upgrade the Claude plan.** Pro to Max gets you roughly 4x more usage. Max to Team or Enterprise adds another step up plus admin features. If you bill Claude Code as a business expense and use it 4+ hours a day, the Max plan pays for itself in saved context-switching. **Lever 2: Move heavy workloads to the Claude API.** This is the exception, not the answer most people want, so I am putting the caveat first. You would be leaving the flat-rate plan you already pay for and switching to metered per-token billing. It only makes sense for unattended production agent loops that run overnight on their own. For everyday coding on a Pro or Max plan, do not do this. The efficiency moves below get you further on the subscription you already have. If you genuinely need it, you run Claude Code against your own Anthropic API key and the setup is one environment variable. **Lever 3: Route specific workloads to a cheaper backend.** Pair Claude Code with [free-claude-code](/tools/claude-status) or Crush for the parts of your work that do not need Sonnet 4.6 quality. Lint fixes, doc generation, file renames, basic refactors. Route them to a local model or to OpenRouter. Keep Claude Code on the actual thinking. If none of those work for you, the better answer is to use the plan you have more efficiently. That is the next 80% of this post. ## How do I reduce Claude Code token usage? Nine moves, ranked by how much they actually move the needle. ### 1. Default to Sonnet, escalate to Opus This is the single biggest lever. Sonnet 4.6 handles 80% of real work at roughly a fifth of the cost of Opus 4.7 on Max plans. Set Sonnet as your default model in your CLAUDE.md or via `/model sonnet`. Reserve Opus for multi-file architecture decisions, hard debugging, and irreversible production work. When the hard part is done, drop back to Sonnet. I run a one-line rule in my CLAUDE.md that says: "Default to Sonnet. Ask before escalating to Opus." It cut my Opus usage by 70% in the first week. One caveat worth knowing before you hardcode it. If you pin Sonnet as your default model, you lose auto mode, where Claude Code picks the model for you and automatically steps down to a cheaper one as you approach your limit. Auto mode is genuinely useful and giving it up stings. So the real trade-off is this. Pin Sonnet when you want hard, predictable cost control. Leave it on auto when you want the routing handled for you. I pin Sonnet on long agentic sessions and let auto run the day-to-day. ### 2. Compact every 20-30 messages Claude Code accumulates context as you go. Every file you read, every tool output, every prior message stays in the working set until you compact. After 30-40 messages, you are paying for 50,000-80,000 tokens of conversation that no longer serves the task. Run `/compact` aggressively. Twice an hour on a long session. Once after any large file read. The first run is the painful one because you watch your context drop. After that you forget you are doing it. ### 3. Use /clear between unrelated tasks `/compact` keeps the gist. `/clear` wipes the session. If you are switching from "fix the auth bug" to "draft a marketing email," you want a clean slate. The new task does not need 80,000 tokens of debugging context attached to it. I run `/clear` 4-6 times a day. Anything more than a 10-minute context switch gets a fresh session. One habit that makes this safe on important work: write a handoff file before you compact or clear. A short `HANDOFF.md` covering what you were doing, what is already done, and where the next session should pick up. Then clear without fear, because the next session reads the handoff and loses nothing. I do this before every clear on a live build, and it is the single reason I can clear so aggressively without dropping the thread. ### 4. Install the token-optimizer skill The [token-optimizer](https://github.com/alexgreensh/token-optimizer) skill by Alex Greensh is the single best Claude Code optimization tool I have installed. It runs as an external process so it costs zero context tokens of its own. What it actually does: - Audits your `.claude/` directory for unused skills, bloated CLAUDE.md files, duplicate system prompts, and stale memory entries. Roughly 75-85% of token waste is structural and this is what removes it. - Compresses verbose CLI output. Git diffs, pytest runs, lint failures, Docker logs, build chains all get summarised before they hit the context window. 16 built-in handlers ship with the skill. - Smart compaction. Checkpoints decisions before `/compact` fires and restores critical content afterwards so you do not lose what mattered. - Delta mode for re-reads. When Claude re-reads a file it has seen before, only the diff is sent. The repo claims ~97% savings on typical re-reads. Install with `/plugin marketplace add alexgreensh/token-optimizer`, then run `/token-optimizer` for an interactive audit. It will tell you exactly what to cut. ### 5. Tighten your CLAUDE.md Every CLAUDE.md byte loads on every session. A 200-line CLAUDE.md across 50 projects a week adds up. My rule: if a CLAUDE.md line is not actively shaping behaviour, it gets cut. Two specific patterns to delete on sight: - "Be helpful and write good code." Generic guidance does nothing. Claude is already trying. - Repeated examples that just rephrase the same rule. One example is plenty. The [Claude Code memory](/blog/claude-code-memory) post goes deeper on writing a tight CLAUDE.md. ### 6. Scope subagents through plan mode first Three parallel subagents each running a 30-step plan can eat an hour of usage in 10 minutes. The fix is to use plan mode first, scope the work, then dispatch. The pattern I run: 1. Switch to plan mode with Shift+Tab. 1. Get Claude to write the plan. 1. Review the plan, kill any steps that are speculative. 1. Exit plan mode and dispatch the pruned plan to subagents. Plan mode is roughly free because it does not edit files. The cost of the dispatched work is whatever the work would have cost anyway, but without the speculation tax. ### 7. Use Haiku for batch tasks Haiku 4.5 is roughly 4x cheaper than Sonnet and roughly fast enough for things like file renames, doc cleanups, lint fixes, and migration scripts. Set it as the model for batch subagent runs. The pattern: main session on Sonnet, dispatched batch work to subagents running Haiku. ### 8. Cap output explicitly Add a line to your CLAUDE.md that says: "Keep responses under 2,000 tokens unless I ask for the full version." Claude obeys it. You stop getting 4,000-token essay answers to two-line questions. ### 9. Look at what other people are running A few other optimization tools worth checking, ranked by what I have either used or seen working in production: - **token-optimizer-mcp** ([ooples/token-optimizer-mcp](https://github.com/ooples/token-optimizer-mcp)). different project from the skill above. Runs as an MCP server doing caching and compression at the tool-call level. Useful if your bottleneck is repeated tool calls. - **claude-modular** ([oxygen-fragment/claude-modular](https://github.com/oxygen-fragment/claude-modular)). a framework with 30+ pre-built commands and a token-optimization layer baked in. Good starting point if you are setting up Claude Code for a team and want sensible defaults out of the box. - **agentwise** ([VibeCodingWithPhil/agentwise](https://github.com/VibeCodingWithPhil/agentwise)). multi-agent orchestration with a 15-30% token savings claim. The orchestration is more interesting than the savings, but the savings are real. - **claude-token-optimizer** ([nadimtuhin/claude-token-optimizer](https://github.com/nadimtuhin/claude-token-optimizer)). a different angle. Reusable setup prompts that optimise documentation for Claude Code consumption. Useful before a big onboarding pass. Pick one, not all. The token-optimizer skill plus the native moves above will cover 80% of the gap for most users. > [CTA-BLUEPRINT] ## Where to start if you only do three things The 80/20 of this post, in order: 1. **Set Sonnet as your default model.** One line in your CLAUDE.md. Cuts Opus burn by 60-70% the first week. 1. **Install the token-optimizer skill.** `/plugin marketplace add alexgreensh/token-optimizer`, then run `/token-optimizer`. Removes the structural waste that nobody catches manually. 1. **Compact and clear ruthlessly.** `/compact` twice an hour during long sessions. `/clear` between unrelated tasks. Free habit, biggest single behavioural change. Everything else in this post is incremental on top of those three. ## What happens when you hit the Claude Code weekly limit? You get a polite message saying you have hit your weekly cap and can either upgrade your plan or wait for the reset. The 5-hour cap keeps working independently, so you can still run short sessions, you just cannot run long ones. Two things to know: 1. The reset time is shown in your console and is tied to your billing cycle, not to a calendar week. If you signed up on a Wednesday, your week resets every Wednesday. 1. Switching to the Claude API with your own key keeps you working immediately. Pay per token, no plan cap. Useful as an overflow buffer. If you are hitting the weekly cap regularly on Max, the optimization moves above will pull you back into the cap on most weeks. If they do not, you are doing genuine production work and the Enterprise tier or API billing is the right answer. ## Claude Code rate limits FAQ ### What is the Claude Code 5-hour limit? The Claude Code 5-hour limit is a rolling usage cap that resets exactly 5 hours after your first message in the current window. It is your plan's standard rate limit and the most common cap you hit during a normal workday. The cap is shared across Claude.ai and Claude Code, so heavy use in either counts towards it. ### What is the Claude Code weekly limit? The Claude Code weekly limit is a 7-day usage ceiling that resets on the day of the week tied to your billing cycle. Hitting it stops your sessions for the rest of the week unless you upgrade or move to API billing. Opus burns through the weekly limit roughly 5x faster than Sonnet on Max plans. ### How do I check my Claude Code usage? Run `/cost` inside Claude Code for the current session, or sign into console.anthropic.com and open Usage for the canonical daily and weekly breakdown. For deeper insight, install the [token-optimizer](https://github.com/alexgreensh/token-optimizer) skill and run `/token-optimizer` for a dashboard with cost per session, model mix, and cache hit rate. ### How do I extend Claude Code rate limits? You have three paths. Upgrade the Claude plan (Pro to Max gives roughly 4x more usage). Move heavy workloads to the Claude API and pay per token, which bypasses the plan cap. Or route specific workloads to a cheaper backend through Crush or free-claude-code. The third option is the cheapest if you are willing to set it up. ### Why is Claude Code running slow? Slow Claude Code is usually one of three things. The session is bloated with old context (fix with `/compact` or `/clear`). The current model is overloaded by Anthropic (check the [Is Claude Down](/tools/claude-status) page). Or your CLAUDE.md is loading too much on every message (tighten it). ### Can I share my Claude Code usage across team members? Yes, on Team and Enterprise plans. Each seat gets its own rate limit, with admin visibility into team-wide consumption. On Pro and Max, usage is per-account and not shareable. ### What is the cheapest way to run Claude Code? The cheapest setup is Claude Code on Pro with Sonnet as the default, token-optimizer installed, and overflow routed to OpenRouter or a local model through Crush. That gets most operators below $25 a month for daily heavy use. ## Ready to cut your Claude Code usage in half? The five moves that matter most are in this post. The Blueprint walks you through the full setup, including the CLAUDE.md template I use, the token-optimizer install, and the model routing pattern. Free, 60 minutes, no coding required. ## Related guides - [Is Claude Down? Check This Before You Debug Claude Code](/blog/is-claude-down-before-you-debug) --- # npm install @anthropic-ai/claude-code: What Actually Happens (and 4 Errors to Watch For) Source: https://theaiarchitects.com/blog/npm-install-claude-code Published: 2026-05-20 What npm install @anthropic-ai/claude-code actually does, what gets installed where, the 4 errors most devs hit on first run, and the verify command that proves it worked. The npm command to install Claude Code is `npm install -g @anthropic-ai/claude-code`. Run it once with Node 20+ and you get a working `claude` CLI binary you can call from any terminal. I'm Tom. I've installed Claude Code on a fresh laptop more times than I can count. Here's exactly what npm does under the hood, the 4 errors that catch most people on first run, and the one verify command that proves the install worked. > [CTA-BLUEPRINT] ## What does npm install @anthropic-ai/claude-code do? Running `npm install -g @anthropic-ai/claude-code` fetches the package from the npm registry, resolves its dependencies, and writes everything to your global node_modules directory. The `-g` flag is the critical piece: without it, npm installs the package locally inside your current project folder, and the `claude` command won't be available system-wide. The install drops a `claude` binary into your npm global bin directory. That binary is what you call from the terminal every time you start a Claude Code session. Anthropic ships the CLI as a self-contained package, so you do not need to clone a repo or build anything yourself. ## What gets installed where When you run a global npm install, npm resolves the destination from your npm prefix setting. On most machines this is configured automatically when you install Node.js. You can check yours by running `npm config get prefix` in your terminal. The `claude` binary ends up in the `bin` subfolder of that prefix. For the install to work from any directory, that bin folder needs to be in your system's PATH. On macOS with Homebrew Node this is handled automatically. On Linux and Windows you may need to add the path manually if you configured a custom npm prefix. - **macOS (Homebrew Node)** — Global bin location: /opt/homebrew/bin/claude. What goes in PATH: /opt/homebrew/bin. - **macOS (system Node)** — Global bin location: /usr/local/bin/claude. What goes in PATH: /usr/local/bin. - **Linux** — Global bin location: ~/.npm-global/bin/claude or /usr/local/bin/claude. What goes in PATH: depends on npm prefix. - **Windows** — Global bin location: %AppData%\npm\claude.cmd. What goes in PATH: %AppData%\npm. ## The 4 errors you'll hit on first run These are the same errors you'd see from any global npm install of a non-trivial CLI, but they trip up Claude Code installs in predictable ways. ### 1. EACCES permission denied **Error:** `npm ERR! code EACCES` followed by a path to your node_modules or bin directory. **Fix:** Do not use `sudo npm install -g`. Instead, configure a user-owned npm prefix. Run `mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`, then add `export PATH=~/.npm-global/bin:$PATH` to your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent) and reload with `source ~/.zshrc`. Once the prefix points to a directory your user owns, the install completes without permission errors. ### 2. command not found: claude (PATH not set) **Error:** The install completes without errors, but running `claude` returns `command not found` or `'claude' is not recognized`. **Fix:** Your npm global bin directory is not in PATH. Run `npm config get prefix` to find where the bin is, then add that path to your shell profile. On macOS with a standard Node install the bin is at `/usr/local/bin`, which is usually already in PATH. On Linux with a custom prefix you'll need to add it manually. After editing your shell profile, run `source ~/.zshrc` (or open a new terminal) and try `claude` again. ### 3. Node version too old **Error:** During install you see something like `Unsupported engine: wanted: {"node":">=20"}` or the install completes but Claude Code refuses to run with a Node version error. **Fix:** Claude Code requires Node 20 or newer. Run `node --version` to check what you have. If you're on an older version, the cleanest upgrade path is to install [nvm](https://github.com/nvm-sh/nvm) and run `nvm install 20 && nvm use 20`, then repeat the Claude Code install. Alternatively, install the latest Node LTS from nodejs.org directly. ### 4. Corporate proxy or firewall blocking npm **Error:** The install hangs indefinitely, or you see `ETIMEDOUT`, `ECONNREFUSED`, or a certificate error pointing at the npm registry. **Fix:** If your machine routes traffic through a corporate proxy, npm needs to know about it. Run `npm config set proxy http://your-proxy:port` and `npm config set https-proxy http://your-proxy:port`. If the error is a self-signed certificate, you may also need `npm config set cafile /path/to/cert.pem`. Your network or IT team can supply the proxy URL and cert. Once the proxy is configured, retry the install. ## How to verify the install worked Run this in a new terminal window after the install completes: A healthy output looks like `claude 1.x.x` (the exact version number varies with each release). If you see a version number, the install worked and the binary is in your PATH. If you see `command not found`, your PATH is missing the npm bin directory. Go back to error 2 above. If you see an error about authentication or credits, the binary is installed correctly and you need to connect it to a Claude account by running `claude` and following the login prompt. ## How to update Claude Code after the first install Run either of these commands to update to the latest version: or, to force the absolute latest release: Anthropic ships new Claude Code versions roughly weekly. Running the update command takes under a minute and keeps you on current model defaults, bug fixes, and new features. You can check your current version at any time with `claude --version`. > [CTA-BLUEPRINT] ## npm install Claude Code FAQ ### What is the npm package name for Claude Code? The package name is `@anthropic-ai/claude-code`. The full install command is `npm install -g @anthropic-ai/claude-code`. The scoped package name (`@anthropic-ai/`) is required: searching for just `claude-code` on npm will find unrelated packages. ### Can I install Claude Code without npm? npm is the primary install method. Anthropic does not currently publish a standalone binary or a Homebrew formula for Claude Code. If you have Node.js installed, npm is already available and the install takes under a minute. ### Do I need to install Claude Code globally? For almost all use cases, yes. The `-g` flag puts the `claude` binary on your system PATH so you can run it from any directory. If you install locally (without `-g`), you'd need to run it via `npx` or a relative path, which is not how Claude Code is designed to be used day to day. ### Why does my Claude Code install hang on npm install? The most common causes are a corporate proxy blocking the npm registry, a slow connection during a large dependency download, or an antivirus tool scanning the install in real time. Check for proxy configuration errors first (error 4 above). If you are on an unrestricted connection and the hang persists past a few minutes, cancel with Ctrl+C and retry. ### Is the Claude Code npm package free? The npm package itself is free to download and install. To actually run Claude Code you need either a paid Claude Pro plan ($20 per month or higher) or Anthropic API credits. The CLI will prompt you to log in and connect a plan on first use. ### What Node version do I need to install Claude Code? Node 20 or newer. Run `node --version` to check. If you're on Node 18 or older, the install may appear to succeed but Claude Code will not run correctly. Use nvm to upgrade: `nvm install 20 && nvm use 20`. ### How do I uninstall Claude Code from npm? Run `npm uninstall -g @anthropic-ai/claude-code`. This removes the package from your global node_modules and deletes the `claude` binary from your npm bin directory. Your Claude account and any conversation history are stored separately and are not affected by the uninstall. ## Related guides For more on getting Claude Code set up and using it effectively: - [How to install Claude Code (all platforms)](/blog/how-to-install-claude-code) - [How to use Claude Code: 60-minute beginner guide](/blog/how-to-use-claude-code) - [Claude Code pricing explained](/blog/claude-code-pricing) ## Sources and official documentation The facts in this post are drawn from the official Anthropic documentation and the published npm package: - [@anthropic-ai/claude-code on npm](https://www.npmjs.com/package/@anthropic-ai/claude-code) - [Claude Code installation docs](https://docs.claude.com/en/docs/claude-code/setup) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) ## Ready to actually use Claude Code? Once the install is verified, the next step is connecting your account and running your first session. > [CTA-BLUEPRINT] ## Frequently Asked Questions ### What is the npm install command for Claude Code? npm install -g @anthropic-ai/claude-code. The scoped package name is required because searching for just claude-code on npm pulls unrelated packages. The -g flag is the critical piece: without it, npm installs locally and the claude command is not available system-wide. Takes under a minute on a normal connection. ### Why does my Claude Code install hang on npm install? Three usual causes. A corporate proxy blocking the npm registry (you will see ETIMEDOUT or ECONNREFUSED). A slow connection during dependency download. Or an antivirus tool scanning the install in real time. Check proxy configuration first with npm config get proxy. If you are on an unrestricted connection and the hang persists past a few minutes, cancel with Ctrl+C and retry. ### Do I need Node.js to install Claude Code? Yes, Node.js 20 or newer. Run node --version to check. If you are on Node 18 or older, the install may appear to succeed but Claude Code will not run correctly. The cleanest upgrade path is nvm: nvm install 20 && nvm use 20, then retry the install. Or grab the latest LTS from nodejs.org. ### Is the Claude Code npm package free? The package is free to download and install. To actually run sessions you need either a paid Claude Pro plan ($20 a month or higher) or Anthropic API credits. The CLI installs cleanly without authentication, but the first time you run claude it prompts you to log in and connect a plan. ### How do I fix EACCES permission denied during install? Do not use sudo. Configure a user-owned npm prefix instead. Run mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global, add export PATH=~/.npm-global/bin:$PATH to your shell profile, then source ~/.zshrc. Retry the install. sudo npm install -g writes to root-owned directories and creates ownership problems later. ### How do I verify the install worked? Open a new terminal window and run claude --version. A healthy output shows claude 1.x.x. If you see command not found, your npm bin directory is not in PATH (run npm config get prefix and add the bin folder to your shell profile). If you see an authentication error, the binary is fine and you just need to log in by running claude. ### How do I update Claude Code? Run npm install -g @anthropic-ai/claude-code@latest or npm update -g @anthropic-ai/claude-code. Anthropic ships new versions roughly weekly with bug fixes, model default updates, and new features. The update takes under a minute. Check the current version any time with claude --version. --- # Claude Code Free Trial: The Honest Path to a Real Test in 2026 Source: https://theaiarchitects.com/blog/claude-code-free-trial Published: 2026-05-20 Is there a Claude Code free trial in 2026? Yes and no. Here's what's actually free, what isn't, and the cheapest path to a real test before you commit to a plan. Claude Code does not have a traditional free trial. There is no 14-day window, no trial mode, and no free-tier access to the CLI that lets you do real work without a subscription or API credits. The CLI installs for free, which is where most of the confusion starts. I'm Tom. I've run every Claude tier from free to Max 20x. Here's the honest map of what's free, what isn't, and the cheapest path to a real test. > [CTA-BLUEPRINT] ## Is there a Claude Code free trial? Claude Code has no dedicated free trial. Anthropic does not offer a timed trial period or a freemium Claude Code mode. The only paths to Claude Code are a paid subscription starting at $20 a month, or the Anthropic API with your own credits. The one partial exception: new Anthropic API accounts get $5 in trial credits. That is technically free Claude Code access, and it lasts as long as the $5 does. ## What you get on the free tier A free Claude.ai account gives you browser-based access to Claude with a daily message cap. You can test Claude's reasoning and writing from a browser. What you cannot do is run Claude Code. Claude Code is a CLI tool that runs in your terminal, edits files, executes commands, and manages agentic workflows. The free tier does not include it. Installing the CLI is free, but authenticating with a free account will not get you past the login screen for serious work. The free tier tests Claude the assistant. It does not test Claude the operator. ## How to test Claude Code without paying $20 There is one legitimate free path: the $5 API trial credits Anthropic issues to new API accounts. Create an account at [console.anthropic.com](https://console.anthropic.com). Anthropic loads $5 of trial credits on signup. Install the Claude Code CLI and authenticate using your API key rather than a subscription login. Every token comes out of that $5 balance. The catch is that $5 goes fast. A 30-minute build on Sonnet 4.6 can cost $0.50 to $2.00 depending on context size. You get two to ten meaningful sessions before the credits run out. Enough to form a view. Not enough to build anything serious. No credit card required until you top up. ## The cheapest way to actually try Claude Code Two paths are worth considering: the API pay-as-you-go approach and a single month of Pro. The API path gives you precise control. Set a spending limit in the console, authenticate with your API key, and pay per token. Sonnet 4.6 runs at $3 per million input and $15 per million output. A focused week of testing typically costs $10 to $30. The Pro path is simpler. Pay $20, cancel before the next billing date, and you have a full month of Claude Code on Sonnet without watching a credit meter. ### Comparison table - **Free Claude account** — Cost: $0. Time limit: None. What you can actually do: Try Claude.ai chat. No Code access.. - **API trial credits** — Cost: $0 (one-time). Time limit: Until credits gone. What you can actually do: Build with the Claude Code CLI via API key. Burns fast.. - **Pro subscription** — Cost: $20/mo. Time limit: Cancel anytime. What you can actually do: Full Claude Code access at Sonnet level.. - **Max 5x** — Cost: $100/mo. Time limit: Cancel anytime. What you can actually do: 5x Pro usage, daily-driver tier.. ## What you should actually do (the 30-minute test) Run this before deciding on a plan. ### 1. Claim your API trial credits Go to [console.anthropic.com](https://console.anthropic.com), create an account, and grab your API key. Set a $5 hard spending limit in billing settings so you cannot accidentally overspend. ### 2. Install and authenticate via API key Install with `npm install -g @anthropic-ai/claude-code`. When you run `claude`, choose the API key option and paste the key from step one. You are now running real Claude Code without a subscription. ### 3. Give it a genuine task Skip hello-world examples. Pick a real file from a project you actually work on and ask Claude Code to read it, suggest improvements, and implement one. That 15-minute session will tell you more than any review. If it clicks, buy a month of Pro. If it does not, you spent nothing. > [CTA-BLUEPRINT] ## Claude Code free trial FAQ ### Is Claude Code free with a Pro subscription? Claude Code is included in Pro at $20 a month. There is no separate charge for the CLI. It runs against your weekly usage cap within the plan. ### How long does the Claude Code free trial last? There is no timed free trial. The $5 API trial credits new accounts receive last until the balance runs out, typically two to ten sessions depending on usage. ### Can I use Claude Code without a credit card? Yes, via the API trial credits. Create a console.anthropic.com account, claim your $5, and run Claude Code against that balance without a card. A card is required once the trial credits are gone. ### Do I get Claude Code free with Claude.ai Free? No. Claude.ai Free gives you browser chat access to Claude, not Claude Code. The CLI requires a paid subscription or API credits. ### Is there a Claude Code free trial for students? Anthropic offers a student discount on Pro via .edu email verification, typically around 50% off. There is no dedicated free trial for students beyond the standard $5 API credits path. ### What happens after the API trial credits run out? Claude Code stops accepting requests and returns a quota error. You will need to add a payment method to the Anthropic console and top up your balance. The trial credits do not reset. ### Is the 30-day Claude Code challenge a free trial? No. The 30-Day Claude Code Challenge is a paid cohort with four live calls and a weekly build track. It assumes you already have Claude Code running. The free Blueprint is the right first step if you want a structured introduction before committing. ## Related guides These posts go deeper on the adjacent questions: - [How to install Claude Code](/blog/how-to-install-claude-code) - [Claude Code pricing explained](/blog/claude-code-pricing) - [Is Claude Code free?](/blog/is-claude-code-free) ## Sources and official documentation Primary sources referenced in this guide: - [Anthropic pricing page](https://www.anthropic.com/pricing) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) ## Ready to test Claude Code in 60 minutes? The free Claude Code Blueprint is a 60-minute guide covering installation, authentication, your first real task, and which plan fits your usage. No subscription required. By the end, you will know whether Claude Code belongs in your stack and what it will cost to run it. > [CTA-BLUEPRINT] ## Frequently Asked Questions ### Is there a Claude Code free trial? No traditional free trial. Anthropic does not offer a timed trial period or a freemium Claude Code mode. The CLI installs for free, which is where most of the confusion starts. The only paths to real Claude Code access are a paid subscription starting at $20 a month, or the Anthropic API with your own credits. ### Can I use Claude Code without a credit card? Yes, via the API trial credits. Create an account at console.anthropic.com and Anthropic loads $5 of trial credits on signup. Install the CLI, authenticate with your API key, and every token comes out of that balance. No card required until you top up. The $5 gets you two to ten meaningful sessions on Sonnet before it runs out. ### Do I get Claude Code free with Claude.ai Free? No. The free Claude.ai plan gives you browser chat access with a daily message cap. Claude Code is a separate CLI that runs in your terminal, edits files, and executes commands. Installing the CLI is free, but authenticating with a free account will not get you past the login screen for serious work. ### What's the cheapest way to actually try Claude Code? Two paths. The API pay-as-you-go route: set a $5 hard spending limit in the console and pay per token (Sonnet 4.6 runs at $3 per million input, $15 per million output). A focused week of testing typically costs $10 to $30. The Pro path: pay $20 for a month, cancel before the next billing date, and you have a full month of Sonnet without watching a credit meter. ### How do I run the 30-minute test before committing to a plan? Three steps. Claim your $5 API trial credits at console.anthropic.com and set a hard spending limit so you cannot overspend. Install with npm install -g @anthropic-ai/claude-code and authenticate with your API key. Give it a genuine task: pick a real file from a project you actually work on and ask Claude Code to read it, suggest improvements, and implement one. Fifteen minutes will tell you more than any review. ### What happens after the API trial credits run out? Claude Code stops accepting requests and returns a quota error. You will need to add a payment method to the Anthropic console and top up your balance. The trial credits do not reset, and you cannot create a second account to get another $5. Once gone, gone. ### Is the 30-Day Claude Code Challenge a free trial? No. The 30-Day Claude Code Challenge is a paid cohort with four live calls and a weekly build track. It assumes you already have Claude Code running, so you need a plan or API credits before you join. The free Blueprint is the right first step if you want a structured introduction before committing to either the challenge or a Pro subscription. --- # The --dangerously-skip-permissions Flag: When to Use It Source: https://theaiarchitects.com/blog/claude-code-dangerously-skip-permissions Published: 2026-05-20 Claude Code's --dangerously-skip-permissions flag bypasses every permission prompt. Here's when it's actually safe, when it will cost you, and the smarter alternatives. `--dangerously-skip-permissions` is a Claude Code CLI flag that bypasses every permission prompt in the session, letting Claude execute shell commands, edit files, and run agent loops without stopping to ask you first. Most developers reach for it when prompt fatigue sets in. That's precisely when it bites you. I've tested Claude Code across dozens of production builds. This flag is legitimate in a narrow set of conditions and genuinely dangerous outside them. This post breaks down exactly where the line is, what the safer middle ground looks like, and what Anthropic's own security documentation says you should do instead. If you're new to Claude Code, start with the [complete Claude Code guide](/blog/how-to-use-claude-code) to get the full picture before diving into permission configuration. [CTA-BLUEPRINT] ## What is `--dangerously-skip-permissions`? `--dangerously-skip-permissions` is a CLI flag that sets Claude Code's permission mode to `bypassPermissions`. According to the [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference), it is equivalent to running `--permission-mode bypassPermissions`. In this mode, every tool call, bash command, file edit, and agentic action executes without a confirmation prompt. The community nickname for this mode is "yolo mode," and the name fits. You are telling Claude to act without a safety net. There is one circuit breaker that stays active regardless: attempts to remove the filesystem root or your home directory (`rm -rf /` and `rm -rf ~`) still trigger a prompt. Everything else proceeds without interruption. ## How does `bypassPermissions` mode work? Claude Code normally uses a tiered permission system. Read-only operations (file reads, grep, ls) run without prompts. Bash commands require approval on first use. File modifications require approval until session end. When you approve a command, you can choose "yes, don't ask again" to allowlist it permanently for that project. `bypassPermissions` collapses all of that. The mode flag tells Claude Code to skip the evaluation layer entirely for the session. From [Anthropic's permissions documentation](https://code.claude.com/docs/en/permissions): "Skips all permission prompts. Root and home directory removals such as `rm -rf /` still prompt as a circuit breaker." Critically, `bypassPermissions` also skips permission checks for writes to `.git`, `.claude`, `.vscode`, `.idea`, and `.husky`. That means Claude can rewrite your git hooks, modify IDE settings, and alter its own configuration files without stopping. ## When is `--dangerously-skip-permissions` actually safe? The flag is genuinely safe in exactly three scenarios. **Sandboxed Docker containers.** If Claude Code runs inside an isolated container with no access to your host filesystem, no production credentials mounted, and no network routes to live services, bypassing permissions costs you nothing. The container boundary is your safety layer. Anthropic explicitly recommends virtual machines or containers as the right isolation environment for this mode. **Throwaway test repositories.** A fresh clone of a repo that contains no secrets, no deployment configs, and nothing you'd care about losing is a reasonable place to let Claude run free. The risk ceiling is "I might need to re-clone this." **Fully trusted, fully reviewed prompts.** If you wrote the CLAUDE.md yourself, you understand every skill and hook in the project, you've read the prompt you're about to run, and you're confident it won't touch anything outside the repo, the flag is an acceptable time-saver for a one-off task. This scenario is rarer than most people assume. ## When will `--dangerously-skip-permissions` bite you? The failure modes cluster around four situations. **Code that touches files outside the repo.** Claude Code's write access is normally restricted to the folder where it was started and its subdirectories. With `bypassPermissions` off, a command reaching for a parent directory or your home folder triggers a prompt that stops you. With it on, the write goes through. **Anything that can run arbitrary shell commands.** If your workflow includes MCP servers, hooks, or skills that invoke bash, you've multiplied your attack surface. A prompt injection buried in a file Claude is reading can issue shell commands that execute immediately with no confirmation gate. The [security documentation](https://code.claude.com/docs/en/security) covers this specifically: prompt injection is a real attack vector, and the permission system is one of the primary defenses against it. **Agent loops without supervision.** Running Claude Code in headless print mode (`-p`) with `--dangerously-skip-permissions` and a long agentic task is the highest-risk combination. The loop can run dozens of turns, each one executing without a check. A misunderstood instruction early in the loop can compound across every subsequent action. **Any session where you have production credentials in scope.** If your environment has AWS credentials, Stripe keys, database connection strings, or any other live-service authentication, `bypassPermissions` means Claude can use them without stopping. This includes credentials in `.env` files, shell environment variables, and SSH keys accessible from the session. ## What people get wrong about the flag The most common misunderstanding is treating `--dangerously-skip-permissions` as a permanent productivity setting rather than a situational tool. Developers add it to their default claude alias, run it for months without incident, then encounter a bad session where a malformed prompt or an unexpected file triggers a cascade of unrecoverable changes. The second misunderstanding is assuming the flag only affects Claude's "dangerous" actions. It affects all actions. A session where you just want Claude to refactor some files without prompting you still runs entirely without safety checks. If the task expands into something you didn't anticipate, there is no gate. The third is assuming the Docker circuit breaker is comprehensive. The circuit breaker only catches `rm -rf /` and `rm -rf ~` style root deletions. It does not catch targeted deletion of important files, writes to credential files, or git operations that can irreversibly alter repository history. ## The proper middle ground: `auto` mode (and what it actually does) Anthropic shipped a permission mode called `auto` that is the halfway-house most people reach for `--dangerously-skip-permissions` to find. From [Anthropic's permissions documentation](https://code.claude.com/docs/en/permissions): *"Auto-approves tool calls with background safety checks that verify actions align with your request. Currently a research preview."* The mechanics matter. Default mode prompts you for every first-use tool call. `bypassPermissions` (the flag) skips every prompt and trusts the model. `auto` sits between the two: it skips prompts when the action clearly aligns with your stated request, and a background classifier flags anything that looks off-pattern. You get the flow-state benefit without giving up the safety net entirely. You set it the same way you'd set any permission mode. In your settings file: Or as a CLI flag for a single session: A few honest caveats. It is currently labelled a research preview, which means Anthropic is still tuning the safety classifier. The [auto-mode-config doc](https://code.claude.com/docs/en/auto-mode-config) lets you tell the classifier which infrastructure your organisation trusts, which reduces false alarms in mature environments. Administrators can disable auto mode entirely with `permissions.disableAutoMode` in managed settings, the same way `bypassPermissions` can be locked out. When `auto` is the right pick: you have a working CLAUDE.md, you've configured your `additionalDirectories` correctly, you're working in a real repo (not a sandbox), and you want to remove the prompt friction without removing the guardrails. That covers most daily Claude Code use. When `auto` is not enough: heavy agentic loops in headless mode, or workflows that touch credentials and live services. Those still warrant the targeted approach below. ## The other safer middle ground: `--allowedTools` and plan mode The right approach for most "I don't want to keep approving prompts" frustrations is a targeted allowlist, not a blanket bypass. `--allowedTools` lets you specify exactly which tools execute without prompting. From the [CLI reference](https://code.claude.com/docs/en/cli-reference): This allows git log and diff commands and all file reads to run silently, while everything else still prompts. You get the flow-state benefit without the open-ended risk. You can also set persistent allowlists in `.claude/settings.json`: For tasks where you want Claude to plan before touching anything, [plan mode](/blog/claude-code-plan-mode) is the cleanest middle ground. Claude reads files and runs read-only shell commands to map out what it wants to do, then presents the plan before making any changes. You approve the plan once rather than approving each individual tool call. For automated pipelines where you genuinely need no-prompt execution, [hooks](/blog/claude-code-hooks) give you enforcement at the tool-call level. A `PreToolUse` hook can block specific commands or command patterns even when other permissions are open, giving you a targeted deny list without removing the permission system entirely. [CTA-BLUEPRINT] ## Frequently asked questions about `--dangerously-skip-permissions` ### What does `--dangerously-skip-permissions` actually skip? It skips all permission prompts for the session, including bash command approvals, file edit confirmations, and writes to configuration directories like `.git`, `.claude`, `.vscode`, and `.husky`. The only exception is filesystem root and home directory deletions (`rm -rf /`, `rm -rf ~`), which still trigger a prompt as a circuit breaker. ### Is `--dangerously-skip-permissions` the same as `--permission-mode bypassPermissions`? Yes. The two flags are functionally equivalent. `--dangerously-skip-permissions` is the shorthand. `--permission-mode bypassPermissions` is the explicit form. Both set Claude Code's session permission mode to `bypassPermissions`. ### Can admins disable `bypassPermissions` mode for a team? Yes. Anthropic's permissions documentation describes a `permissions.disableBypassPermissionsMode` setting that can be placed in managed settings. When set to `"disable"`, the mode cannot be activated by any user or project-level configuration, including the CLI flag. ### What is `--allow-dangerously-skip-permissions` (with the extra `allow-` prefix)? This is a separate, more conservative flag. It adds `bypassPermissions` to the Shift+Tab mode cycle without starting in it. You might begin a session in plan mode and switch to bypass later if needed. It does not enable bypass by default. Example: `claude --permission-mode plan --allow-dangerously-skip-permissions`. ### What is "Claude Code yolo mode"? "Yolo mode" is the community nickname for `--dangerously-skip-permissions` / `bypassPermissions` mode. The nickname reflects what the flag does: run without checking anything. ### When should I use `--dangerously-skip-permissions` vs `--allowedTools`? Use `--dangerously-skip-permissions` only inside isolated environments (containers or VMs) where damage is contained. Use `--allowedTools` any time you want to reduce prompts in a real working environment. `--allowedTools` gives you the same friction reduction for specific commands without removing the safety net for everything else. ### Does `--dangerously-skip-permissions` let Claude access files outside my project? The flag bypasses prompt-based restrictions, but Claude Code's default write boundary (the directory where it was launched plus subdirectories) still applies unless you explicitly add directories with `--add-dir`. The flag removes confirmation prompts, not filesystem-level enforcement. ## Ready to build safer Claude Code workflows? The permission system in Claude Code exists because agentic tools that execute code need guardrails. `--dangerously-skip-permissions` is a valid escape hatch for isolated environments, not a default setting for daily use. If you want to reduce friction without removing safety, the [Claude Code Blueprint](/blueprint) walks through the permission configuration patterns, allowlist syntax, and hook setup that I use across all my production projects. Start there before reaching for the bypass flag. --- # Claude Agent SDK: Build Your First Production Agent Source: https://theaiarchitects.com/blog/claude-agent-sdk Published: 2026-05-20 The Claude Agent SDK lets you build production AI agents in Python or TypeScript. Inbox triage tutorial, MCP servers, cron deploy, rate-limit gotchas. The Claude Agent SDK is a Python and TypeScript library that gives you a production-ready AI agent loop — file reading, command execution, code editing, and web search — built directly on top of the same engine that powers Claude Code. If you have spent any time with the raw Anthropic Messages API, you know the drill: send a prompt, check whether the response includes a tool call, execute the tool, send the result back, repeat. The Claude Agent SDK removes that entire plumbing layer. You hand it a prompt and a list of allowed tools, then stream the results while Claude handles the loop. This post walks through a real working agent — a daily inbox triage system that summarises high-priority emails and posts to Slack — including the rate-limit gotchas, the tool-loop pattern, and a cron-based production deploy. I have been building production agents with Claude for over a year. This is the clearest path I have found from zero to a working autonomous system. --- [CTA-BLUEPRINT] --- ## What is Claude Agent SDK? The Claude Agent SDK is a library from Anthropic that exposes the full Claude Code agent loop as a programmable interface in Python and TypeScript. Rather than implementing your own tool-use loop against the Messages API, you import `query` from the SDK, pass it a prompt and a set of permitted tools, and stream back structured messages as Claude reads files, runs commands, searches the web, and edits code autonomously. Anthropic recently renamed it from the Claude Code SDK to the Claude Agent SDK. If you see references to `claude-code-sdk` in older posts or packages, they point to the same thing. The current Python package is `claude-agent-sdk` and the npm package is `@anthropic-ai/claude-agent-sdk`. The SDK sits between the raw Anthropic Client SDK (which requires you to write the tool loop) and Managed Agents (where Anthropic runs the infrastructure). With the Agent SDK, the loop runs in your own process, on your own infrastructure. ## How does Claude Agent SDK work? The Agent SDK exposes a single core function called `query`. You call it with a natural-language prompt and an `options` object that specifies which tools Claude is allowed to use. `query` returns an async iterator that yields messages as Claude works: reasoning text, tool calls, tool results, and a final result message. Under the hood, Claude reads your prompt, decides which tool to call first, executes it, observes the output, and decides what to do next. That loop continues until Claude decides the task is complete. The SDK handles retries, context management, and session state — none of that is your problem. ### The tool-loop pattern Here is the minimal Python pattern: The `async for` loop is the whole pattern. Claude calls tools, you get message objects. Filter for `AssistantMessage` to show Claude's reasoning, and `ResultMessage` for the final output. ### Built-in tools The SDK ships with ten built-in tools you can enable by name: - **Read** — Read any file in the working directory - **Write** — Create new files - **Edit** — Make targeted edits to existing files - **Bash** — Run terminal commands, scripts, git operations - **Monitor** — Watch a background script and react to each output line - **Glob** — Find files by pattern (`**/*.ts`, `src/**/*.py`) - **Grep** — Search file contents with regex - **WebSearch** — Search the web for current information - **WebFetch** — Fetch and parse web page content - **AskUserQuestion** — Ask the user clarifying questions ### Permission modes `permission_mode` controls how much the agent can do without pausing to ask: - **`acceptEdits`** — Auto-approves file edits and common filesystem commands - **`dontAsk`** — Denies anything not in `allowed_tools` - **`bypassPermissions`** — Runs every tool without prompts (for sandboxed CI) - **`default`** — Requires a `canUseTool` callback to handle approval For production headless agents, `acceptEdits` with a narrow `allowed_tools` list is the safest default. ## What I built: a daily inbox triage agent The agent reads unread emails via a local `fetchmail` dump, classifies them by priority, writes a Markdown summary, then posts it to a Slack webhook. The whole thing runs in under two minutes and costs roughly $0.04 per run. ### Project structure ### The agent script Three tools only: `Read` to open emails, `Glob` to find all `.eml` files, `Write` to save the summary. No `Bash`, no internet access. The agent cannot do anything outside those three operations, which is exactly right for production. ## Standout features ### 1. MCP server support The Claude Agent SDK can connect to any MCP server, which means you can drop in a Postgres MCP server and your agent can query your database, or add the Playwright MCP server for browser automation, all without writing custom tool code. I use this pattern to connect inbox-triage agents to CRM databases for customer lookup. The Agent SDK is also how Claude Code itself exposes MCP to the rest of your stack. For a full breakdown of MCP setup, see our [Claude Code MCP guide](/blog/claude-code-mcp). ### 2. Session continuity You can resume a session across multiple calls, which means Claude retains memory of everything it has read and done. The session ID comes from the first `SystemMessage` with `subtype == "init"`. This is the pattern that makes multi-step research agents practical. Each sub-task builds on what Claude already knows. ### 3. Subagents for parallel workloads You can spawn named subagents with their own tools and system prompts. The orchestrator delegates, subagents report back. For a codebase audit, for example, you might have a `security-reviewer` subagent with `Read`, `Glob`, and `Grep`, and a separate `docs-writer` subagent with `Read` and `Write`. ### 4. Hooks for audit and control Hooks let you run custom code at lifecycle events. A `PostToolUse` hook fires after every tool call. Use it for audit logs, cost tracking, or blocking writes to production paths. For a deeper look at how hooks apply to the broader Claude Code configuration system, see our [Claude Code guide](/blog/how-to-use-claude-code). ## Where Claude Agent SDK falls short The SDK runs inside your process, on your infrastructure. That is a feature for most teams, but it means you own all the operational overhead: container sizing, retry logic, cold-start latency, and session storage (stored as JSONL on your filesystem by default). For long-running or asynchronous jobs, Anthropic's Managed Agents API offloads that to Anthropic-hosted infrastructure. Rate limits are the other practical friction point. The SDK does not have built-in backoff. If you fire twenty concurrent agents with `Bash` and `WebSearch` enabled, you will hit token-per-minute limits quickly. The safest production pattern is a queue with one agent running at a time, or a semaphore if you need concurrency. The Claude Agent SDK also does not yet expose a direct REST interface, so you cannot call it from a non-Python, non-TypeScript runtime without spawning a subprocess. For Go or Java backends, Managed Agents is the right call. --- [CTA-HOSTINGER] --- ## How to install Claude Agent SDK ### Step 1: Install the package For Python (using pip): For Python (using uv, the faster option): For TypeScript: The TypeScript package bundles a native Claude Code binary for your platform, so you do not need to install Claude Code separately. ### Step 2: Set your API key Get an API key from the [Anthropic Console](https://platform.claude.com/), then set it: Or write it to a `.env` file in your project root. The SDK reads it automatically. The SDK also supports Amazon Bedrock (`CLAUDE_CODE_USE_BEDROCK=1`), Google Vertex AI (`CLAUDE_CODE_USE_VERTEX=1`), and Microsoft Azure (`CLAUDE_CODE_USE_FOUNDRY=1`) if you need to run agents through those providers. ### Step 3: Run your first agent Save this to `agent.py`: Run it: ### Step 4: Deploy to production with cron For the inbox triage agent, I use a simple cron job on a $6/month VPS: That runs Monday to Friday at 7am. The agent finishes in under two minutes, posts to Slack, and exits. Total monthly cost: the VPS + roughly $1 in API calls. For n8n users, wrap the agent in a Python subprocess node on a scheduled trigger. See our [Claude Code and the web guide](/blog/claude-code-web) for the broader deployment patterns. ## Claude Agent SDK vs alternatives ### Claude Agent SDK vs Anthropic Client SDK The Client SDK gives you raw API access: you send a prompt and implement every tool call yourself. The Agent SDK wraps that loop. If you want control over every decision point, use the Client SDK. If you want Claude to run autonomously and just tell you when it is done, use the Agent SDK. ### Claude Agent SDK vs Managed Agents - **Runs in** — Agent SDK: Your process. Managed Agents: Anthropic infrastructure. - **Interface** — Agent SDK: Python / TypeScript library. Managed Agents: REST API. - **Works on** — Agent SDK: Your filesystem. Managed Agents: Anthropic-managed sandbox. - **Best for** — Agent SDK: Local dev, filesystem agents. Managed Agents: Long-running, async, any language. The practical path: prototype with the Agent SDK, move to Managed Agents when you need Anthropic to handle the infrastructure. ### Claude Agent SDK vs OpenAI Agents SDK OpenAI's Agents SDK follows a similar pattern. The main difference is tool inventory: Claude Agent SDK ships with `Bash`, `Monitor`, and `WebFetch` out of the box, which OpenAI's does not. Claude also handles long-context tasks (200k token window) better than GPT-4o for codebase-wide analysis. For MCP support, the Claude Agent SDK is currently more mature. ## Verdict: is Claude Agent SDK worth it? Yes, if you are building any kind of autonomous workflow that touches files, code, or the web. The SDK collapses what would be three to four hundred lines of tool-loop boilerplate into a ten-line async iterator. The built-in tools are production-quality. The MCP integration means you can add capabilities without writing custom tool definitions. It is not the right choice if you need a non-Python, non-TypeScript runtime, if you want Anthropic to own the sandboxing and session storage, or if your task is simple enough that a single Messages API call handles it. For most builders in the AI Operators community, the Claude Agent SDK is the correct abstraction. You get Claude's full capability set without owning the plumbing. --- [CTA-BLUEPRINT] --- ## Claude Agent SDK FAQ ### What is Claude Agent SDK? The Claude Agent SDK is a Python and TypeScript library from Anthropic that gives you a production-ready AI agent loop. You pass it a prompt and a list of allowed tools, and Claude autonomously reads files, runs commands, edits code, and searches the web until the task is complete. ### Is Claude Agent SDK free? The SDK itself is free to download and use. You pay for API usage at standard Anthropic pricing. A typical agent run that reads ten files and makes a few edits costs between $0.02 and $0.10 depending on the model. Sonnet 4.6 is the cost-efficient default. Opus 4.7 is the high-capability option. ### How is Claude Agent SDK different from Claude Code SDK? They are the same thing. Anthropic renamed the Claude Code SDK to the Claude Agent SDK. The Python package changed from `claude-code-sdk` to `claude-agent-sdk`. The TypeScript package changed from `@anthropic-ai/claude-code-sdk` to `@anthropic-ai/claude-agent-sdk`. All the APIs are the same. ### Can Claude Agent SDK call MCP servers? Yes. Pass an `mcp_servers` dict in `ClaudeAgentOptions` with the command and args for each server. The SDK connects to any MCP-compliant server: databases, browsers, APIs, and the growing ecosystem of community-built servers. ### What Python version do I need for Claude Agent SDK? Python 3.10 or later. For TypeScript, Node.js 18 or later. The TypeScript package bundles a native binary, so you do not need Claude Code installed separately. ### How do I handle rate limits with Claude Agent SDK? The SDK does not have built-in backoff. For production deployments with multiple concurrent agents, add a semaphore or run agents sequentially through a queue. Hitting rate limits produces an API error you can catch and retry with exponential backoff. ### Can I use Claude Agent SDK with Amazon Bedrock or Google Vertex? Yes. Set `CLAUDE_CODE_USE_BEDROCK=1` for Bedrock or `CLAUDE_CODE_USE_VERTEX=1` for Vertex AI and configure the corresponding cloud credentials. The SDK routes calls through the appropriate provider automatically. ## Ready to build your first autonomous agent? The Claude Agent SDK gives you the same tools that power Claude Code, wrapped in an async iterator you can run anywhere. The inbox triage agent above is a good starting point: narrow tool set, clear task, sub-two-minute runtime, and a Slack notification when it is done. If you want a structured path from your first agent to a full AI operating system for your business, the [Claude Code Blueprint](/blueprint) lays it out step by step. ## Frequently Asked Questions ### What is the Claude Agent SDK? The Claude Agent SDK is a Python and TypeScript library from Anthropic that exposes the full Claude Code agent loop as a programmable interface. You pass it a prompt and a set of allowed tools, and Claude autonomously reads files, runs commands, edits code, and searches the web until the task is done. It used to be called the Claude Code SDK before Anthropic renamed it. ### How much does the Claude Agent SDK cost to run? The SDK itself is free. You pay standard Anthropic API pricing for tokens. A typical agent run that reads ten files and makes a few edits costs $0.02 to $0.10 on Sonnet 4.6. The inbox triage agent in this post runs in under two minutes and costs roughly $0.04 per run, plus a $6 a month VPS to host it. ### When should I use the Agent SDK vs Managed Agents? The Agent SDK runs in your own process on your own infrastructure, which gives you control but means you own retries, container sizing, and session storage. Managed Agents runs on Anthropic infrastructure with a REST API, which fits Go or Java backends or long-running async jobs. Prototype with the Agent SDK, move to Managed Agents when you need someone else handling the plumbing. ### Can the Claude Agent SDK call MCP servers? Yes. Pass an mcp_servers dict in ClaudeAgentOptions with the command and args for each server, and the SDK connects to any MCP-compliant server. Drop in a Postgres MCP server and your agent can query your database. Add the Playwright MCP server and it can drive a browser. No custom tool code needed. ### How do I handle rate limits with the Agent SDK? The SDK does not ship with built-in backoff. If you fire twenty concurrent agents with Bash and WebSearch enabled, you will hit token-per-minute limits fast. The safest production pattern is a queue running one agent at a time, or a semaphore if you need controlled concurrency. Wrap your call in a try block and retry rate-limit errors with exponential backoff. ### What Python or Node version do I need? Python 3.10 or later for the Python SDK. Node.js 18 or later for TypeScript. The TypeScript package bundles a native Claude Code binary for your platform, so you do not need to install Claude Code separately to use the TS SDK. ### How is the Agent SDK different from the Anthropic Client SDK? The Client SDK gives you raw API access where you implement every tool call yourself. The Agent SDK wraps that loop. Want control over every decision point? Use the Client SDK. Want Claude to run autonomously and tell you when it is done? Use the Agent SDK. The Agent SDK collapses three to four hundred lines of tool-loop boilerplate into a ten-line async iterator. --- # 24 Claude Code Skills, Subagents and Hooks Worth Stealing in 2026 Source: https://theaiarchitects.com/blog/best-claude-code-skills Published: 2026-05-20 The 24 skills, subagents, and hooks I actually run in my Claude Code setup, with one-line problem statements and the .claude/ files behind each one. My `.claude/` directory has 24 things in it that I'd rebuild from scratch if I lost them tomorrow. Skills, subagents, hooks. Each one earns its keep or gets deleted on the next Sunday cleanup. I've shipped 11 client projects and run a daily content operation through this stack. Each entry below solves a specific problem in one move. No "nice to haves". No "I might use this someday". > [CTA-BLUEPRINT] ## What are Claude Code skills, subagents and hooks? Three different layers of the same engine. [Skills](/blog/claude-code-skills) are markdown files that teach Claude how to do a specific job (write a newsletter, audit a brand, build a deck). You trigger them by intent. [Subagents](/blog/claude-code-subagents-vs-skills) are separate Claude instances with their own context window and tool list. You delegate a chunk of work to them and get a clean result back. [Hooks](/blog/claude-code-hooks) are shell commands that fire on lifecycle events. SessionStart, PreToolUse, Stop, and so on. They run deterministically. They're how you make Claude Code behave like a real production system instead of a clever chatbot. If you want the full primer, start with my walkthrough on [how to use Claude Code](/blog/how-to-use-claude-code) and then come back here. ## How I picked these 24 Three rules. I had to have actually used the thing in the last 30 days. It had to solve a real problem in one move, not five. And I had to be willing to rebuild it from scratch if it disappeared overnight. That cut my install list from around 60 down to these 24. Some are from [Anthropic's official skills repo](https://github.com/anthropics/skills). Some are community pulls. Most are mine, hand-built for the AI Architects operation and tuned every week. A note on category. The line between a skill and a subagent is fuzzier than the docs suggest. My working rule: if the job needs its own context window (long codebase searches, security audits, stack-trace triage), it's a subagent. If the job is mostly a writing or structural task that reads files in my main context, it's a skill. Hooks are for things I never want Claude to forget or skip. ## 10 skills worth stealing These are the skills I trigger by name almost daily. Each one has a `SKILL.md` file in `.claude/skills/` with frontmatter, a description, and the instructions Claude follows when invoked. ### `humanizer` Problem: AI drafts have tells. Em dashes, rule-of-three parallels, words like "comprehensive" and "robust". This skill strips them out in one pass. I run every piece of copy through it before anything goes live. It's the single highest-leverage skill in my stack because it makes everything else usable. Built on Wikipedia's "Signs of AI writing" guide plus a personal blacklist I've added to every week since January. ### `voice-analysis` Problem: I want Claude to write like me, not like ChatGPT in a wig. This skill ingests a folder of my best-performing posts and outputs a `voice-profile.md` that other skills read at runtime. Sentence rhythm, banned phrases, hook formulas, the lot. Fed straight into `humanizer` and `direct-response-copy` so they share a brain. ### `presentation` Problem: I need a slide deck and I don't want to open Keynote. I drop in an outline. The skill outputs `presentation.html` plus `presentation.pdf` in my locked ink/bone/orange editorial design. About 4 minutes from outline to PDF. I've used it for client workshops, internal training, and one paid talk. ### `direct-response-copy` Problem: Landing page copy that sounds like a smart friend, not a marketing intern. Loaded with reference material from Schwartz, Hopkins, Halbert, Caples and Sugarman. Reads the voice profile, takes a brief, returns headlines, body, and CTA variants. The headline-rating pass is built in so I get scored options instead of one weak attempt. ### `brand-voice` Problem: Starting a new client project from zero with no voice guide. Two modes. Extract pulls a voice from existing content. Build constructs one strategically when there's nothing to pull from. Outputs a profile that every other content skill can read. This is how I onboard a new brand in under an hour. ### `content-atomizer` Problem: I wrote a 2,000-word newsletter and I want LinkedIn, X, and Instagram versions without sitting at the desk for three more hours. Takes the source, returns platform-specific drafts. Hook formulas, character limits, format conventions are all baked in. I still edit the output. But the lift goes from 90 minutes to 15. ### `newsletter` Problem: The weekly issue has a locked house style and I do not want to redesign it every Sunday. This one is brutal in scope. Editorial masthead, decisive periods, numbered showcase section, image placeholders with prompts, direct-response CTA. I drop in the week's topics. The skill returns a publication-ready file in `AI OPERATOR OS/Email Campaigns/Newsletters/`. ### `reddit-post` Problem: I want to share a build on r/ClaudeAI without sounding like a marketer. The skill drafts a native, value-first post with karma-warm strategy and a quality-gate checklist. No CTAs in the body. No links in the title. It's saved me from at least three shadowbans I would have walked straight into. ### `token-optimizer` Problem: Context feels tight and I don't know why. Audits my Claude Code setup, shows where tokens are going, and recommends specific cuts. I run this once a month. Last audit found I was loading a 14k-token reference doc into every session I didn't need. One delete bought me back half my budget. ### `recall` Problem: I worked on something three weeks ago and I cannot find the file. Searches prior session transcripts by topic or date. Native JSONL for temporal queries ("what was I doing last Tuesday"), QMD BM25 for topic queries. Ends every search with a single highest-leverage next action. The closest thing I have to long-term memory across sessions. Pairs naturally with [slash commands](/blog/claude-code-commands) so I can fire it with two keystrokes. ## 8 subagents worth stealing Subagents are different. They run in their own context window with a restricted tool list. You delegate, they return, you keep going. Configured in `.claude/agents/` or via the Task tool. ### `error-debugger` Problem: I have a 200-line stack trace and I do not want it polluting my main context. I paste the trace into a Task call. The subagent returns a diagnosis, a suggested fix, and a confidence level. Main thread stays clean. Worth its weight in tokens. ### `process-analyzer` Problem: I'm describing a manual workflow and I want to know which steps an AI agent could own. Takes a process description, returns a ranked list of automation candidates with effort estimates. Used this last week to spec out a client's CRM hygiene flow. Saved a half-day of discovery. ### `api-integration-expert` Problem: I'm staring at a 401 from an API and the docs are lying to me. The subagent walks the auth flow, checks for common mistakes (header case, token expiry, scope), and returns a fix. Specialized for OAuth, API keys, and webhook signatures. Beats Googling the same Stack Overflow thread for the eighth time. ### `Explore` Problem: I need to find where a function is defined across a 400-file codebase without burning context on grep output. Read-only codebase search. Returns the relevant paths and a summary. I use it before any non-trivial edit so I'm not guessing at structure. ### `code-reviewer` Problem: I want a second opinion before I merge to main. Independent review pass on the diff. Flags logic issues, missing tests, security smells. Returns a verdict with line-level comments. Catches things my own implementation context blinds me to. ### `security-review` Problem: I'm about to ship payment logic and I want a focused pre-flight. Scoped audit of pending changes. API keys, injection risks, auth boundary checks. I run this on anything touching Stripe or user data. Cheap insurance. ### `Plan` Problem: I have a complex feature and I need a step-by-step plan before touching code. Acts as a software architect. Returns numbered steps, file targets, and verification commands. I use it whenever the work spans more than three files. The plan becomes the to-do list for the implementation session. ### `general-purpose` Problem: Multi-step research that does not fit any specialist subagent. The catch-all. "Find every place we reference the old pricing tier across the vault and the codebase". "Compare these three vendors and tell me which has webhook retry semantics". Slower than a specialist, broader than anything else. When I'm not sure which subagent to call, I default to this one and let it scope the work itself. ## 6 hooks worth stealing Hooks are the deterministic layer. They fire on events whether Claude likes it or not. Configured in `settings.json` under the `hooks` key. This is where you bolt down the operation. ### `SessionStart` context loader Problem: Every new session, Claude has zero memory of what I was doing yesterday. A SessionStart hook runs a bash script that pulls my last three session summaries from Open Brain and the current sprint notes. Loaded as context before I type a single character. Saves the "remind me where we left off" round-trip. ### `PreToolUse` block `rm -rf` Problem: Claude is autonomous enough to delete things I did not want deleted. A PreToolUse hook on the Bash tool that regex-matches destructive patterns (`rm -rf`, `git reset --hard`, `git push --force` to main) and refuses them with a clear error. Slash commands like [slash commands](/blog/claude-code-commands) can override when I genuinely need to nuke a directory. ### `PostToolUse` auto-format Problem: I do not want to remember to run prettier after every edit. A PostToolUse hook on the Edit and Write tools that runs `prettier --write` (or `ruff format`) on the changed file. Code stays consistent without me thinking about it. Lints never get checked in dirty. ### `Stop` Slack notification Problem: Long-running jobs finish and I miss them because I switched windows. A Stop hook that posts to Slack with the session summary and the elapsed time. I'll kick off a 40-minute video transcription job, walk to make coffee, and get pinged when it's done. Tiny change, huge quality of life. ### `Notification` push Problem: Permission prompts block the session and I'm in another room. Notification hook fires a push to my phone via ntfy.sh whenever Claude asks for permission. I can approve from the kitchen. Means I can leave longer agentic runs going without babysitting. ### `UserPromptSubmit` lint Problem: I write a vague prompt and Claude spends 8 minutes producing the wrong thing. A UserPromptSubmit hook checks my prompt against a small ruleset (does it specify the output file, does it name the skill if one applies, does it include a target word count). If it fails, the hook prints a warning before Claude even reads the prompt. Forces me to write better briefs. Bonus hook I'm testing: a Stop hook that auto-captures the session summary to Open Brain so I never lose a decision. Two weeks in. It's earning its place. ## How I'd build a skill stack from scratch (4 starter picks) If you're staring at an empty `.claude/` and you've read [the Anthropic skills docs](https://code.claude.com/docs/en/skills), here's the order I'd add them in. First, `humanizer`. Even before you have a voice profile, the AI tells are the most expensive thing in your output. Strip them at the door. Second, `voice-analysis` so every skill that comes after it shares a brain. Pair these two before anything else. Third, whatever your highest-leverage output is. For me that was `newsletter`. For a SaaS founder it might be a changelog skill. Pick the thing you do every week and automate the structure. Fourth, `recall` so you stop losing work between sessions. Get this far and you've already overtaken 90 percent of Claude Code users I've onboarded through the mentorship. After that it gets personal. Look at your last 10 prompts and ask which ones you'll send again next month. Those are your next skills. The [Claude plugins](/blog/claude-plugins) ecosystem is growing fast, so check there before you build from scratch. > [CTA-BLUEPRINT] ## Best Claude Code skills FAQ ### What's the best Claude Code skill? For me it's `humanizer`, because it touches every piece of output before it ships. Most useful single install across any use case I've tested. If you write anything customer-facing, this is the one to copy first. ### Where do I find awesome Claude Code skills on GitHub? The official starting point is [github.com/anthropics/skills](https://github.com/anthropics/skills), Anthropic's curated repo. Beyond that, search GitHub for `claude-code-skills` and `claude-skills` as topics. Community repos pop up weekly. I pull from three or four I trust and ignore the rest. ### How do I install someone else's Claude Code skill? Copy their `SKILL.md` file into your `.claude/skills//SKILL.md`. The skill's frontmatter handles registration. Restart your session, type the trigger phrase, and you're running it. No build step, no plugin loader. That's the whole point of the format. ### Are Claude Code skills the same as plugins? No. Skills are markdown instructions Claude reads at invocation time. Plugins are bundled packages that can include skills, subagents, hooks, and slash commands together. A plugin can contain ten skills. A skill is a single file. ### Can I share my Claude Code skills with my team? Yes. Drop the `.claude/skills/` folder into your project repo and commit it. Anyone who clones the repo gets the same skill set. For team-wide skills that span projects, ship a small internal repo and have everyone symlink it into `~/.claude/skills/`. That's how my mentorship cohort shares the AI Architects skill library. ### How do skills compare to subagents for daily work? Skills feel like keyboard shortcuts. You hit them constantly, they do small focused jobs in your main context. Subagents feel like delegations. You hand off a chunk of work and get back a clean answer. Most days I trigger 15-20 skill invocations and 3-4 subagent calls. ## Ready to build your own Claude Code stack? The 24 above took me about 14 months of iteration to settle on. You don't need to repeat that work. Inside the AI Architects Blueprint I walk through the exact `.claude/` directory, the hook scripts, and the subagent configs I use every day. Same stack. Same files. Yours to fork. ## Frequently Asked Questions ### What is the best Claude Code skill to install first? Humanizer. It touches every piece of output before it ships. Strips em dashes, rule-of-three parallels, and AI-tell words like comprehensive and robust. Built on Wikipedia's Signs of AI writing guide plus a personal blacklist I have added to every week since January. If you write anything customer-facing, this is the one to copy first. ### What is the difference between skills, subagents, and hooks? Three layers of the same engine. Skills are markdown files that teach Claude how to do a specific job (newsletter, brand audit, slide deck). Subagents are separate Claude instances with their own context window for delegated work. Hooks are shell commands that fire deterministically on lifecycle events. Skills suggest. Subagents delegate. Hooks enforce. ### How do I install someone else's Claude Code skill? Copy their SKILL.md file into your .claude/skills//SKILL.md. The frontmatter handles registration. Restart your session, type the trigger phrase, and you are running it. No build step, no plugin loader. That is the whole point of the format. Always read a skill before installing it because skills can include instructions that mutate files. ### Where can I find good Claude Code skills on GitHub? The official starting point is github.com/anthropics/skills, Anthropic's curated repo. Beyond that, search GitHub for claude-code-skills and claude-skills as topics. Community repos pop up weekly. Pull from three or four you trust and ignore the rest. Quality varies wildly outside the official repo. ### Are Claude Code skills the same as plugins? No. Skills are markdown instructions Claude reads at invocation time. Plugins are bundled packages that can include skills, subagents, hooks, and slash commands together. A plugin can contain ten skills. A skill is a single file. Use standalone skills for single-project work and plugins when you need versioning, sharing, or cross-project reuse. ### If I am starting from an empty .claude/, what is the first stack to build? Four picks in this order. First, humanizer to strip AI tells at the door. Second, voice-analysis so every skill that comes after it shares a brain. Third, whatever your highest-leverage output is (for me, newsletter, for a SaaS founder it might be a changelog skill). Fourth, recall so you stop losing work between sessions. Get this far and you have already overtaken 90% of Claude Code users I have onboarded. ### Can I share my Claude Code skills with my team? Yes. Drop the .claude/skills/ folder into your project repo and commit it. Anyone who clones the repo gets the same skill set. For team-wide skills that span projects, ship a small internal repo and have everyone symlink it into ~/.claude/skills/. That is how my mentorship cohort shares the AI Architects skill library across 20 plus students. --- # Claude Code vs Copilot vs Codex: Three Tools, Three Jobs Source: https://theaiarchitects.com/blog/claude-code-vs-copilot Published: 2026-05-20 I ran the same five tasks through Claude Code, GitHub Copilot, and Codex CLI. Here's where each one wins and why pairing them beats picking one. Claude Code, GitHub Copilot, and Codex CLI aren't competing for the same job, even though every comparison thread treats them like they are. They sit in three different categories, solve three different problems, and the moment you stop treating them as rivals is the moment your output goes up. I run all three. Five tasks tested in each, on real client work, over the past three weeks. This post is what I learned, with receipts. > [CTA-BLUEPRINT] ## What's the difference between Claude Code, Copilot, and Codex? The category confusion is the whole problem. [GitHub Copilot](https://github.com/features/copilot) is an inline autocomplete engine that lives inside your IDE and finishes the line you're typing. Claude Code is a terminal agent that runs in a loop, reads files, edits them, runs tests, and reports back. [Codex CLI](https://github.com/openai/codex) is also a terminal agent, but it's OpenAI's take, with a different default model and a leaner footprint. Calling all three "AI coding tools" is technically correct and practically useless. One predicts your next token. The other two run autonomous loops. Different jobs. The category split also explains the pricing weirdness. Copilot at $10 a month feels cheap because it's doing a smaller job. Claude Code at $200 a month for the Max plan feels expensive until you realise you're paying for an agent that can hold an entire feature in its head and ship it without supervision. Comparing the two on monthly cost alone is like comparing a calculator to an accountant. ## How do Claude Code, Copilot, and Codex compare? - **Category** — Claude Code: Terminal agent. GitHub Copilot: IDE autocomplete + chat. Codex CLI: Terminal agent. - **Primary surface** — Claude Code: Terminal, runs in your repo. GitHub Copilot: VS Code, JetBrains, Neovim. Codex CLI: Terminal, runs in your repo. - **Agent loop** — Claude Code: Yes, multi-step with tool use. GitHub Copilot: Limited (Copilot Workspace in beta). Codex CLI: Yes, multi-step. - **Plan mode** — Claude Code: Yes, explicit plan-then-execute. GitHub Copilot: No. Codex CLI: Partial, via prompting. - **Multi-file edits** — Claude Code: Native, with diff review. GitHub Copilot: Chat-based, less reliable at scale. Codex CLI: Native, smaller context window. - **Pricing entry point** — Claude Code: $20/mo Pro, $200/mo Max. GitHub Copilot: $10/mo individual, $19/mo business. Codex CLI: Free CLI, pay per token. - **Best for** — Claude Code: Refactors, multi-file features, PR review. GitHub Copilot: Inline completion while typing. Codex CLI: Quick scripted tasks, rate-limit fallback. The table flattens the actual experience. What it misses is feel. Copilot is invisible when it works, finishing the thought you were already having. Claude Code is more like delegating to a junior engineer who reads the whole codebase before touching anything. Codex sits closer to Claude Code in shape but with a different temperament, faster on small jobs and less patient on big ones. If you only read one row, read "Category". Inline autocomplete and terminal agent aren't variants of the same product. They're different software categories that happen to share a marketing label. ## The 5 tasks I ran through all three I picked tasks I had already done by hand, so I knew what good looked like. Same prompt where possible, same repo state, same model defaults for each tool. ### Adding a new API endpoint to a Next.js app Claude Code wrote the route handler, added the Zod schema, updated the typed client, and ran the build. Three files touched, one round of fixes after I pointed out a missing error case. Total time: about six minutes. Copilot finished individual lines beautifully once I started typing the file, but it couldn't scaffold the whole endpoint from a chat prompt without me steering each step. It's a passenger on this kind of task, not a driver. Codex CLI did it in five minutes, slightly tighter code, but missed the typed client update because the context window dropped that file. I had to prompt again. The fix was a single re-prompt, so the time penalty was small, but the trust penalty was real. Once a tool drops a file silently, I start second-guessing the diffs. The winner here was Claude Code by a thin margin. The thing that mattered wasn't speed, it was that I didn't have to babysit the file list. ### Refactoring a tangled React component This is where Claude Code's plan mode earned its keep. It read the component, listed the responsibilities it would extract, and waited for me to approve before writing a line. Final output was four smaller components plus a hook, tests still passing. Copilot Chat could discuss the refactor but couldn't reliably apply it across files. Every multi-file edit needed me to copy code between buffers. Codex did the refactor in one shot but produced one component with a stale prop. Fixable, but I trusted the diff less than Claude Code's. This is the kind of task that exposes the category boundary the cleanest. Refactoring isn't typing assistance, it's structural surgery, and a surgeon who can only operate on one line at a time isn't a surgeon. ### Writing a bash script with arg parsing + error handling Codex won this one. It produced a tight 40-line script with `getopts`, trap handlers, and a usage block on the first try. Claude Code wrote a more verbose version with extra logging I didn't ask for. Copilot autocompleted the script line by line and was honestly fine, just slower because I had to drive every line. ### Reviewing a 400-line PR Claude Code, easily. I pointed it at the diff and asked for a review. It flagged two real bugs, one style nit, and a missing test case. Reading 400 lines is exactly the kind of task an agent loop is built for. Codex did a shorter pass with one of the same bug catches, plus a hallucinated concern about a function it had misread. Copilot doesn't really do this job. Copilot Chat will discuss a diff if you paste it, but at 400 lines you're fighting the chat window. If I had to pick the single task that makes the $200 Max plan pay for itself, it's PR review. The number of bugs Claude Code has caught in client work over the past month would have cost me more than the subscription in rework. ### Debugging a flaky test The flaky test was a race condition in a Jest setup. Claude Code ran the test in a loop, captured the failure, traced the async chain, and fixed it. Took two passes. Codex tried, missed, and asked for more context. I gave it the failure log and it got there on the third try. Copilot was useless here because the problem wasn't local to one line. ## Where Claude Code wins Any task that crosses more than two files and needs the agent to actually read the codebase. Refactors, new features that touch routes plus types plus tests, PR review, debugging that needs to run code. The plan mode is the underrated bit. Telling the model to plan before it edits cuts the regenerate-this rate by roughly half in my use. If you haven't tried it, you're using about 60% of the tool. It also wins on context handling. Claude Code's longer effective window means it can hold three or four files in working memory without forgetting the first one. On tasks that touch a route, a schema, a test, and a typed client, that single property is the difference between a clean ship and a half-finished diff. For the deeper how-to, see my [Claude Code walkthrough](/blog/how-to-use-claude-code). ## Where Copilot wins Inline completion while you're typing. Nothing else matches the latency and the muscle memory of just pressing Tab. If you spend most of your day inside an IDE writing code by hand, Copilot is paying for itself every hour. It also wins on cost for solo developers who don't want an agent loop. Ten dollars a month for unlimited inline completion is still the best deal in the category. The thing Copilot is bad at is anything that needs to span files or run for more than one turn. That's not a flaw. It's a category boundary. One underrated Copilot use: it's still the best tool for languages and frameworks where Claude Code's plan mode is overkill. Quick HTML edits, CSS tweaks, small Python utility scripts. The agent loop adds friction when the task is genuinely one file long. ## Where Codex CLI wins Quick scripted tasks where I want a terminal agent but don't want to spend Claude Code tokens. Bash scripts, one-off data munging, small CLI tools. It's faster on these and the output is usually cleaner. It also wins as a rate-limit fallback. When I hit the Claude Code Max ceiling on a heavy day, Codex steps in. Not because it's better, because it's different infrastructure. Having two terminal agents from two different providers is the closest thing to redundancy you get in this category. The honest knock on Codex is that its context handling on larger codebases is noticeably tighter than Claude Code's. On the five tasks above, every miss Codex made traced back to it dropping a file that mattered. Fine for small jobs, painful for big ones. ## The pairing strategy I actually use Copilot runs inline in VS Code while I'm typing. Always on. I don't think about it. Claude Code runs in a terminal tab next to the editor for anything agentic. Refactors, new features, PR review, debugging. This is where the real leverage is. If you want the cost math on going heavier on Claude Code, [Claude Code pricing](/blog/claude-code-pricing) breaks down the Pro versus Max decision. Codex CLI sits in a third terminal as the fallback agent for when Claude Code is rate-limited or when the task is small enough that I don't want to spend Sonnet tokens on it. Three tools, three jobs, zero overlap in practice. If you're choosing one, you're solving the wrong problem. > [CTA-BLUEPRINT] ## Claude Code vs Copilot vs Codex FAQ ### Is Claude Code better than Copilot? For agent work, yes. For inline autocomplete, no. They're different categories. Claude Code runs multi-step loops across your codebase. Copilot finishes the line you're typing. The honest answer is most working developers should run both. ### Can I use Claude Code and Copilot together? Yes, and you should. Copilot stays on in your IDE for inline completion. Claude Code runs in a terminal for agent tasks. They never collide because they operate on different surfaces. This is the setup I use every day. ### How much does Claude Code cost compared to Copilot? Copilot starts at $10 per month for individuals. Claude Code Pro is $20 per month, and the Max plan is $200 per month for heavy use. If you only need inline completion, Copilot is cheaper. If you need an agent that can refactor or debug across files, Claude Code is the only one of the two doing that job. ### What's the difference between Claude Code and Codex? Both are terminal-based coding agents. Claude Code runs on Anthropic models and has a stronger plan mode and a larger effective context. Codex runs on OpenAI models and is faster on small tasks with a leaner footprint. I use Claude Code as the primary and Codex as the fallback. ### Should I switch from Copilot to Claude Code? Don't switch. Add. Copilot keeps doing the inline job it's good at. Claude Code adds the agent loop Copilot doesn't have. If your budget only allows one, pick based on what you actually do most: lots of typing inside the IDE means Copilot, lots of cross-file changes means Claude Code. If you want a deeper comparison with the closest IDE alternative, see [Claude Code vs Cursor](/blog/claude-code-vs-cursor). ## Ready to try Claude Code? If you've read this far, you already know which category you live in. The pairing strategy above is the setup I run on every client build. Grab the [Blueprint](/blueprint) for the full workflow, including the prompts and the plan-mode templates I use to keep Claude Code on the rails. ## Frequently Asked Questions ### Is Claude Code better than Copilot? For agent work, yes. For inline autocomplete, no. They sit in different categories. Claude Code runs multi-step loops across your codebase, reading files, making edits, and running tests. Copilot finishes the line you are typing. Most working developers should run both, because they solve different problems. ### How much does Claude Code cost compared to Copilot? Copilot starts at $10 a month for individuals and $19 for business. Claude Code Pro is $20 a month, Max is $200 a month for heavy use. Copilot is cheaper if you only need inline completion. Claude Code is the only one of the two that can refactor or debug across files, so monthly cost alone is the wrong comparison. ### Can I use Claude Code and Copilot together? Yes, and you should. Copilot runs inline in your IDE while you type. Claude Code runs in a terminal tab for anything agentic: refactors, new features, PR review, debugging. They never collide because they operate on different surfaces. This is the setup I run every day on client work. ### What's the difference between Claude Code and Codex CLI? Both are terminal-based coding agents. Claude Code runs on Anthropic models with a stronger plan mode and a larger effective context. Codex runs on OpenAI models, is faster on small tasks, and has a leaner footprint. On the five tasks I tested, every miss Codex made traced back to it dropping a file that mattered. I use Claude Code as the primary and Codex as the rate-limit fallback. ### Which tool wins for refactoring a tangled React component? Claude Code by a clear margin. Plan mode reads the component, lists the responsibilities it would extract, and waits for approval before writing a line. Copilot Chat can discuss the refactor but cannot reliably apply it across files. Codex did the refactor in one shot but produced one component with a stale prop. Multi-file structural work is where Claude Code earns its keep. ### Should I switch from Copilot to Claude Code? Do not switch. Add. Copilot keeps doing the inline job it is good at. Claude Code adds the agent loop Copilot does not have. If your budget only allows one, pick based on what you actually do most. Lots of typing inside the IDE means Copilot. Lots of cross-file changes means Claude Code. --- # Claude Plugins Explained: Install, Create, and Distribute Source: https://theaiarchitects.com/blog/claude-plugins Published: 2026-05-20 Claude plugins bundle skills, agents, hooks, and MCP servers into one installable package. How to install, create, and compare plugins to .claude/ config. ## Keyword map - **claude plugins** — Volume: 4,400. Layer: 3 (anchor). - **claude code plugins** — Volume: 3,600. Layer: 3 (anchor). - **claude skills marketplace** — Volume: 1,900. Layer: 2 (long-tail). - **claude code extensions** — Volume: 880. Layer: 2 (long-tail). - **claude-plugins-official** — Volume: 720. Layer: 2 (long-tail). - **claude plugin marketplace** — Volume: 720. Layer: 1 (AEO). - **claude code plugin marketplace** — Volume: 590. Layer: 2 (long-tail). - **best claude code plugins** — Volume: 320. Layer: 1 (AEO). - **claude plugins vs skills** — Volume: 70. Layer: 1 (AEO). - **what are claude plugins** — Volume: 70. Layer: 1 (AEO). - **how to use claude plugins** — Volume: 70. Layer: 1 (AEO). - **how to install claude plugins** — Volume: 40. Layer: 1 (AEO). - **best claude plugins** — Volume: 210. Layer: 1 (AEO). --- ## Post body A Claude Code plugin is a self-contained directory that bundles skills, agents, hooks, MCP servers, and LSP support into a single installable package you can share with a team or distribute to thousands of people with one command. It is the distribution layer that `.claude/` never had. If you have been building skills and slash commands in your `.claude/` directory, you already understand 80% of how plugins work. The remaining 20% is the manifest, the namespace, and the marketplace. This post covers all three. I am Tom. I run AI Architects. I have been working inside Claude Code since before skills had a name. Here is what plugins actually are and how to use them from day one. [CTA-BLUEPRINT] ## What are Claude plugins? A Claude plugin is a directory with a `.claude-plugin/plugin.json` manifest at its root and one or more component folders alongside it. The manifest tells Claude Code the plugin's name, version, and description. The component folders hold the actual functionality: skills in `skills/`, agents in `agents/`, hooks in `hooks/hooks.json`, MCP server configs in `.mcp.json`, LSP server configs in `.lsp.json`, and background monitors in `monitors/monitors.json`. When you install a plugin, Claude Code copies it to a local cache and makes every component inside it available to your session. Skills get namespaced as `/plugin-name:skill-name`. Agents appear in `/agents`. Hooks fire automatically on the events they listen for. MCP servers start in the background. All of it activates with a single install command and a `/reload-plugins`. The mental model that makes this click: your `.claude/` directory is a shoebox. A plugin is a labeled box with a lid. The contents are the same type of thing. The difference is that the labeled box can be versioned, shared via a marketplace, installed in seconds, and updated in one step. ## How do Claude plugins work? Plugins work through three mechanisms that run in sequence when you install one. ### The manifest registers the plugin Every plugin must have `.claude-plugin/plugin.json` at its root. The minimum viable manifest is four fields: The `name` field is the namespace. If the name is `commit-commands`, every skill inside the plugin is reachable as `/commit-commands:skill-name`. The `version` field is what drives updates: Claude Code only delivers a new copy to installed users when this field changes. ### The component folders define the functionality Each type of functionality lives in its own folder at the plugin root. A plugin can have any combination of these, or all of them: - **`skills/`** — Auto-triggered skills, namespaced as `/plugin-name:skill-name` - **`commands/`** — Legacy flat Markdown commands (use `skills/` for new work) - **`agents/`** — Specialized subagents Claude can invoke automatically - **`hooks/hooks.json`** — Event handlers for tool use, file edits, session start, and more - **`.mcp.json`** — Bundled MCP server configurations - **`.lsp.json`** — Language server configurations for code intelligence - **`monitors/monitors.json`** — Background watchers for logs, files, or external state - **`settings.json`** — Default settings applied when the plugin is active - **`bin/`** — Executables added to the Bash tool's PATH One common mistake: do not put these folders inside `.claude-plugin/`. Only `plugin.json` goes in `.claude-plugin/`. Everything else sits at the plugin root. ### The marketplace delivers the plugin to users A marketplace is a JSON catalog that lists available plugins and their source URLs. When you run `/plugin marketplace add anthropics/claude-code`, Claude Code downloads that catalog and makes the plugins inside it browsable via `/plugin`. When you install a specific plugin, Claude fetches the source, copies it to cache, and activates its components. Anthropic ships one official marketplace, `claude-plugins-official`, which is automatically available in every Claude Code install. You browse it in the Discover tab of `/plugin`. There is also a community demo marketplace at `anthropics/claude-code` you can add manually. ## What are the best Claude plugins? The official `claude-plugins-official` marketplace ships plugins in four categories. Based on the official docs, here are the standout ones. ### Code intelligence plugins These are the plugins most developers will install first. Each one pairs a language server binary you already have installed with a Claude Code plugin that connects it to your sessions. Once active, Claude sees type errors immediately after edits, can jump to definitions, find references, and trace call hierarchies without running a compiler. Available language pairings: TypeScript (`typescript-lsp`), Python (`pyright-lsp`), Go (`gopls-lsp`), Rust (`rust-analyzer-lsp`), C/C++ (`clangd-lsp`), Java (`jdtls-lsp`), Swift (`swift-lsp`), Kotlin, Lua, PHP, and C#. Install with: `/plugin install typescript-lsp@claude-plugins-official` ### External integration plugins These bundle pre-configured MCP servers so you get authenticated access to external services without manual setup. Available integrations include GitHub, GitLab, Atlassian (Jira and Confluence), Figma, Vercel, Supabase, Firebase, Slack, Linear, Asana, Notion, and Sentry. Before these plugins existed, each integration required you to find the right MCP server package, write a config block in `.mcp.json`, pass the right environment variables, and verify it worked. The plugin does all of that in one install. ### Development workflow plugins These add skills and agents for day-to-day coding work: - `commit-commands`: Git workflow skills for staging, committing, and opening PRs - `pr-review-toolkit`: Specialized agents for structured pull request review - `agent-sdk-dev`: Tools for building with the Claude Agent SDK - `plugin-dev`: A toolkit for building your own plugins (meta, but useful) ### Output style plugins `explanatory-output-style` and `learning-output-style` change how Claude responds: the first adds implementation reasoning to replies, the second turns sessions into an interactive learning mode. Both install as `settings.json` overrides the plugin activates automatically. [CTA-BLUEPRINT] ## How do I install Claude plugins? Installing a Claude plugin takes two commands. First, add a marketplace if you haven't. Second, install the plugin. ### Step 1: Add a marketplace The official Anthropic marketplace is pre-loaded, so for official plugins you can skip this step. For the community demo marketplace: You can also add marketplaces from any git URL, local directory, or hosted JSON file: ### Step 2: Install the plugin Swap `github` for whichever plugin name you want. Add `@marketplace-name` to target a specific catalog. The interactive UI at `/plugin` lets you choose the installation scope: - **User scope**: installs across all your projects - **Project scope**: adds to `.claude/settings.json`, shared with everyone who clones the repo - **Local scope**: installs only for you in this repo, not committed ### Step 3: Reload That is it. Skills appear under their namespace. Agents show in `/agents`. Hooks start firing. MCP servers start in the background. ## How do I create a Claude Code plugin? Creating a plugin is three steps: directory, manifest, components. ### Step 1: Create the directory and manifest Create `my-plugin/.claude-plugin/plugin.json`: ### Step 2: Add components Add a skill: Create `my-plugin/skills/hello/SKILL.md`: Add a hook by creating `my-plugin/hooks/hooks.json`: ### Step 3: Test locally The `--plugin-dir` flag loads your plugin for that session only without installing it. Make changes, then run `/reload-plugins` to pick them up. Test multiple plugins at once by repeating the flag. ### Distribute via marketplace When you are ready to share, publish the plugin directory to a GitHub repo. Create a `marketplace.json` in a `.claude-plugin/` folder at the repo root that lists your plugin. Others add your marketplace with: To submit to the official Anthropic marketplace, use the form at `platform.claude.com/plugins/submit`. ## Claude plugins vs MCP servers: what is the difference? Claude plugins and MCP servers serve different purposes and operate at different layers. The confusion is common because a plugin can bundle an MCP server inside it. An MCP server is a process that exposes tools to Claude over a standard protocol. Claude calls MCP tools the same way it calls built-in tools: read a file, search the web, query a database. The MCP server handles the call and returns structured output. MCP is the protocol. The server is the implementation. A Claude plugin is a packaging format for distributing Claude Code extensions. A plugin can include zero or more MCP servers in its `.mcp.json`. When you install the plugin, Claude Code starts those servers automatically. Without the plugin, you would configure each MCP server manually in your own `.mcp.json` and manage the credentials yourself. The short version: MCP is about tools Claude can call. Plugins are about distributing and activating Claude Code extensions, which may or may not include MCP tools. For a deeper look at MCP server setup in Claude Code, see the [Claude Code MCP guide](/blog/claude-code-mcp). ## Claude plugins vs skills: what is the difference? A skill is a single `SKILL.md` file that teaches Claude how to do one job. A plugin is a package that can contain many skills plus agents, hooks, MCP configs, and other components. The relationship is container to contents. Skills are a component type that plugins can ship. Standalone skills live in your `.claude/skills/` directory and are only available in that project (or globally if in `~/.claude/skills/`). Plugin skills travel with the plugin, get namespaced automatically, and update when the plugin updates. - **Location** — Standalone skill: `.claude/skills//`. Plugin-bundled skill: `plugin-name/skills//`. - **Invocation** — Standalone skill: `/skill-name`. Plugin-bundled skill: `/plugin-name:skill-name`. - **Sharing** — Standalone skill: Commit to git, copy manually. Plugin-bundled skill: Install via marketplace. - **Updates** — Standalone skill: Manual. Plugin-bundled skill: Automatic on plugin update. - **Scope** — Standalone skill: Project or user. Plugin-bundled skill: User, project, or local. If you are building a skill for one project, keep it standalone. If you are building something you want to reuse across projects or share with others, package it as a plugin. The skills article covers the standalone case in detail: [Claude Code skills explained](/blog/claude-code-skills). ## Where Claude plugins fall short Plugins are not perfect yet. Three things to know before you invest. First, the namespacing adds friction. Standalone skills fire with `/skill-name`. Plugin skills fire with `/plugin-name:skill-name`. That extra prefix is a small thing until you are typing it fifty times a session. The auto-trigger behavior (where Claude fires a skill because the description matches) still works for plugin skills, which cuts most of the manual invocation. But for skills you run explicitly via slash command, the namespace is a daily reminder that you are inside a plugin. Second, plugins are copied to a cache, not symlinked. Files your plugin references must live inside the plugin directory. Paths that point outside the plugin directory break on install. This matters if you are converting an existing `.claude/` config that relies on project-specific files. Third, the official marketplace is curated, which means the selection is limited compared to the raw number of skills floating around GitHub. The community catalog is smaller. If you want a specific integration, you may need to build and self-host the plugin for now. ## Verdict: are Claude plugins worth it? Yes, with a clear condition: they are worth it when you need to share or reuse across projects. For single-project personal workflows, your `.claude/` directory is faster and simpler. For anything you want your team to have, or that you want to version and iterate on, plugins are the right format. The code intelligence plugins alone are worth installing for any serious Claude Code user. Type errors surfacing in real time inside your Claude session eliminates an entire category of debugging loop. The external integration plugins (GitHub, Jira, Figma) remove the manual MCP setup that used to take an hour. The development workflow plugins are genuinely useful if you commit and review code inside Claude Code daily. If you are a builder who ships tools for other Claude Code users, plugins are now the correct distribution mechanism. The marketplace submission process is straightforward. The versioning system means your users get updates without touching their configs. The namespace prevents conflicts with other plugins. Start here: add the official marketplace if it isn't loaded, install one code intelligence plugin for your primary language, and install `commit-commands` if you commit from inside Claude Code. That is a ten-minute setup that changes how you work. [CTA-BLUEPRINT] ## Claude plugins FAQ ### What are Claude plugins? Claude plugins are installable packages that extend Claude Code with skills, agents, hooks, MCP servers, LSP servers, and background monitors. Each plugin is a directory with a `.claude-plugin/plugin.json` manifest and one or more component folders. Install from a marketplace with `/plugin install plugin-name@marketplace-name`. ### How do I install Claude plugins? Run `/plugin install plugin-name@claude-plugins-official` for official plugins. For community plugins, first add the marketplace with `/plugin marketplace add owner/repo`, then install with `/plugin install plugin-name@marketplace-name`. Run `/reload-plugins` after installing to activate. ### What is the Claude plugin marketplace? The Claude plugin marketplace is a catalog of plugins you can install into Claude Code. Anthropic maintains the official marketplace at `claude.com/plugins`, automatically available in every Claude Code install. You browse it with `/plugin` in the Discover tab. Anyone can create and host a marketplace from a GitHub repo. ### What is the best Claude plugin for developers? For code intelligence, the LSP plugin matching your primary language (`typescript-lsp`, `pyright-lsp`, `rust-analyzer-lsp`) gives Claude real-time diagnostics and code navigation. For workflow, `commit-commands` and `pr-review-toolkit` are the most-used in the developer community according to the official docs. ### How do Claude plugins differ from MCP servers? MCP servers are processes that expose tools Claude can call via a standard protocol. Plugins are a packaging format for distributing Claude Code extensions, which may include MCP servers. A plugin can bundle an MCP server so it starts automatically on install. MCP is the transport layer; plugins are the distribution layer. ### How do Claude plugins differ from skills? Skills are individual `SKILL.md` files that teach Claude one job. Plugins are packages that can contain multiple skills plus agents, hooks, and MCP configs. Standalone skills in `.claude/skills/` use short names like `/skill-name`. Plugin skills are namespaced as `/plugin-name:skill-name`. Use standalone skills for single-project work and plugins when you need sharing or cross-project reuse. ### How do I create a Claude Code plugin? Create a directory, add `.claude-plugin/plugin.json` with name, description, and version fields, then add component folders at the plugin root: `skills/`, `agents/`, `hooks/`, `.mcp.json`. Test locally with `claude --plugin-dir ./my-plugin`. Distribute by publishing to GitHub and creating a `marketplace.json`. Submit to the official marketplace at `platform.claude.com/plugins/submit`. ### Can I convert my existing `.claude/` directory into a plugin? Yes. Create the plugin structure, copy your existing `commands/`, `skills/`, and `agents/` folders into it, migrate hooks from `settings.json` into `hooks/hooks.json`, and test with `--plugin-dir`. The component formats are identical between standalone and plugin configurations. ## Ready to go deeper into Claude Code? Plugins are the distribution layer. The underlying components are where the real power is. The [Claude Code skills guide](/blog/claude-code-skills) covers SKILL.md anatomy and how auto-triggers work. The [commands guide](/blog/claude-code-commands) covers slash command patterns. The [MCP guide](/blog/claude-code-mcp) covers connecting external tools. And the [complete Claude Code guide](/blog/how-to-use-claude-code) covers how everything fits together from installation to production. If you want a structured path through all of it, the Blueprint walks you from install to your first production skill in 60 minutes. ## Frequently Asked Questions ### What are Claude plugins? A Claude plugin is a self-contained directory that bundles skills, agents, hooks, MCP servers, LSP support, and background monitors into a single installable package. Each plugin has a .claude-plugin/plugin.json manifest at its root and component folders alongside it. Install from a marketplace with one command and every component activates after /reload-plugins. ### How do I install a Claude plugin? Run /plugin install plugin-name@claude-plugins-official for official Anthropic plugins (the marketplace is pre-loaded). For community plugins, first add the marketplace with /plugin marketplace add owner/repo, then install with /plugin install plugin-name@marketplace-name. Run /reload-plugins after installing. Skills appear under their namespace, hooks start firing, MCP servers boot in the background. ### What is the difference between Claude plugins and skills? A skill is a single SKILL.md file that teaches Claude one job. A plugin is a package that can contain many skills plus agents, hooks, and MCP configs. Standalone skills in .claude/skills/ fire as /skill-name. Plugin skills are namespaced as /plugin-name:skill-name and travel with the plugin. Use standalone skills for single-project work, plugins when you need sharing or cross-project reuse. ### What is the difference between Claude plugins and MCP servers? MCP servers are processes that expose tools Claude can call over a standard protocol. Plugins are a packaging format for distributing Claude Code extensions. A plugin can bundle one or more MCP servers in its .mcp.json so they start automatically on install. MCP is the transport layer. Plugins are the distribution layer. ### How do I create my own Claude plugin? Three steps. Create a directory and add .claude-plugin/plugin.json with name, description, version, and author fields. Add component folders at the plugin root (skills/, agents/, hooks/, .mcp.json). Test locally with claude --plugin-dir ./my-plugin. To share, publish the directory to GitHub and create a marketplace.json. Submit to the official marketplace at platform.claude.com/plugins/submit. ### Are Claude plugins worth installing if I already have .claude/? Yes when you need to share or reuse across projects. For single-project personal workflows, your .claude/ directory is faster and simpler. Plugins win for anything you want a team to install, version, and update in one step. The code intelligence plugins (typescript-lsp, pyright-lsp, rust-analyzer-lsp) and external integration plugins (GitHub, Jira, Figma) are worth installing on day one regardless. ### Can I convert my existing .claude/ directory into a plugin? Yes. Create the plugin structure, copy your existing commands/, skills/, and agents/ folders into it, migrate hooks from settings.json into hooks/hooks.json, and test with claude --plugin-dir ./my-plugin. The component formats are identical between standalone and plugin configurations. One gotcha: plugins are copied to a cache, not symlinked, so paths that reference files outside the plugin directory will break. --- # Claude for Excel: The Honest Guide to AI in Spreadsheets Source: https://theaiarchitects.com/blog/claude-for-excel Published: 2026-05-20 Claude for Excel is an AI add-in that lets you ask questions about any cell, fix formula errors, test scenarios, and build models from scratch inside your workbook. Here is how it actually works. Claude for Excel is an AI add-in from Anthropic that sits inside Microsoft Excel, reads your entire workbook, and helps you interrogate formulas, fix errors, update assumptions, and build financial models without breaking anything. I'm Tom. I've been using Claude as a daily work tool for over a year, and the Excel add-in is one of the more quietly useful things they've shipped. Below is an honest look at what it does well, what it can't do, and how to wire it into a real finance or ops workflow. The "Claude" in this context is the same Claude that powers Claude.ai, Claude Code, and Claude Cowork. This article is specifically about Claude for Excel, the Microsoft Excel add-in. If you've arrived here looking for Claude Cowork (the broader desktop automation product), I'll cover that too since Excel is part of the Cowork ecosystem. [CTA-BLUEPRINT] ## What is Claude for Excel? Claude for Excel is a Microsoft Excel add-in built by Anthropic. It gives you a chat panel inside Excel where you can ask questions about any cell, formula, or tab in your workbook. Claude reads the full model, including cross-tab dependencies, and responds with cell-level citations so you can verify the logic. You install it from the Microsoft marketplace, open it with `Control+Option+C` on Mac or `Control+Alt+C` on Windows, and from that point it stays alongside your spreadsheet as a persistent sidebar. Key difference from pasting data into Claude.ai: the add-in has read-write access to your workbook. It can make changes, highlight what it changed, and explain why. You're not copying and pasting ranges back and forth. ## What is Claude Cowork? Claude Cowork is the broader product that Claude for Excel sits within. Cowork is Anthropic's agentic system for knowledge work: it runs on your desktop, connects to local files and applications, and completes multi-step tasks from start to finish. Excel is one of many things it can work with. You describe the outcome, Claude figures out how to get there. The difference between Cowork and regular Claude chat: in chat, Claude responds to messages but can't touch your files. In Cowork, Claude has permission to read, edit, and create files in folders you specify. The Claude for Excel add-in brings that same file-access model directly into your spreadsheet. ## How does Claude for Excel work? The add-in reads your full workbook context when you open it, including formula structures, cross-tab references, and named ranges. When you ask a question or request a change, Claude works through the model, shows you a diff of every change it plans to make, and waits for your review before writing anything to the sheet. ### Formula understanding and cell citations Claude parses nested formulas across tabs and responds with explicit cell references. Ask "what drives the Q3 revenue forecast?" and it will trace back through SUMIF, INDEX/MATCH, and lookup tables, citing every cell that contributes to the answer. This is more useful than Googling the formula syntax, because it's explaining your model, not a generic example. ### Scenario testing without breaking dependencies You can tell Claude to update an assumption, such as "increase revenue growth by 2% and show the impact on terminal value," and it will propagate the change across every dependent cell while preserving formula structure. It highlights each change with an explanation. If the change would break a reference, Claude flags it rather than silently corrupting the model. ### Error debugging Claude traces `#REF!`, `#VALUE!`, and circular reference errors to their source. Give it a broken cell and it explains what went wrong and how to fix it without disrupting the rest of the sheet. This is where most people save the most time, because debugging a cascading `#REF!` in a 40-tab model manually takes hours. ### Building models from scratch You can describe a financial model in plain English and Claude will build a draft structure with standard financial modeling conventions. It also populates existing templates with fresh data while maintaining formulas and formatting. ## The 5 things Claude for Excel actually does well Here's where the tool earns its keep for business owners and analysts: **1. Formula generation with context.** Not just "write me a VLOOKUP." You describe what you're trying to calculate in plain English and Claude generates the formula with references to your actual column headers and named ranges. It also explains the formula so you understand what it's doing. **2. Data cleaning on messy imports.** When you pull data from a CRM, accounting system, or manual entry sheet, it arrives inconsistent. Claude can identify formatting issues, flag duplicates, standardise date formats, and clean string fields without you writing a custom macro. **3. Model-from-prompt for simple structures.** Give Claude a brief, for example "build a monthly P&L with rows for revenue, COGS, gross margin, operating expenses, and EBITDA, using assumptions in a separate tab," and it will scaffold the structure. You fill in the numbers. It handles the formulas. **4. Summary tab generation.** One of the most-used workflows: Claude reads a complex multi-tab model and generates a clean executive summary tab, pulling key metrics with live references back to the source data. The summary updates automatically when inputs change. **5. What-if scenario analysis.** You can set up scenario toggles by describing them to Claude. "Add a dropdown to this assumptions tab so I can switch between base, bull, and bear cases, and have the rest of the model respond to the selection." Claude builds it. You approve the changes cell by cell. ## The 3 things Claude for Excel cannot do Honest review means calling out the gaps. **1. It does not connect to live external data.** Claude for Excel reads whatever is already in your workbook. It has no direct access to market data feeds, live API connections, or external databases. If you need live pricing or real-time metrics in your model, you'll need a separate data connector or the broader Claude Cowork with access to your browser and other tools. **2. It does not write complex VBA macros reliably.** Claude can write basic VBA and Power Query M code, but it is not a coding agent. For complex automation inside Excel, Claude Code in the terminal is the better tool. Claude for Excel is designed for knowledge-work users, not developers. **3. It is not available for Google Sheets.** Despite searches for "Claude Sheets," there is no official Claude add-in for Google Sheets. The add-in is Microsoft Excel-only. There is a separate [Google Drive connector for Claude.ai](https://claude.com/connectors) that lets Claude read your Drive files (Sheets, Docs, PDFs) inside chat sessions, but it is read-only and not the same as a live two-way Sheets integration. If your team is Sheets-first, the realistic workflow is Drive-connector reads inside Claude.ai or Claude Cowork with browser access, not a native add-in. ## How to install Claude for Excel Claude for Excel is available on Claude Pro, Max, Team, and Enterprise plans. Free plan users cannot access it. **Step 1: Confirm your plan.** Log into claude.ai and check you're on Pro ($17/month annual, $20 monthly), Max, Team, or Enterprise. If you're on free, you'll need to upgrade first. **Step 2: Install from the Microsoft marketplace.** Go to the [Microsoft AppSource page for Claude for Excel](https://marketplace.microsoft.com/en-us/product/saas/wa200009404?tab=overview). Click Install. Sign in with your Microsoft account. The add-in will appear in your Excel ribbon. **Step 3: Open Excel and activate.** Open any workbook. Press `Control+Option+C` on Mac or `Control+Alt+C` on Windows to open the Claude sidebar. Sign in with your Anthropic account when prompted. **Step 4: Grant workbook access.** Claude asks which workbook to access. Select the file. From this point the conversation panel is live. The add-in works within your existing Microsoft 365 security framework. For enterprise deployments, you can also access it through Amazon Bedrock, Google Cloud's Vertex AI, or Microsoft Foundry rather than directly through a Claude account. ## Claude for Excel vs Microsoft Copilot The obvious comparison. Both are AI tools inside Excel, and if your organisation runs Microsoft 365, Copilot may already be available to you. The difference in practice: Copilot is tightly integrated with the Microsoft ecosystem and works well for generating charts, summarising data in the ribbon, and basic formula help. Claude tends to perform better on complex multi-tab financial models where you need precise, traceable reasoning across dependencies. The cell-level citation format and the "show me the plan before making changes" workflow makes Claude safer to use on models that other people will review. Claude for Excel vs Copilot is not a clear win for either. If you're already paying for Copilot via Microsoft 365, test it on your actual models before switching. If you're already on a Claude plan and working in Excel regularly, the add-in is a no-brainer add-on. ## How to wire Claude for Excel into a finance or ops workflow This is where the tool earns its value beyond one-off queries. The most useful workflow pattern: a monthly reporting model that your team updates manually. Inputs come in from various sources, formulas cascade through the model, and the output is a deck or executive summary. This is painful without AI. With Claude for Excel, the workflow looks like this. After pulling data into the workbook, open the Claude sidebar and ask it to check for data quality issues: missing values, outliers, formatting inconsistencies. Fix those first. Then ask Claude to update the specific assumption cells with the new period's inputs and verify that downstream formulas updated correctly. Finally, ask Claude to refresh the summary tab with commentary on the period-over-period changes, citing the cells that drove any material movements. That workflow, which used to take two to three hours of error-prone manual review, takes 30 to 45 minutes with Claude. The remaining time is yours for analysis and judgment, not for tracing formula errors. If you want to go further, Claude Cowork can handle the data pull step: it can check your email, pull the source file from an attachment, save it to the right folder, and trigger the Excel workflow. That's the bridge from "AI inside a spreadsheet" to "AI running your ops." [CTA-BLUEPRINT] ## Verdict: is Claude for Excel worth it? Yes, for analysts, finance teams, and business owners who live in Excel and are already on a Claude paid plan. The formula debugging alone saves enough time to justify the add-in. The scenario testing and model scaffolding are genuine workflow improvements, not demo features. Who it is not for: free plan users (they cannot access it), Google Sheets users (no add-in exists), or developers who need VBA/Power Query automation (Claude Code is the better tool for that). The honest framing: Claude for Excel is a spreadsheet co-pilot, not an autonomous agent. It asks before it acts, shows you every change, and waits for your approval. That conservative approach is exactly right for financial models, where a silent mistake cascades. It means you stay in control while still cutting the repetitive work. If you're using Claude for Excel and want to extend that same logic to the rest of your business, the natural next step is Claude Code. That's where you build the automation layer that feeds the spreadsheet. The [Claude Code guide](/blog/how-to-use-claude-code) on this site is the place to start. ## Claude for Excel FAQ ### What is Claude for Excel? Claude for Excel is a Microsoft Excel add-in from Anthropic that lets you ask questions about any cell or formula in your workbook, fix errors, test scenarios, and build models from natural language descriptions. It reads your entire workbook structure and shows you proposed changes before writing anything. ### How do I use Claude in Excel? Install the Claude for Excel add-in from Microsoft AppSource, open Excel, and press `Control+Option+C` (Mac) or `Control+Alt+C` (Windows) to open the Claude sidebar. Sign in with a Claude Pro, Max, Team, or Enterprise account. From there you can ask questions about your model, request formula changes, and run scenario tests. ### Is Claude for Excel free? No. Claude for Excel requires a paid Claude plan: Pro ($17/month on annual billing), Max, Team, or Enterprise. The free Claude plan does not include the Excel add-in. ### Does Claude for Excel work with Google Sheets? No. Claude for Excel is a Microsoft Excel add-in only. There is no official Claude add-in for Google Sheets. The closest equivalent is the [Google Drive connector for Claude.ai](https://claude.com/connectors), which lets Claude read your Drive files (including Sheets) inside chat sessions, but it is read-only access from chat, not a live two-way Sheets integration. Sheets-first teams can also use Claude Cowork with browser access to view and edit their workbook in the browser. ### What is the difference between Claude for Excel and Claude Cowork? Claude for Excel is the specific Excel add-in that lives inside Microsoft Excel. Claude Cowork is the broader desktop automation product that can work across multiple apps, including Excel, Word, PowerPoint, Slack, and your browser. The add-in is the focused, spreadsheet-specific entry point. Cowork is the full agentic system. ### Can Claude for Excel fix formula errors? Yes. Claude for Excel traces `#REF!`, `#VALUE!`, and circular reference errors to their source and explains what went wrong and how to fix it. You approve the fix before it writes to the sheet. ### What plans include Claude for Excel? Claude for Excel is available on Pro, Max, Team, and Enterprise plans. It is not available on the free Claude plan. For enterprise deployments, it can also run through Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry. ### What file formats does Claude for Excel support? Claude for Excel currently supports `.xlsx` and `.xlsm` files. File size limits apply based on your Claude plan. It does not currently support `.xls` (older format) or `.csv` files through the add-in, though CSV data can be imported into a supported Excel file first. ## Ready to build AI into your operations? Claude for Excel is a good starting point. The bigger opportunity is building the systems that feed it. If you want to see how to wire Claude into a real business operating system, start with the [free Claude Code Blueprint](/blueprint). It covers the foundation every serious AI operator needs before they start automating. The [30-Day Claude Code Challenge](/challenge) takes you further: from the basics of Claude Code through to building your first production automation. The cohort runs quarterly with Thursday calls. If it's open, join it. ## Frequently Asked Questions ### What is Claude for Excel? Claude for Excel is a Microsoft Excel add-in from Anthropic that lets you ask questions about any cell, formula, or tab in your workbook. It reads the full model including cross-tab dependencies and responds with cell-level citations so you can verify the logic. It has read-write access, so it can make changes, highlight what it changed, and explain why. You install it from Microsoft AppSource. ### Is Claude for Excel free? No. Claude for Excel requires a paid Claude plan. Pro ($17 a month annual, $20 monthly), Max, Team, or Enterprise all work. The free Claude plan does not include the Excel add-in. For enterprise deployments, you can also run it through Amazon Bedrock, Google Cloud Vertex AI, or Microsoft Foundry rather than directly through a Claude account. ### How do I install Claude for Excel? Four steps. Confirm you are on Pro, Max, Team, or Enterprise. Install from the Microsoft AppSource page (the add-in appears in your Excel ribbon). Open Excel and press Control+Option+C on Mac or Control+Alt+C on Windows to open the Claude sidebar. Sign in with your Anthropic account and grant workbook access to the file you want to work on. ### Does Claude for Excel work with Google Sheets? No. Claude for Excel is a Microsoft Excel add-in only. There is no official Claude add-in for Google Sheets. The closest equivalent is the Google Drive connector for Claude.ai, which lets Claude read your Drive files (Sheets, Docs, PDFs) inside chat sessions, but it is read-only access from chat, not a live two-way Sheets integration. Sheets-first teams can use Claude Cowork with browser access instead. ### Claude for Excel vs Microsoft Copilot: which is better? Not a clear win for either. Copilot is tightly integrated with Microsoft 365 and works well for charts, ribbon-level summaries, and basic formula help. Claude tends to perform better on complex multi-tab financial models where you need precise, traceable reasoning across dependencies. The cell-level citations and show-me-the-plan workflow makes Claude safer on models other people will review. If you already pay for Copilot, test it on your actual models first. ### What can Claude for Excel not do? Three honest gaps. It does not connect to live external data feeds, so no live market prices or real-time API connections. It does not write complex VBA macros reliably (use Claude Code in the terminal for serious automation inside Excel). And it is not available for Google Sheets at all. For most analyst and finance work in .xlsx files, the gaps do not matter. For developer-grade automation, they do. ### How much time does it actually save on a real model? On a monthly reporting model that used to take two to three hours of error-prone manual review, the same workflow with Claude for Excel takes 30 to 45 minutes. The remaining time is yours for analysis and judgment, not for tracing #REF! errors across 40 tabs. The biggest single win is formula debugging, where Claude traces #REF!, #VALUE!, and circular reference errors to the source without you scrolling cell by cell. ## Related guides - [What Is Claude Cowork? The AI That Does Your Work For You](/blog/claude-cowork) - [How to Use Claude Cowork (Step-by-Step for Operators)](/blog/how-to-use-claude-cowork) --- # Claude Code GitHub Integration: Actions, MCP, Auto-Review in 2026 Source: https://theaiarchitects.com/blog/claude-code-github Published: 2026-05-20 How to wire Claude Code into GitHub. Three integration paths (Actions, MCP, /review), copy-paste workflow file, and the auto PR review setup. You use Claude Code with GitHub through three integration paths: the official GitHub Actions runner that posts PR reviews on every commit, the GitHub MCP server that lets your local CLI read and write issues and PRs, and the bundled `/review` skill paired with the `claude --from-pr ` flag for one-off audits. I run the AI Architects mentorship and I have all three wired into the same repo. The Actions runner catches obvious bugs before I look at the diff. The MCP server lets me triage issues from the terminal without opening a browser. The `/review` skill is what I reach for when a contributor opens a messy PR and I want a structured second opinion before I merge. Most tutorials cover one of these in isolation and skip the trade-offs. I want to show you the whole picture, because each path has a different cost, a different setup time, and a different failure mode. By the end of this you will know which one to install first for your repo. > [CTA-BLUEPRINT] ## What is the Claude Code GitHub integration? The Claude Code GitHub integration is Anthropic's official set of tools for running Claude inside your GitHub workflow. It ships as three separate pieces: a [GitHub Actions runner](https://code.claude.com/docs/en/github-actions), a GitHub MCP server, and a [code review skill](https://code.claude.com/docs/en/code-review) bundled with the Claude Code CLI. Each piece solves a different problem. Actions handles automation inside CI. The MCP server handles read and write access from your terminal. The review skill handles the actual code analysis prompt. You can install one, two, or all three depending on how much of your workflow you want Claude inside. ## How does Claude Code work with GitHub? Claude Code talks to GitHub in three different ways, and most people only know about the first one. Path one is the GitHub Action: a YAML workflow file in `.github/workflows/` that triggers on pull requests, runs Claude inside a runner, and posts the review as a PR comment. It is the most public-facing of the three and the easiest to demo. Path two is the GitHub MCP server. MCP stands for Model Context Protocol, the spec Anthropic released for giving Claude tool access to external systems. The GitHub MCP server exposes GitHub's REST API to your local Claude Code CLI, which means you can say "list open issues on this repo" or "open a PR with these changes" from inside a terminal session. If you have not set up MCP yet, my [Claude Code MCP](/blog/claude-code-mcp) walkthrough covers the basics. Path three is the `/review` skill plus the `--from-pr` CLI flag. The skill is a structured review prompt that ships with the Claude Code install. The flag lets you pull a PR diff directly into a local session without cloning the branch. Together they give you the same review quality as the GitHub Action, but run on your machine and on demand. ## The three Claude Code + GitHub integration paths ### GitHub Actions: auto PR review on every commit The Action is the integration most people start with because it runs without you doing anything once it is installed. Every time someone pushes a commit to a PR, the workflow triggers, Claude reads the diff, and a review comment appears on the PR within a minute or two. The setup is a single YAML file and one repo secret. The workflow uses Anthropic's official `claude-code-action` and a standard `GITHUB_TOKEN` for posting comments. You drop the file into `.github/workflows/`, add your `ANTHROPIC_API_KEY` as a secret, and the next PR triggers a review automatically. Here is a clean version of the workflow file I use: That is the entire integration. No extra config, no separate GitHub App install for basic usage. ### GitHub MCP server: read issues from your terminal The GitHub MCP server is what I use when I am already in a Claude Code session and I do not want to context-switch to a browser. It exposes GitHub's API as MCP tools, so Claude can list issues, read PR comments, open new issues, and even merge PRs if you give it write scope. The install is a single block in your `.mcp.json` file at the repo root or in `~/.claude.json` for global access. You need a GitHub personal access token with `repo` scope, which goes in the env block. Configuration looks like this: Once that is in place, Claude Code can use natural language for any GitHub action: "show me open issues tagged bug", "open a PR from this branch", "leave a review comment on PR #42 asking about the loop". The first time it feels uncanny because there is no UI in the loop. ### The `/review` skill + `claude --from-pr` flag The third path is the most flexible because it runs entirely locally. The `/review` skill is one of the built-in skills that ships with Claude Code. You invoke it inside a session and it runs a structured audit against the current diff or working tree, checking for bugs, security issues, and style problems. The `--from-pr` flag is what makes it useful for GitHub workflows. Instead of cloning a contributor's branch and checking it out, you run `claude --from-pr https://github.com/owner/repo/pull/42` and Claude pulls the diff straight from the PR URL. Then you fire `/review` and you get a full audit without ever leaving your terminal. I use this path when the Action's automated review is not enough. The Action runs once per push and produces a single comment. The local `/review` lets me iterate, ask follow-up questions, and dig into specific files. The two paths complement each other rather than competing. ## How to set up Claude Code GitHub Actions (step by step) ### Step 1: Get an Anthropic API key Go to console.anthropic.com, sign in, and create a new API key under the API Keys tab. Copy the key once because the console will not show it again. If you already use Claude Code locally with a Claude.ai subscription, you still need an API key for the Action because GitHub runners do not have access to your local session. ### Step 2: Add it as a GitHub repo secret In your repo, go to Settings, then Secrets and variables, then Actions, then New repository secret. Name it `ANTHROPIC_API_KEY` and paste the key. The workflow file references this exact name, so spelling matters. ### Step 3: Drop in the workflow file Create `.github/workflows/claude-review.yml` in your repo. Paste in the YAML block from the section above. Commit it to your default branch. The Action will not run on the commit that adds it, only on subsequent PRs. ### Step 4: Open a test PR Make a small change on a feature branch and open a PR against main. Anything works: a typo fix, a comment update, a renamed variable. Push the branch and open the PR through the GitHub UI or with `gh pr create`. ### Step 5: Confirm the run Go to the Actions tab on your repo. You should see a "Claude PR Review" run in progress. It usually finishes in 60 to 120 seconds. When it completes, refresh the PR page and you will see Claude's review as a new comment with inline annotations on the diff. If the run fails, the most common culprits are a missing or misspelled secret, missing `pull-requests: write` permission, or running on a fork PR without the `pull_request_target` event. The Actions log tells you which one. One extra step I always do on day one: open the PR review comment Claude posts and check whether the tone matches what you want from a teammate. The default prompt is solid, but if your repo has house style rules around commits, types, or test coverage, you can extend the workflow with a `prompt` input that adds those rules. That turns the Action from a generic reviewer into a reviewer that already knows your codebase conventions. ## When to use each integration path The Action is best for automated coverage across every PR. The MCP server is best for human-in-the-loop work where you are already in a terminal session. The `/review` skill with `--from-pr` is best for deep audits on specific PRs where the automated comment is not detailed enough. Most repos I work on use the Action as a default safety net and the local `/review` for anything sensitive. The MCP server is the one I forget about most often, but it pays for itself the first time you triage 20 stale issues without leaving your editor. There is also a cost calculation that matters once you scale. The Action runs on every push, which means a 30-commit PR triggers 30 reviews. That can add up if you are on Sonnet or Opus and the diffs are large. For repos with heavy churn I usually scope the Action to `pull_request: types: [opened, ready_for_review]` so it runs once per PR rather than once per commit, and I lean on `/review` locally for the rest. - **Auto review on every PR** — GitHub Action - **Triage open issues from the terminal** — GitHub MCP server - **Deep audit before merging a sensitive PR** — `/review` + `--from-pr` - **Bulk-close or label issues by query** — GitHub MCP server - **Run review without burning Action minutes** — `/review` + `--from-pr` > [CTA-BLUEPRINT] ## Claude Code GitHub FAQ ### What is the Claude Code GitHub Action? The Claude Code GitHub Action is Anthropic's official workflow that runs Claude inside a GitHub Actions runner. It triggers on pull request events, reads the diff, and posts a structured review as a PR comment. You install it by dropping a YAML file into `.github/workflows/` and adding your Anthropic API key as a repo secret. ### How do I install the Claude Code GitHub MCP server? You install it by adding a `github` entry to your `.mcp.json` file with the `@modelcontextprotocol/server-github` package and a GitHub personal access token in the env block. The token needs `repo` scope for full access. Restart Claude Code and the GitHub tools become available in any session. For background on MCP setup, my [Claude Code MCP](/blog/claude-code-mcp) post covers it end to end. ### Can Claude Code review my pull requests automatically? Yes. The GitHub Action reviews PRs automatically on every push. The workflow triggers on `pull_request` events, runs the `anthropics/claude-code-action`, and posts a review comment within a minute or two. You can also run reviews manually with `claude --from-pr ` and the `/review` skill if you want more control. ### How much does the Claude Code GitHub Action cost? The Action itself is free. You pay for Anthropic API usage and for GitHub Actions minutes. A typical PR review uses between 5,000 and 50,000 input tokens depending on diff size, so cost lands in the cents per review range on Sonnet. Public repos get free Action minutes on GitHub, private repos use your plan's quota. ### Can Claude Code create GitHub issues for me? Yes, through the GitHub MCP server. Once installed, you can ask Claude to open an issue with a title, body, labels, and assignee, and it uses the GitHub API directly. You can do the same with PRs, comments, and labels. If you want to layer it with [Claude Code hooks](/blog/claude-code-hooks), you can have Claude open an issue every time a hook detects a failed build. ## Ready to wire Claude Code into GitHub? Three integration paths, one repo, full coverage. The Action catches issues automatically, the MCP server moves your triage into the terminal, and the `/review` skill plus `--from-pr` handles the deep audits. If you want the full Claude Code build path, including the GitHub setup I run on my own repos, grab the [Blueprint](/blueprint). And if you are still getting Claude Code installed in the first place, start with [how to use Claude Code](/blog/how-to-use-claude-code) and come back here once the CLI is running. ## Frequently Asked Questions ### How does Claude Code work with GitHub? Three ways. The GitHub Action runs Claude inside a CI runner and posts PR reviews on every commit. The GitHub MCP server gives your local CLI read and write access to issues and PRs. The /review skill paired with claude --from-pr handles deep audits on demand. Most people only know about the Action. ### How do I install the Claude Code GitHub Action? Drop a YAML file into .github/workflows/, add ANTHROPIC_API_KEY as a repo secret, and the next PR triggers automatically. The whole workflow is one file using anthropics/claude-code-action@v1 in review mode, with contents: read and pull-requests: write permissions. The next PR you open gets a review comment within 60 to 120 seconds. ### How much does the GitHub Action cost to run? The Action itself is free. You pay for Anthropic API usage and GitHub Actions minutes. A typical PR review uses 5,000 to 50,000 input tokens depending on diff size, which lands in the cents per review range on Sonnet. Public repos get free Action minutes. For heavy churn, scope the Action to types: [opened, ready_for_review] so it runs once per PR instead of once per commit. ### What's the difference between the Action and the /review skill? The Action runs once per push in CI and produces a single review comment automatically. The /review skill runs locally on demand, lets you iterate, ask follow-up questions, and dig into specific files. Use the Action as the default safety net across every PR. Reach for /review locally when the automated comment is not detailed enough. ### Can Claude Code create GitHub issues for me? Yes, through the GitHub MCP server. Once installed, you can ask Claude to open an issue with a title, body, labels, and assignee, and it uses the GitHub API directly. Same for PRs, comments, and labels. Pair it with hooks to have Claude open an issue every time a hook detects a failed build. ### Why is my GitHub Action failing? Three usual culprits: a missing or misspelled ANTHROPIC_API_KEY secret, missing pull-requests: write permission in the workflow, or running on a fork PR without the pull_request_target event. The Actions log tells you which one. Misspelt secrets are the most common, because the workflow file references the name exactly. --- # Claude Chrome Extension: Setup, 8 Use Cases, Privacy Source: https://theaiarchitects.com/blog/claude-chrome-extension Published: 2026-05-20 The Claude Chrome extension gives Claude real browser control. Here's the setup, the 8 use cases that matter, and the privacy trade-off in plain language. The Claude Chrome extension is a browser add-on from Anthropic that lets Claude read the page you're on, fill in forms, click buttons, and take actions across tabs on your behalf. It is not a sidebar chatbot. It gives Claude actual browser control, which is useful and comes with real privacy considerations you should understand before you install it. I'm Tom. I build AI workflows for business owners and have been testing Claude for Chrome since it expanded to Pro and Team plans in December 2025. This post covers the eight use cases that matter most for business owners, the privacy trade-off in plain language, and a side-by-side look at how it compares to the ChatGPT extension and the Cursor browser extension. --- [CTA-BLUEPRINT] --- ## What is the Claude Chrome extension? The Claude Chrome extension is a browser tool that gives Claude the ability to see and interact with what's on your screen. Install it from the Chrome Web Store, authenticate with your Claude account, and Claude can navigate pages, extract data, draft replies in the context of what you're reading, and complete long forms. It works alongside Claude Code for developers who want to build in the terminal and verify results in the browser in the same loop. Anthropic launched it as a pilot to 1,000 Max plan users in August 2025, expanded it to all Max subscribers in November 2025, and opened it to Pro, Team, and Enterprise plans on 18 December 2025. If you're on a paid Claude plan today, you have access. --- ## How does the Claude Chrome extension work? When you install the extension, Claude gains the ability to read the content of pages you explicitly give it access to. You grant access site by site in the extension settings. Claude can then see text, form fields, and DOM structure on those pages, which lets it act on your instructions instead of waiting for you to copy-paste content into the chat. The extension operates in two modes. In standard mode, Claude asks for confirmation before taking high-risk actions like submitting a form, making a purchase, or sharing personal data. In autonomous mode, it can chain actions together without a confirmation prompt, but Anthropic maintains additional safeguards for the most sensitive actions even in that mode. For Claude Code users, the integration is more direct. You can build in the terminal, point Claude at the browser, and have it read console errors and DOM state to help debug, all without leaving the workflow. ### What sites can Claude read? Claude reads only sites you specifically grant access to in the Settings panel. Anthropic automatically blocks certain categories regardless of your settings: financial services sites, adult content sites, and pirated content. Every other site is off by default until you enable it. --- ## The 8 use cases business owners actually get value from This is the section most articles skip over. The Anthropic announcement page lists calendar management and expense reports. Those are fine, but they're not where business owners tend to find the most leverage. Here are the eight cases that have come up repeatedly in the workflows I build. ### 1. Summarise any page without copy-pasting Give Claude access to a site, open an article, a research report, or a competitor's pricing page, and ask for a summary. Claude reads the full page and returns a structured summary without you lifting anything into the chat window. Useful for research sessions where you're moving through 10 or 15 tabs. ### 2. Extract data from your CRM If your CRM runs in the browser (HubSpot, Pipedrive, Attio, most of the modern stack), Claude can pull contact data, deal stage information, and activity history from the page. No API key, no export, no manual copy. You ask, it reads, it compiles. Combine this with a Claude Code workflow and you can push the extracted data directly into a spreadsheet. ### 3. Draft email replies in context Open an email thread. Claude reads the entire conversation and drafts a reply that matches the context without you summarising what happened first. This is the use case that saves the most time per day for most business owners I work with because the setup cost is zero and the payoff is immediate. ### 4. Fact-check claims while you read Grant Claude access to a news site or an industry blog and ask it to cross-reference a specific claim against other sources. Claude navigates to supporting sources, reads them, and reports back on whether the claim holds. This is slower than a human researcher but faster than doing it yourself and more thorough than trusting the original article. ### 5. Convert a screenshot or page into a structured document Ask Claude to read a complex web page, a pricing table, or a long spec document and convert it into a structured format: a table, a bulleted brief, a comparison matrix. The output lands in the Claude chat window, where you can copy it into Docs or pass it to a Claude Code workflow. ### 6. Fill long forms without re-entering the same data If you regularly fill in grant applications, supplier onboarding forms, or government portals with the same business information, Claude can handle the repetitive field completion. You review the completed form before it submits. This is not magic, it is just boring work that Claude is better suited for than you are. ### 7. Run competitive research across multiple tabs Open four competitor sites in separate tabs. Ask Claude to pull their pricing, their positioning headline, their main CTA, and their top-listed features from each. Claude moves through the tabs and compiles everything into a comparison you can use. This used to take 30 to 45 minutes of manual work. ### 8. Research mode across linked pages Give Claude a starting URL and ask it to follow a chain of links and report back on what it finds. Useful for due diligence on a supplier, background research on a potential hire, or mapping a competitor's content strategy without visiting every page yourself. --- ## The privacy trade-off: what actually gets sent to Anthropic This is the part most review posts gloss over and it is the most important section if you handle client data or operate in a regulated space. When Claude reads a page, the content of that page goes to Anthropic's servers to be processed. That is how the AI works. Anthropic processes it the same way it processes any message you send in claude.ai. You are not in a local sandbox. The page content travels over the network. **What this means in practice:** - Do not grant access to banking or financial services sites. Anthropic blocks these categories automatically, but be deliberate about what you enable. - Do not use Claude in Chrome for legal documents, medical records, or anything covered by a confidentiality agreement unless your organisation has an Enterprise plan with the appropriate data processing agreement in place. - For most business owner use cases, reading a competitor's pricing page or drafting a reply to a supplier email, the privacy profile is no different from typing that content into claude.ai yourself. Anthropic published adversarial testing data alongside the launch. Without safety mitigations, malicious actors achieved a 23.6% success rate at prompt injection attacks designed to trick Claude into sharing your data or taking unintended actions. With the current mitigations in place, that number dropped to 11.2%. That is a meaningful improvement, but it is not zero. On browser-specific attack scenarios, mitigations reduced the success rate from 35.7% to 0%. The lesson: use the extension on sites you trust, keep autonomous mode off until you understand what a workflow does, and review actions before they touch anything sensitive. **The on/off toggle:** You control access site by site in the extension settings panel. Revoking access to a site is instant. You can also have your Team or Enterprise admin configure org-wide allowlists and blocklists, which is the right approach if you're rolling this out to a team. --- [CTA-BLUEPRINT] --- ## How to install the Claude Chrome extension ### Step 1: Open the Chrome Web Store Go to the [Claude AI for Chrome listing](https://chromewebstore.google.com/detail/claude-ai-for-chrome/mmpfdbkbpokgghegejphmpmpnjncehip) in the Chrome Web Store. You need a Chromium-based browser: Chrome, Edge, Arc, or Brave all work. ### Step 2: Click "Add to Chrome" Click the Add to Chrome button and confirm the permissions prompt. The extension installs in seconds. ### Step 3: Authenticate with your Claude account Click the extension icon in your browser toolbar and sign in with the same account you use at claude.ai. You need an active paid plan: Pro ($20/mo), Max ($100/mo), Team, or Enterprise. ### Step 4: Grant access to sites In the extension settings, add the sites you want Claude to read. Start with one or two trusted sites. Test a simple task before expanding access further. ### Step 5: Open claude.ai and start a conversation Once you're authenticated and have granted site access, navigate to a page on one of your enabled sites and open a new Claude conversation. Claude will confirm it can see the page and you can start giving it instructions. --- ## Claude Chrome extension vs ChatGPT extension vs Cursor browser extension - ****What it can do**** — Claude for Chrome: Read pages, fill forms, click buttons, multi-tab. ChatGPT (with browser): Web browsing in chat, page summarisation. Cursor browser extension: MCP-based browser control for coding. - ****Primary use case**** — Claude for Chrome: Business workflows, automation, research. ChatGPT (with browser): Research in chat, summarisation. Cursor browser extension: Dev debugging, browser-to-editor loop. - ****Privacy control**** — Claude for Chrome: Site-by-site toggle, org allowlists. ChatGPT (with browser): Per-session browsing. Cursor browser extension: Per-session, dev-focused. - ****Plan required**** — Claude for Chrome: Pro, Max, Team, Enterprise. ChatGPT (with browser): Plus, Pro, Team. Cursor browser extension: Cursor Pro. - ****Claude Code integration**** — Claude for Chrome: Native. ChatGPT (with browser): No. Cursor browser extension: Native. - ****Autonomous mode**** — Claude for Chrome: Yes, with safeguards. ChatGPT (with browser): No. Cursor browser extension: No. The honest answer is that if you are a business owner using Claude for day-to-day work, the Claude extension is the right choice. If you are a developer, the Cursor integration may serve you better because it is built around the coding workflow. The ChatGPT extension works well for simple research tasks but does not offer the same level of browser control. --- ## Where the Claude Chrome extension falls short The extension is in active development and there are real limitations to know about before you build workflows around it. It does not work on every site. Some sites block automated browser access or use structures that Claude cannot read reliably. Dynamic single-page applications built on React or Vue sometimes behave unpredictably. Autonomous mode requires trust in Claude's judgment about what constitutes a "safe" action. Anthropic's definition of high-risk is sensible but not comprehensive. You should review any autonomous workflow before running it unattended. The extension is not available on Firefox or Safari at launch. If your team uses a mix of browsers, that creates an inconsistent experience. Finally, it requires an active Claude subscription. There is no free tier access to the browser extension. --- ## Is the Claude Chrome extension free? The Claude Chrome extension itself is free to download from the Chrome Web Store. Using it requires an active paid Claude subscription. The entry-level access is the Pro plan at $20 a month. Team and Enterprise plans add admin controls, org-wide configuration, and data processing agreements for regulated industries. There is no free trial of the browser extension separate from a Claude subscription. --- ## Verdict: is the Claude Chrome extension worth it? Yes, if you are already on a paid Claude plan and you do repetitive browser-based work. The email reply drafting alone justifies the time to install and configure it. The competitive research and CRM extraction use cases add compounding value as you build familiarity with what Claude can do in context. It is not worth the additional mental overhead if you are using Claude only occasionally or if your work is primarily document-based rather than browser-based. The privacy considerations are also worth taking seriously before you grant access to sites that contain client data. For developers already using Claude Code, the browser integration closes a workflow loop that previously required manual copy-paste between the terminal and the browser. That alone is worth the upgrade to Pro if you are not already on it. Read my [complete Claude Code guide](/blog/how-to-use-claude-code) for the broader picture of how Claude Code and the browser extension fit together. If you work with data in spreadsheets, the [Claude for Excel post](/blog/claude-for-excel) covers a different but complementary workflow. --- [CTA-BLUEPRINT] --- ## Claude Chrome extension FAQ ### What is the Claude Chrome extension? The Claude Chrome extension is a browser add-on that gives Claude the ability to read web pages, fill in forms, click buttons, and take actions across multiple tabs. It connects your browser activity to your Claude conversations so Claude can act on context without you manually copying content into the chat. ### How do I install the Claude Chrome extension? Go to the Chrome Web Store, search for "Claude AI for Chrome," and click Add to Chrome. You authenticate with your Claude account after installation. Access requires an active paid Claude plan: Pro, Max, Team, or Enterprise. ### Is the Claude Chrome extension free? The extension is free to download. Using it requires a paid Claude subscription starting at $20 a month for the Pro plan. There is no free-tier access to browser control features. ### Is the Claude Chrome extension safe? It is safe to use on trusted, non-sensitive sites with the default settings. Anthropic blocks access to financial services and other high-risk categories automatically. Adversarial testing found that safety mitigations reduce prompt injection attack success rates from 23.6% to 11.2%. Do not use it on pages containing confidential client data, medical records, or financial accounts unless you are on an Enterprise plan with appropriate data agreements. ### Which plans support the Claude Chrome extension? Pro ($20/mo), Max ($100/mo), Team, and Enterprise plans all support the extension as of December 2025. Free accounts do not have access. Team and Enterprise admins can configure org-wide allowlists and blocklists. ### Does the Claude Chrome extension work on Firefox or Safari? No. The extension is currently Chrome-only, with support for Chromium-based browsers including Edge, Arc, and Brave. Firefox and Safari are not supported at launch. ### How does Claude Chrome extension compare to the ChatGPT extension? The Claude extension offers deeper browser control, including form filling, multi-tab workflows, and autonomous mode. The ChatGPT extension is primarily built around in-chat web browsing and summarisation. For business workflow automation, Claude for Chrome provides more capability. For simple research tasks in chat, either works. ### Can I control which sites Claude can see? Yes. You grant and revoke access site by site in the extension settings. Claude cannot read any site you have not explicitly enabled. Team and Enterprise admins can also enforce org-wide site allowlists and blocklists. --- ## Ready to build faster with AI? The Claude Chrome extension is one piece of a broader AI workflow stack. If you want to see how business owners are putting Claude, Claude Code, and browser automation together into systems that save 10 to 20 hours a week, the Blueprint is where to start. [Get the Claude Code Blueprint](/blueprint) ## Frequently Asked Questions ### What is the Claude Chrome extension? The Claude Chrome extension is a browser add-on from Anthropic that gives Claude the ability to read web pages, fill in forms, click buttons, and take actions across multiple tabs. It connects your browser activity to your Claude conversations so Claude can act on context without you copying anything into the chat. Anthropic opened it to Pro, Team, and Enterprise plans on 18 December 2025. ### Is the Claude Chrome extension free? The extension is free to download from the Chrome Web Store. Using it requires an active paid Claude subscription, starting at Pro ($20 a month). Max ($100), Team, and Enterprise plans also work. There is no free-tier access to the browser control features and no trial separate from the Claude subscription itself. ### Is the Claude Chrome extension safe to use on client data? It is safe on trusted, non-sensitive sites with the default settings. Anthropic blocks financial services, adult content, and pirated sites automatically. But page content goes to Anthropic's servers to be processed, the same way any Claude message does. Adversarial testing showed safety mitigations cut prompt injection success from 23.6% to 11.2%. Do not enable it on legal documents, medical records, or anything under a confidentiality agreement unless you are on Enterprise with the right data processing agreement. ### Which sites can Claude actually read? Only sites you specifically grant access to in the extension settings panel. Every site is off by default. Anthropic automatically blocks financial services, adult content, and pirated content categories regardless of your settings. You can revoke access to any site instantly. Team and Enterprise admins can configure org-wide allowlists and blocklists for the whole company. ### Does the Claude Chrome extension work on Firefox or Safari? No. It is Chrome-only at launch, with support for Chromium-based browsers including Edge, Arc, and Brave. Firefox and Safari are not supported. If your team uses a mix of browsers, that creates an inconsistent experience and is worth knowing before you roll it out. ### How does the Claude Chrome extension compare to the ChatGPT extension? The Claude extension offers deeper browser control: form filling, multi-tab workflows, and an autonomous mode with safeguards. The ChatGPT extension is built around in-chat web browsing and page summarisation. For business workflow automation, Claude for Chrome provides more capability. For simple research tasks in chat, either works. The Cursor browser extension is a different category aimed at developers debugging through the browser. ### What is the single best use case for the extension? Drafting email replies in context. Open a thread, Claude reads the whole conversation, and you get a reply that matches the context without summarising what happened first. The setup cost is zero and the payoff is immediate. After that, competitive research across multiple tabs (pulling pricing, positioning, and CTAs from four competitors at once) is the use case that saves the most time per week. ## Related guides - [How to Install the Claude Chrome Extension](/blog/how-to-install-claude-chrome-extension) - [Claude Chrome Extension Permissions: What It Can See](/blog/claude-chrome-extension-permissions) - [Claude vs ChatGPT Chrome Extension: Which Wins?](/blog/claude-vs-chatgpt-chrome-extension) --- # Claude Code Slash Commands: What They Do and How They Work in 2026 Source: https://theaiarchitects.com/blog/claude-code-commands Published: 2026-05-20 Claude Code slash commands turn repeat prompts into one keystroke. Here's how they work, the 9 I run, and the quiet merge into skills. A Claude Code slash command is a saved prompt you trigger with `/name` inside the terminal, instead of retyping the same instruction every session. I'm Tom. I run 9 custom slash commands in my own Claude Code setup, on top of the bundled ones Anthropic ships. They run my Reddit marketing loop, capture bugs, sync sessions to Obsidian, and load context from a year of prior work. If you want the foundation before this post makes sense, start with my [60-minute beginner guide](/blog/how-to-use-claude-code) and come back. > [CTA-BLUEPRINT] ## What is a Claude Code slash command? A slash command is a markdown file Claude Code reads as a reusable prompt. You type `/track-bug "auth flow returns 401"` and Claude executes the instructions inside `track-bug.md` against your current project, with the argument injected where you tell it to land. Think of it as a saved prompt with variables. The same idea as a snippet in your text editor, except the snippet is interpreted by a coding agent that can read your files, run shell commands, and edit code based on what the prompt tells it to do. ## How do Claude Code slash commands work? Every slash command is a `.md` file in a `.claude/commands/` folder. The filename becomes the command name. `track-bug.md` becomes `/track-bug`. Drop the file in, restart Claude Code, and the command is live. The top of the file is optional YAML frontmatter. You can set a `description` (shown in the `/help` menu), an `allowed-tools` allowlist, and a `model` override. Below the frontmatter, the body is the actual prompt. Plain English instructions for what Claude should do. The clever part is dynamic context injection. You can run shell commands inline with backticks and Claude will execute them before the prompt is sent. So a line like `` Current branch: `git branch --show-current` `` gets resolved to the live branch name. Same trick with `$ARGUMENTS` for the user's input. That's why slash commands feel less like text macros and more like tiny programs. See [Anthropic's official commands doc](https://code.claude.com/docs/en/commands) for the full spec. ## The built-in Claude Code commands you should know These ship with Claude Code. No setup required. This is the Claude Code commands cheat sheet I'd hand a new hire on day one. ### 1. /init Generates a `CLAUDE.md` at the project root by scanning your codebase. It's the first command I run on any new repo. It catalogues your tech stack, scripts, and conventions so future Claude sessions have a memory of the project. ### 2. /help Lists every available command in the current scope, built-in and custom. When something stops working after a [Claude Code update](/blog/claude-code-update), `/help` is the fastest way to see what's still registered. ### 3. /clear Wipes the current conversation context. Use it when you're switching tasks mid-session and don't want the previous thread polluting the next one. Cheaper than starting a fresh terminal session. ### 4. /compact Summarises the current conversation in place, keeping the key decisions and dropping the noise. I run this around the 70% context mark on long sessions. It buys back roughly 40% of the window without losing the thread. ### 5. /cost Shows token usage and dollar spend for the current session. Useful for sanity-checking whether a long Opus run actually justified the bill, or for catching a runaway loop before it bleeds through your monthly allowance. ### 6. /memory Opens your project and user memory files for editing. This is where the persistent instructions live. The Claude Code memory command is how you change Claude's behaviour without retyping rules in every prompt. ### 7. /plan Forces Claude into plan mode for the next request. It drafts a step-by-step plan and waits for your approval before touching code. I use it for anything multi-file or irreversible. ### 8. /review Runs a code review on the current branch's diff against main. The Claude Code review command is genuinely useful for catching dumb mistakes before a PR goes out, especially when you've been heads-down for two hours. ### 9. /security-review Same idea as `/review`, but tuned for security concerns. Looks at auth flows, input validation, secrets handling, and obvious injection vectors. Not a replacement for a real audit. Good as a first pass. ### 10. /loop Runs a prompt or another slash command on a recurring interval. `/loop 5m /check-deploy` keeps polling every 5 minutes. This is how I run my hourly Reddit monitoring agent. ### 11. /ultrareview A heavier review pass that pulls in plan mode and multiple verification steps. Slower and more expensive than `/review`. Worth it before a deploy you can't easily roll back. ## How to create your own custom slash command Building a custom command takes about 30 seconds the first time. Once you've done it, you'll wonder why you ever retyped the same prompt twice. ### 1. Create the commands folder In your project root, run `mkdir -p .claude/commands`. This is the project-scoped Claude Code commands folder. Anything inside it is available when you run Claude Code from that repo. ### 2. Write the markdown file Create `.claude/commands/my-command.md`. The filename becomes the command name. Keep names short and kebab-cased. `/track-bug` not `/TrackBugInTheCurrentProject`. ### 3. Add frontmatter (optional but recommended) At the top of the file, add a YAML block: The description is what other people on your team will see when they run `/help`. Treat it like a function docstring. ### 4. Write the prompt body Below the frontmatter, write the actual instruction. Use `$ARGUMENTS` where you want the user's input to land. Use backtick-wrapped shell commands for live context. Example: ### 5. Choose your scope Three options. Project scope (`.claude/commands/` in the repo) ships with the codebase. User scope (`~/.claude/commands/`) is available in every project you open. Local scope (`.claude/commands.local/` or gitignored files) is for personal commands you don't want committed. I keep `/recall` and `/sync-claude-sessions` at user scope and `/reddit-loop` at project scope. ### 6. Test it Restart Claude Code so it picks up the new file. Run `/help` and confirm your command appears. Then run it with a test argument and watch what Claude does. If the prompt is ambiguous, the run will be ambiguous. Iterate the markdown like you'd iterate a regular prompt. ## 5 custom slash commands worth stealing These are real commands I run. Steal the patterns and rewrite the bodies for your own workflow. ### /track-bug Captures a bug report into a project-local `BUGS.md` with current branch, recent commits, and a one-line reproduction. Argument is the bug description. Saves me from context-switching to a separate issue tracker for the small stuff. ### /track-idea Same shape as `/track-bug`, but writes to `IDEAS.md`. I run this any time something feels like a future product or content angle. Two months later I have a running log instead of forty Apple Notes. ### /recall Loads context from my Obsidian vault by date. `/recall yesterday` pulls the previous day's session log into context so I can resume without re-explaining what I was doing. The killer feature for multi-day projects. ### /sync-claude-sessions Exports the current Claude Code session into a markdown file inside my `Claude-Sessions/` Obsidian folder. Pairs with `/recall`. One command to save, one to load. That's my entire memory system. ### /reddit-loop Runs my hourly Reddit marketing agent. Fetches new r/ClaudeAI posts, runs each through my answer skill, and sends me a Slack notification when something's worth replying to. Triggered by `/loop 1h /reddit-loop` so it runs unattended. ## The quiet merge into skills Here's the part nobody flagged. Anthropic's October 2025 update (v2.1.118+) merged several bundled slash commands into the new [Claude Code skills](/blog/claude-code-skills) system. The commands you used to run as `/foo` now live as skills in `.claude/skills/foo/SKILL.md`. The behaviour is the same. The plumbing isn't. Check the [CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) for the exact version bumps. Skills are richer than commands. A skill can bundle code, reference files, and progressive disclosure (load extra context only when triggered) rather than being one flat markdown file. That's why Anthropic moved the heavier built-ins over. The [skills doc](https://code.claude.com/docs/en/skills) explains the model. The TL;DR: a skill is what a command grows into when it needs more than a single prompt. Practical impact. If you wrote a custom slash command before October 2025 that depended on a built-in command (calling it from inside another command), some of those calls now route through the skills system instead. If your old command stopped working, the fix is usually a one-line update or a rewrite as a skill. Commands ran fast. Skills run smart. Both still exist, and you can mix them in the same project. > [CTA-BLUEPRINT] ## Claude Code commands FAQ ### Where are Claude Code commands stored? Project commands live in `.claude/commands/` inside the repo. User-scope commands live in `~/.claude/commands/` and are available in every project. Local commands (personal, not committed) go in a gitignored folder or use the `.local` suffix. That's the entire Claude Code commands folder hierarchy. ### How do slash commands differ from skills? A slash command is a single markdown file with a prompt. A skill is a directory that can include the prompt plus code, reference docs, and helper files, with progressive disclosure built in. Commands are best for short, repeatable tasks. Skills are best when the workflow needs more than one file or pulls in optional context. The Claude Code commands vs skills decision is mostly about complexity. ### Can I share a slash command across projects? Yes. Put it in `~/.claude/commands/` (user scope) and it's available everywhere. If you want it scoped to one repo, leave it in `.claude/commands/` and commit it. You can also publish a command as part of a plugin or share the markdown file directly with a teammate. ### Why did my old slash command stop working? Two common causes. First, an Anthropic update after October 2025 moved some built-ins into the skills system, so commands that called those built-ins broke. Second, the frontmatter spec changed once during the v2 rollout, and old `allowed-tools` syntax silently fails on newer versions. Run `/help` to confirm the command is still registered and check the [CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) for breaking changes. ### Can a slash command call another slash command? Yes, with caveats. You can reference another command in the prompt body and Claude will follow the instruction to invoke it. Behaviour is more reliable when both commands live in the same scope. Calling a user-scope command from inside a project-scope command works, but the reverse is fragile. ### What's the difference between commands, skills, hooks, and subagents? Commands are reusable prompts. Skills are richer reusable workflows with their own files. [Hooks](/blog/claude-code-hooks) run automatically on events (before a tool call, after a message). [Subagents](/blog/claude-code-subagents-vs-skills) are separate Claude instances dispatched from the main session for parallel or specialised work. Different layers of the same stack. ## Ready to build your own Claude Code commands? If you've made it this far, you already know what to do. Pick three prompts you retype every week. Convert them into slash commands tonight. You'll save more time in the next month than this post took to read. For the full system, the one I use to run my mentorship, my content, and my code reviews, check out the [Blueprint](/blueprint). It walks through commands, skills, hooks, and subagents as one connected workflow, with the exact files I run on my own machine. ## Frequently Asked Questions ### What is a Claude Code slash command? A slash command is a markdown file Claude Code reads as a reusable prompt. You type /track-bug "auth flow returns 401" and Claude executes the instructions inside track-bug.md against your current project, with your input injected where you tell it to land. Think of it as a saved prompt with variables, interpreted by an agent that can read files, run commands, and edit code. ### How do I create a custom Claude Code slash command? Create .claude/commands/ in your repo, drop in a markdown file named after your command (track-bug.md becomes /track-bug), add optional YAML frontmatter for description and allowed-tools, then write the prompt body using $ARGUMENTS for user input. Restart Claude Code and the command is live. Takes about 30 seconds the first time. ### Where are Claude Code commands stored? Three scopes. Project commands live in .claude/commands/ inside the repo and ship with the codebase. User-scope commands live in ~/.claude/commands/ and are available in every project you open. Local commands (personal, not committed) go in a gitignored folder or use the .local suffix. I keep /recall at user scope and /reddit-loop at project scope. ### How do slash commands differ from skills? A slash command is a single markdown file with a prompt. A skill is a directory that bundles the prompt plus code, reference docs, and helper files with progressive disclosure. Commands are best for short, repeatable tasks. Skills are best when the workflow needs more than one file or pulls in optional context on demand. Both still exist and you can mix them. ### What are the built-in commands worth knowing? Eleven worth memorising: /init generates a CLAUDE.md, /help lists everything, /clear wipes context, /compact summarises to buy back ~40% of the window, /cost shows token spend, /memory edits your CLAUDE.md, /plan forces plan mode, /review audits the diff, /security-review hunts for auth and injection issues, /loop runs prompts on a recurring interval, and /ultrareview is the heavier pre-deploy pass. ### Why did my old slash command stop working? Two common causes. An Anthropic update after October 2025 moved several built-ins into the new skills system, so commands that called those built-ins broke. Second, the frontmatter spec changed once during the v2 rollout, and old allowed-tools syntax silently fails on newer versions. Run /help to confirm registration and check the CHANGELOG for breaking changes. --- # Markdown vs HTML for Claude Code: When to Use Which (and Why Anthropic Just Switched) Source: https://theaiarchitects.com/blog/markdown-vs-html-claude-code Published: 2026-05-20 On May 9, Thariq from the Claude Code team published a piece arguing HTML beats markdown for plans, audits, reports, and reviews. 10.9M views in 48 hours. Here is the head-to-head: where HTML wins, where markdown still wins, the gotchas, and 5 prompts to test it on real work. On May 9, 2026, Thariq ([@trq212](https://x.com/trq212)) from the Claude Code team at Anthropic published a short piece called _"Using Claude Code: The Unreasonable Effectiveness of HTML"_. 48 hours later it had 10.9M views. The argument is one line. Stop telling Claude Code to write markdown. Tell it to write HTML. That is not a small swap. Markdown has been the default agent output for every shipped LLM product since GPT-3.5. Specs, plans, reviews, audits, code reviews, customer reports, all of it pours out the same way. Headers. Bullets. Tables that break above 30 rows. You scroll. You ctrl-F. You forget where you were. Thariq is from the team that builds Claude Code. He is now switching default output to HTML for the work he ships internally. That matters more than another influencer take. I have spent the last week running both formats side by side on real client work. Audits, plans, dashboards, reviews. Here is the head-to-head, the gotchas, and 5 prompts you can paste into Claude Code today to test it on your own pipeline. [CTA-BLUEPRINT] ## TL;DR - **HTML wins** for anything you send to a human. Audits, reports, plans, pricing models, dashboards, deliverables. - **Markdown still wins** for chained agents, git repos, short outputs, and anything inside the engineering loop. - **Generation cost** is 2 to 4x more for HTML. Token cost is 4 to 8x. Budget for it. - **The format is a lever, not a religion.** Default per-artifact, not per-agent. ## Head-to-head - **Readability over 100 lines** — Markdown: Wall of text. Scroll-only.. HTML: Sticky sidebar, collapsible sections, table of contents.. - **Shareability** — Markdown: Paste into Gmail and pray.. HTML: One URL. Opens in any browser. Mobile-friendly out of the box.. - **Interactivity** — Markdown: Read-only.. HTML: Sliders, toggles, copy-as-prompt buttons, edit-in-place fields.. - **Generation time** — Markdown: 30s for a 1,000-word doc.. HTML: 90 to 120s for the same content.. - **Token cost (input later)** — Markdown: ~250 tokens per 1,000 words.. HTML: ~1,500 tokens per 1,000 words.. - **Version control** — Markdown: Clean diffs. Reviewable in PRs.. HTML: Attribute-noise diffs. Unreadable in git.. - **Chained-agent handoff** — Markdown: Parses cleanly into the next agent.. HTML: Carries layout the next agent has to strip.. - **Client perception** — Markdown: Looks like a transcript.. HTML: Looks like a deliverable.. - **Best use** — Markdown: Engineering plumbing, drafts, short replies.. HTML: Anything you would otherwise paste into a Google Doc.. The honest read of the table: HTML is better at being a finished thing. Markdown is better at being a working thing. ## Where HTML actually wins Five places I have seen the format swap change the output quality, not just the look. Each comes with a prompt you can paste straight into Claude Code today. ### 1. Audits and reviews A markdown audit reads like a checklist. An HTML audit reads like a deliverable. Same content. The client pays for the second one without question. They quibble on the first one. ### 2. Plans with sub-tasks A 14-step plan in markdown is a wall. The same plan in HTML can have collapsible phases, a progress bar at the top, and a copy-as-prompt button on every sub-task. The plan stops being a document and starts being a tool. ### 3. Competitor research 8 competitors. 12 attributes each. In markdown that is a table that breaks on mobile and is unreadable after the third column. In HTML it is a sortable filterable grid. ### 4. Financial and pricing models A revenue forecast in markdown is a guess. The same forecast in HTML with input sliders is a model. The client moves the slider and watches year-end revenue change. That is the difference between sending a report and sending decision support. ### 5. Weekly dashboards from MCP data A markdown weekly report is stale the day it is generated. An HTML dashboard that pulls from MCPs when you open it is live. Run one of these on a real piece of work this week. Compare the artifact to the markdown version you would have produced. The first one feels slow. The second one does not. For 30 more examples, Thariq published an open repo of HTML artifacts at [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/). The source is on GitHub at [github.com/thariqs/html-effectiveness](https://github.com/thariqs/html-effectiveness). Worth bookmarking. ## Where markdown still wins This is the part Thariq's piece soft-pedals. Markdown is not dead. It is the right default for a specific kind of work. **Chained agent workflows.** When the output of one agent is the input to another, you want clean structured text. Markdown parses. HTML carries layout the next agent has to throw away. A planning agent that hands a task list to an execution agent should hand markdown bullets. **Anything inside a git repo.** Thariq calls this out. HTML diffs are a wall of attribute changes that hide the substance. If the artifact lives in a repo and gets edited weekly, markdown is what lets you actually review what changed. The fix when you want both: keep markdown as source of truth, generate HTML on demand, gitignore the rendered output. **Short outputs.** A 20-line answer to "what is the syntax for X" does not need a styled HTML page. The format should match the use of the artifact, not the ambition of the prompt. **Inline notes and drafts.** When you are still figuring out what you think, markdown gets out of the way. HTML invites you to style your way out of doing the actual work. ## The gotchas Three things to budget for before you swap your defaults. **Generation time.** A markdown plan that takes 30 seconds takes 90 to 120 seconds in HTML. On long sessions this stacks. If your loop depends on fast turns, stay in markdown for the loop and convert at the end. **Token cost.** A 1,000-word doc costs ~250 input tokens in markdown. In HTML it costs ~1,500. I optimised my OpenClaw bill from $600 a month to $25 last quarter. One of the levers was capping output. Defaulting every output to HTML reverses that work for the wrong reasons. **Diff noise.** Keep a markdown source. Render HTML on demand. Gitignore the output. None of these kill the argument. They just stop you defaulting blindly. ## The decision rule After a week of running both on the same pipeline: **Markdown** for short outputs, chained agents, anything in a git repo, anything you will iterate on weekly, anything inside the engineering loop. **HTML** for anything you send to another human, anything over 100 lines, anything with comparisons or sliders or dashboards, anything you would otherwise paste into a Google Doc. That rule covers about 80% of the calls. The other 20% is judgment. ## How to start in one line The simplest test is one prompt change. Take the next plan or audit you would normally ask Claude Code to write in markdown. Append this to the prompt: Run it once on real work. Compare the artifact. The second one is the deliverable. ## Format is a lever. Pick the one that ships. Thariq's piece is the highest-signal Claude Code post of May. It moved 10.9M views in 48 hours because it touched something every Claude Code user has been quietly frustrated by. Markdown was never the right output for half the work we use it for. The real lesson is not "switch to HTML." The real lesson is that format is a lever. Most people pick the default and never touch it. Architects pick the format that fits the use of the artifact and ship the right thing for the audience on the other end. If you are running Claude Code on real client work and you have never written a custom output prompt, that is the gap. Close it this week. If you want a structured way to do that, the Claude Code Blueprint walks through 60 minutes of guided builds inside Claude Code, including the output-format prompts I use on every client deliverable. Free. ## Markdown vs HTML for Claude Code FAQ ### Should I always switch from Markdown to HTML in Claude Code? No. Format is a lever, not a default. Use HTML for finished deliverables a human will read. Use Markdown for short outputs, drafts, chained-agent handoffs, and anything that lives inside a git repo. ### Does HTML cost more tokens than Markdown in Claude Code? Yes. A 1,000-word doc costs around 250 input tokens in Markdown and around 1,500 in HTML — roughly 4 to 8x more. Generation time is 2 to 4x longer. Budget for it if you are running long sessions or chained agents. ### When is Markdown still the right output for Claude Code? For chained agent handoffs (clean parsing), inline drafts, short answers under 20 lines, and anything that lives in a git repo where diffs matter. Markdown's whole job is to get out of the way while you work. ### How do I tell Claude Code to output HTML? Append a single prompt instruction: "Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies." Add specific structural requirements (badges, sliders, sortable tables) per artifact. ### What is the unreasonable effectiveness of HTML in Claude Code? The phrase is from Thariq at Anthropic's Claude Code team. The thesis: Markdown is fine for the loop, but the final artifact a human reads (audit, plan, dashboard, deliverable) is meaningfully better as HTML because the model can ship layout, interactivity, and styling in one self-contained file. ### Does this apply to other AI tools or just Claude Code? The format-as-output argument applies to any model that can output structured text and HTML — GPT-5.5, Gemini 3, Claude. The reason this lands inside Claude Code specifically is that the artifact is local: you can save the file, open it in a browser, and ship it. Web chat interfaces add friction the local CLI doesn't have. ### Should the Claude Code Skill or Plugin handle this automatically? Yes. The cleanest pattern is a Skill that takes any Markdown source file and emits a styled HTML deliverable. See the Claude Code Skills guide for how to wrap a recurring output transform into a one-shot trigger. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Best Claude Code skills worth stealing](/blog/best-claude-code-skills) - [Claude Code commands and slash commands](/blog/claude-code-commands) - [How to use Claude Code: 60-minute beginner guide](/blog/how-to-use-claude-code) ## Sources and official documentation Primary sources referenced in this guide: - [Thariq's HTML effectiveness examples](https://thariqs.github.io/html-effectiveness/) - [HTML effectiveness source on GitHub](https://github.com/thariqs/html-effectiveness) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) [CTA-CHALLENGE] Build something. I will be there for the parts that break. --- _Originally referenced: [Thariq's open repo of HTML examples](https://thariqs.github.io/html-effectiveness/) and the [GitHub source](https://github.com/thariqs/html-effectiveness). [@trq212 on X](https://x.com/trq212). Published May 9, 2026. 10.9M views as of May 12._ ## Frequently Asked Questions ### Should I switch from markdown to HTML in Claude Code? Not by default. Format is a lever, not a religion. Use HTML for finished deliverables a human will read: audits, plans, dashboards, pricing models. Use markdown for short outputs, drafts, chained-agent handoffs, and anything that lives in a git repo. The decision rule covers about 80% of the calls. The other 20% is judgment. ### Does HTML cost more tokens than markdown? Yes, significantly. A 1,000-word doc costs around 250 input tokens in markdown and around 1,500 in HTML, roughly 4 to 8x more. Generation time is 2 to 4x longer (90 to 120 seconds vs 30 seconds for the same content). I optimised my OpenClaw bill from $600 a month to $25 last quarter by capping output. Defaulting to HTML reverses that work for the wrong reasons. ### When is markdown still the right output? Chained agent handoffs where the output of one agent feeds another. Anything inside a git repo where diffs matter (HTML diffs are walls of attribute noise). Short answers under 20 lines. Inline notes and drafts where you are still figuring out what you think. Markdown's whole job is to get out of the way while you work. ### How do I tell Claude Code to output HTML? Append one prompt instruction: "Output as a single self-contained HTML file with inline CSS. Sticky sidebar nav, collapsible sections, print-friendly. No external dependencies." Add specific requirements per artifact (severity badges, sortable tables, input sliders). Run it once on real work and compare the artifact to the markdown version you would have produced. ### What's the unreasonable effectiveness of HTML thesis? Thariq from the Claude Code team at Anthropic published a piece on May 9, 2026 arguing HTML beats markdown for finished deliverables. 10.9M views in 48 hours. The thesis: markdown is fine for the loop, but the final artifact a human reads (audit, plan, dashboard) is meaningfully better as HTML because the model can ship layout, interactivity, and styling in one self-contained file. ### Where does HTML actually win in practice? Five places I have seen the format swap change output quality, not just look. Client audits with severity badges and an executive summary. Plans with collapsible phases and copy-as-prompt buttons. Competitor research as sortable, filterable grids. Pricing models with input sliders the client actually moves. Weekly dashboards that pull live data from MCP servers when you open the file. ### How should I handle HTML in a git repo? Keep markdown as the source of truth, generate HTML on demand, gitignore the rendered output. HTML diffs hide substance behind attribute noise. This pattern gives you both clean reviewable diffs in PRs and a styled deliverable when you need to send the file to a human. --- # The Ralph Wiggum Loop and /goal in Claude Code (2026) Source: https://theaiarchitects.com/blog/claude-code-ralph-loop Published: 2026-05-20 The Ralph Wiggum loop is the AI coding pattern where the agent keeps building until a verifiable condition is met. Claude Code's /goal command is the official version. Here's how to use it. The Ralph Wiggum loop is the AI coding pattern where an agent works on a task in a loop, checking after each turn whether a verifiable completion condition is met, and only stopping when it is. Claude Code's `/goal` command and Codex's `goal` subcommand are the official implementations. Same pattern, two names, two CLIs. I'm Tom. Claude Code runs my entire business and it is the thing I teach, every day, with more conviction than anything else I do. I've been using `/goal` to ship internal tools while I sleep, and this post is the playbook. Small disambiguation up front: yes, the pattern is named after the Simpsons character. > [CTA-BLUEPRINT] ## What is the Ralph Wiggum loop? The Ralph Wiggum loop is a development pattern where you set a measurable end condition, hand it to an AI coding agent, and let the agent loop on the task. After each turn, the agent checks whether the condition has been met. If yes, it stops. If no, it keeps going. The name is a community joke. Ralph Wiggum is the Simpsons character whose contributions to a scene are usually a single repeated line. The pattern carries the same energy: one condition, one job, infinite turns until done. The dev community started using "ralph loop" and "ralph wiggum loop" interchangeably in late 2025. Search volume for both terms went from roughly 10 a month in November 2025 to over 12,000 a month by March 2026. That is what happens when a community names a pattern and the pattern actually works. ## What is /goal in Claude Code? `/goal` is the Claude Code command that runs the Ralph Wiggum loop natively. You type `/goal` followed by a completion condition, up to 4,000 characters. Claude Code sets the condition, starts working, and a small fast model checks after every turn whether the condition holds. If it does not, Claude takes another turn. If it does, the goal clears automatically and control returns to you. The same feature exists in Codex CLI as the `goal` subcommand. The behaviour is functionally identical. Anthropic shipped `/goal` in Claude Code shortly after OpenAI shipped it in Codex. Both reference the same underlying pattern. The Claude Code docs at [code.claude.com/docs/en/goal](https://code.claude.com/docs/en/goal) cover the official command spec. Codex's version is at the OpenAI Codex docs. ## How does the Ralph Wiggum loop work? The mechanism has four parts: 1. **You set a completion condition.** A sentence or paragraph that describes the verifiable end state. Up to 4,000 characters. 1. **Claude Code starts working.** Reads files, makes edits, runs tools, calls subagents. 1. **A fast checker model runs after every turn.** It evaluates whether the condition is satisfied. The checker is a small model so the cost overhead is tiny. 1. **The loop continues until the checker says done.** No prompting between turns. No babysitting. If the condition is never met, the loop runs until you stop it or hit a usage limit. The whole point is that the agent decides what each turn does. You only set the destination. This is a significant shift from the old prompt-and-edit-and-prompt-again rhythm. If you have used the [plan mode](/blog/claude-code-plan-mode) workflow before, `/goal` is the next step up. Plan mode produces a plan you execute manually. `/goal` produces a plan and executes it for you. ## What is the difference between ralph loop, ralph wiggum loop, and /goal? Three names for variations of the same idea, with one important distinction: - **Ralph loop** is the older community term, used since early 2025. It originally referred to a hand-rolled bash script or hook that re-invoked Claude Code repeatedly until a target file showed a "DONE" marker. - **Ralph Wiggum loop** is the same pattern with the Simpsons reference attached. Dev Twitter started swapping the names around late 2025. They mean the same thing. - **`/goal`** is the official Anthropic implementation of the pattern, built into Claude Code as a first-class command. Same behaviour, no shell script required. If you read someone tweeting about a ralph loop or a ralph wiggum loop in 2026, they almost certainly mean `/goal`. ## How to write a strong /goal condition Four ingredients separate a goal that works from a goal that runs forever: ### 1. A measurable end state The condition has to be verifiable by the checker model. "Build a good app" is not measurable. "All 62 tasks in product-roadmap.md are checked off and the test suite passes" is. I run my goals with a checklist file in the repo. The condition is always some version of: "every item in CHECKLIST.md is marked complete and the tests pass." The agent and the checker can both look at the file. ### 2. Scope Tell `/goal` what is in and what is out. If you say "build the auth flow", the agent might also rewrite three unrelated files. Add scope: "edit only files under src/auth and src/middleware. Do not touch the marketing pages." ### 3. Constraints Anything that must not change on the way to done. "Do not modify package.json. Do not change the database schema. Do not edit existing tests." Constraints are how you stop the agent from getting clever. ### 4. Validation method How the agent should verify each step. Tests? A specific bash command? A file existence check? Be specific. "Run `npm test` after each task and only mark complete when it passes" beats "verify the work." I keep a small template for this. Slug it as four lines at the top of every goal: end state, scope, constraints, validation. Saves time and stops me from writing vague goals. ## The setup that makes /goal actually work `/goal` is only as strong as the context you feed it. The setup I run for any non-trivial build: 1. **A `CLAUDE.md` at the project root.** Project context, conventions, the four Karpathy rules for code agents. The [Claude Code memory](/blog/claude-code-memory) post covers what goes in here. 1. **A `docs/PRD.md` file.** Product spec. What we are building, who it is for, the user flows. 1-2 pages. 1. **A `docs/product-roadmap.md` file.** A flat list of tasks broken down into phases, with checkboxes. Phases like "Phase 1: scaffolding", "Phase 2: data model", "Phase 3: auth". 40-80 tasks total for a full app. 1. **A `docs/design.md` file.** Design tokens, colour palette, font, component patterns. Use this so the agent does not pick generic AI-slop styling. With those four files in place, the goal becomes a one-liner: "Build the app described in docs/PRD.md by completing every task in docs/product-roadmap.md, using docs/design.md for visual direction. Stop when all checkboxes are marked and the test suite passes." That goal sends Claude Code into a 30-90 minute build with no further input from you. ## How /goal pairs with auto mode `/goal` on its own still asks for permission on tool calls. If you want a fully hands-off build, pair it with auto mode (`claude --auto` or the `/auto` toggle in-session). Auto mode grants extended permissions so the agent does not stop to ask before running bash commands, editing files, or calling MCP tools. In a `/goal` loop, that means the agent runs end-to-end without intervention. This is genuinely powerful. It is also a foot-gun. Pair it with the [--dangerously-skip-permissions](/blog/claude-code-dangerously-skip-permissions) defaults only inside a sandboxed environment. A throwaway Docker container. A fresh repo. Not your production directory. I run `/goal` plus auto mode plus a fresh git branch. Anything the agent breaks, I throw away the branch and start over. ## What I built with /goal The first thing I shipped with `/goal` was an experimental project in the local hosting space. Something I'd been wanting to prototype for a while but kept putting off because the setup cost felt too high to justify before I knew the idea was viable. `/goal` was the test of whether I could get from concept to a working prototype in one sitting. Setup took about 40 minutes: - PRD: one page covering what the tool needs to do and the local-first constraint. - Product roadmap: roughly 30 tasks across three phases. Scaffolding, the core feature, then local persistence. - design.md: brief notes on the layout. Nothing fancy. - CLAUDE.md: project context, plus a note that nothing leaves localhost. I dropped the goal in and let it run. Claude Code finished the build in about 30 minutes. All tasks complete, the prototype booting locally, the core feature working end to end. I stepped away to do something else while it ran. The build was further along when I got back than I expected. The watch-it-build experience is genuinely strange the first time. > [CTA-BLUEPRINT] ## Common /goal mistakes Three patterns kill goals more than anything else: 1. **Vague end conditions.** "Build the feature" is not a goal. "All tests pass and the new endpoint returns 200 on a sample request" is. If the checker model cannot tell whether you are done, the loop runs until your weekly cap kicks in. 1. **No scope.** The agent will touch files you did not expect. Always specify which directory the work lives in. 1. **No constraints.** Without explicit "do not change X" rules, the agent will sometimes rewrite shared utilities, change a database migration that already shipped, or refactor a config file out from under you. Constraints stop this. A fourth one worth flagging separately: running `/goal` without a roadmap. A goal of "build the app" with no task list is asking the agent to invent its own plan and then verify its own work. The results vary. With a roadmap, the checker has something concrete to verify against. Without one, the checker is guessing. ## /goal vs plan mode vs subagents - **`/plan`** — generates a plan, you execute it manually. Use for one-shot tasks where you want control. - **`/goal`** — generates a plan AND executes it in a loop. Use for multi-task builds with a clear end state. - **Subagents** — splits work across parallel sessions. Use for independent tasks that can run concurrently. - **`/goal` + subagents** — the agent dispatches subagents during the loop. Use for large multi-phase builds. - **`/goal` + auto mode** — full autonomy, no permission prompts. Use only inside a sandboxed environment. `/goal` is the right tool when you have a measurable end state and want the agent to keep working without you. Plan mode is the right tool when you want to see the plan first. Subagents are the right tool when work can be parallelised. They compose. The [subagents vs skills](/blog/claude-code-subagents-vs-skills) post covers when subagents are the right call. ## Where /goal falls short Two things `/goal` does not solve: - **Open-ended creative tasks.** "Write something interesting about Claude Code" has no measurable end state. The checker has nothing to verify. The loop will either run forever or exit on the first turn. Use plan mode for creative work. - **Tasks that touch external systems with no fallback.** If your goal requires hitting a live Stripe webhook or a third-party API that might be down, the agent will mark steps complete that have not actually verified end to end. Bake fallback assertions into your validation method. For everything else, the pattern is the cleanest single feature shipped to Claude Code in 2026. ## Ralph Wiggum loop FAQ ### What is the Ralph Wiggum loop? The Ralph Wiggum loop is a development pattern where an AI coding agent loops on a task until a verifiable completion condition is met. The pattern is named after the Simpsons character. Claude Code's `/goal` command and Codex's `goal` subcommand are the official implementations. ### Is the Ralph Wiggum loop the same as the ralph loop? Yes. They are two names for the same pattern. "Ralph loop" was the original term, used for hand-rolled implementations in early 2025. "Ralph Wiggum loop" is the same pattern with the Simpsons reference attached. The community uses them interchangeably in 2026. ### How do I use /goal in Claude Code? Type `/goal` followed by a completion condition up to 4,000 characters. Claude Code will work in a loop, checking after each turn whether the condition is met. The goal clears automatically when done. Pair with auto mode for fully hands-off runs. ### How long can /goal run for? In practice, 15 minutes to several hours. The longest published `/goal` build I have seen took roughly 90 minutes to ship a full 62-task app. The hard ceiling is your weekly usage cap. Long `/goal` runs burn through usage fast, so check the [Claude Code rate limits](/blog/claude-code-rate-limits) post before running overnight. ### Can I use /goal without auto mode? Yes. Without auto mode, Claude Code will stop and ask for permission on tool calls that need approval. The loop continues after you approve. This is the safer default for production-adjacent work. ### Is /goal available in Codex? Yes. Codex shipped the `goal` subcommand first. Claude Code's `/goal` is functionally identical. Same pattern, different CLI. The behaviour and best practices are the same. ### Does /goal work with subagents? Yes. A `/goal` run can dispatch subagents during the loop, then continue once they return. This is useful for the parallel-task phases of a longer build. ### What is the difference between /goal and a Ralph loop bash script? `/goal` is a built-in command with a managed checker model and a clean exit condition. A Ralph loop bash script is a hand-rolled wrapper that re-invokes Claude Code in a shell loop with a custom check. Same idea, but `/goal` is more reliable, more efficient, and does not require maintaining the script. ## Ready to try /goal? The fastest way to feel the difference is to set up a PRD plus roadmap plus design.md on a small project, drop in a `/goal` condition, and watch it run. The Blueprint walks through the full Claude Code workflow including the spec-driven pattern that makes `/goal` actually work. Free, 60 minutes, no coding required. ## Frequently Asked Questions ### What is the Ralph Wiggum loop in Claude Code? The Ralph Wiggum loop is a coding pattern where you give an AI agent a verifiable completion condition and let it work in a loop until that condition is met. Claude Code's /goal command is the official implementation. You set the destination, the agent decides every turn, and a small checker model runs after each turn to ask one question: are we done yet? ### How do I use /goal in Claude Code? Type /goal followed by a completion condition up to 4,000 characters. Claude Code starts working, a fast checker model evaluates after every turn whether the condition holds, and the goal clears automatically when it does. Pair it with auto mode for fully hands-off runs and a fresh git branch so you can throw away anything that goes sideways. ### What makes a strong /goal condition? Four ingredients: a measurable end state, a defined scope, explicit constraints, and a validation method. "Build a good app" runs forever because the checker has nothing to verify. "Every item in CHECKLIST.md is marked complete and the test suite passes" is something the checker can actually evaluate. Keep the four lines at the top of every goal. ### How long can a /goal run last? In practice, 15 minutes to several hours. The longest published build I have seen took roughly 90 minutes to ship a 62-task app. The hard ceiling is your weekly usage cap, so /goal burns through usage fast on long runs. Check the rate limits before pointing it at an overnight build. ### Is /goal the same as the ralph loop bash script? Same pattern, different implementation. The original ralph loop was a hand-rolled bash wrapper that re-invoked Claude Code in a shell loop with a custom check. /goal is the built-in command with a managed checker model and a clean exit condition. Same idea, more reliable, no script to maintain. ### Where does /goal fall short? Two places. Open-ended creative tasks ("write something interesting about Claude Code") have no measurable end state, so the loop either runs forever or exits on turn one. Tasks that touch external systems with no fallback can mark steps complete that have not actually verified end to end. Bake fallback assertions into your validation method for anything that hits a live API. ### What setup do I need before running /goal on a real build? Four files at minimum: CLAUDE.md for project context, docs/PRD.md for the spec, docs/product-roadmap.md as a checkbox list of tasks broken into phases, and docs/design.md so the agent does not pick generic AI-slop styling. With those in place, the goal becomes a one-liner pointing at the roadmap, and the agent runs for 30 to 90 minutes with no further input. --- # Claude vs Gemini for Real Work in 2026 Source: https://theaiarchitects.com/blog/claude-vs-gemini Published: 2026-05-20 Claude vs Gemini tested on 6 real workloads: code review, email, spreadsheets, research, agent building, and long-doc QA. Honest results and a clear verdict. --- Claude and Gemini are the two most capable AI assistants you can put to work today, and choosing between them based on benchmarks will steer you wrong. Benchmarks measure what a model knows on a controlled test. Real work measures what a model actually delivers inside the tools you use every day. I tested both across six real workloads, scored them on output quality, speed, cost, and workflow fit, and the results were not the lopsided win most comparison posts pretend to find. I'm Tom. I run an AI mentorship business, I build automations in Claude Code daily, and I have used both Claude and Gemini on live projects over the past six months. This comparison covers the six workloads I actually ran: code review, email drafting, spreadsheet analysis, research synthesis, agent building, and long-document QA. I will tell you honestly where Gemini wins, where Claude wins, and when to pick which. --- [CTA-BLUEPRINT] --- ## What is Claude? Claude is a family of large language models built by Anthropic, a safety-focused AI company founded in 2021. The current flagship is **Claude Opus 4.7**, released in 2026, which sits at $5 per million input tokens and $25 per million output tokens via the API. Below it sits **Claude Sonnet 4.6** ($3 in / $15 out), the best speed-to-intelligence ratio in the lineup, and **Claude Haiku 4.5** ($1 in / $5 out) for high-volume, latency-sensitive tasks. All three current models share a 1M token context window (Opus and Sonnet) or 200k (Haiku), support image input, and are available on Claude Pro ($20/mo), Claude Max ($100–$200/mo), or direct API. The Claude Code CLI runs on top of these models and adds file editing, terminal commands, MCP integrations, and agent orchestration — which is where the comparison with Gemini gets interesting for builders. Anthropic's positioning is built around safety and reliability rather than raw multimodal breadth. You will not find native video generation or music synthesis in the Claude lineup. What you get is a model that writes carefully, follows complex instructions consistently, and rarely hallucinates on long documents. ## What is Gemini? Gemini is Google DeepMind's model family. The current generation spans **Gemini 3.1 Pro** ($2–$4 per million input tokens, $12–$18 output depending on context length), **Gemini 2.5 Pro** ($1.25–$2.50 in / $10–$15 out), and **Gemini 2.5 Flash** ($0.30 in / $2.50 out) for speed-focused workloads. Most models have a free tier, which is one of Gemini's strongest practical advantages for individual users. Gemini's differentiators are native multimodality (image, video, audio input and output from the same model), deep Google Workspace integration, and the 1M token context window on Gemini 2.5 Pro and Flash. Veo 3 handles video generation. Imagen 4 handles image generation. Lyria 3 handles music. If your workflow touches Google's ecosystem — Docs, Sheets, Drive, Gmail, YouTube — Gemini has architectural advantages that no other model can match. Google positions Gemini as intelligence woven into the products you already use. Anthropic positions Claude as the model you trust for high-stakes output. Both frames are accurate. ## The six workloads I tested I ran both models through six tasks that represent real business use, not synthetic benchmarks. ### Workload 1: Code review I gave each model a 400-line Python script with three deliberate bugs: a silent type coercion, an off-by-one in a date range loop, and an uncaught exception path. I asked for a complete review with specific line references. **Claude** caught all three bugs. The explanations were precise and referenced the exact lines. It also flagged two non-bugs that were worth discussing: a mutable default argument and a style inconsistency in the error handling. The output was structured, easy to act on, and did not pad with generalities. **Gemini 2.5 Pro** caught two of the three bugs. It missed the off-by-one in the date loop, which was the subtlest of the three. The review was well written and clear, but I had to prompt a second pass before it found the third issue. **Winner for code review: Claude**, by a clear margin on the hardest bugs. ### Workload 2: Email drafting I gave each model the same brief: write a follow-up email to a potential mentorship student who had filled in an application form but not booked a call. Tone: direct, warm, not pushy. Length: under 150 words. **Gemini** produced a cleaner first draft. It respected the word limit, hit the tone, and avoided the sycophantic opener that Claude default-produces. The subject line options were sharper. **Claude** produced a longer draft (around 210 words) and needed a trim pass. When prompted again with the word limit reinforced, the second draft was excellent, but it required that second step. **Winner for email drafting: Gemini**, on first-attempt compliance with constraints. ### Workload 3: Spreadsheet analysis I uploaded a 200-row Airtable export as CSV (revenue data, client names, dates, plan types) and asked for a summary: top three revenue months, average revenue per client, and any anomalies. **Claude** handled this cleanly. The calculations were correct. It spotted one anomaly (a single client appearing twice under different names) and called it out unprompted. **Gemini 2.5 Flash** also handled it cleanly and was noticeably faster. It did not catch the duplicate client anomaly without prompting. **Winner for spreadsheet analysis: Claude** on accuracy; **Gemini** on speed. If you are doing exploratory analysis and anomaly detection matters, Claude. If you want fast summaries at volume, Gemini Flash is hard to beat. ### Workload 4: Research synthesis I gave each model five articles on the same topic (AI agent frameworks in 2026) and asked for a 600-word synthesis that identified the main points of agreement, the open debates, and a recommendation. Both models performed well here. **Gemini** leaned on the Google-adjacent sources more confidently and produced a slightly more current-feeling synthesis because of its training data access and native search integration. **Claude** produced a synthesis that was better organized and had cleaner sourcing: it attributed specific claims to specific articles rather than blending them into a general voice. **Winner for research synthesis: draw**, with a slight lean toward Claude on citation clarity and Gemini on recency. ### Workload 5: Agent building This is where the gap widens. I built a simple lead-capture automation in each ecosystem: a webhook that receives a form submission, enriches it with a contact lookup, and writes a formatted summary to a Notion database. **Claude Code** with MCP servers (Notion MCP, webhook handler) had this running in about 40 minutes. Plan mode planned the architecture, the agent wrote and debugged the code, and the MCP integrations handled the Notion writes without extra scaffolding. The workflow was clean. **Gemini** via Google AI Studio and the Gemini API required more manual wiring. The ecosystem does not have a Claude Code equivalent as of mid-2026. Google's agent tooling is capable, but it is spread across Vertex AI, Agent Builder, and Google Cloud Functions in a way that adds friction compared to the tightly integrated Claude Code stack. If you are building inside Google Cloud and already know Vertex, Gemini is the right call. If you are starting fresh, Claude Code is faster to a working result. **Winner for agent building: Claude Code**, by a meaningful margin for builders starting outside the Google ecosystem. ### Workload 6: Long-document QA I uploaded a 90-page PDF (a SaaS contract with complex renewal clauses) and asked each model to find the auto-renewal trigger date, the notice period for cancellation, and any caps on annual price increases. **Claude Opus 4.7** (1M context, Jan 2026 knowledge cutoff) found all three correctly and quoted the exact clause text. No hallucinations, all page references accurate. **Gemini 2.5 Pro** (1M context) found two of the three correctly. It missed the price cap clause, which was in a rider rather than the main body. When I pointed to the rider section, it found it immediately. **Winner for long-document QA: Claude**, on first-pass completeness for dense documents. --- ## Where Gemini genuinely wins Gemini is not a consolation prize. There are three areas where it has a structural advantage that Claude cannot easily match. ### Google Workspace integration If your business runs on Google Docs, Sheets, Drive, and Gmail, Gemini is woven into those surfaces in a way Claude is not. Gemini can read your Drive files, summarize your Gmail threads, and write back to Sheets from inside the same interface. Claude requires MCP tools or custom integrations to reach those same surfaces. For Google-first teams, that integration gap is real. ### Generous free tier Gemini 2.5 Flash is free to use up to the API rate limits. Gemini 2.5 Pro has a free tier. Claude's free tier (claude.ai) is capped and does not include API access. If you are an individual builder running low-stakes tasks and you want to keep costs at zero, Gemini is the clear choice. Claude Pro starts at $20 a month and the API is pay-as-you-go from the first token. ### Native image and video generation Imagen 4 and Veo 3 are part of the same Google AI ecosystem as Gemini. If you need text-to-image or text-to-video alongside language tasks, Gemini lets you stay in one platform. Anthropic does not offer image or video generation. Claude handles image input (reading and describing images) but not image output. --- ## Claude vs Gemini API pricing At the API level, the comparison for the most-used models looks like this: - **Claude Sonnet 4.6**: $3 / $15 per million tokens (in/out) - **Gemini 2.5 Pro**: $1.25 / $10 per million tokens (under 200k context), $2.50 / $15 over 200k - **Claude Haiku 4.5**: $1 / $5 per million tokens - **Gemini 2.5 Flash**: $0.30 / $2.50 per million tokens For budget API usage, Gemini Flash is cheaper than any Claude model at equivalent capability. For mid-range work, Gemini 2.5 Pro and Claude Sonnet 4.6 are competitive. At the frontier tier (Opus 4.7 at $5/$25 vs Gemini 3.1 Pro at $2/$12), Gemini 3.1 Pro is cheaper — but the capability comparison at that tier is genuinely contested. The Claude API includes prompt caching, which reduces costs by up to 90% on repeated context. If you are running agent loops that re-read the same system prompt and files on each turn, Claude's caching makes the effective cost lower than the headline rates suggest. --- ## Is Claude better than Gemini? Claude is better for writing-intensive work that requires following complex multi-step instructions, for long-document QA on dense or technical documents, for code review where catching subtle bugs matters, and for any workflow built on Claude Code's agent stack. Gemini is better for Google Workspace integration, for image and video generation, for high-volume low-cost API tasks, and for users who need a capable free tier. The honest answer most comparison posts avoid: these models are not interchangeable, and the gap between them depends entirely on the workload. For four of my six tests, Claude produced better first-pass output. For two (email drafting and spreadsheet speed), Gemini was equal or better. That is a closer race than the fanboy threads on either side suggest. --- ## Should I use Claude or Gemini for coding? For coding tasks, Claude has a consistent edge on code review and debugging. For agent building, Claude Code is the more complete platform. Gemini is a capable coding assistant, and Gemini 2.5 Pro scores competitively on coding benchmarks. In practice, the difference shows up most on complex multi-file refactors and subtle bug catching, where Claude's instruction-following consistency gives it an advantage. If you are building inside Google Cloud (Cloud Functions, BigQuery, Firebase), Gemini's training data and integration familiarity give it a real edge. Outside the Google ecosystem, Claude Code is the better builder's tool. ## Should I use Claude or Gemini for writing? For writing, Claude's output is more consistent with instructions on tone, length, and format. Gemini produces sharp first drafts but requires more steering on constraints. Both are capable of excellent writing output. The difference is mostly in how much prompting you need to get there. Claude tends to get there in one pass on precise briefs. Gemini sometimes needs two. --- [CTA-BLUEPRINT] --- ## Gemini 2.5 vs Claude 4: how the current generations compare The generational comparison that most people are actually searching for: Gemini 2.5 Pro versus the Claude 4 family. **Gemini 2.5 Pro** offers: 1M context, multimodal input and output, strong reasoning scores on standard benchmarks, $1.25/$10 pricing, free tier access, deep Google integration. **Claude Opus 4.7** offers: 1M context, 1M-token output capacity on batch, adaptive thinking for complex reasoning, $5/$25 pricing, no free API tier, top-tier performance on instruction following and long-document tasks. **Claude Sonnet 4.6** is the more direct comparison at $3/$15. Sonnet 4.6 includes extended thinking, faster latency than Opus, and a context window that handles almost any document you throw at it. The 2025-2026 benchmark races between these two have been genuinely contested. Both models sit at or near the top on most measures. The practical differences come down to ecosystem fit and the six workload categories above, not benchmark percentages. --- ## Verdict: use both, but here is when to pick which Pick **Claude** when: - You are doing serious code review or debugging - You are working with long, dense documents (contracts, research papers, technical specs) - You are building automations with Claude Code and MCP - Instruction-following on precise briefs matters - You are doing writing where getting it right in one pass saves you time Pick **Gemini** when: - Your work lives in Google Workspace - You need native image or video generation - You want a capable free tier for individual or low-budget use - You are building inside Google Cloud - You are doing high-volume API work and want the lowest per-token cost Pick **both** if you can. I use Claude Code as my primary build tool, Gemini for Google Workspace tasks where the integration removes friction, and neither has displaced the other. The developers worth watching are the ones who treat these as complementary tools rather than as a binary choice. If you want to get serious about Claude Code as your primary build environment, the next stop is the guide below. --- ## Claude vs Gemini FAQ ### Is Claude better than Gemini? Claude is better than Gemini for long-document QA, complex code review, and instruction-following on precise writing briefs. Gemini is better for Google Workspace integration, native image and video generation, and high-volume API tasks where cost per token matters. Neither model is universally better — the right answer depends on the workload. ### Which is better for coding, Claude or Gemini? Claude edges ahead for code review and debugging on complex multi-file work, and Claude Code is a more complete agent platform for building automations. Gemini 2.5 Pro is a capable coding model and has an advantage on tasks that touch Google Cloud services. For general coding assistance, both are excellent. For agent building outside Google Cloud, Claude Code is the stronger choice. ### Which is better for writing, Claude or Gemini? Claude produces more consistent first-draft output on precise writing briefs because it follows length and tone constraints reliably. Gemini writes sharp drafts but sometimes needs a second pass to respect word limits or tonal constraints. For most writing tasks the quality ceiling is similar; the difference is in how much prompting you need to reach it. ### What is the Claude vs Gemini API pricing comparison? Claude Sonnet 4.6 costs $3 per million input tokens and $15 per million output tokens. Gemini 2.5 Pro costs $1.25/$10 (under 200k context) and $2.50/$15 (over 200k). For budget API work, Gemini 2.5 Flash at $0.30/$2.50 is cheaper than any Claude model. Claude's prompt caching can reduce effective costs by up to 90% on repeated context, which changes the math for agent loops. ### Is Gemini free to use? Yes. Gemini 2.5 Flash and 2.5 Pro both have free API tiers with rate limits. Gemini in Google Workspace is available through Google One AI Premium plans. Claude's free tier at claude.ai exists but API access is paid from the first token. For zero-cost AI experimentation, Gemini is the more accessible entry point. ### Can I use Claude and Gemini together? Yes. Many builders use Claude Code for coding and automation work, Gemini for Google Workspace tasks, and switch based on the job. They are not mutually exclusive, and the per-token costs are low enough that using both for different tasks is practical. Most workflow tools (n8n, Make, Zapier) support both model providers in the same automation. ### What is Gemini 2.5 vs Claude 4? Gemini 2.5 Pro and Claude 4 (Opus 4.7 and Sonnet 4.6) are the competing frontier-tier models from Google and Anthropic as of mid-2026. Both offer 1M token context windows, strong reasoning, and multimodal input. The key differences: Gemini 2.5 Pro is cheaper at the API level and includes native Google integration, Claude Opus 4.7 leads on long-document accuracy and instruction following, and Claude Code has a more complete agent-building platform than Google's equivalent tooling. --- ## Ready to build with Claude Code? If this comparison pointed you toward Claude for your serious work, the fastest way in is the free Claude Code Blueprint. 60 minutes, no coding required, and you walk out with a working setup and a first build under your belt. The blueprint covers installation, your first CLAUDE.md, your first MCP server, and how to get a real task shipped on day one. The 30-Day Claude Code Challenge goes further: four live calls, a real build per week, and a deployed agent by the end of the month. ## Frequently Asked Questions ### Is Claude better than Gemini? Claude is better for long-document QA, complex code review, and instruction-following on precise writing briefs. Gemini is better for Google Workspace integration, native image and video generation, and high-volume API tasks where cost per token matters. Neither is universally better. Across six real workloads I tested (code review, email, spreadsheets, research, agent building, long-doc QA), Claude won four. Gemini won or tied on two. ### Which is better for coding, Claude or Gemini? Claude edges ahead for code review and debugging on complex multi-file work. In my test, Claude caught all three deliberate bugs in a 400-line Python script (including a subtle off-by-one), while Gemini 2.5 Pro caught two and needed a second prompt for the third. For agent building outside Google Cloud, Claude Code is the stronger platform. Inside Google Cloud (Cloud Functions, BigQuery, Firebase), Gemini has the home-court advantage. ### What is the Claude vs Gemini API pricing comparison? Claude Sonnet 4.6 costs $3 per million input tokens and $15 per million output. Gemini 2.5 Pro costs $1.25/$10 under 200k context and $2.50/$15 over 200k. At the budget tier, Gemini 2.5 Flash at $0.30/$2.50 is cheaper than any Claude model. Claude's prompt caching reduces effective costs by up to 90% on repeated context, which changes the math for agent loops that re-read the same system prompt every turn. ### Is Gemini free to use? Yes. Gemini 2.5 Flash and 2.5 Pro both have free API tiers with rate limits. Gemini in Google Workspace is available through Google One AI Premium. Claude's free tier at claude.ai exists but API access is paid from the first token. For zero-cost AI experimentation, Gemini is the more accessible entry point. Once you are doing serious work, both move into paid plans. ### Can I use Claude and Gemini together? Yes, and most serious operators do. I use Claude Code as my primary build tool, Gemini for Google Workspace tasks where the integration removes friction, and neither has displaced the other. Most workflow tools (n8n, Make, Zapier) support both providers in the same automation. The developers worth watching treat these as complementary tools, not a binary choice. ### Which model wins for writing? Gemini produced a cleaner first draft on my email test, respected the 150-word limit, and avoided Claude's default sycophantic opener. Claude produced a 210-word draft that needed a trim pass. The quality ceiling is similar. The difference is how much prompting you need to reach it. Claude tends to get there in one pass on precise briefs. Gemini sometimes needs two. ### Should I pick Claude or Gemini for long-document work? Claude, by a clear margin on first-pass completeness. I uploaded a 90-page SaaS contract with complex renewal clauses and asked both models to find the auto-renewal trigger, the notice period, and any price-increase cap. Claude Opus 4.7 found all three with exact quotes. Gemini 2.5 Pro found two of three and missed the price cap in a rider until I pointed at the rider section directly. ## Related guides - [Claude Code vs Copilot vs Codex: Three Tools, Three Jobs](/blog/claude-code-vs-copilot) - [Claude Code vs Cursor: An Honest Comparison](/blog/claude-code-vs-cursor) - [The Best Vibe Coding Tools in 2026: Tested and Ranked](/blog/best-vibe-coding-tools) --- # Claude 4 models (Opus, Sonnet, Haiku): which for which job Source: https://theaiarchitects.com/blog/claude-4-models Published: 2026-05-20 Opus 4.7, Sonnet 4.6, Haiku 4.5: three models, three jobs. The pricing crossover points, version numbering explained, and the default setup I use in Claude Code daily. Claude 4 is Anthropic's current model family, covering three distinct tiers: Opus 4.7 for maximum reasoning power, Sonnet 4.6 for the daily driver balance of speed and intelligence, and Haiku 4.5 for the fastest and cheapest production workloads. Most people spend ten minutes on the Anthropic pricing page, pick one, and then quietly swap back and forth wondering if they made the right call. This post is the decision framework I use inside Claude Code every day, with the actual API strings, the pricing crossover points, and the one version-numbering quirk that trips up almost everyone. I'm Tom. I run Claude Code on Opus 4.7 for hard architecture decisions and default to Sonnet 4.6 for everything else. I have tested Haiku 4.5 in batch pipelines where cost per token actually matters. The model you pick for a given job is not about preference. It is about throughput, cost, and whether the task actually needs 1M tokens of context window or not. --- [CTA-BLUEPRINT] --- ## What is Claude 4? Claude 4 is Anthropic's fourth generation of large language models, released starting May 2025. The family includes Opus 4, Sonnet 4, and Haiku 4 at the top level, but within each tier Anthropic has shipped incremental versions. As of mid-2026, the three models in active production use are: - Opus 4.7 (API: `claude-opus-4-7`) — most capable, 1M context window, moderate latency - Sonnet 4.6 (API: `claude-sonnet-4-6`) — best speed-to-intelligence ratio, 1M context window, fast latency - Haiku 4.5 (API: `claude-haiku-4-5-20251001`) — fastest, 200k context window, cheapest tier All three support text and image input, text output, multilingual use, and vision. Claude 4 models are available via the Claude API, Amazon Bedrock, Google Cloud Vertex AI, and Microsoft Foundry. ## How does Claude 4 versioning work? The version numbers are the single biggest point of confusion in the Claude ecosystem, so let me work through it clearly. The "4" refers to the generation. Opus, Sonnet, and Haiku are size tiers within that generation, roughly analogous to large, medium, and small. The decimal after the tier number (the ".7" in Opus 4.7, the ".6" in Sonnet 4.6, the ".5" in Haiku 4.5) indicates the iteration count within that tier, not the overall generation ranking. Opus 4.7 does not mean Opus is version 7 of something. It means Anthropic has shipped seven iterations of the Opus 4 tier. This matters because Sonnet 4.6 came out after Opus 4.5. The version numbers are not synchronized across tiers. You cannot infer recency or capability from the iteration number alone. Always check the official models page. Starting with the 4.6 generation, Anthropic moved to dateless model IDs. `claude-sonnet-4-6` is a pinned snapshot, not an evergreen pointer. Every Claude model ID points to a fixed release. ### What is Claude Sonnet 4.6? Claude Sonnet 4.6 is Anthropic's current mid-tier model, combining fast latency with near-frontier intelligence. It is the default model inside Claude Code for most paid plans. API pricing is $3 per million input tokens and $15 per million output tokens. Context window is 1M tokens. It supports adaptive thinking and priority tier routing. ### What is Claude Opus 4.7? Claude Opus 4.7 is Anthropic's most capable generally available model as of mid-2026. The official description is "a step-change improvement in agentic coding over Claude Opus 4.6." API pricing is $5 per million input tokens and $25 per million output tokens. Context window is 1M tokens, using a new tokenizer. Max output is 128k tokens. Reliable knowledge cutoff is January 2026. ### What is Claude Haiku 4.5? Claude Haiku 4.5 is the fastest and cheapest model in the Claude 4 family. It is designed for high-volume, cost-sensitive workloads where latency and price per token matter more than maximum reasoning depth. API pricing is $1 per million input tokens and $5 per million output tokens. Context window is 200k tokens. Reliable knowledge cutoff is February 2025. ## The three jobs: what each model is actually for The way I think about it is three distinct jobs, matched to three models. Not best, better, good. Three different tools for three different kinds of work. ### Haiku 4.5: production batch and cost-sensitive pipelines Haiku 4.5 is the model you reach for when you are running something at scale and every token costs real money. Think classification pipelines, routing logic in multi-agent workflows, quick summarisation of large document sets, or any automation that fires hundreds of times a day. At $1 per million input tokens, Haiku 4.5 is five times cheaper than Sonnet 4.6 and five times cheaper again than Opus 4.7. For batch work that does not need deep reasoning, routing a task through Haiku first and escalating to Sonnet only when confidence is low is a real cost optimisation, not just a theoretical one. I have seen this pattern knock 70-80% off API spend on pipelines that were naively using Sonnet for everything. The tradeoff is the 200k context window (versus 1M on Opus and Sonnet) and the older knowledge cutoff. For most batch jobs this is not a constraint. For anything that needs to hold a long conversation or reason across a massive codebase, it is. ### Sonnet 4.6: the daily driver Sonnet 4.6 is the model I use by default for everything. Code review, first drafts of complex scripts, multi-file refactors that fit inside a reasonable context window, explaining a codebase to a new team member, summarising a research paper. It is fast enough to feel like a conversation. It is capable enough to handle most tasks on the first pass. The price is $3 per million input tokens and $15 per million output. Inside a Claude Code subscription (Pro or Max), this is what you are spending your weekly cap on by default. The 1M context window means you can drop an entire project directory in without hitting limits, and the August 2025 reliable knowledge cutoff means it knows about most of the tools released in the last year. Sonnet 4.6 also supports extended thinking, which lets it reason step-by-step through hard problems before responding. This narrows the gap with Opus 4.7 on structured reasoning tasks without the Opus price. ### Opus 4.7: hard thinking and 1M context Opus 4.7 is the model you reach for when the task is genuinely hard. Multi-file architecture decisions. Debugging a problem where you have already looped twice and the model keeps getting it wrong. Anything involving a 1M context window where you are asking it to reason across a very large codebase or document set. Irreversible production work where an error costs real time to undo. The pricing of $5 per million input tokens and $25 per million output is roughly five times Sonnet per token on a subscription basis. Inside Claude Code, this is why the CLAUDE.md model defaults in my setup say: "Default to Sonnet 4.6. Opus 4.7 is the escalation tier." The question is not whether Opus is better. It is whether the task is hard enough to justify the cost. Opus 4.7 has a step-change improvement in agentic coding according to Anthropic's own comparison against Opus 4.6. If you are running long multi-step agent loops, Opus 4.7 is the right model. It sustains performance across hours of task execution in a way smaller models do not. ## Pricing: the real crossover points The model pricing from the official Anthropic docs page, current as of mid-2026: Haiku 4.5: $1 input / $5 output per million tokens. Sonnet 4.6: $3 input / $15 output per million tokens. Opus 4.7: $5 input / $25 output per million tokens. So Opus is five times the per-token cost of Haiku and roughly 1.7 times the cost of Sonnet. When should you pay five times more for Opus? When the task takes more time to debug on Sonnet than the cost difference covers. If a Sonnet loop takes you six back-and-forth turns to solve something Opus gets in two, Opus is cheaper on wall-clock time even if it costs more in tokens. The crossover is task complexity, not task type. The batch API brings all three models down by roughly 50% for non-time-sensitive work. If you are building a data pipeline or a nightly enrichment run, batching on Haiku 4.5 is the cheapest path by a wide margin. --- [CTA-BLUEPRINT] --- ## Claude 4 model comparison: which is best for coding? Sonnet 4.6 handles most coding tasks. It covers code review, function-level rewrites, unit tests, and most debugging scenarios. For everyday coding work inside Claude Code, Sonnet is what you want on by default. Opus 4.7 wins on complex architecture decisions, large-scale refactors that touch many files, and debugging hard problems where the root cause is not obvious. On SWE-bench, the original Claude Sonnet 4 (the first iteration, now deprecated) scored 72.7%. Opus 4 hit 72.5% on SWE-bench and 43.2% on Terminal-bench at launch. The iteration releases since have improved on those numbers. For agentic coding specifically, where the model has to plan and execute a multi-step workflow without constant hand-holding, Opus 4.7 is Anthropic's recommended model. Sonnet 4.6 handles most of it, but on tasks that require sustained performance across a long context, Opus 4.7 is more consistent. ### Is Claude 3.5 Sonnet still worth using? Claude 3.5 Sonnet (`claude-sonnet-3-5`) is a previous generation model, not part of the Claude 4 family. It is still available and still capable for many tasks. But Claude Sonnet 4.6 has better reasoning, a newer knowledge cutoff, and a 1M context window versus Claude 3.5 Sonnet's 200k. If you are on Claude 3.5 Sonnet in your API calls, migrating to Sonnet 4.6 is a straight upgrade in almost every dimension. The search volume for Claude 3.5 Sonnet (5,400 per month) tells you a lot of people are still on it. Most of them should move. ## How to use Claude models inside Claude Code Claude Code lets you set the default model and override it per session or per task. The way I run it: Default model is Sonnet 4.6. Most tasks run there. When I hit something that Sonnet has looped on twice, I switch to Opus using the `/model` command in Claude Code. When I need to process a large batch of files quickly and cost matters, I drop to Haiku in a script that calls the API directly. You can also set the model via the environment. Set `ANTHROPIC_MODEL=claude-opus-4-7` in your shell to override the Claude Code default for a session. This is useful when you know upfront that a task is hard enough to warrant Opus from the first turn. The CLAUDE.md model defaults pattern I use: "Default to Sonnet 4.6. Opus 4.7 is the escalation tier at 5x token cost. Ask before escalating. Cases that warrant it: multi-file architecture decisions, hard debugging where Sonnet looped twice, irreversible production work, real planning sessions, or work needing 1M context." For Claude Code subscription users, this matters in a different way. The model you run against your weekly usage cap burns through it at different rates. Opus burns three to five times faster than Sonnet on the same task. Use Sonnet as your daily driver and save Opus for the genuinely hard problems. See the full guide on setting up and running Claude Code effectively: [how to use Claude Code](/blog/how-to-use-claude-code) and [Claude Code pricing](/blog/claude-code-pricing). ## Where Claude 4 models fall short No model is right for everything. A few real constraints worth knowing: Haiku 4.5's knowledge cutoff is February 2025. If your task requires current information (recent tool releases, API changes from the last year), Haiku will get it wrong. Use Sonnet 4.6 or Opus 4.7 for anything time-sensitive. Opus 4.7 is slower than Sonnet at the same task. The moderate latency is fine for planning and architecture work where you are reading the output carefully. It is less fine for iterative debugging where you want tight feedback loops. The context windows sound enormous (1M tokens is approximately 750,000 words for Sonnet), but very large contexts can degrade model performance on needle-in-a-haystack retrieval tasks. Dropping an entire 1M token codebase and asking "find the bug" is less reliable than scoping the context to the relevant files first. Claude 4 models do not have real-time internet access via the standard API. If your workflow requires live web data, you need to bring in tools or an MCP server that handles web search. The models themselves are frozen at their training cutoffs. ## The "stop chasing the latest model" argument Every two to three months, Anthropic ships an incremental iteration. Opus 4.5 became Opus 4.6, then Opus 4.7. Sonnet 4 became Sonnet 4.5, then Sonnet 4.6. There is a predictable pattern of people dropping what they are doing to retest and re-benchmark every release. Most of the time, the difference between adjacent iterations is smaller than the difference between using the model well and using it badly. A well-constructed prompt on Sonnet 4.6 will outperform a lazy prompt on Opus 4.7 on most tasks. The fundamentals of prompting, providing context, and scoping tasks clearly matter more than chasing the freshest release. The exceptions are real step-changes. Opus 4.7's agentic coding improvement over 4.6 was significant enough to warrant switching. The jump from Claude 3.5 to Claude 4 generation was real across the board. But within a generation, between minor iterations, the upgrade is rarely the most important variable in your workflow. Pick your tier (Haiku, Sonnet, or Opus), use it well for a month, and only switch when there is a specific task where the current model is genuinely failing you. That approach will save you more time than constant benchmarking. --- [CTA-BLUEPRINT] --- ## Claude 4 FAQ ### What is the best Claude model in 2026? The best Claude model depends on the task. Opus 4.7 is Anthropic's most capable generally available model. Sonnet 4.6 is the best combination of speed and intelligence for daily use. Haiku 4.5 is the best for cost-sensitive, high-volume workloads. Most developers should default to Sonnet 4.6 and escalate to Opus 4.7 selectively. ### What is the difference between Claude Opus 4 and Claude Sonnet 4? Claude Opus 4 models are larger, more capable, and slower, designed for complex reasoning, agentic workflows, and tasks where quality matters more than speed. Claude Sonnet 4 models are faster, cheaper, and still highly capable, designed as the primary daily driver for coding, writing, and analysis. On API pricing, Opus 4.7 is $5/$25 per million tokens versus Sonnet 4.6 at $3/$15 per million tokens. ### What is Claude Haiku 4.5? Claude Haiku 4.5 is the fastest and cheapest model in the Claude 4 family, priced at $1 per million input tokens and $5 per million output tokens. It has a 200k token context window and a reliable knowledge cutoff of February 2025. It is designed for production batch workloads, routing logic, and any high-volume pipeline where cost per token matters. ### Is Claude Sonnet 4.6 better than Claude 3.5 Sonnet? Yes. Claude Sonnet 4.6 has better reasoning, a larger 1M token context window (versus 200k for Claude 3.5 Sonnet), a newer knowledge cutoff, and support for adaptive thinking. For almost every use case, Sonnet 4.6 is a straight upgrade. The main reason to stay on Claude 3.5 Sonnet is existing integrations where the cost of migration outweighs the benefit. ### How do I set the Claude model in Claude Code? Use the `/model` command in a Claude Code session to switch models on the fly. You can also set `ANTHROPIC_MODEL=claude-sonnet-4-6` (or another model ID) as an environment variable to change the default for a shell session. Inside a CLAUDE.md file in your project root, you can document the model defaults your project uses so Claude Code respects them automatically. ### What is Claude Opus 4.7's context window? Claude Opus 4.7 has a 1M token context window, which is approximately 555,000 words or 2.5 million Unicode characters, using a new tokenizer introduced with this model version. Max output is 128k tokens. On the Message Batches API, Opus 4.7 supports up to 300k output tokens using the extended output beta header. ### Should I use Claude Opus 4.7 or Sonnet 4.6 for Claude Code? Default to Sonnet 4.6. Escalate to Opus 4.7 for multi-file architecture decisions, hard debugging where Sonnet has looped twice, irreversible production changes, planning sessions requiring 1M context, or long-running agentic tasks. Opus 4.7 costs roughly five times more per token than Sonnet 4.6, so the escalation should be deliberate, not habitual. ### When will Claude 4 models be deprecated? The original Claude Sonnet 4 (claude-sonnet-4-20250514) and Claude Opus 4 (claude-opus-4-20250514) are deprecated and scheduled for retirement on June 15, 2026. The current production models, Opus 4.7 and Sonnet 4.6, have no announced retirement date. Haiku 4.5 is also current with no announced deprecation. ## Ready to build with the right model? Picking the right Claude model is one decision. Using Claude Code well is a month-long practice. The fastest way to shortcut that is the free Claude Code Blueprint: 60 minutes, no coding required, and you come out with a working setup, your first real build, and a clear sense of which model tier fits your work. If you want to go further and actually ship something in 30 days, the [30-Day Claude Code Challenge](/challenge) is the cohort. For a deeper look at how Claude Code works and how to get the most out of your model choice, see the [Claude Code guide](/blog/how-to-use-claude-code) and [Claude Code memory](/blog/claude-code-memory). ## Frequently Asked Questions ### What is the best Claude model in 2026? It depends on the task. Opus 4.7 is Anthropic's most capable generally available model. Sonnet 4.6 is the best combination of speed and intelligence for daily use. Haiku 4.5 is best for cost-sensitive, high-volume workloads. Most developers should default to Sonnet 4.6 and escalate to Opus 4.7 selectively. Three different tools for three different kinds of work, not best/better/good. ### How does Claude 4 version numbering work? The 4 refers to the generation. Opus, Sonnet, and Haiku are size tiers. The decimal (the .7 in Opus 4.7, the .6 in Sonnet 4.6) is the iteration count within that tier. Opus 4.7 does not mean Opus is version 7 of something. It means Anthropic has shipped seven iterations of the Opus 4 tier. Version numbers are not synchronised across tiers. Sonnet 4.6 came out after Opus 4.5. Check the official models page. ### What does each Claude 4 model cost on the API? Haiku 4.5: $1 per million input tokens, $5 per million output. Sonnet 4.6: $3 input, $15 output. Opus 4.7: $5 input, $25 output. So Opus is five times the per-token cost of Haiku and roughly 1.7 times the cost of Sonnet. The batch API drops all three by roughly 50% for non-time-sensitive work. Routing a task through Haiku first and escalating to Sonnet only when confidence is low can cut 70-80% off API spend on pipelines that were naively using Sonnet for everything. ### Should I use Opus 4.7 or Sonnet 4.6 inside Claude Code? Default to Sonnet 4.6. Escalate to Opus 4.7 for multi-file architecture decisions, hard debugging where Sonnet has looped twice, irreversible production changes, planning sessions requiring 1M context, or long-running agentic tasks. Opus costs roughly five times more per token than Sonnet, so the escalation should be deliberate, not habitual. On a subscription, Opus burns three to five times faster against your weekly cap. ### Is Claude Sonnet 4.6 better than Claude 3.5 Sonnet? Yes. Sonnet 4.6 has better reasoning, a 1M token context window (versus 200k on Claude 3.5 Sonnet), a newer knowledge cutoff, and support for adaptive thinking. For almost every use case it is a straight upgrade. The search volume for Claude 3.5 Sonnet (5,400 a month) tells you a lot of people are still on it. Most of them should move. ### How do I set the Claude model in Claude Code? Use the /model command in a Claude Code session to switch on the fly. Set ANTHROPIC_MODEL=claude-sonnet-4-6 as an environment variable to change the default for a shell session. Document the model defaults in your CLAUDE.md so Claude Code respects them automatically. The pattern I use: 'Default to Sonnet 4.6. Opus 4.7 is the escalation tier at 5x token cost. Ask before escalating.' ### When will the older Claude 4 models be deprecated? The original Claude Sonnet 4 (claude-sonnet-4-20250514) and Claude Opus 4 (claude-opus-4-20250514) are deprecated and scheduled for retirement on June 15, 2026. The current production models, Opus 4.7 and Sonnet 4.6, have no announced retirement date. Haiku 4.5 is also current with no announced deprecation. Starting with the 4.6 generation, Anthropic moved to dateless model IDs that point to fixed releases. ## Related guides - [Claude Opus 4.8: The Model That Stopped Guessing](/blog/claude-opus-4-8) --- # Karpathy's CLAUDE.md: 4 Rules That Fix Claude Code Source: https://theaiarchitects.com/blog/karpathy-claude-md-rules Published: 2026-05-20 Andrej Karpathy's CLAUDE.md is a 4-rule behavioral file that stops Claude Code from over-engineering. Here's what each rule does, plus 8 more rules from six weeks of testing that cut mistake rates from 41% to 3%. Andrej Karpathy's CLAUDE.md is a short behavioral file you drop into a Claude Code project to stop the agent over-engineering your code. Four rules. About fifty lines. It's the closest thing the AI coding world has to a Strunk and White. To be precise about what we're talking about: there is no official "Karpathy CLAUDE.md" published by Anthropic. The file is a community-shared distillation of [Karpathy's observations on how LLMs fail at coding](https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md), mirrored on GitHub at *forrestchang/andrej-karpathy-skills*. The original repo has 97.8k stars on the back of those four rules alone. I'm Tom. I've been running Claude Code on every part of my business since the day it shipped. I've also written my own [CLAUDE.md](https://docs.claude.com/en/docs/claude-code/memory) for an AI-operated business that is mostly content and operations, not code. So I read Karpathy's file as both a user and an author. Here's what's working in it, what doesn't translate, and how to write yours. > [CTA-BLUEPRINT] ## What is a CLAUDE.md file? A CLAUDE.md file is a behavioral memory document that Claude Code automatically loads at the start of every session. It lives in your project root, or in `~/.claude/` for global rules. Claude reads it before it does anything else and treats it as a higher-priority instruction than the default system prompt. Think of it as the instruction page you'd hand a new contractor before letting them touch the codebase. Style preferences. Conventions you've decided on. Mistakes you've watched the agent make twice. Anything you don't want to say out loud every single session. The file is plain markdown. No special syntax. Claude follows what's written. The more specific and load-bearing your rules, the better the agent behaves. ## What is Karpathy's CLAUDE.md? Karpathy's CLAUDE.md is a four-rule behavioral spec for Claude Code. It's not aimed at any one project. It's a general posture for the agent. The four rules are: 1. **Think Before Coding.** Don't assume, don't hide confusion, surface tradeoffs. 1. **Simplicity First.** Minimum code that solves the problem. Nothing speculative. 1. **Surgical Changes.** Touch only what you must. Clean up only your own mess. 1. **Goal-Driven Execution.** Define success criteria. Loop until verified. Each rule has half a dozen bullet expansions and a "test" sentence you can apply to any diff. The file ends with one line that describes when it's working: "fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes." That's the entire file. It does more for an agent than 500 lines of style guide. ## How does CLAUDE.md work? When you run `claude` in a project, the agent walks up the directory tree looking for a `CLAUDE.md` file. It loads the closest one it finds, then layers your global `~/.claude/CLAUDE.md` on top of that. Both feed into the system prompt as project-level memory. You don't need to invoke the file. You don't need to pass a flag. Claude reads it automatically and treats it as a binding contract. If you say "no em dashes," it stops writing em dashes. If you say "ask before installing dependencies," it asks. If you say "match existing file structure," it stops inventing new patterns. The technical reason it works so well: Claude Code prepends the contents of CLAUDE.md into the system prompt with strong instruction priority. Anthropic's [official memory documentation](https://docs.claude.com/en/docs/claude-code/memory) confirms it. The file isn't a suggestion. It's a directive. ## How do the 4 Karpathy rules work? Each rule sits at a specific failure mode of LLM coding assistants. Read the rule, then read what it's actually catching. ### Rule 1: Think Before Coding The full text is short. Don't assume. Don't hide confusion. Surface tradeoffs. If something is unclear, stop. Name what's confusing. Ask. The failure mode this catches is the agent guessing at intent. You say "add a search bar" and the model invents an entire search architecture, picks a library you don't use, and writes 800 lines before you can intervene. Karpathy's rule forces a beat. Restate the assumption. Offer the two interpretations. Wait. Practically, this rule pulls clarifying questions to the front of the session. You spend 30 seconds confirming what you actually want and save twenty minutes of rolling back the agent's first guess. ### Rule 2: Simplicity First Minimum code that solves the problem. Nothing speculative. No features beyond what was asked. No abstractions for single-use code. No "flexibility" or "configurability" that wasn't requested. No error handling for impossible scenarios. The test Karpathy ships with this rule is the one you'll use most: "Would a senior engineer say this is overcomplicated?" If yes, simplify. Claude reads that line and you can feel the difference in the next diff. The function gets shorter. The interface gets concrete. The mock factory disappears. This rule alone is worth installing the file. It's the most common LLM coding tax there is. ### Rule 3: Surgical Changes Touch only what you must. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style, even if you'd do it differently. The test: every changed line should trace directly to the user's request. I cannot count the number of times I've watched Claude reformat an entire file because it touched two lines in it. This rule fixes that. The agent edits what it needs to and leaves the rest of the file alone. PR reviews get readable. Diffs get small. The signal-to-noise ratio of every change goes up. There is a softer second clause inside the rule that matters too. "If you notice unrelated dead code, mention it, don't delete it." The agent surfaces the observation, doesn't act on it. That's the difference between a useful collaborator and a chaotic one. ### Rule 4: Goal-Driven Execution Transform tasks into verifiable goals. "Add validation" becomes "write tests for invalid inputs, then make them pass." "Fix the bug" becomes "write a test that reproduces it, then make it pass." For multi-step tasks, state a brief plan with checks attached to each step. The point of this rule isn't TDD. It's verifiability. Strong success criteria let the agent loop independently. Weak criteria force you to babysit every iteration. The rule transfers the verification burden from you to the agent, where it belongs. This is also the rule that makes Anthropic's new `/goal` command useful. The command runs Claude in a loop until the goal is met. Without a clean success criterion, the loop never terminates well. With one, it just works. > [CTA-BLUEPRINT] ## Where the 4 rules don't quite reach Karpathy's spine was written in late January 2026 to fix code-writing mistakes. It does that job well. The Claude Code ecosystem in May 2026 is wider than code editing alone. There are multi-step agent loops, hook cascades, skill loading conflicts, and token budgets that blow past unsupervised. The original 4 rules don't reach those. A separate operator who goes by [Mnimiy](https://x.com/Mnilax) tested the 4-rule template across 50 representative tasks in 30 codebases over six weeks, then re-ran the same tasks with 8 additional rules layered on top. The mistake rate dropped from 41% (no CLAUDE.md) to 11% (Karpathy's 4) to 3% (his expanded 12). Compliance barely moved between 4 rules and 12, which is the interesting part. The new rules cover failure modes the original 4 weren't aimed at, so they don't compete for the same attention budget. I tested all 8 against the work I actually do. Six earned a permanent spot in my own file. Here is the full set with the moment each one catches. ### Rule 5: Use the model only for judgment calls Use Claude for classification, drafting, summarisation, and extraction from unstructured text. Don't use it for routing, retries, status-code handling, or deterministic transforms. If code can answer the question, code answers the question. The failure mode: a snippet that asks Claude "should we retry on a 503?" runs cleanly for two weeks, then starts flaking because the model has begun reading the request body as context for the decision. The retry policy goes random because the prompt has gone random. Pull the call out of the model and into code. ### Rule 6: Token budgets are not advisory Per-task budget: 4,000 tokens. Per-session: 30,000. If a task is approaching the budget, summarise and start fresh. Surface the breach. Don't silently overrun. The failure mode: a debugging session runs for 90 minutes. Claude is happily iterating on the same 8KB error message, gradually losing track of which fixes it has already tried. By the end it's re-suggesting fixes you rejected forty messages ago. A hard budget kills the loop at minute 12 before it spirals. ### Rule 7: Surface conflicts, don't average them If two existing patterns in the codebase contradict, pick one (the more recent or more tested), explain why, and flag the other for cleanup. Don't blend them. The failure mode: a codebase has two error-handling patterns. One uses async/await with explicit try/catch. The other uses a global error boundary. Claude writes new code that does both. Errors get caught twice and swallowed silently. The averaging is the bug. ### Rule 8: Read before you write Before adding code in a file, read the file's exports, the immediate caller, and any obvious shared utilities. If you don't understand why existing code is structured the way it is, ask before adding to it. "Looks orthogonal to me" is the most dangerous phrase in any codebase. The failure mode: Claude adds a function next to an existing identical function it never read. Both functions do the same thing. The new one wins on import order and the old one (which had been the source of truth for six months) goes quietly defunct. ### Rule 9: Tests verify intent, not just behaviour Every test must encode why the behaviour matters, not just what it does. A test like `expect(getUserName()).toBe('John')` is worthless if the function returns a hardcoded ID. If you can't write a test that would fail when business logic changes, the function is wrong. The failure mode: twelve passing tests on an auth function. All green. Auth is broken in production. The tests were checking the function returned something, not whether it returned the right thing. The function passes because it returns a constant. ### Rule 10: Checkpoint after every significant step After each step in a multi-step task, summarise what was done, what is verified, and what remains. Don't continue from a state you can't describe back. If you lose track, stop and restate. The failure mode: a 6-step refactor goes wrong on step 4. By the time you notice, Claude has also done steps 5 and 6 on top of the broken state. Untangling takes longer than redoing the work. Checkpoints catch it at step 4. ### Rule 11: Match the codebase's conventions, even when you disagree If the codebase is snake_case and you'd prefer camelCase, the answer is snake_case. If it uses class-based components and you'd prefer hooks, the answer is class-based. Conformance beats taste inside the file. If you genuinely think a convention is harmful, surface it. Don't fork silently. The failure mode: Claude introduces hooks into a class-component codebase. They work. They also break every testing pattern that assumed `componentDidMount`. Half a day to remove and rewrite. ### Rule 12: Fail loud If you can't be sure something worked, say so. "Migration completed" is wrong if 30 records were skipped silently. "Tests pass" is wrong if any were skipped. "Feature works" is wrong if you didn't verify the edge case I asked about. Default to surfacing uncertainty, not hiding it. The failure mode: Claude reports a database migration completed successfully. It silently skipped 14% of records that hit a constraint violation. The skip was logged but never surfaced. The error shows up 11 days later when downstream reports start looking wrong. > [PULLQUOTE] Karpathy's 4 fix what happens in the moment. Rules 5 to 12 fix what happens across time. ### Why the lift compounds Going from 4 rules to 12 added almost no compliance overhead (78% down to 76%) and cut the mistake rate by another 8 points. The new rules cover failure modes the original 4 didn't address, so they don't compete for the same attention budget. A useful mental model: Karpathy's 4 fix what happens when Claude is writing code in a single moment. Rules 5 to 12 fix what happens when Claude is running across time, files, sessions, and pipelines. The first set is a posture. The second set is a contract for long-running work. ## How to write a CLAUDE.md file Three steps. Each takes five minutes. You can copy Karpathy's file verbatim and you'll already be ahead of 90% of projects. The real wins come from layering your project specifics on top. ### 1. Start with Karpathy's four rules Drop his file in your project root as-is. Don't edit it yet. Run Claude Code on a real task for a session or two. Notice which rules fire. Notice which ones never come up because they don't match your work. Here's the copy-paste block. Save it as `CLAUDE.md` in your project root. If your work is mostly multi-step agent runs, hook chains, or anything that survives across sessions, paste rules 5 to 12 from the section above directly below the 4. The 12-rule version is the floor for that kind of work. Keep the combined file under 200 lines or compliance starts to drop. ### 2. Add a "what this project is" block at the top One paragraph. Name the project, the stack, the audience, the things you've already decided. Claude wastes the most tokens re-deriving context that should be a one-liner. Pre-empt it. ### 3. Layer in your repeat corrections Every time you correct Claude on something twice, add it to CLAUDE.md. "No em dashes." "Match the existing test file structure." "Don't add a README unless I ask." These are the highest-leverage lines because they encode a real correction you watched the agent need. My personal CLAUDE.md for the business behind this site has about 60 lines of these. They aren't clever. They aren't even well-written. They are scar tissue from sessions where the agent made the same mistake twice and I decided I'd rather write one line of memory than fix the same mess a third time. ## Should I copy Karpathy's CLAUDE.md? For coding projects, yes. Copy it verbatim and add a project header above it. The four rules are well-tuned for the way most engineers actually want to work with an LLM. There is very little to argue with. The honest caveat is that Karpathy's CLAUDE.md is written for one kind of work, which is code. If your project is content, ops, or anything where the agent isn't editing source files, the rules need to be adapted. "Surgical Changes" doesn't mean the same thing when the agent is drafting an email as when it's editing a function. "Simplicity First" reads differently when the deliverable is a 2,000 word blog post. I've adapted mine. Tom's CLAUDE.md for AI Operator OS has 11 sections, almost none of which are about source code. The Karpathy spine is there in the background. The body of the file is operating rules for an agent that runs a business. ## Karpathy's CLAUDE.md vs my CLAUDE.md The fastest way to show the difference is to put them side by side. Karpathy's file has four sections: - Think Before Coding - Simplicity First - Surgical Changes - Goal-Driven Execution Mine has eleven: - Content Creation Rules - Writing Style Rules - Content Constraints - Workflow Discipline - Efficiency Rules - Voice & Copywriting System - Operational Rules (copy formatting, email length, video scripts, product work, deployment, model defaults) - MCP Servers - Memory System - Quick Directory Reference - Project Areas Karpathy's rules are about *how* to code. Mine are about *what work to do* in an AI-run business and which constraints are non-negotiable. They are doing different jobs. Use Karpathy's for engineering work and write something heavier when the agent is running your operations. The longer you sit with the file, the more it teaches you about *how* you want to work with an agent. Less about syntax, more about taste. [Keven Ellison](/case-studies/keven) is one of my mentorship students who pushed this further than most. He had no coding background, started with a basic CLAUDE.md, and now runs a 180-plus node content management system, a personal memory layer, and his own autonomous agent on a cron job, all of it shaped by the rules he iterated into his own file over six months. His story is a useful reference point for what good CLAUDE.md discipline looks like outside of a pure coding project. ## Where does CLAUDE.md fall short? Two things to be honest about. CLAUDE.md is read-only memory from Claude's side. The agent obeys the rules in the file but cannot update them mid-session. That's a feature for stability and a bug for learning. If you watched Claude make a new mistake today, you have to be the one who writes the rule to prevent it tomorrow. The other limit is sprawl. A 500-line CLAUDE.md will get partially ignored. Long files eat context and dilute the priority signal. Karpathy's 50 lines is closer to the sweet spot than the kitchen-sink documents people end up writing six months in. Cut ruthlessly. Every rule that isn't pulling weight is making the rest weaker. ## Verdict: is Karpathy's CLAUDE.md worth using? Yes. For any coding project, drop it in today and you will see fewer over-engineered diffs by the end of the week. The rules are short, the wording is tight, and the philosophy ("verifiable goals, surgical changes, simplicity first") matches the way good engineers already prefer to work. If your project isn't code, treat Karpathy's file as the spine and write your own body. Same posture, different content. Either way, the right move is to stop arguing with Claude in chat and put the argument in CLAUDE.md once. > [CTA-BLUEPRINT] ## Karpathy CLAUDE.md FAQ ### Is CLAUDE.md project-level or global? It can be both. A `CLAUDE.md` in your project root applies to that project. A `CLAUDE.md` in `~/.claude/` applies globally to every Claude Code session on your machine. Claude loads both. Project-level rules override global ones when they conflict. ### What's the difference between CLAUDE.md and AGENTS.md? CLAUDE.md is the Anthropic-specific memory file for Claude Code. AGENTS.md is a cross-vendor proposal aimed at being readable by any coding agent, including Cursor, Codex, and Gemini CLI. They overlap. In a Claude-only stack you only need CLAUDE.md. If you switch between agents, AGENTS.md gives you portable rules. ### Does Karpathy's CLAUDE.md work with Claude Sonnet 4.6 and Opus 4.7? Yes. The file is model-agnostic. It works with Sonnet 4.6, Opus 4.7, and any future Claude Code model. The four rules describe behavior, not implementation, so model upgrades only make the file more effective. ### Can I use Karpathy's rules with Codex or Cursor? Yes, with one rename. Save the file as `AGENTS.md` instead of `CLAUDE.md` and most coding agents will read it. The wording works across tools because the failure modes Karpathy is describing (assumption, overcomplication, scope drift) are common to all LLM coding assistants, not just Claude. ### Will Claude actually follow CLAUDE.md instructions? Mostly yes, especially for hard rules. Phrasings like "Never do X" and "Always do Y" hold up well across long sessions. Subjective rules like "be concise" drift over time and need to be reinforced with specifics. The fix is to write your rules as testable directives, not vibes. ### Should I use the 4-rule version or the 12-rule version? Use the 4-rule version if your work is mostly Claude writing code in single sessions. Use the 12-rule version if you're running multi-step agents, hook chains, or anything that survives across sessions. The extra 8 rules (budgets, checkpoints, fail-loud, read-before-write, conventions, intent-aware tests, conflict surfacing, judgment-only model use) catch failure modes the original 4 weren't aimed at. Across tested codebases, mistake rates moved from 41% with no CLAUDE.md, to 11% with 4 rules, to 3% with 12. ### How long should a CLAUDE.md file be? Karpathy's is about 50 lines and that's a good ceiling for the behavioral spine. Add a short project header on top (10 to 20 lines) and you're done. If your file is creeping past 200 lines, you're documenting things that should live in code, not memory. ### Where can I find more CLAUDE.md examples? The original Karpathy mirror at [github.com/forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) is the canonical reference. Anthropic's official [Claude Code memory docs](https://docs.claude.com/en/docs/claude-code/memory) cover the loading rules. For broader patterns, the curated awesome-claude-code list on GitHub has dozens of community CLAUDE.md files worth reading. ## Ready to build with the four rules? The 60-minute [Claude Code Blueprint](/blueprint) is the fastest path from zero to a working Claude Code setup with a CLAUDE.md that actually behaves. You'll have the file written, the agent installed, and a first working build by the end of the hour. Free. No coding required. If you want to go further than the blueprint, the [30 Day Claude Code Challenge](/challenge) takes the four-rule posture and applies it across 30 days of structured builds with live calls every Thursday. Karpathy's file fixes the agent. The Blueprint fixes the operator. ## Frequently Asked Questions ### Do I have to copy Karpathy's CLAUDE.md exactly? No. The four rules (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) are the spine, not a script. Drop the file in your project root verbatim, run Claude Code for a session or two, then layer your own project context and repeat corrections on top. Most of the real wins come from the lines you add after watching the agent make the same mistake twice. ### What is a CLAUDE.md file actually doing under the hood? Claude Code prepends the contents of CLAUDE.md into the system prompt with strong instruction priority at the start of every session. The agent walks up the directory tree, loads the closest CLAUDE.md it finds, then layers your global ~/.claude/CLAUDE.md on top. You do not invoke it or pass a flag. It is read automatically and treated as a binding contract. ### Should I use the 4-rule version or the 12-rule version? Use the 4-rule version if your work is mostly Claude writing code in single sessions. Use the 12-rule version if you are running multi-step agents, hook chains, or anything that survives across sessions. In Mnimiy's testing across 50 tasks in 30 codebases, mistake rates moved from 41% with no CLAUDE.md, to 11% with the 4 rules, to 3% with 12. ### Will the file still work if I switch from Claude Sonnet 4.6 to Opus 4.7? Yes. The four rules describe behaviour, not implementation, so they are model-agnostic. Karpathy's CLAUDE.md works with Sonnet 4.6, Opus 4.7, and any future Claude Code model. Model upgrades only tend to make the file more effective, because better models follow load-bearing instructions more reliably. ### How long should my CLAUDE.md be? Karpathy's is about 50 lines and that is a sensible ceiling for the behavioural spine. Add a short project header on top (10 to 20 lines) and you are done. If your file is creeping past 200 lines, you are documenting things that should live in code, not memory. Long files dilute the priority signal and the agent starts ignoring sections. ### Can I use Karpathy's rules with Codex or Cursor? Yes, with one rename. Save the file as AGENTS.md instead of CLAUDE.md and most coding agents will read it. The wording transfers because the failure modes Karpathy is describing (assumption, overcomplication, scope drift) are common to every LLM coding assistant, not just Claude. ### Will Claude actually follow the rules I put in CLAUDE.md? Hard rules hold up well across long sessions. Phrasings like 'Never do X' and 'Always do Y' stick. Subjective rules like 'be concise' drift over time and need to be reinforced with specifics. The fix is to write your rules as testable directives, not vibes. Treat every rule as scar tissue from a real correction. ## Related guides - [Claude Code Memory: CLAUDE.md, Auto Memory, and Path Rules](/blog/claude-code-memory) - [Claude Code Settings: The settings.json Guide](/blog/claude-code-settings) - [Markdown vs HTML for Claude Code: When to Use Which (and Why Anthropic Just Switched)](/blog/markdown-vs-html-claude-code) --- # How to Install Claude Code on Mac, Windows, Linux + WSL Source: https://theaiarchitects.com/blog/how-to-install-claude-code Published: 2026-05-14 Step-by-step Claude Code install guide for Mac, Windows, Linux, and WSL. Exact commands, prerequisites, troubleshooting, update and uninstall paths. To install Claude Code, run npm install -g @anthropic-ai/claude-code in your terminal (you'll need Node.js 18 or higher), or use Anthropic's native installer at claude.ai/install.sh on macOS and Linux, or claude.ai/install.ps1 in Windows PowerShell. Then run claude in any project folder and log in with your Anthropic account. I'm Tom. I've installed Claude Code on five machines across Mac, Windows, WSL, and a Linux VPS, and I run it inside a desktop app, the terminal, VS Code, and on the web. Below is the full step-by-step install for every OS, the exact commands, the prerequisites people skip, the update and uninstall paths, and the four errors that trip people up most often. > [CTA-BLUEPRINT] ## Before you install Claude Code Claude Code needs three things before the install command will work. Get these in place first or you'll burn an hour on errors that look like the install is broken when it isn't. ### Anthropic account or API key Sign in with an Anthropic account on the [Claude Pro or Max plan](https://claude.com/pricing) for the all-in-one subscription. Pro is $20/month and includes Claude Code on Sonnet. Max 5x ($100/month) and Max 20x ($200/month) raise the weekly limits and unlock Opus access. If you'd rather pay per token, generate an API key at console.anthropic.com instead. You'll wire it up after install with the /login command. ### Node.js 18 or higher If you install Claude Code via npm (the cross-platform path), you need Node.js 18 LTS or newer on your machine. Node 20 or 22 is the safer bet because some MCP servers expect newer engines. Check what you have with node --version. If it returns nothing or a version below 18, install the latest LTS from nodejs.org first. ### A terminal you actually use Claude Code is a CLI first. On Mac you'll use Terminal or iTerm. On Windows you'll use PowerShell, Windows Terminal, or WSL. On Linux you'll use whatever shell you already run. The desktop app and IDE plugins all wrap the same CLI underneath, so getting comfortable with one terminal pays off for the rest. ## How to install Claude Code on Mac On Mac you have three install paths: the npm install (works on any version of macOS with Node), the Anthropic native installer, or Homebrew. The npm path is the most common because it gives you the same command across every OS. I'll walk all three but start with npm. ### Step 1: Install Node.js Download the macOS installer from [nodejs.org](https://nodejs.org) and pick the LTS build. Run the .pkg file, follow the prompts, then open Terminal and confirm the version with node --version. Anything 18 or higher is fine. If you already use Homebrew, brew install node works too. ### Step 2: Run the npm install command In your terminal, paste this and hit return: `npm install -g @anthropic-ai/claude-code` The -g flag installs Claude Code globally so you can run claude from any folder. The package name is @anthropic-ai/claude-code, not claude-code. Wrong package = wrong tool. The official package shows the @anthropic-ai scope on npmjs.com. ### Step 3: Verify the install Run claude --version. You should see a version number like 2.1.x. Then change into any project folder and run claude. The first time you run it, you'll be prompted to log in. Pick "Claude account" if you have a Pro or Max subscription, or paste your API key. Then ask Claude something simple like "what files are in this folder?" to confirm it works. ### Optional: Native installer or Homebrew If you'd rather skip Node, Anthropic's native installer is a single command: [curl -fsSL https://claude.ai/install.sh | bash](https://docs.anthropic.com/en/docs/claude-code). Or with Homebrew, run brew install --cask claude-code. The native install auto-updates in the background. Homebrew does not, so you have to brew upgrade manually. ## How to install Claude Code on Windows On Windows you have three options: a clean PowerShell native install, npm via Node.js for Windows, or WSL (Windows Subsystem for Linux). I'd default to PowerShell for the simplest setup, and WSL only if you're already running a Linux dev environment. The PowerShell native installer was added so Claude Code Windows users can avoid Node entirely. ### Step 1: Install Node.js (skip if using the native installer) If you want the npm install path, download the Node.js LTS installer for Windows from [nodejs.org](https://nodejs.org). Run the .msi file and accept the defaults. Open a fresh PowerShell window and run node --version to confirm. If it returns a version, you're set. ### Step 2: Run the install command Two options. PowerShell native (no Node needed): `irm https://claude.ai/install.ps1 | iex` Or via npm (after installing Node): `npm install -g @anthropic-ai/claude-code` Or via WinGet: `winget install Anthropic.ClaudeCode` ### Step 3: Verify and log in Open a new PowerShell window so PATH refreshes. Run claude --version. Then run claude in any folder and follow the login prompt. If PowerShell can't find claude after install, close and reopen the window. Claude Code adds itself to PATH but the existing window won't see it until restart. ## How to install Claude Code on Linux On Linux the npm install command is identical to Mac. The native installer works the same way. Most distros (Debian, Ubuntu, Fedora, RHEL, Alpine) have apt or dnf packages too. Pick whichever matches how you manage everything else on your box. ### Step 1: Install Node.js On Debian or Ubuntu: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs` On Fedora or RHEL: `sudo dnf install -y nodejs npm` Confirm with node --version. You want 18 or higher. ### Step 2: Run the install command npm path: `npm install -g @anthropic-ai/claude-code` Or the Anthropic native installer (recommended for VPS deployments because it auto-updates): `curl -fsSL https://claude.ai/install.sh | bash` ### Step 3: Verify and authenticate Run claude --version. Then claude in your project. Log in via /login the same way as the other platforms. On a headless VPS, the login flow gives you a URL you copy into your local browser, complete the auth, then paste the token back into the SSH session. ## How to install Claude Code with WSL Claude Code with WSL is a clean way to run it on Windows without leaving a Linux dev environment. Open Ubuntu (or whichever distro you've installed under WSL2), then follow the Linux install steps above. The npm install command is the same. The login flow opens a URL in your Windows browser even though you're running inside WSL, so it just works. One gotcha: install Node and Claude Code inside the WSL distro, not on Windows. If you mix the two, claude will run in PowerShell against your Windows file paths but expect Linux paths. Pick a side. I run everything inside Ubuntu under WSL2 and it's been the smoothest setup of all four. ## How to install the Claude Code Desktop app The Claude Code desktop app is a separate download for Mac and Windows that wraps the same CLI in a native app window. Get it from [claude.ai/download](https://claude.ai/download). Run the installer, log in with your Anthropic account, open a folder, and you're in. The desktop app pulls the same skills, MCP servers, and CLAUDE.md files as the terminal version, so a project you set up in one shows up in the other. If you're new and you don't yet care about the terminal, the desktop app is the gentlest entry. The 30-Day Challenge students start there because the file tree, the chat, and the model picker are all visible in one window. You can drop into the terminal later when you want it. ## How do I update Claude Code? If you installed via the Anthropic native installer or the desktop app, Claude Code updates itself automatically in the background. You don't need to do anything. The CLI tells you when a new version is available and prompts a restart. If you installed via npm, run: `npm update -g @anthropic-ai/claude-code` Or to force the latest: `npm install -g @anthropic-ai/claude-code@latest` If you used Homebrew on Mac, run brew upgrade claude-code. WinGet on Windows: winget upgrade Anthropic.ClaudeCode. Check your installed version anytime with claude --version. The current changelog lives on the Claude Code GitHub repo. ## How do I uninstall Claude Code? To uninstall Claude Code from npm, run npm uninstall -g @anthropic-ai/claude-code. From Homebrew, brew uninstall --cask claude-code. From WinGet, winget uninstall Anthropic.ClaudeCode. The desktop app uninstalls like any other app: drag it to the Trash on Mac or use Add/Remove Programs on Windows. Your config and project memory live in ~/.claude on Mac and Linux, or %USERPROFILE%\.claude on Windows. Delete that folder if you want a completely clean slate. Otherwise leave it in place and your skills, CLAUDE.md files, and Auto Memory survive a reinstall. ## Why is my Claude Code install failing? Four problems cover 90% of failed installs. Run through them in order before you go hunting on Reddit. ### Node version too old If npm install throws errors about engines, syntax, or unsupported features, your Node is too old. Run node --version. If it's below 18, update Node to LTS (20 or 22) and try again. nvm makes this trivial: nvm install --lts then nvm use --lts. ### Permission errors on global npm install On Mac and Linux, if npm install -g throws EACCES errors, npm is trying to write to /usr/local without permission. Don't fix this with sudo. Instead, set npm's global prefix to a folder you own: `mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'` Then add ~/.npm-global/bin to your PATH in ~/.zshrc or ~/.bashrc. Restart your shell. Re-run the install. This is also the safest fix long-term because you stop polluting system directories. ### Command not found after install If install completes but claude --version returns "command not found" or "zsh: command not found: claude" (yes, that's a real top-search query), your shell hasn't picked up the new binary. Close and reopen your terminal. If it still doesn't work, check that npm's bin folder is in your PATH. Run npm bin -g to find it. On Windows, restart PowerShell. On WSL, source ~/.bashrc. ### Claude Code Windows install hangs or fails If the PowerShell native installer stalls, you're behind a corporate proxy that's blocking the script. Use the npm install path instead with explicit registry: npm install -g @anthropic-ai/claude-code --registry https://registry.npmjs.org/. If npm is also blocked, install via WinGet, which uses the Microsoft Store backend most enterprise networks already permit. ## What to do after installing Claude Code Once claude --version runs cleanly and you're logged in, the next step is to actually build something with it. The path I send everyone down is the [Claude Code Blueprint](/blueprint). It's a free 60-minute interactive lesson that runs inside Claude Code itself. You open the folder, type "start lesson 1", and it walks you through your first CLAUDE.md, your first slash command, your first skill, and your first MCP integration. By the end you have a working Brief Generator that researches a company in 60 seconds. If you want to go further into production-grade systems, the [30-Day Challenge](/challenge) is the cohort version. Same starting point, but you ship five projects across the month with weekly live calls. Either way, the install is just the gate. The skill comes from building. > [CTA-BLUEPRINT] ## Claude Code install FAQ ### Do I need Node.js for Claude Code? If you install Claude Code via npm (npm install -g @anthropic-ai/claude-code), yes, you need Node.js 18 or higher. If you use the Anthropic native installer (curl https://claude.ai/install.sh | bash on Mac/Linux, irm https://claude.ai/install.ps1 | iex on Windows), Homebrew, or WinGet, you don't need Node. The native installers ship a self-contained binary. ### Is Claude Code free to install? Installing Claude Code is free. The CLI itself doesn't cost anything to download. You pay for the model behind it: a Claude Pro subscription ($20/month) includes Claude Code on Sonnet, Max 5x ($100/month) adds Opus, or you can pay per token via the Anthropic API. ### How do I install Claude Code in VS Code? Install Claude Code on the command line first (any of the methods above). Then open VS Code, search the Marketplace for "Claude Code", and install the official Anthropic extension. The extension wraps the same CLI inside the editor sidebar, so your skills and CLAUDE.md files work the same. JetBrains IDEs have an equivalent plugin in the JetBrains Marketplace. ### What's the difference between Claude Code CLI and the desktop app? The CLI runs in your terminal. The desktop app is a native Mac or Windows app that wraps the same CLI in a chat-style window with a file tree. Both pull from the same project folders, the same skills, the same MCP config, and the same Auto Memory. Pick whichever feels better. Most people use the desktop app for greenfield projects and the CLI for repos they're already SSH'd into. ### Can I install Claude Code on Ubuntu? Yes. Install Node.js 18+ via apt or NodeSource, then run npm install -g @anthropic-ai/claude-code. Or use Anthropic's native installer with curl -fsSL https://claude.ai/install.sh | bash. Both work cleanly on Ubuntu 20.04, 22.04, and 24.04. Same path works on Debian, Fedora, RHEL, and Alpine. ### How do I install a specific version of Claude Code? Pin a version with npm: npm install -g @anthropic-ai/claude-code@2.1.119 swaps the @latest tag for the version you want. Useful if you're testing a regression or a CHANGELOG note pinned to a release. List versions with npm view @anthropic-ai/claude-code versions. ### Can I run Claude Code on a VPS? Yes, and it's how I run a lot of production work. SSH into the box, install Node, run the npm install command, then run claude. The login flow gives you a URL you open in your local browser, finish auth, and paste the token back into the SSH session. Lock the VPS down with Tailscale or SSH keys before you put real workloads on it. ### How do I update Claude Code to the latest version? If you used the native installer or desktop app, it auto-updates. For npm: npm install -g @anthropic-ai/claude-code@latest. For Homebrew: brew upgrade claude-code. For WinGet: winget upgrade Anthropic.ClaudeCode. Check the running version with claude --version. ### Does Claude Code run offline? No. Claude Code is a frontend to Anthropic's models, so it needs an internet connection to send each prompt and receive each response. The CLI binary runs locally and the file edits happen on your machine, but the reasoning step is all cloud. ## Ready to build with Claude Code? The install is the easy part. The build is where the value lives. Grab the free [Claude Code Blueprint](/blueprint) and you'll be running your first real automation 60 minutes from now. It's the same starting point I use with every new student, every new team I install Claude Code for, and every new VPS I spin up. If you want a deeper read on what Claude Code can actually do once it's installed, this breakdown of [the upgrades that made Claude Code 10x more powerful](/blog/claude-code-10x-more-powerful) covers the changes between v1 and v2 and what they unlock. ## Frequently Asked Questions ### How do I install Claude Code? Run npm install -g @anthropic-ai/claude-code in your terminal (you need Node.js 18 or higher), or use Anthropic's native installer at claude.ai/install.sh on Mac and Linux or claude.ai/install.ps1 in Windows PowerShell. Then run claude in any project folder and log in. The same install path works on Mac, Windows, Linux, and WSL. ### Do I need Node.js to install Claude Code? Only if you install via npm. If you use the Anthropic native installer (curl https://claude.ai/install.sh | bash on Mac/Linux, irm https://claude.ai/install.ps1 | iex on Windows), Homebrew, or WinGet, you do not need Node. Those ship a self-contained binary. The npm path is the most common because it gives you the same command across every OS. ### Is Claude Code free to install? The CLI itself is free to download. You pay for the model behind it. Claude Pro at $20 a month (or $17 annual) includes Claude Code on Sonnet. Max 5x at $100 adds Opus access. Max 20x at $200 unlocks the highest effort tier. You can also bring your own API key and pay per token through console.anthropic.com. ### Can I install Claude Code on Windows without using Node? Yes. The PowerShell native installer was added so Windows users can avoid Node entirely. Run irm https://claude.ai/install.ps1 | iex in a fresh PowerShell window. WinGet also works (winget install Anthropic.ClaudeCode) and is often the cleanest path on corporate networks that block other installers. Open a new PowerShell window after install so PATH refreshes. ### Why does my Claude Code install fail with permission errors? On Mac and Linux, npm install -g often throws EACCES errors because npm is trying to write to /usr/local without permission. Do not fix this with sudo. Set npm's global prefix to a folder you own with mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'. Add ~/.npm-global/bin to your PATH in ~/.zshrc or ~/.bashrc, restart your shell, and re-run the install. ### How do I update Claude Code to the latest version? If you used the Anthropic native installer or the desktop app, it auto-updates in the background. For npm, run npm install -g @anthropic-ai/claude-code@latest. Homebrew on Mac: brew upgrade claude-code. WinGet on Windows: winget upgrade Anthropic.ClaudeCode. Check the running version anytime with claude --version. ### Can I run Claude Code on a VPS? Yes, and it is how a lot of production work gets done. SSH into the box, install Node, run npm install -g @anthropic-ai/claude-code, then run claude. The login flow gives you a URL you open in your local browser, finish auth, and paste the token back into the SSH session. Lock the VPS down with Tailscale or SSH keys before you put real workloads on it. ## Related guides - [How to Install Claude Code on Windows in 2026 (PowerShell, WSL, and the Path Gotcha)](/blog/claude-code-windows-install) - [npm install @anthropic-ai/claude-code: What Actually Happens (and 4 Errors to Watch For)](/blog/npm-install-claude-code) --- # Claude Code Just Got 10x More Powerful: 10 New Features Source: https://theaiarchitects.com/blog/claude-code-10x-more-powerful Published: 2026-05-14 10 new Claude Code features that change how I build day-to-day: insights reports, effort levels, remote control, batch, simplify, hooks, agent teams. Claude Code is Anthropic's terminal-based coding agent that turns your command line into a full engineering teammate. The product just got a lot more powerful. There are 10 features buried in the docs that 10x how I actually use Claude Code day-to-day, and the gap between knowing they exist and not knowing is the gap between prompting a chatbot and running a real engineering agent. Some shipped in the last few weeks. Others have been sitting there since launch, ignored. I'm Tom. I use Claude Code every day to build apps, write content, and orchestrate AI teams. Below is a walkthrough of every feature, what it does, when to use it, and where it falls short. > [CTA-BLUEPRINT] ## What is Claude Code? Claude Code is Anthropic's command-line coding agent. Install it via npm, point it at a folder, and it can read your repo, run commands, edit files, push commits, and connect to external services through MCP servers. It's the same Claude model as the desktop app, but the terminal harness adds tools, memory, hooks, and a permission system the chat app doesn't have. Claude Code is the difference between asking an AI to write code and giving an AI the keys to your machine so it can ship code itself. The new features turn a coding assistant into an engineering agent that runs autonomously, in parallel, on a schedule, and from your phone. https://www.youtube.com/watch?v=F_i_s0L2aWY ## What's new in Claude Code? The short list of what's new in Claude Code: an insights report that audits your last 30 days of sessions, an effort command for controlling reasoning depth, remote control so you can drive sessions from your phone, batch for parallel multi-file edits, simplify for automated code review, loop for cron-style scheduled prompts, escape-twice rewind, hooks for pre and post tool actions, the BTW side-question command, and agent teams (the big one) where multiple full Claude Code instances work in parallel with their own context windows. Here's how each of the 10 features actually works in practice. ## How does Claude Code's new insights report work? Type /insight into Claude Code and it generates a report analyzing the last 30 days of your sessions. It pulls a URL after about 30 seconds to a minute. Open it in the browser and you get a personalised audit of your own usage. Where you're duplicating yourself. What skills you should install. What custom subagents would save you time. The exact prompts to feed back into Claude Code to install them. As the report puts it: "what's working, what's hindering you, quick wins to try, and ambitious workflows you should strive to implement yourself." Mine flagged that I write 90% markdown content and repeatedly catch AI-slop patterns after review. Its fix: install a hook that runs an auto-scan after every piece of content I generate. That's the kind of recommendation you don't get from a tutorial. When I shared this with people who'd never heard of /insight, they were genuinely shocked at the recommendations. If you do nothing else from this list, run /insight today. ## How do I control reasoning with the Claude Code effort command? Type /effort and you get five levels: low, medium, high, max, and auto. Default is medium. Crank it to max for a final review of a project you're about to deploy or any problem that needs deep reasoning. Drop it to low for tiny edits where you're burning tokens for no reason. If you're on the API, this is your single biggest lever for cost. Effort directly controls how many tokens Claude Code burns per task. If you're on a Claude Max subscription, you're not paying per token, so just leave it on auto or max. Either way, this is something you can't do in the Claude desktop app, which is one of the reasons Claude Code has the edge for serious work. ## Claude Code remote control: working from your phone This one just dropped. Type /remote-control inside an active Claude Code session and it gives you a URL. Open it on your phone, log in, and you're inside the same session that's running on your laptop. You can keep working from a taxi, a train, an airport queue, anywhere. It only works if you're connected with a Claude subscription (not the API key) and you're on the latest Claude Code version. If you don't see the command, update. This changes Claude Code from a desk tool to an always-on agent. Spin up a long task before you leave, check progress on the train, redirect from the bus. The mobile app shows the same interactive session, the same tool calls, the same approvals. ## How does the Claude Code batch command work? /batch is for large-scale changes across many files at once. Developer use case: connect your repo to a GitHub remote, ask Claude Code to add error handling to all your Python scripts, and it spins up parallel agents that each generate a pull request for the files they touch. You review and merge. Content use case: I asked it to write a LinkedIn post for each of the 14 lessons in my Claude Code course. It entered plan mode, read all 14 lessons in parallel, and built the content plan. Worth knowing: even with /batch, Claude decides whether to actually run things in parallel. For a stack of plain text files it'll usually default to sequential because there's no win in spinning up parallel agents. But if you're working with worktrees and a code base on GitHub, it'll fan out to genuine parallel edits. ## Simplify: Claude Code's automated code review /simplify spins up three review agents at once: one checks code duplication, one checks code quality and bugs, one checks efficiency. They run simultaneously and apply fixes automatically. I ran it on my sponsored post manager app after two sessions of work. It found inconsistent colours, missing error handling, a stack of duplication, and efficiency issues, then patched them while I sat there. Pair it with shift-tab to flip on accept-edits mode and you don't have to approve every change one by one. I didn't have to lift a finger. The three agents finished, dropped their edits in, and the app got cleaner without me touching it. ## How to schedule prompts with Claude Code loop /loop runs a prompt or a slash command on a recurring interval. Type /loop, set the interval (every three hours, every day, every Monday), and give it a prompt. For example: every three hours, check my inbox for urgent messages that need responding to. Hook your inbox up to Claude Code via an MCP server and you've got a mini cron job inside your terminal. Caveat: the loop stops when you close the session. So this isn't a replacement for a real n8n workflow or a deployed agent on a VPS. But for a quick reminder to commit your work every hour, or a ping when something specific lands in your inbox, it's lightweight and useful. ## How do I undo edits in Claude Code? (the rewind trick) Press escape twice and Claude Code drops you into rewind mode. You see every prompt in the session and you can restore the code and the conversation to the state before any of them. If Claude Code just modified 11 files and you don't like the result, escape-escape, click the prompt before that change, and the edits unwind. This is the feature you reach for when you tell Claude Code to refactor and it goes off-piste. Press escape to exit rewind. Most people don't know it exists. ## What are Claude Code hooks? Hooks are actions Claude Code runs before or after a tool call. Think of them as automatic rules. A few real uses: - Quality control: scan every piece of generated content for AI-slop patterns before it's saved. - Cost control: count tokens in each request, and if the prompt exceeds your limit, block and ask Claude to summarise first. - Brand voice enforcement: every time Claude writes copy, run it through a tone-matching prompt before it ships. - Automatic backups: every time Claude edits a file, copy the original to a backup folder. - Workflow automation: build an n8n flow inside Claude Code, then trigger a hook that posts it to your live n8n instance the moment it's saved. You can find your hook configurations inside Claude Code settings. This is where the harness stops being a chat box and starts being a programmable runtime. ## The /BTW command: side questions without breaking flow /BTW lets you ask a quick side question without interrupting the work Claude Code is already doing. Classic example: type /BTW context and it tells you how much context window you've got left in the session. Or ask why Claude chose a specific approach to a problem mid-task. The query doesn't eat into your main session's context, but it does have access to the context of that session, so the answer is grounded in what you're actually working on. Small command, real problem solved. When Claude Code is hammering away on a 10 to 20 minute task and you've got a question, /BTW lets you ask in place instead of opening another terminal. ## What are Claude Code subagents and agent teams? This is the juicy one. I wrote an article about Claude Code agent teams a few weeks ago and it pulled over a million views on X. Agent teams let you spin up multiple full Claude Code sessions in parallel, each with its own context window and workspace, all coordinated by a lead agent. Subagents already existed. They're focused, lightweight workers spawned inside your main session that run a single task and report back. Think of a subagent as sending an assistant to fetch an answer. Agent teams are different. Each teammate is a fully independent Claude Code session with its own context window. The lead agent breaks the task into pieces, dispatches each piece to a teammate, manages a shared task list, and stitches the output together. You can jump in and message any teammate directly to redirect them. As I put it in the video: "It's like moving from being a freelancer doing everything solo to a project manager who shows up with a full crew and delegates across all of them." ### How to enable Claude Code agent teams Add the agent teams flag to your Claude Code config (a single JSON snippet in your env file) and restart with /exit. Easiest path: ask Claude Code itself to enable agent teams and paste in the JSON. To test it, give it a multi-role task: "team of agents reviewing my course curriculum, one is a skeptical student, one is a curriculum designer, one is a judge." Three agents spin up in parallel, each running its own Claude Code instance, and the lead compiles all three reviews into a single report. Heads up: agent teams burn considerably more tokens than a single session. It's like having three or four Claude Code sessions open at once, because that's what it is. Use it for genuinely parallelisable work (multi-perspective review, large refactors, content pipelines with distinct roles) and stick with sequential prompts for the simple stuff. > [CTA-BLUEPRINT] ## Where Claude Code falls short None of this comes for free. Three things to know before you crank every dial to max. First, costs scale fast. Effort on max plus agent teams plus loop in the background will hit Claude Max limits or burn API budget. Use /effort low for cheap work, reserve max for final review. Second, dangerous-skip-permissions exists for a reason and it's also a footgun. Running Claude Code with --dangerously-skip-permissions bypasses every approval prompt. I only use it inside a virtual machine. There are real horror stories of Claude Code wiping someone's entire computer when given full permission. Don't run skip-permissions on your daily-driver laptop unless you understand the risk. Third, /loop stops when you close the session. So it's a half-measure for true automation. If you want a process that runs whether your laptop is open or not, you still need n8n, a cron job on a VPS, or a deployed agent. Claude Code's loop is for in-session reminders, not production scheduling. ## How to update Claude Code A few of these features (especially /remote-control) only work on the latest Claude Code version. To update Claude Code, run npm update -g @anthropic-ai/claude-code in your terminal. Restart any open sessions with /exit and reopen with claude. You can verify the version with claude --version. If a slash command isn't showing up in your menu, the most common causes are: outdated CLI, you're authenticated with an API key when the feature requires a Claude subscription, or the feature flag isn't enabled in your settings file. Run /insight first. It often points at exactly which feature you're missing. ## Verdict: is Claude Code worth it now? Yes. With these 10 features in play, Claude Code stops feeling like a coding assistant and starts feeling like an engineering teammate. Insights audits how you work, effort tunes the brain, remote control puts it in your pocket, batch and simplify run multi-file work hands-off, hooks turn it into a programmable runtime, and agent teams move you from one worker to a crew. Who Claude Code is for: people building real software or automations who'll spend 30 minutes learning a few slash commands. Who it's not for: people who want a chat box. If you want a conversation, use the Claude desktop app. If you want a system that ships work, Claude Code is now the strongest agent on the market. Official [Anthropic Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) covers every command in detail, and the [Claude Code GitHub repo](https://github.com/anthropics/claude-code) lists every release with the exact features that shipped. Both worth bookmarking if you want to track what's new in Claude Code as it ships. For a worked example of how this kind of agent stack runs in production, the [case study with Keven Elison](/case-studies/kevin) walks through how he wired Claude Code, n8n, and MCP servers into a real B2B marketing operation. Same orchestration mindset, applied at scale. > [CTA-BLUEPRINT] ## Claude Code FAQ ### What is Claude Code? Claude Code is Anthropic's terminal-based coding agent. Install via npm, point it at a folder, and it can read your code, run commands, edit files, push commits, and connect to MCP servers. Same Claude model as the desktop app, with tools, memory, hooks, and a permission system layered on top. ### What's new in Claude Code? The latest Claude Code update introduces 10 standout features: /insight (30-day usage report), /effort (reasoning level control), /remote-control (drive sessions from your phone), /batch (parallel multi-file edits), /simplify (three-agent code review), /loop (cron-style scheduled prompts), escape-twice rewind, hooks (pre and post tool actions), /BTW (side questions), and agent teams (multiple parallel Claude Code instances coordinated by a lead). ### How do Claude Code skills work? Claude Code skills are scoped capabilities you load into a session. Each skill bundles a system prompt, tool permissions, and a reusable workflow. The /insight report often recommends specific skills based on the patterns it sees in your last 30 days. You install them by pasting the skill prompt into Claude Code, and from that point Claude can invoke the skill on demand. ### What are Claude Code subagents? Claude Code subagents are focused workers spawned inside your main session that run a single task and report back. They share your main context but execute their work in isolation. Subagents are lightweight and cheap on tokens. Agent teams are the heavier version: each teammate is a fully independent Claude Code session with its own context window, coordinated by a lead agent. ### Is Claude Code free? The Claude Code CLI is free to install. What costs money is the model behind it. You can connect Claude Code to a Claude Pro or Claude Max subscription (a flat monthly fee covers your usage up to the plan's limits) or to an Anthropic API key (pay per token). Claude Max is the best value if you're using Claude Code daily, because effort, agent teams, and loops can burn tokens fast on the API. ### How do I update Claude Code? Run npm update -g @anthropic-ai/claude-code in your terminal, then restart any open sessions with /exit and reopen with claude. Verify the new version with claude --version. Several of the newest features only show up on the latest version, so update first if a slash command isn't appearing. ### What is Claude Code MCP? Claude Code MCP refers to Model Context Protocol servers that plug into Claude Code as tools. You can connect Claude Code to your inbox, your CRM, your project management board, your file system, anything that has an MCP server. Once connected, Claude Code can read and act on those services inside any session, which is what makes commands like /loop "check my inbox" actually work. ### What's the difference between Claude Code and the Claude desktop app? The Claude desktop app is a chat interface for the same model. Claude Code is the terminal harness with tools, memory, hooks, slash commands, MCP integration, agent teams, and direct file system access. If you want a conversation, use the desktop app. If you want a system that ships work, use Claude Code. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [The best Claude Code skills](/blog/best-claude-code-skills) - [Claude Code commands and slash commands](/blog/claude-code-commands) - [Claude Code hooks](/blog/claude-code-hooks) ## Sources and official documentation Primary sources referenced in this guide: - [Claude Code on GitHub](https://github.com/anthropics/claude-code) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) ## Ready to build production-ready AI systems with Claude Code? Knowing the features is half of it. Most people stall out because they open Claude Code, have no idea what to build, and close the terminal again. The [30-Day Claude Code Challenge](/challenge) fixes that. You start by building something concrete inside Claude Code itself. There are four live calls where I go through your builds and unblock anything that's stuck, and by the end you have a deployed agent with a real URL running on a real schedule. Not ready for the challenge? Grab the [free Claude Code Blueprint](/blueprint) first. It's the foundation every Claude Code workflow on this page sits on top of, and it'll take you from terminal-curious to first-build in 60 minutes. ## Frequently Asked Questions ### What are the 10 new Claude Code features I should know about? Insights (/insight, a 30-day usage audit), effort (/effort, five reasoning levels), remote control (/remote-control, drive sessions from your phone), batch (/batch, parallel multi-file edits), simplify (/simplify, three review agents at once), loop (/loop, cron-style scheduled prompts), escape-twice rewind, hooks (pre and post tool actions), /BTW for side questions, and agent teams. Agent teams is the big one. Multiple full Claude Code instances running in parallel, coordinated by a lead agent. ### How do I update Claude Code so the new commands show up? Run npm update -g @anthropic-ai/claude-code in your terminal, then restart open sessions with /exit and reopen with claude. Verify the version with claude --version. Several of the newest features (especially /remote-control) only appear on the latest version. If a slash command is missing from your menu, the cause is usually an outdated CLI, an API key where a Claude subscription is required, or a feature flag that is not enabled. ### Will agent teams blow up my token bill? Yes, if you use them for everything. Agent teams burn considerably more tokens than a single session because each teammate is a fully independent Claude Code session with its own context window. Reserve them for genuinely parallelisable work like multi-perspective review, large refactors, or content pipelines with distinct roles. Use sequential prompts for the simple stuff. On the API, /effort low for cheap work and max for final review is the single biggest cost lever. ### Is --dangerously-skip-permissions safe to use? Not on your main machine. The flag exists for a reason and it is also a footgun. There are real horror stories of Claude Code wiping someone's entire computer when given full permission. I only run it inside a virtual machine. If you are running it on your daily-driver laptop without understanding the risk, stop. ### Can I use /loop instead of n8n for production automations? No. /loop stops the moment you close the Claude Code session, so it is a half-measure for true automation. Use it for in-session reminders, like a ping when something specific lands in your inbox, or a commit-your-work nudge every hour. For anything that has to run whether your laptop is open or not, you still need n8n, a cron job on a VPS, or a deployed agent. ### Who is Claude Code actually for now? People building real software or automations who will spend 30 minutes learning a few slash commands. With these 10 features in play, Claude Code stops feeling like a coding assistant and starts feeling like an engineering teammate. If you want a conversation, use the Claude desktop app. If you want a system that ships work, Claude Code is the strongest agent on the market right now. --- # How to Use Claude Code: The 60-Minute Beginner Guide Source: https://theaiarchitects.com/blog/how-to-use-claude-code Published: 2026-05-13 How to use Claude Code in 60 minutes: install it, write CLAUDE.md, build a slash command, add a skill, run subagents in parallel, deploy to Vercel. You use Claude Code by installing the desktop or CLI version, opening a project folder, writing a [CLAUDE.md file](/blog/claude-code-memory) that tells the model what you're building, then driving it with slash commands, skills, MCP connections, and parallel subagents. That sentence is the whole job. The rest of this post is how to do each piece in about 60 minutes. I'm Tom. I run AI Architects and teach Claude Code to non-developers every week. I built a free 60-minute walkthrough called the Blueprint that takes a beginner from a fresh install to a public URL. Everything below is pulled from it and from watching real students get stuck and unstuck. > [CTA-BLUEPRINT] ## What is Claude Code? Claude Code is the agentic version of Claude that lives on your machine and edits your files, runs your commands, calls external services, and spawns sub-sessions of itself when work splits into parallel pieces. It comes in two flavours, a desktop app and a command-line tool, both signed in with the same Claude account. The bit most tutorials miss is that Claude Code is not a chatbot with file access. It is a project-shaped tool. Once you point it at a folder it reads a [CLAUDE.md file](/blog/claude-code-memory) at the root and treats every prompt as a request to do work inside that folder. That mental model is what makes the rest of this guide make sense. ## Before you start: what you'll need Four things, open and signed in before you type your first prompt: a Claude account on the standard plan or higher (the free tier will frustrate you on a first project), the Claude Code desktop app or CLI installed and signed in, a free Airtable account at airtable.com (we'll use it as the database), and a free Vercel account at vercel.com (you'll deploy to it in Step 6). You do NOT need coding experience, knowledge of git or npm, or a domain name. Claude Code does the heavy lifting. Your job is to point and confirm. ## Step 1: Install Claude Code [Claude Code installs in one of two ways](/blog/how-to-install-claude-code) depending on whether you prefer a graphical app or a terminal. Pick one. Both work. Most beginners I teach pick the desktop app. ### How do I install Claude Code on the desktop? Go to [claude.com/claude-code](https://www.claude.com/claude-code) and download the desktop app for Mac, Windows, or Linux. Install it like any other app. Open it and sign in with the same account you use on claude.ai. The first launch will offer to open a folder. Skip that for now and read Step 2 first. ### How do I install Claude Code from the command line? If you're comfortable with a terminal, run npm install -g @anthropic-ai/claude-code in your shell. Then run claude in the folder you want to work in. The first run prompts you to sign in via a browser. The official docs at [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code) cover Linux, WSL, and Ubuntu edge cases. ### Which Claude Code install should I pick? If you've never opened a terminal, install the desktop app. The interface is friendlier and the file tree is what you'd expect from VS Code. If you already live in a terminal, the CLI is faster to launch. The project folder is the same either way. ## Step 2: Set up your [CLAUDE.md file](/blog/claude-code-memory) Create a folder called brief-generator. Lowercase, hyphen, no spaces. Open it in Claude Code: in the desktop app, choose Open Folder. In the CLI, run claude inside the folder. ### What is a [CLAUDE.md file](/blog/claude-code-memory)? A [CLAUDE.md file](/blog/claude-code-memory) is a markdown document at the root of your project that Claude Code reads at the start of every session. It is the standing brief for the project. It tells Claude what you're building, which files matter, how you want changes made, and any rules of the road. Without one, Claude has to be re-briefed every session. With one, you start work in two seconds instead of two minutes. In the chat, send: Create a CLAUDE.md file in this folder with the content I'll paste next. Then paste a brief that names the project (Brief Generator), the stack (Claude Code desktop app, Airtable MCP, one skill called company-brief), how you work (confirm before non-trivial changes, edit existing files only, be concrete), and what lives where (.claude/commands/ for slash commands, .claude/skills/ for skills, briefs/ for local copies). This is the same CLAUDE.md I have Blueprint students use on lesson one. Test that the file is being read. Send: Without reading any files, what's this project about? Claude should answer correctly without being told to look at CLAUDE.md. If it doesn't, restart the session. CLAUDE.md is loaded at session start, not mid-session. ## Step 3: Create your first slash command [Slash commands turn a prompt](/blog/claude-code-commands) you'd otherwise type fifty times a week into one keystroke. The file lives at .claude/commands/.md. The dot in front of .claude is intentional. Some file viewers hide it. The folder is still there. ### How do I create a slash command in Claude Code? Send in chat: Create a new file at .claude/commands/brief.md with the content I'll paste next. Paste a markdown file with a frontmatter description and a body saying: You are running the /brief command. The user will give a company name or URL. If a company-brief skill is installed, use it. Otherwise generate a basic brief with Summary, Recent News, Key People, Suggested Angles. Test it. Type /brief stripe.com. Claude should respond with a structured brief on Stripe. If /brief is treated as plain text, the file is in the wrong place. Confirm the path is exactly .claude/commands/brief.md and restart the session. That fixes 90% of slash command issues. ## Step 4: Add a skill and connect an MCP server A slash command is a one-shot prompt. [A skill is a reusable instruction set](/blog/claude-code-skills) Claude loads when the topic comes up. [An MCP is a connection to an external system](/blog/claude-code-mcp) so Claude can read and write outside the file tree. You're about to use all three together. This is the basic shape of every internal tool you'll build with Claude Code. ### What are Claude Code skills? Claude Code skills are folders inside .claude/skills/ containing a SKILL.md file. The frontmatter has a name and a description. The body teaches Claude how to do a job: what input to expect, what the output looks like, where to save it. Claude loads a skill automatically the moment a matching task comes up. You don't have to re-paste instructions. Install the Airtable MCP. In Claude Code's settings or extensions, find the MCP/plugins section, find Airtable, click install, and either sign in with Airtable or paste a personal access token from airtable.com/create/tokens with scopes data.records:read, data.records:write, and schema.bases:read. Create the base. In airtable.com, click Add a base, name it Brief Generator. Rename the default table to Briefs. Set up exactly five fields in order: Company (single line text), Summary (long text), Recent News (long text), Key People (long text), Date (date). The skill references these names verbatim, so don't get creative. Confirm Claude can see the base. Send: List the bases I have access to in Airtable. Brief Generator should show up. Then ask Claude to list the fields in the Briefs table. You should get back the five field names. Now write the skill at .claude/skills/company-brief/SKILL.md. The frontmatter sets the name (company-brief) and a description that names the trigger words (Use whenever the user asks for a brief or runs the /brief slash command). The body specifies four sections: Summary (2-4 concrete sentences), Recent News (2-4 dated bullets), Key People (2-4 bullets with name, role, one specific fact), Suggested Angles. Print the brief, save to Airtable mapped Company, Summary, Recent News, Key People, Date, confirm the record ID back to the user. Run /brief on a real company. The brief prints. The MCP write fires. Refresh your Airtable tab and there's a row. That's the moment most people realise Claude Code is not a chatbot. > [CTA-BLUEPRINT] ## Step 5: Run subagents in parallel Up to here, Claude has been doing one thing at a time. Step 5 is the upgrade that makes Claude Code feel different from [every other AI tool](/tools/claude-status). You teach the skill to [spawn three Claude sub-sessions](/blog/claude-code-subagents-vs-skills) at the same time and [merge their output](/blog/claude-code-ralph-loop). ### What are Claude Code subagents? A subagent is a separate Claude session your main session spawns using the Agent tool. Each has its own clean context window, does the focused job you give it, and returns a short summary. The main session only sees the summary. When you spawn three at once, they run in parallel. Three focused researchers in roughly the wall-clock time of one. Replace the contents of SKILL.md with a parallel version. The body says: produce a one-page research brief by running three subagents in parallel using the Agent tool. Subagent A (Website researcher) reads the homepage, About, and pricing pages and returns Summary and Product Notes. Subagent B (News researcher) searches the last 12 months for funding, launches, leadership changes, returns 3-5 dated bullets. Subagent C (Key People) returns 2-4 bullets with name, role, and one specific fact each. The critical line in the skill: dispatch all three Agent calls in a single message so they run simultaneously, not in sequence. The main session assembles the sections, writes a Suggested Angles section based on combined findings, prints, then saves to Airtable. Run /brief on a different company. You'll see three Agent tool calls fire at once. If you only see one, the parallelism didn't trigger. Send: Re-run, but make all three Agent calls in a single tool-use message so they run simultaneously. That fixes it. Compare the new brief to the Step 4 one. The new one has sharper Recent News, richer Key People, and a Product Notes section the old one didn't have. Each subagent had a clean context focused on one job. Three focused Claudes per task is what makes Claude Code feel like a team. ## Step 6: Deploy your project to Vercel You have briefs in Airtable. They live behind your login. [Step 6 puts a public showcase page on the internet](/blog/claude-code-web). Claude builds the page. Vercel hosts it. You don't write any HTML. ### How do I deploy a Claude Code project to Vercel? Sign up free at [vercel.com](https://vercel.com) on the Hobby plan. Back in Claude Code, send a single prompt: Create a new folder at the project root called showcase. Inside it, create a single file called index.html that displays a list of company briefs. Read the most recent 10 briefs from the Briefs table of the Brief Generator base in Airtable. For each brief, render a card with Company as the heading, Summary as a paragraph, Recent News and Key People as bullets, Date as small grey text. Single static HTML file with inline CSS, no frameworks, no build step, max width 720px, readable on mobile. Claude reads your briefs through the MCP and writes showcase/index.html. Open the file in your browser to preview. If anything looks off, tell Claude in plain language and refresh the tab. Now deploy. The simplest path is drag and drop. Go to vercel.com/new, drag the showcase folder onto the page, click the URL Vercel gives you. If the drag and drop UI has moved, ask Claude to install the Vercel CLI and deploy the showcase folder. Either way you end with a *.vercel.app URL that loads on any device. That's the proof. ## Common Claude Code mistakes (and how to avoid them) I've watched dozens of beginners go through this build. Five mistakes show up over and over. ### Skipping the CLAUDE.md file People send their first prompt before writing any project context. Claude has to guess. The output is generic. The fix takes two minutes: write a 10-line CLAUDE.md before you do anything else. Every project I build starts with one. ### Writing skills the model can't find A skill is only useful if Claude knows when to load it. The frontmatter description is the trigger. Vague descriptions like 'Helps with research' don't fire. Specific descriptions like 'Use whenever the user asks for a brief or runs the /brief slash command' do. If your skill isn't being picked up, rewrite the description to name the trigger words verbatim. ### Running subagents in sequence by accident If you call the Agent tool in three separate messages, they run one after another. You lose the parallelism. The fix: tell Claude to dispatch all three Agent calls in a single tool-use message. The skill should specify this in writing. ### Treating Claude Code like a chatbot Claude Code's value is in the project context, file edits, MCPs, and subagents. If you're using it like claude.ai in a tab, you're paying for features you're not using. Every prompt is a request to do work inside the folder. The folder is the project. CLAUDE.md is the brief. Slash commands are macros. Skills are playbooks. MCPs are the wires to the outside world. ### Building something nobody will use Most people pick the wrong process to automate first. They reach for something judgement-heavy, spend a week building it, end up with a tool worse than doing it manually. Look for the opposite: repetitive plus research-heavy plus structured output equals a candidate. Judgement-heavy or one-off, leave it alone. Company research is the textbook case. Pick yours the same way. ## Is Claude Code free? [Claude Code itself is free to download](/blog/is-claude-code-free) and use. The cost is in the Claude usage that powers it. The [free Claude tier](/blog/claude-code-pricing) gives you a [small amount of Claude Code time per day](/blog/claude-code-rate-limits), enough to test but not enough to build the Brief Generator end to end. The Pro plan at $20/month covers most beginners and the Max plan covers heavy users. Anthropic's pricing page at [anthropic.com/pricing](https://www.anthropic.com/pricing) has the current limits. As of April 2026 they updated the Pro tier limits, so always check the live page rather than third-party guides. ## How long does it take to learn Claude Code? Sixty minutes for the first usable build, thirty days to confidence. The [Blueprint](/blueprint) takes most students 60 to 80 minutes to go from a fresh install to a public URL. After that they can repeat the pattern on their own. The [30-Day Challenge](/challenge) takes people from one build to four or five, including production reliability, scheduling, and multiple MCPs. If you want a sense of how non-coders progress, read [Kevin's case study](/case-studies/kevin) and [Chris Cole's case study](/case-studies/chris-cole), both built real internal tools without a developer background. ## Verdict: who Claude Code is actually for Claude Code is for operators and founders who want to build internal tools without hiring a developer. It is not a chatbot and it is not a no-code visual builder. It sits in the middle. You write project briefs in plain English, point Claude at external systems, let it spawn parallel sessions when work splits, and ship the result to the public internet. If you've ever thought 'I'd build this myself if I could code', Claude Code is the answer. If you're a developer, it is a force multiplier on the work you already do. If you just want to ask a model questions, stay on claude.ai. > [CTA-BLUEPRINT] ## Claude Code FAQ ### What is Claude Code? Claude Code is Anthropic's terminal and desktop coding agent. It opens a project folder, reads a CLAUDE.md file at the root, edits your files, calls external services through MCPs, and spawns parallel subagents when work splits naturally. Same Claude models as claude.ai, designed for project work instead of chat. ### How do I install Claude Code? Download the desktop app at [claude.com/claude-code](https://www.claude.com/claude-code) or install the CLI with npm install -g @anthropic-ai/claude-code. Sign in with the same account you use on claude.ai. Open a folder. The full install matrix for Mac, Windows, Linux, and WSL is at [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code). Once installed it keeps itself current in the background, and here is [how to update Claude Code](/blog/claude-code-update) if you ever need to force it. ### Is Claude Code free? [Claude Code itself is free to download](/blog/is-claude-code-free). The Claude usage behind it costs. The free tier gives you a small daily quota. Pro at $20/month covers most beginner workflows. Max covers heavy users. Anthropic adjusts the limits periodically, so check the live pricing page. ### What is a CLAUDE.md file? A markdown file at the root of your project that Claude reads at the start of every session. It tells Claude what you're building, which folders mean what, and how you want changes made. Without it, you're re-explaining the project on every prompt. ### What are Claude Code skills? Reusable instruction folders inside .claude/skills/. Each has a SKILL.md with frontmatter (name and description) and a body teaching Claude how to do a job. Claude loads a skill automatically when the description matches the user's request. Skills are how you stop pasting the same instructions over and over. ### What are Claude Code subagents? Separate Claude sessions your main session spawns using the Agent tool. Each one has a clean context window. Called in a single message, they run in parallel. Use them when work splits into independent pieces. The main session merges the summaries. ### How long does it take to learn Claude Code? About 60 minutes to a working first project using the Blueprint. About 30 days to confidence on multiple projects using the Challenge. After that you stop learning Claude Code itself and start learning what to point it at. ### Can non-developers use Claude Code? Yes. Most of the people I teach in the Blueprint and the Challenge cohort are not developers. [Kevin](/case-studies/kevin) is a service business owner. [Chris Cole](/case-studies/chris-cole) runs a property company. Both built real tools without writing code themselves. Claude does the writing. You do the directing. ### Where can I find the Claude Code GitHub repo? Examples, plugins, and reference skills live at [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code). The core agent is closed-source but the surrounding ecosystem of skills and plugins is public. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [How to install Claude Code](/blog/how-to-install-claude-code) - [Claude Code commands cheat sheet](/blog/claude-code-commands) - [Claude Code memory (CLAUDE.md, Auto Memory, Path Rules)](/blog/claude-code-memory) ## Sources and official documentation Primary sources referenced in this guide: - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) ## Ready to build your first Claude Code project? If you read this far you have the mental model. The fastest way to internalise it is to build the Brief Generator end to end. The [Blueprint](/blueprint) walks you through it in 60 minutes, free. For the production version with multiple MCPs, scheduled briefs, and team workflows, the [30-Day Challenge](/challenge) is where I take people next. ## Frequently Asked Questions ### How do I use Claude Code as a beginner? Install Claude Code (desktop app or npm install -g @anthropic-ai/claude-code), open a project folder, write a CLAUDE.md at the root, then drive it with slash commands, skills, MCP connections, and parallel subagents. The Blueprint walkthrough takes a beginner from a fresh install to a public Vercel URL in about 60 minutes. You point and confirm. Claude does the heavy lifting. ### Do I need to know how to code to use Claude Code? No. Most of the people I teach in the Blueprint and the Challenge cohort are not developers. Kevin runs a service business. Chris Cole runs a property company. Both built real internal tools without writing code themselves. Claude does the writing. You do the directing. ### Is Claude Code free? Claude Code itself is free to download. The Claude usage behind it costs money. The free tier gives you a small daily quota, enough to test but not enough to build the Brief Generator end to end. Pro at $20/month covers most beginners. Max covers heavy users. Anthropic adjusts the limits periodically, so check the live pricing page. ### What is the difference between Claude Code and the Claude desktop app at claude.ai? Claude.ai is a chat interface. Claude Code is a project-shaped tool. Once you point it at a folder it reads CLAUDE.md and treats every prompt as a request to do work inside that folder. It edits files, runs commands, calls external services through MCPs, and spawns parallel subagents. If you just want to ask questions, stay on claude.ai. If you want a system that ships work, use Claude Code. ### Why are my subagents running one after another instead of in parallel? If you call the Agent tool in three separate messages, they run sequentially. The fix is to tell Claude to dispatch all three Agent calls in a single tool-use message. Write that line into your skill verbatim. If you only see one Agent tool call when you expected three, send: 'Re-run, but make all three Agent calls in a single tool-use message so they run simultaneously.' ### Why isn't my slash command working? Ninety percent of slash command issues are a wrong file path. Confirm the file is at exactly .claude/commands/.md (the dot in front of .claude is intentional, some viewers hide it) and restart the session. If /brief is still being treated as plain text, the file is in the wrong place or the session was started before the file existed. ### What should I build first with Claude Code? Look for repetitive plus research-heavy plus structured output. Company research briefs are the textbook case, which is why the Blueprint uses them. Avoid judgement-heavy or one-off tasks. Most beginners pick something judgement-heavy, spend a week on it, and end up with a tool that is worse than doing the work manually. - [Claude Code Tutorial: The Only One You Need](/blog/claude-code-tutorial) --- # Is n8n Dead in 2026? My Honest Verdict After 8 Years Source: https://theaiarchitects.com/blog/is-n8n-dead-in-2026 Published: 2026-05-13 Is n8n dead in 2026? No. It is still relevant for production automations. My honest take after 8 years in automation, plus a real student case study. No, n8n is not dead in 2026. n8n is a visual workflow automation tool that lets non-technical people build production-ready automations and AI agents on a canvas, with full execution logs, schedule-based runs, and team-readable workflows. Quick disambiguation. "n8n" (pronounced n-eight-n) is the open-source workflow automation platform from [n8n.io](https://n8n.partnerlinks.io/mk0n45p9qc40). Not to be confused with N8 model designations or generic AI tools that get bundled into the same searches. This post is about the actual product you self-host or run on n8n cloud, the one with nodes, triggers, and a visual canvas. I'm Tom. I've been in the automation space for over 8 years and generated over $25 million in revenue for my clients. Every YouTube creator right now is screaming that n8n is dead because Claude Code, Open Claude, and Lovable are taking over. I'll show you why that take is wrong, where it's half-right, and where n8n still wins for any team that actually has to run real operations in 2026. > [CTA-BLUEPRINT] ## What is n8n? n8n is a fair-code visual workflow automation platform from [n8n.io](https://n8n.partnerlinks.io/mk0n45p9qc40). You build workflows by dragging nodes onto a canvas, connecting them with lines, and configuring each step. A node can be a trigger (webhook, cron, email received), an action (send a message, update a row, call an API), or a logic block (if/else, switch, merge). It supports HTTP requests to anything, native integrations with hundreds of apps, and AI agent nodes that wrap LLMs like OpenAI, Anthropic, and Google. You can run n8n two ways. n8n Cloud currently lists Starter at €20 a month when billed annually, with 2,500 workflow executions, and Pro at €50 a month when billed annually, with 10,000 workflow executions. Both plans include unlimited steps per execution. Or you can self-host n8n on your own infrastructure. The free Community edition does not require a license key, but your infrastructure cost and capacity are yours to manage. Here's the full video where I break this down on YouTube: https://www.youtube.com/watch?v=kA7LPKBaaBI ## How does n8n work? n8n works on a simple loop. A trigger fires, data flows through the nodes you've connected, each node transforms or sends that data, and the workflow finishes. You can branch, loop, retry, and merge data along the way. Every execution is logged, so you can replay it, see exactly what data came through each node, and pinpoint where things broke. ### Triggers and the visual canvas You can see every step, every trigger, every decision laid out on a canvas like a map. That visual layout is the appeal for most people getting into this. With the right documentation, anyone on your team can open it up and understand what the system is doing without needing to read code. ### Execution logs and debugging When something breaks, n8n shows you the execution logs, exactly which node failed, what data came through, and where it went wrong. You can hopefully diagnose a problem in just a few minutes. Code-based automations give you stack traces, and if you know what you're looking at, great. Most people don't. ### AI agents inside n8n n8n's official AI material describes workflows that combine AI agents with explicit logic, human approvals, code, and 500+ integrations. You can inspect executions, including the prompt sent, model response, and what happened next. People are already using Claude Code to build n8n workflows through MCPs. That's how I create most of my workflows in n8n today. The two tools sit together, not against each other. ## Is n8n dead? No, n8n is not dead. The chatter on YouTube saying "n8n is dead" is content theatre. "n8n is dead" gets more clicks than "these tools work together," so creators frame every video as a fight. The Google Trends chart looks dramatic because Claude Code went vertical, but interest in Claude Code rising is not the same as interest in n8n collapsing. n8n is actually growing. Multi-billion-dollar companies are running real operations on n8n every single day. The [open-source repo on GitHub](https://github.com/n8n-io/n8n) sits in the top automation projects on the platform, with active releases, a huge contributor base, and a massive node ecosystem. That's not a dead project. That's a maturing one. ## Is n8n still good in 2026? Yes. n8n is still good in 2026 because it does four things no code-only tool can replace right now. These are the things that actually matter when you're trying to build production-ready automations for your work, not a YouTube demo. 1. You can actually see the logic. n8n is visual, every step on a canvas. Claude Code hides that logic in code. Developers can read it. Everyone else has no idea, including me, when I'm staring at someone else's repo at midnight. 1. Your team can maintain it without you. The thing that kills most code-based automations is simple. The person who built it leaves, gets busy, or moves on. Suddenly nobody can touch the system because nobody understands it. In n8n, someone on your team can literally open the workflow, click a node, change something, and hit save. 1. When something breaks, you can find out why fast. Execution logs in n8n show every node, every payload, every failure point in plain English data. You don't need a software engineer or a developer to understand or tweak the system. You just need good documentation. 1. It runs reliably on a schedule without you having to baby-sit it. Finding qualified leads at 8am every morning. Sending follow-up sequences every 36 hours. Creating and maintaining weekly reports. n8n was built for work like this, work that needs to run in the background consistently without anyone touching it. ## Is n8n still relevant in 2026? Yes, n8n is still relevant in 2026. Install base, integration library, and teams running production workloads on it have all grown year over year. The "n8n is dead" YouTube narrative is content theatre, not a fact about the company. Two facts tell the story. n8n's current official product pages describe active cloud plans, self-hosted editions, and AI workflows built around explicit logic and human approvals. On real production workloads (scheduled sequences touching 5+ tools, webhook intake, dispatcher review queues), n8n still ships in days where Claude Code alone takes weeks of debugging. Where it stops being relevant is the lane n8n was never built for. Custom software and long-running AI agents with their own UIs are Claude Code's lane, not n8n's. If your question is whether n8n is worth investing time in for production automations in 2026, the answer is yes. If your question is whether n8n is the right tool to build your next AI product, the answer is no. ## What I built with n8n: Cal Hewitt's dispatch workflow If you still don't believe n8n is the real deal, here's an example of what I mean. [Cal Hewitt](/case-studies/cal-hewitt) is one of my students. He works in commercial construction and facility management over in Toronto. He's non-technical with zero coding experience. His company gets slammed with service requests every single day. Each one needs to be categorised, matched to the right contractor in the right area, and dispatched fast. The entire process was manual, 30 to 45 minutes per request. Cal built an n8n workflow that handles everything. The email comes in, AI categorises it, the system matches and ranks the right contractor for the job. A dispatcher reviews and approves the match before anything goes out. Human in the loop. Then the contractor gets notified with all the job details. He automated the whole process using AI inside n8n. What used to take 30 to 45 minutes for every request is now down to just seconds. And here's the part that actually matters. Cal's company asked him to present the system to the board, who are non-technical people. People who have never seen an AI automation tool in their lives. Because it was built in n8n, Cal didn't need to explain how the code works. He didn't need to walk them through scripts and files. He just pulled up the workflow and walked them through each step on the canvas. Cal went from a regular employee to the person his company can't afford to lose, and he's getting invited to build more projects. That doesn't happen with a Python script. It only happens with a tool like n8n. https://www.youtube.com/watch?v=j7AjCeXVuQw ## Where n8n falls short Honest review section. n8n is not perfect, and I'm not pretending it is. First, complex AI agents and custom software are not n8n's lane. If you're building a multi-step coding agent that writes its own code, debugs itself, and ships features, Claude Code is better suited. n8n can host that agent's tool calls, but writing the agent itself in n8n gets messy fast. Second, n8n Cloud plans have execution allowances that matter on serious workloads. Starter lists 2,500 workflow executions and Pro lists 10,000 when billed annually, while each execution includes unlimited steps. Self-hosting removes n8n Cloud's plan allowance, but you take on infrastructure capacity, security, upgrades, and backups. Third, the learning curve is steeper than tools like Zapier or Make. The visual canvas is a feature, not a shortcut. You still need to understand triggers, expressions, and how data moves between nodes. Most people get over the curve in a weekend, but it's a curve. ## How to install n8n on a VPS You can self-host n8n on a VPS for a fraction of what n8n cloud is going to charge. Here's the path I use. ### Step 1: Pick a VPS I personally use [Hostinger](https://hostinger.com/GROWTHLAB) for my VPS needs. The provider's price depends on the plan and billing term, so check the current offer before quoting a monthly number. With self-hosting, you control the environment, but you also own the capacity, security, updates, and backups. ### Step 2: Use the one-click n8n install [Hostinger](https://hostinger.com/GROWTHLAB) has a simple one-click n8n install you can run to get started without any issues. Pick a plan, deploy the template, and the install handles Docker, the database, and the n8n container for you. Takes a couple of minutes from sign-up to first login. ### Step 3: Lock down access and import a workflow Set up basic auth, point a subdomain at the VPS, and add SSL through your hosting dashboard. Then import a starter workflow JSON, swap the credentials for your own, and run a test execution. If the first run goes green, you're production-ready. > [CTA-HOSTINGER] | Self-host n8n on Hostinger VPS | Run n8n on a real VPS, not your laptop. The Hostinger KVM plan handles it cleanly and keeps your workflows online 24/7. | Spin up your VPS | http://hostinger.com/GROWTHLAB | GROWTHLAB ## n8n vs Zapier n8n vs Zapier comes down to power versus polish. Zapier is the polished default. Click two apps, connect them, done. Great for marketers and operators who need a simple A-to-B trigger and don't care about cost per task. The pricing scales aggressively as soon as you ship anything serious. n8n is the power tool. You get branching logic, code nodes, AI agent nodes, custom HTTP requests, and self-hosting. The trade-off is the learning curve. If you only ever need a Slack-to-Sheets zap, stick with Zapier. If you want to run a real automation system across your business without execution caps eating your budget, n8n wins on every dimension that matters past month one. ## n8n vs Make n8n vs [Make](https://www.make.com) is the closer fight, because Make (formerly Integromat) is also visual and node-based. The difference is openness. n8n is fair-code, self-hostable, and lets you drop into a Code node and write JavaScript or Python whenever the visual nodes can't do what you need. Make is fully cloud-locked, with a per-operation pricing model that adds up fast on high-volume workflows. For a non-technical user running a few visual scenarios, Make is friendlier out of the box. For anyone planning to scale, self-host, or own their data, n8n is the better long-term bet. ## n8n vs Claude Code This is the comparison every YouTuber is botching, so let's be precise. Claude Code is awesome. You describe what you want, it writes the code, it writes the content, whatever you're doing. It fixes its own errors. I use it every single day for a bunch of different tasks across different skills and different projects. I'm not denying any of that. But there are things that n8n does that no coding tool can replace right now. Claude Code is great for building custom software or complex AI agents. You can use Open Claude as your personal AI assistant. The automations that connect your systems, run on a schedule, and your whole team can see and understand, n8n is going to be your best bet there. And here's the real kicker. People are already using Claude Code to build n8n workflows through MCPs. That's how I create most of my workflows in n8n today. The smart play in 2026 is using both, not picking sides for the algorithm. ## Verdict: is n8n worth learning in 2026? Yes, n8n is worth learning in 2026. Direct opinion. The people who are actually building systems that their companies depend on every day are using n8n, and they're becoming irreplaceable, while everyone else is still arguing about the best tool on YouTube. Who n8n is for: non-technical professionals who want to automate real work inside their job or business, agency owners who deliver automation to clients, and operators who need a system the rest of the team can read. Who it's not for: developers who only ever need to ship code-based agents and have no team to hand things off to. For everyone in the middle, which is most people, n8n is the tool you should know in 2026. > [CTA-BLUEPRINT] ## n8n FAQ ### Is n8n dead? No, n8n is not dead. The "n8n is dead" framing on YouTube is clickbait. n8n is actively maintained, growing on GitHub, used by multi-billion-dollar companies in production, and increasingly paired with Claude Code through MCP servers rather than replaced by it. ### Is n8n still good in 2026? Yes. n8n is still the best tool in 2026 for visual, team-readable automations that need to run on a schedule. It wins on transparency (visual canvas), maintainability (anyone on your team can edit it), debugging (full execution logs), and reliability (background runs without baby-sitting). ### Is n8n still relevant in 2026? Yes, n8n is still relevant in 2026. n8n's official product pages describe active cloud plans, self-hosted editions, and AI workflows built around explicit logic and human approvals. Production workloads that touch 5+ tools still go from weeks to days when you build them on n8n. It is not the right tool for building a custom AI product, but it remains relevant for production automations inside a company. ### What is n8n used for? n8n is used for workflow automation: lead routing, email follow-up sequences, weekly reports, AI agent orchestration, CRM updates, content pipelines, support triage, and any process that connects multiple apps and runs on a schedule. The Cal Hewitt dispatch workflow above is a typical real-world example. ### Is n8n free? n8n is fair-code, source-available, and free to self-host with the Community edition when no license key is provided. You pay for the infrastructure you choose, and you manage its capacity, security, updates, and backups. n8n Cloud currently lists Starter at €20 a month when billed annually with 2,500 workflow executions, and Pro at €50 a month when billed annually with 10,000 workflow executions. Both include unlimited steps per execution. ### Is n8n better than Zapier? For anything beyond a basic two-app trigger, yes. n8n gives you branching logic, code nodes, AI agent nodes, custom HTTP requests, and self-hosting at a fraction of the long-term cost. Zapier wins on initial polish and simplicity. n8n wins on power, control, and total cost of ownership. ### Should I use n8n or Claude Code? Both. Use Claude Code to build custom software, complex agents, and to scaffold n8n workflows through the n8n MCP server. Use n8n to host the automations that have to run on a schedule, in the background, that your team needs to read and maintain. They're complementary, not competing. ### Where can I host n8n cheaply? A VPS like [Hostinger](https://hostinger.com/GROWTHLAB) can cost more or less depending on the plan and billing term, so check the provider's current offer before quoting a monthly number. Self-hosting gives you control over the environment, but you manage its capacity, security, updates, and backups.[r/n8n subreddit](https://www.reddit.com/r/n8n/) include DigitalOcean, Hetzner, and Railway, each with their own trade-offs on pricing, region, and ease of setup. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Claude Agent SDK explained](/blog/claude-agent-sdk) - [Claude Code plugins](/blog/claude-plugins) - [Claude Code MCP integrations](/blog/claude-code-mcp) ## Sources and official documentation Primary sources referenced in this guide: [n8n.io official site](https://n8n.io/) [n8n documentation (home)](https://docs.n8n.io/) [n8n hosting overview (self-host vs cloud)](https://docs.n8n.io/hosting/) [n8n pricing (current tiers)](https://n8n.io/pricing/) [n8n integrations and built-in nodes](https://docs.n8n.io/integrations/builtin/) [n8n GitHub repository](https://github.com/n8n-io/n8n) [n8n GitHub releases](https://github.com/n8n-io/n8n/releases) [n8n workflow nodes reference](https://docs.n8n.io/workflows/components/nodes/) [n8n AI page](https://n8n.io/ai/) ## Ready to build automations your company can't replace? In just 16 weeks, I'll take you from zero to AI operator that your company simply cannot afford to replace. The [30-Day Claude Code Challenge](/challenge) is the on-ramp into the full mentorship. You'll build your first real n8n automation, your first AI agent, and the foundation that students like Cal Hewitt have used to make themselves indispensable. Not ready for the challenge? Grab the [free Claude Code Blueprint](/blueprint) first. Sixty minutes, no coding required, and you'll have a working automation by the end. It's the fastest way to test whether this stack is for you before you commit to the full thing. --- # OpenClaw: 95% Cheaper Than Claude Code (Real Setup) Source: https://theaiarchitects.com/blog/openclaw-95-percent-cheaper-than-claude Published: 2026-05-12 OpenClaw setup that cuts your Claude Code bill by 95%. Open Router, model routing, heartbeat tuning, QMD, and the exact config I use. OpenClaw is a free, open-source agent harness for Claude Code that lets you run autonomous AI agents on a VPS or your own machine, controlled through Telegram or WhatsApp. The catch: most people install it, plug in Claude Opus 4.6 as the default, and burn $300 to $600 a month on API credits. One person on Reddit reported $3,600 in a single month. Configured properly, the same setup runs for $6 to $25 a month. A 95% cost reduction on the same tool, same features. Quick disambiguation. OpenClaw (sometimes written as "open claw" or "open code claude") is an open-source agent harness on GitHub. Not to be confused with Anthropic's Claude Code itself, or with closed-source agent platforms. Nvidia's Jensen Huang called it "the new computer and the most important release of software probably ever." That's the one I'm covering. I'm Tom. I've been running OpenClaw on a Hostinger VPS for months and I've tested every cost-cutting setting in the docs. This is the exact config I use to keep my bill under $25 a month. Specific models, specific settings, and the techniques that turn OpenClaw into a 95% cheaper Claude Code. > [CTA-BLUEPRINT] ## What is OpenClaw? OpenClaw is an open-source AI agent harness that wraps Claude Code (and any other LLM you connect) and gives you a chat interface to run agents from Telegram or WhatsApp. You install it once on a VPS or a Mac Mini, connect it to a model provider, and from there you can spin up agents, schedule them on heartbeats, and have them run tasks like a junior on autopilot. The pitch is simple. Instead of paying for a managed agent service or running Claude Code manually in a terminal, you self-host OpenClaw, plug in your own API keys, and pay only for the tokens your agents actually burn. Free, open source, and over 9,900 GitHub searches a month tells you the community is paying attention. https://www.youtube.com/watch?v=rVAzoNf-w-M ## How does OpenClaw work? OpenClaw has two costs: the hosting (the machine that runs it) and the API spend (the fuel). Every time your agent thinks, replies, checks your email, or runs a heartbeat, it burns tokens against whichever model you've set as default. Most people leave that default on Claude Opus 4.6 and pay premium prices for tasks a 10-cent model could handle. As I said in the video, "most people are putting premium race fuel in a car that they're driving to the grocery store." That's exactly what's happening. The fix is model routing, context discipline, and search optimisation. OpenClaw supports all three out of the box, you just have to actually turn them on. ### Heartbeats and context accumulation Two hidden cost killers run in the background of every OpenClaw install. First, heartbeats. These are recurring triggers that fire on an interval and let your agent check in even when you're not chatting with it. Default settings often set them every 30 minutes, which is overkill for most use cases. Second, context accumulation. Every message in a chat includes all previous messages. By message 50, you're paying for the weight of every conversation stacked on top of each other. That's the single biggest hidden cost most OpenClaw users don't even know is happening. ### Open Router as the routing layer Open Router is the third-party routing layer that lets OpenClaw call cheap models like MiniMax M2.7, DeepSeek V3.2, and Kimi 2.5 instead of always defaulting to Opus. It also has an auto mode that picks the most cost-effective model based on the complexity of each prompt. That alone is most of the 95% saving. ## OpenClaw vs Claude Code Claude Code is Anthropic's official terminal coding agent. You run it locally, talk to it from your CLI, and it edits files, runs commands, and ships code. OpenClaw is a layer that wraps Claude Code (or any model) and makes it accessible from a chat interface like Telegram or WhatsApp, with scheduling, heartbeats, and multi-agent support baked in. You don't pick one or the other. OpenClaw uses Claude Code (and other models) as its workforce. The difference is who pays. With raw Claude Code on Anthropic's API at full Opus pricing, you're looking at $5 per million input tokens and $25 per million output tokens. Routed through Open Router with MiniMax M2.7, you're at $0.30 per million input and $1.20 per million output. That's a 10x difference on input and 20x on output before you even start optimising heartbeats and context. ### OpenClaw vs running Claude Code on a Mac Mini A lot of OpenClaw tutorials tell you to buy a Mac Mini for $600 to $800 and run it as your always-on machine. That works, but it's expensive upfront, only runs while the Mac is awake, and you still have to handle security, updates, and backups yourself. A managed VPS at $6 to $9 a month gives you 24/7 uptime, automatic backups, and a hardened security layer. For most people, the VPS path is the cheaper and cleaner OpenClaw setup. ### OpenClaw vs other Claude Code alternatives The closest OpenClaw alternative is Paperclip AI, which sits one layer up and orchestrates entire AI teams. Adjacent tools include CrewAI and AutoGen on the Python side, but those are libraries, not chat-first agent harnesses. If you're searching for an open source Claude Code alternative that just works from Telegram, OpenClaw is the closest match. If you're trying to figure out where OpenClaw sits in the broader stack, my [Paperclip AI review](/blog/paperclip-ai-review) walks through the orchestration layer that sits on top of harnesses like OpenClaw. Same mindset, different layer. ## What I tested with OpenClaw I deployed OpenClaw on a Hostinger VPS using their one-click Docker install, then ran a fresh setup from Telegram. The goal: take a default OpenClaw install (running Opus on every action) and squeeze it down using only the settings inside OpenClaw and Open Router. No code changes, no custom builds. Five levers actually move the bill: Open Router for cheap models, Open Router auto mode for prompt-aware routing, heartbeat optimisation with cron schedules and the cheapest model, regular session compacting, and QMD for low-token markdown search. I'll walk through each one in the install section below. Together they took the same workload from a projected $300 a month to under $25. ## Where OpenClaw falls short Honest take, because anyone who tells you OpenClaw is plug-and-play hasn't actually used it for more than a week. First, the default settings will drain your wallet. Out of the box, OpenClaw points at premium models, runs heartbeats every 30 minutes, and never compacts context for you. If you don't tune it, the bill grows by message 50. Second, security is your problem. The default install is reachable from the public internet if you don't lock it down. SSH hardening, firewall rules, and ideally Tailscale to keep access private are all on you. The Hostinger managed install handles a lot of this, but a self-hosted VPS install needs the security pass. Third, the cheap models aren't free of trade-offs. MiniMax M2.7 and DeepSeek V3.2 are great for heartbeats and simple replies, but you'll feel the drop in capability on heavy reasoning or long coding tasks. The fix is to keep auto mode on for general traffic and manually pin Opus 4.6 for the agent that does your hardest work. Fourth, dropping API keys into Telegram chat to bootstrap the install is not the most optimal solution, even though it's what most tutorials show. Delete the message after setup, rotate the key, and store secrets in the .env file going forward. This is exactly what I do on a fresh install. Fifth, and this is important: Anthropic's updated rules say you cannot connect your Anthropic Claude subscription to third-party harnesses like OpenClaw. Use an Anthropic API key, or route everything through Open Router. Don't try to wire your subscription in. > [CTA-HOSTINGER] | Get your managed OpenClaw account | One-click managed OpenClaw install on Hostinger. The same setup I use myself. | Get the deal | https://www.hostg.xyz/SHJDR ## How to install OpenClaw Here's the full OpenClaw install and cost-optimisation walkthrough. I'll assume you already have a basic OpenClaw instance set up and connected to Telegram. If not, follow the official OpenClaw documentation first, then come back for the cost-cutting steps. ### Step 1: Install Open Router and add cheap models From your OpenClaw Telegram chat, ask the bot: "Hey, can you help me set up Open Router? I want to be able to configure different models so we can reduce the cost of using OpenClaw." Drop your Open Router API key in the chat (delete the message after), and tell it to add three specific models: MiniMax M2.7, DeepSeek V3.2, and Kimi 2.5. Once the bot finishes, run the models command and confirm Open Router shows the three new options. ### Step 2: Switch the default model to a cheap one Inside OpenClaw, manually select MiniMax M2.7 as your active model. Send a test prompt and confirm the response includes the model name. If it complains about "think" reasoning depth, set it to medium. This single change moves you from $5 per million input tokens (Opus) to $0.30 per million (MiniMax). A 10x cut before you do anything else. ### Step 3: Enable Open Router auto mode for prompt-aware routing Open Router has an auto mode that automatically routes each prompt to the cheapest model that can handle it. Coding task? It picks something stronger. Heartbeat check? It picks something dirt cheap. Ask the bot: "Can you set up the Open Router auto mode so that when a prompt comes into OpenClaw it routes to the most cost-effective model based on complexity?" The model ID is openrouter/auto. Once it's added, set it as the new default. ### Step 4: Optimise your heartbeats Heartbeats are the silent budget killers. By default they fire every 30 minutes on whatever your default model is. Ask the bot to switch your heartbeats to a cron schedule (twice a day at 9am and 6pm is plenty for most workflows), pin them to MiniMax M2.7 specifically, enable light context mode, set isolated session to true, and set active hours so they only run while you're awake. That alone can knock another 50% off your bill. ### Step 5: Compact your context regularly Every long Telegram thread sends the entire conversation back to the model on every reply. Use the /compact command at the end of a session and OpenClaw will summarise the conversation and reset the context window. In my test it dropped from 55K tokens to 23K tokens, immediately. Before compacting, ask the bot to save any key decisions or preferences to a memory.md file so nothing important gets lost. ### Step 6: Set max output tokens Tell OpenClaw: "Set max output tokens to 248 in the config. This prevents runaway long responses that burn through your output token budget." 248 is aggressive. Adjust to 512 or 1024 if you actually need longer answers. The point is to put a hard ceiling on every reply so a chatty agent can't run away with your wallet. ### Step 7: Install QMD for low-token markdown search QMD (Quick Markdown) is a local search engine for your markdown notes. It turns your files into mini vectors with reranking, so when an agent needs to look something up it runs a cheap search instead of stuffing every file into context. Ask OpenClaw: "Hey, can you install QMD from this GitHub repo?" Then tell it: "Add the QMD agent integration to the agents.md file so it runs the QMD search before answering anything about prior work, decisions, dates, people, preferences, or to-dos." Once it's wired in, every "do you remember when..." question gets answered for pennies. ## Verdict: is OpenClaw worth it? Yes, with one condition. OpenClaw is worth it if you're willing to spend an afternoon tuning it. Out of the box it'll bleed money. Tuned, it's the cheapest way to run autonomous agents on Claude Code's capability without paying full Anthropic API rates. Who OpenClaw is for: builders who already understand prompts, want chat-first access to agents from Telegram or WhatsApp, and care about controlling costs. Who it's not for: complete beginners who've never opened a terminal, or people who want a polished SaaS dashboard with a billing graph. OpenClaw is open source, which means powerful and a little rough. My honest take: if you're spending hundreds of dollars a week on OpenClaw and you're not building anything that either saves you money or makes you more money, you're using the tool wrong. The people winning with AI automation are the ones who learn to build workflows that solve expensive problems. OpenClaw is a great fit when you've already got that mindset. For a real example of what optimised AI workflows look like in production, this [case study with Keven Elison](/case-studies/kevin) walks through how he stitched together n8n, RAG, and MCP servers to run a real B2B marketing operation. Same cost-discipline mindset, applied to a different stack. > [CTA-BLUEPRINT] ## OpenClaw FAQ ### What is OpenClaw? OpenClaw is a free, open-source AI agent harness that wraps Claude Code and other LLMs and gives you a chat interface (typically Telegram or WhatsApp) to control agents from. You self-host it on a VPS or Mac Mini, plug in your own API keys, and only pay for the tokens your agents burn. ### How does OpenClaw work? OpenClaw runs as a Docker app on your hardware. You connect a model provider (Anthropic, Open Router, or any compatible API), define agents, set heartbeats and routines, and chat with them from Telegram or WhatsApp. Every prompt goes from chat, through OpenClaw, to whichever model you've selected, and the reply comes back to your chat window. ### Is OpenClaw free? Yes, OpenClaw the software is free and open source on GitHub. You pay for two things on top: the hosting (a VPS like Hostinger starts at around $6 to $9 a month, or you can run it on a Mac Mini you already own) and the LLM tokens. With the cost-cutting setup in this guide, total monthly cost runs $6 to $25 instead of the $300 to $600 most unoptimised installs hit. ### How to install OpenClaw? The fastest path is a Hostinger VPS with the OpenClaw Docker template, or their managed OpenClaw instance which is one-click. After deploy, log in, drop your Open Router API key in, and follow the seven steps above to add cheap models, switch the default, enable auto mode, optimise heartbeats, set max tokens, install QMD, and lock down security. ### OpenClaw vs Claude Code: which one should I use? They're not competitors. Claude Code is Anthropic's official terminal coding agent. OpenClaw is a chat-first harness that can use Claude Code as one of its model adapters. Use Claude Code directly if you want a terminal coding tool. Use OpenClaw if you want chat-controlled agents from your phone, with scheduling, heartbeats, and cheaper model routing built in. ### Why is my OpenClaw bill so high? Three reasons. You're using Claude Opus 4.6 as the default for every action including simple heartbeats. Your context window is full and you've never run /compact, so every reply re-sends the entire conversation. Your heartbeats run every 30 minutes 24/7. Fix all three with Open Router auto mode, regular compacting, and a cron-scheduled heartbeat on a cheap model. That's the 95% saving. ### Can I run OpenClaw on a Mac Mini? Yes, but it's not the cheapest option. A Mac Mini costs $600 to $800 upfront and only runs while it's awake and online. A VPS at $6 to $9 a month gives you 24/7 uptime, automatic backups, and security hardening. Unless you already own the Mac Mini, the VPS path is the better OpenClaw setup. ### Is OpenClaw safe to run? It's as safe as the security around it. Don't paste API keys into Telegram chat permanently (delete the bootstrap message after setup), keep secrets in the .env file, harden the VPS with SSH key auth and a firewall, and consider Tailscale so the instance is only reachable when you're connected. The managed Hostinger OpenClaw template handles most of this for you. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Paperclip AI review](/blog/paperclip-ai-review) - [Claude Code pricing explained](/blog/claude-code-pricing) - [Claude Code rate limits](/blog/claude-code-rate-limits) ## Sources and official documentation Primary sources referenced in this guide: - [Open Claude on GitHub](https://github.com/openclawai/openclaw) - [Anthropic API pricing](https://www.anthropic.com/pricing) ## Ready to build production-ready AI systems? OpenClaw is a tool. The skill is knowing what to build with it. If you want to go deeper than "I installed an agent harness" and actually build production-ready AI systems for your business, the [30-Day Claude Code Challenge](/challenge) walks you through an interactive Claude Code course inside Claude Code. You'll build your first web app and your first automation in 30 days. Not ready for the challenge yet? Grab the [free Claude Code Blueprint](/blueprint). It's the foundation OpenClaw sits on top of, so going through the Blueprint first will make every OpenClaw workflow you build hit harder. ## Frequently Asked Questions ### What is OpenClaw? OpenClaw is a free, open-source AI agent harness that wraps Claude Code (and any other LLM you connect) and gives you a chat interface to run agents from Telegram or WhatsApp. You self-host on a VPS or Mac Mini, plug in your own API keys, and only pay for the tokens your agents actually burn. Nvidia's Jensen Huang called it 'the new computer and the most important release of software probably ever.' ### How does OpenClaw end up cheaper than Claude Code? Five levers. Route through Open Router to swap Opus 4.6 for MiniMax M2.7 ($0.30 input vs $5 input per million tokens). Use Open Router auto mode so each prompt routes to the cheapest model that can handle it. Drop heartbeats from every 30 minutes to a cron schedule pinned to MiniMax. Run /compact regularly to stop the entire conversation re-sending on every reply (in my test, 55K tokens to 23K immediately). Add QMD so memory queries hit a cheap local search instead of stuffing files into context. ### Why is my OpenClaw bill so high? Three reasons, almost every time. You are using Claude Opus 4.6 as the default for every action, including simple heartbeats. Your context is full and you have never run /compact, so every reply re-sends the entire conversation. Your heartbeats fire every 30 minutes, 24/7. One person on Reddit reported $3,600 in a single month from exactly this setup. Fix all three with Open Router auto mode, regular compacting, and a cron-scheduled heartbeat on a cheap model. ### Is OpenClaw free? The software is free and open source on GitHub. You pay for two things: the hosting (a Hostinger VPS starts around $6 to $9 a month, or run it on a Mac Mini you already own) and the LLM tokens. With the cost-cutting setup in the guide, total monthly cost runs $6 to $25. Without it, most unoptimised installs land at $300 to $600 a month. ### Can I connect my Claude subscription to OpenClaw? No. Anthropic's updated rules say you cannot connect your Anthropic Claude subscription to third-party harnesses like OpenClaw or Paperclip AI. Use an Anthropic API key, or route everything through Open Router. Trying to wire your subscription in risks getting your account flagged. ### Is OpenClaw safe to run? It is as safe as the security around it. Do not paste API keys into Telegram chat permanently. Delete the bootstrap message after setup. Keep secrets in the .env file. Harden the VPS with SSH key auth and a firewall. Use Tailscale so the instance is only reachable when you are connected. The managed Hostinger OpenClaw template handles most of this for you out of the box. ### Who should not use OpenClaw? Complete beginners who have never opened a terminal, and anyone expecting a polished SaaS dashboard with a billing graph. OpenClaw is open source, which means powerful and a little rough. The default settings will drain your wallet if you do not tune them. If you are spending hundreds a week on OpenClaw and not building anything that saves you or makes you money, you are using the tool wrong. Get comfortable with Claude Code first. --- # Claude Code Subagents vs Skills: When to Use Each Source: https://theaiarchitects.com/blog/claude-code-subagents-vs-skills Published: 2026-05-12 Claude Code subagents vs skills, compared side by side. Decision tree, 5 production subagents I run daily, plus YAML frontmatter to copy in 2026. Subagents in Claude Code are specialized assistants you call into a task, each running in its own context window with its own system prompt, tools, and (optionally) model. Skills are reusable instructions plus scripts that the main Claude Code agent loads when a task matches the skill's description. They look similar in the file system. They do completely different jobs. I'm Tom. I run Claude Code every day to ship the apps, content, and automations behind my mentorship business. I have built skills for things like brand voice analysis and humanizing AI copy. I have built subagents for code review, security review, n8n workflow validation, and Codex rescue. This post is the side-by-side that Anthropic's docs do not give you, plus the five production subagents I actually use, the decision tree I use to pick between them, and the YAML frontmatter you can copy. > [CTA-BLUEPRINT] ## What are Claude Code subagents? Claude Code subagents are independent assistants that the main agent can call into a task. Each subagent has its own system prompt, its own context window, its own tool permissions, and can run on a different model than the parent agent. [Anthropic launched subagents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) in late July 2025 as a way to keep the main context clean and to delegate narrow jobs to focused specialists. In practice, a subagent is a markdown file with YAML frontmatter that lives in either .claude/agents/ for project-scoped agents or ~/.claude/agents/ for user-scoped ones. The frontmatter sets the name, description, allowed tools, and model. Everything below the frontmatter is the system prompt the subagent runs under. ## What are Claude Code skills? [Skills are reusable packages](https://docs.anthropic.com/en/docs/claude-code/skills) of instructions and scripts that Claude Code can pull into the main agent's context when a task matches. A skill is a folder containing a SKILL.md file plus any helper scripts, templates, or reference docs. The main agent reads SKILL.md frontmatter on startup, scans descriptions, and loads the full skill body when the user's request triggers it. Anthropic shipped skills in October 2025. Skills do not get their own context window. They do not run on a different model. They are instructions the parent agent loads, plus scripts the parent agent can execute. That difference matters more than anything else in this post. ## Subagents vs skills in Claude Code The fastest way to think about it: skills extend what the main agent can do. Subagents replace the main agent for one task. A skill teaches the parent new tricks. A subagent forks off a specialist who does the work and reports back. Here is the breakdown I keep on my wall. ### Context window Skills load into the parent context. They eat tokens from your active session. Subagents get [their own context window](https://docs.anthropic.com/en/docs/claude-code/sub-agents). Anything the subagent does, including its tool calls and file reads, never touches the parent context until it returns a final summary. ### Model selection Skills run on whatever model the parent is running. Subagents can run on a cheaper model than the parent. I run my main agent on Sonnet 4.5 and farm out review work to a Haiku-powered subagent when the job is mechanical. The cost difference shows up on the monthly bill. ### Tool permissions Skills inherit the parent agent's tool permissions. Subagents can declare a restricted tool list in YAML. A code review subagent can be limited to Read and Grep with no Edit, no Bash, no MCP write tools. That is a real safety control, not a vibe. ### Reusability and triggering Both reuse across projects. Drop a skill in ~/.claude/skills/ or a subagent in ~/.claude/agents/ and every project on your machine sees it. The difference is invocation. Skills auto-load when their description matches the task. Subagents are called explicitly: the parent decides to delegate, or you ask by name. ## When should I use a subagent vs a skill? Use a skill when the work is short, runs on the same model, needs the parent's context, and benefits from being injected into an ongoing conversation. Use a subagent when the work is long-running, mechanical, repeatable, would pollute the parent context, or could safely run on a cheaper model. Here is my decision tree. Run through it top to bottom. The first yes wins. ### 1. Does the task need its own context window? If the task involves reading a lot of files (a full repo audit, security review, dependency upgrade), the answer is yes. Use a subagent. [Anthropic's docs make this point too](https://docs.anthropic.com/en/docs/claude-code/sub-agents). A 200k-token review eats your main session if you run it inline. ### 2. Could it run on a cheaper model? Mechanical work like linting, formatting, validation, or syntax checks does not need Opus or Sonnet. Subagents let you pin Haiku or Sonnet for the cheap stuff. Skills cannot. ### 3. Does it need its own tool permissions? If the work touches sensitive tools (git push, MCP write tools, Bash) and you want to lock those down, a subagent is the only way. Skills inherit your full permission set. ### 4. Otherwise, write a skill. If none of those three are yes, you want a skill. Skills are lighter, faster to author, easier to debug, and they keep the conversation in one context. ## The 5 production subagents I run every day These are the actual subagents in my .claude/agents/ directories. I am pasting the frontmatter and the use case for each one. Steal them. Adapt them. The names are mine, the patterns are not. ### 1. review (built-in /review) Claude Code ships with a built-in /review command that fires up a code review subagent. It reads the diff or the current branch, runs through a structured review checklist, and returns a markdown report. I use this before every PR. The frontmatter pattern looks like this: `--- name: review description: Review pending changes for bugs, regressions, and quality issues. Runs on PR diff or current branch. tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*) model: sonnet ---` Why a subagent and not a skill: the review reads dozens of files. If it ran in my main context, it would burn through the session and crowd out the actual work I am doing. Forking off a Sonnet subagent with read-only tools means the review happens in parallel and the parent context stays clean. ### 2. security-review (built-in /security-review) Same pattern as /review but tuned for security: SQL injection patterns, secret exposure, auth flow regressions, unsafe deserialization. Anthropic ships this one too. I run it on every PR that touches auth, payments, or user-uploaded files. `--- name: security-review description: Audit pending changes for security regressions. Use on auth, payments, file uploads, or any user-input handling. tools: Read, Grep, Glob, Bash(git diff:*) model: sonnet ---` This one is read-only. No Edit. No write tools. The whole point is for it to flag, not fix. Fixes happen in the main agent after I read the report. ### 3. n8n-validator I run a lot of n8n workflows for my mentorship business and for clients. Every time I generate or edit a workflow JSON, I delegate the validation to an n8n-validator subagent that knows the n8n MCP toolset, the validation profiles, and how to interpret a 47-error noise list. It reads the workflow, runs validate_workflow with the right profile, and returns a clean fix list. `--- name: n8n-validator description: Validate n8n workflow JSON, interpret validation profiles, and return a prioritized fix list. Use after generating or editing any n8n workflow. tools: Read, mcp__n8n__validate_workflow, mcp__n8n__get_node_essentials, mcp__n8n__search_nodes model: sonnet ---` Subagent because validation reports are noisy. I do not want 47 lines of n8n schema warnings in my main context. The subagent triages, summarizes, and only the summary returns to the parent. ### 4. codex:rescue When Claude Code gets stuck on a hard bug after two or three rounds, I delegate to a Codex rescue subagent. It runs OpenAI's Codex CLI with a tighter system prompt, returns a second-opinion diagnosis, and proposes a patch as text for me to review. I do not let it write directly. The point is to break out of a single-model groupthink loop. `--- name: codex-rescue description: Delegate stuck investigations to OpenAI Codex CLI for a second-opinion diagnosis. Use after 2-3 failed fix attempts in the main agent. tools: Read, Bash(codex:*), Grep model: sonnet ---` ### 5. process-analyzer This one is mine, not Anthropic's. It analyzes business processes from interview notes and returns automation opportunities scored on feasibility and time saved. I built it for the AI Operator program because students were sending me long process docs and I needed a structured pass before our calls. `--- name: process-analyzer description: Analyse business processes for automation opportunities. Returns pain points, opportunities scored Easy/Medium/Hard, and a recommended priority list. tools: Read, Grep, WebFetch model: sonnet ---` The system prompt hard-codes the output format: PROCESS OVERVIEW, PAIN POINTS, AUTOMATION OPPORTUNITIES, RECOMMENDED PRIORITY, IMPLEMENTATION NOTES. Every output is reviewable in 30 seconds. That structure is the whole product. ## How do I create a Claude Code subagent? There are two ways. The interactive way is the /agents command, which [Anthropic added to Claude Code](https://docs.anthropic.com/en/docs/claude-code/sub-agents) in 2025 and which spins up a guided wizard. The manual way is to drop a markdown file into the right folder. ### Step 1. Pick a scope Project-scoped subagents go in .claude/agents/ inside your repo. They ship with the codebase and your team gets them on git pull. User-scoped subagents go in ~/.claude/agents/ and follow you across every project. Project scope wins by default. Only use user scope for genuinely cross-project tools like a generic code reviewer. ### Step 2. Write the YAML frontmatter Every subagent file starts with frontmatter that sets the name, description, tools, and model. Skip any of the four and Claude Code applies a default. The description is the most important part. The parent agent uses it to decide whether to delegate. `--- name: my-subagent description: One sentence on what this subagent does and when to use it. The parent agent reads this to decide whether to delegate. tools: Read, Grep, Glob model: sonnet ---` ### Step 3. Write the system prompt Below the closing --- you write the system prompt that runs every time the subagent is called. Treat it like a spec. State the role, the inputs it expects, the outputs it should return, the constraints, and an explicit Boundaries section listing what the subagent should refuse to do. Mine all end with a Boundaries block. It saves time later. ### Step 4. Test the description In the parent session, ask Claude Code to delegate the kind of task you want this subagent to handle. If the parent does not pick it up, your description is too vague. Rewrite the description until the parent reaches for the subagent automatically. This is the part most tutorials skip. > [CTA-BLUEPRINT] ## Where do subagents live in Claude Code? [Subagents live in two places](https://docs.anthropic.com/en/docs/claude-code/sub-agents): .claude/agents/ for project-scoped subagents that ship with the repo, and ~/.claude/agents/ for user-scoped subagents that work across every project on your machine. Each subagent is one markdown file with YAML frontmatter. There is no registry, no index, no compile step. The parent agent scans the folders on startup and reads frontmatter for every file it finds. Project scope beats user scope when the team needs the same subagent. User scope wins for personal tools you carry across clients. If you have both files with the same name, project scope wins. ## Can a subagent call a skill? Yes. A subagent runs on the same Claude Code runtime as the parent, so it can see and load skills from the same folders. The subagent's system prompt can reference a skill explicitly, or the subagent can be given a description that triggers a skill in its own context. The skill loads inside the subagent's context window, not the parent's. That is the most useful pattern in this whole post: subagent for context isolation, skill for the reusable instructions inside it. Tom's voice-analysis skill, for example, is loaded inside a content-generation subagent so the parent agent never has to carry the voice rules in its main context. ## How much do Claude Code subagents cost? Subagents cost the same per token as any other Claude Code call, billed against your active plan. The reason people ask is that subagents can either burn more tokens (parallel work) or save tokens (cheaper models on mechanical work). Both happen. On [Pro](https://www.anthropic.com/news) with 5x weekly usage, a single repo-wide review subagent can chew through a real slice of your weekly cap if you forget to scope it. On Max with 20x usage, it barely registers. Two ways to keep cost flat: pin the subagent to a cheaper model in the frontmatter, and restrict tools so it cannot recursively spider the whole repo. ## What's the difference between a skill and a subagent? A skill is loaded instructions plus scripts the parent agent runs. A subagent is an independent assistant the parent calls into a task with its own context, model, and tools. Skills extend the parent. Subagents fork the parent. Practical version: if you would explain it as 'when X happens, the agent should do Y this way,' that is a skill. If you would explain it as 'send this whole task to a specialist and come back with a summary,' that is a subagent. ## Can Claude Code run subagents in parallel? [Yes](https://docs.anthropic.com/en/docs/claude-code/sub-agents). Claude Code spawns multiple subagents in parallel for independent tasks. Fan out a review subagent across each package of a monorepo, each running in its own context, then aggregate. The constraint is that parallel subagents do not see each other, so you have to merge their reports in the parent agent. ## Claude Code subagent YAML frontmatter reference The frontmatter is a tight YAML block with four keys. Anything else gets ignored. ### name Lowercase, hyphenated. This is what the parent agent uses to call the subagent. Match the filename. If the file is review.md, the name is review. ### description One sentence on what the subagent does and when to use it. The parent agent reads this and decides whether to delegate. Make it specific. 'Review pending changes for bugs, regressions, and quality issues' is good. 'Reviews code' is too vague to trigger. ### tools Comma-separated list of tools the subagent can use. Restrict aggressively. A review subagent should be Read, Grep, Glob and nothing else. Bash should be scoped (Bash(git diff:*) not bare Bash). MCP tools follow the same naming convention as the parent. ### model Either sonnet, haiku, opus, or inherit. Default is inherit. Pin to haiku for mechanical work. Pin to sonnet for anything requiring judgment. Opus rarely makes sense at the subagent level because the cost stacks fast. ## Verdict: subagent or skill? If you are starting out, write skills first. They are easier to author, faster to debug, cheaper to run. Most of what you think you need a subagent for is actually a skill the parent agent can run inline. Reach for a subagent only when you have all three: long-running work, dirty context, and a clear input/output contract. Code review, security audits, schema validation, repo-wide refactors, second-opinion bug rescues. Those are the jobs subagents earn their keep on. If you are running a team, build the four or five subagents your team uses on every PR, commit them to .claude/agents/, and let everyone benefit. > [CTA-BLUEPRINT] ## Claude Code subagents FAQ ### Are subagents free with Claude Code Pro? Yes. Subagents do not cost extra. They run on your existing Pro or Max usage allowance, billed the same way as any other Claude Code call. The only thing they change is how fast you burn through that allowance. ### Can I version control subagents? Yes. Project-scoped subagents in .claude/agents/ are plain markdown files that commit to your repo like any source file. The whole team gets the same subagents on git pull. This is the right default for most teams. ### Can subagents call MCP tools? Yes. Subagents can call any MCP tool the parent agent has access to, as long as the tool is listed in the subagent's frontmatter tools field. The MCP server itself does not know it is being called by a subagent. It just sees a tool call from the Claude Code session. ### How do I debug a subagent that won't trigger? Almost always, the description is too vague. The parent agent uses the description string to decide whether to delegate. Make the description name the trigger condition explicitly: 'when the user asks for a code review' or 'after generating an n8n workflow.' Specific descriptions trigger reliably. ### Are there ready-made subagents I can install? Yes. There are growing GitHub repos collecting community subagents (search 'awesome-claude-code-subagents'), plus the official Anthropic agents repo. Be careful with anything that requests broad tool permissions. Read the frontmatter and the system prompt before dropping any subagent into ~/.claude/agents/. ### Can a skill replace a subagent for code review? It can, but you lose context isolation. A review skill loaded into the main agent will work for small diffs. On a large diff, it will eat the parent context and crowd out the conversation you started. Use a subagent for any review that touches more than a handful of files. ### Should I migrate my old slash commands to subagents or skills? Most slash commands map cleanly to skills, not subagents. The /commands folder was Anthropic's first version of reusable workflows. Skills are the second generation, with better triggering and packaging. Migrate to skills first. Promote to a subagent only if you hit one of the three subagent triggers: long-running, dirty context, or restricted tools. ## Ready to build production-grade Claude Code workflows? If you want the full mental model behind skills, subagents, MCP, hooks, and memory, plus the templates I use day to day, [the Claude Code Blueprint](/blueprint) walks through the whole stack in 60 minutes with no coding required. If you would rather build alongside other operators, [the 30-day Claude Code challenge](/challenge) is the cohort version with weekly calls, real builds, and real feedback. For the foundations, start with [my Claude Code beginner guide](/blog/how-to-use-claude-code). For the sibling deep-dive, read [the skills explainer](/blog/claude-code-skills). ## Frequently Asked Questions ### What is the difference between a Claude Code skill and a subagent? A skill is loaded instructions plus scripts the parent agent runs. A subagent is an independent assistant the parent calls into a task with its own context window, model, and tools. Skills extend the parent. Subagents fork the parent. If you would explain it as 'when X happens, do Y this way', that is a skill. If you would explain it as 'send this whole task to a specialist and come back with a summary', that is a subagent. ### When should I use a subagent instead of a skill? Reach for a subagent only when you have all three: long-running work, dirty context, and a clear input/output contract. Code review, security audits, schema validation, repo-wide refactors, second-opinion bug rescues. If the task involves reading a lot of files (200k tokens for a security review), the subagent's own context window keeps your main session clean. If you cannot tick all three boxes, write a skill instead. ### Are subagents free with Claude Code Pro? Yes. Subagents do not cost extra. They run on your existing Pro or Max usage allowance, billed the same way as any other Claude Code call. The only thing they change is how fast you burn through that allowance. A repo-wide review subagent can chew through a real slice of your weekly Pro cap if you forget to scope it. Pin to Haiku for mechanical work to keep cost flat. ### Can a subagent call a Claude Code skill? Yes. A subagent runs on the same Claude Code runtime as the parent, so it can see and load skills from the same folders. The skill loads inside the subagent's context window, not the parent's. That is the most useful pattern in this space: subagent for context isolation, skill for the reusable instructions inside it. ### How do I create a Claude Code subagent? Drop a markdown file with YAML frontmatter into .claude/agents/ for project scope, or ~/.claude/agents/ for user scope. The four frontmatter keys are name (lowercase, hyphenated), description (the trigger sentence the parent reads), tools (restrict aggressively, scope Bash to specific subcommands), and model (sonnet for judgment, haiku for mechanical work). Anything below the closing --- is the system prompt the subagent runs under. ### Why is my subagent not getting triggered? Almost always, the description is too vague. The parent agent uses the description string to decide whether to delegate. 'Reviews code' will not trigger. 'Review pending changes for bugs, regressions, and quality issues. Runs on PR diff or current branch.' will. Rewrite the description until the parent reaches for the subagent automatically on a real task. ### Should I migrate my old slash commands to subagents or skills? Most slash commands map cleanly to skills, not subagents. The /commands folder was Anthropic's first version of reusable workflows. Skills are the second generation, with better triggering and packaging. Migrate to skills first. Promote to a subagent only if you hit one of the three triggers: long-running work, dirty context, or restricted tools. ## Related guides - [Claude Code Agents Explained: Subagents, Agent View, and Teams](/blog/claude-code-agents) --- # Claude Code vs Cursor: An Honest Comparison Source: https://theaiarchitects.com/blog/claude-code-vs-cursor Published: 2026-05-12 Claude Code vs Cursor, compared after building 12 real projects in both tools. Honest pros, cons, pricing, and a clear verdict on which to pick in 2026. Claude Code vs Cursor is the comparison most people botch because they treat the two tools as the same thing. They are not. Cursor is an AI-first code editor, a fork of VS Code that wraps autocomplete, chat, and agents around a familiar IDE. Claude Code is a terminal-native coding agent from Anthropic that reads your repo, edits files, runs commands, and shows up in your IDE, desktop, browser, and phone. Both can ship code. They get there in completely different ways. I'm Tom. I use Claude Code every single day to build apps, write content, and run automations for my mentorship business. I have also tested Cursor on real projects, including the same brief in both tools side by side. This post is the honest version of that comparison: where each one wins, where each one loses, and which one I would tell a friend to install today. > [CTA-BLUEPRINT] ## Claude Code vs Cursor: which is better? Short answer: Claude Code is better if you want an autonomous agent that ships work end to end. Cursor is better if you want a polished IDE with the best autocomplete on the market and an agent bolted on. They are different categories pretending to be the same. After running both tools across 12 projects (a Next.js web app, two Python data pipelines, an n8n integration, a Sanity blog, three landing pages, an iOS prototype, an Airtable migration, and two content automations) my pattern is the same every time. Cursor wins for hands-on-keyboard work where you want to write each line yourself. Claude Code wins for hands-off-keyboard work where you describe the outcome and let the agent figure it out. If I had to pick one, I would pick Claude Code, and most days I do. The reason is in the next section. ## What is Claude Code? Claude Code is Anthropic's agentic coding tool. The [official Anthropic documentation](https://docs.anthropic.com/en/docs/claude-code) describes it as a tool that "reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser." It runs the same Claude model as the chat app, but the harness adds tools, memory, hooks, MCP integrations, skills, subagents, and a permission system the chat app does not have. In practice, you install Claude Code with a single curl command, point it at a folder, and start describing what you want. It plans the change, edits across files, runs your test suite, commits the result, and asks before doing anything destructive. You can drive the same session from your terminal, your VS Code panel, your iPhone, or claude.ai/code in a browser. That multi-surface design is the part Cursor cannot easily copy. ## What is Cursor? Cursor is an AI-first fork of Visual Studio Code. The [Cursor homepage](https://www.cursor.com) pitches itself as "the best way to code with AI" and leans on three lead features: Tab autocomplete, an autonomy slider that lets you choose between inline edits and full agents, and codebase-wide context. The product targets professional engineering teams and claims to be trusted by more than half of the Fortune 500. If you have ever used VS Code, you can use Cursor in 30 seconds. Same shortcuts, same extensions, same file tree. The differences live in the AI panel: Cmd+K for inline edits, Cmd+L for chat across the codebase, and the Agents tab for autonomous tasks that work in the background. Cursor also ships its own autocomplete and inline edit model that working developers rate highly. If you write code by hand all day, that is the part Cursor wins. ## Is Claude Code better than Cursor? For agent work and end-to-end shipping, yes. For developers who want a polished editor with AI inline, Cursor is still excellent. The short version: Claude Code's agent is more autonomous, plans further ahead, and ships larger multi-file changes without losing the thread. Cursor stays the cleaner experience if you live inside a code editor and write each line yourself. I built the same feature in both: a Sanity NDJSON importer that reads from a CSV, transforms it, and writes a Portable Text array. In Claude Code I described the brief once and walked away. It read three reference files, asked a clarifying question about my preferred ID format, wrote the script, ran it on a test fixture, and showed me the result. In Cursor I had to babysit. The agent kept stopping to ask permission for routine reads, lost track of an earlier rename, and I ended up steering each step. Cursor finished about 25% faster on raw lines of code. Claude Code finished a working pull request first. That gap widens with project complexity. For one-file edits, Cursor is fine. For anything that touches more than three files or needs to run a command, Claude Code is the cleaner agent. ## Should I use Claude Code or Cursor? Use Cursor if you live inside a code editor and write code by hand most of the day. Use Claude Code if you want to describe an outcome in plain English, leave the room, and come back to a finished result. The honest answer for most builders is both. They are not mutually exclusive. My setup: Claude Code is my default for anything that involves planning, multi-file work, MCP integrations, content, or running automations across an org. I keep Cursor in my dock for the rare days I want to pair-code a tricky component by hand. The two coexist without friction, which I will cover further down. ## Is Claude Code free? Is Cursor free? Both have a free tier. Neither is genuinely free if you use them daily. Here is the breakdown. ### Claude Code pricing The Claude Code CLI itself is free to install. Usage runs on either a Claude subscription (Pro at $20 a month, Max 5x at $100, Max 20x at $200) or an Anthropic API key billed per token. Pro covers most light users. Max 5x is the sweet spot for daily builders. Max 20x is what you want if you are running agent teams, parallel sessions, and the xhigh effort tier on Opus 4.7. The CLI is the same on every plan. Only usage caps and effort levels change. ### Cursor pricing Cursor offers Hobby (free, capped Agent and Tab usage), Pro ($20 a month for extended limits and frontier model access), Pro+ ($60 a month for 3x usage), Ultra ($200 a month for 20x usage), and Teams ($40 per user a month with SSO and central billing). Pro is the same headline price as Claude Pro. Cursor Ultra and Claude Max 20x both land at $200, which is the comparison that matters: at the top tier, you are choosing positioning, not price. ## Which has better agents — Claude Code or Cursor? Claude Code, by a meaningful margin. The depth of the agent stack is just deeper. You get plan mode (a read-only mode that produces a plan before any edit), subagents (independent context windows for delegated work), agent teams (multiple parallel Claude Code instances coordinated by a lead agent), hooks (pre and post tool actions for deterministic guardrails), MCP servers (Anthropic invented the protocol, so support is first-class), and skills (reusable workflows you trigger with a slash command). Cursor's agent is good. It is not in the same league as Claude Code's agent stack. Where Cursor still has an edge is the inline editing experience for working developers: highlighting code, pressing Cmd+K, and getting a clean diff in seconds. For that specific workflow, nothing else feels as polished. ## Can I use Claude Code with Cursor? Yes. Claude Code ships an official extension for Cursor (Cursor is a VS Code fork, so the same extension works in both). Install it from the VS Code Marketplace, open the command palette, type Claude Code, and you get inline diffs, plan review, and chat history right inside Cursor. You can run Cursor for autocomplete and Claude Code for agent work in the same window. This is the setup I would recommend to most builders who already love Cursor. You keep the IDE you know. You add the agent that ships work. There is no migration, no relearning your shortcuts, no new file tree. The CLI also still runs in your terminal, so you can drive Claude Code from inside Cursor's integrated terminal whenever you want a clean session. ## Claude Code vs Cursor for non-developers Claude Code is the better choice for non-developers, and that is not the answer most reviewers give. The reason is plain: Claude Code lets you describe outcomes in English. Cursor is built for people who already write code and want AI to type it faster. The clearest example I have is the [case study with Keven](/case-studies/keven), a non-coder who rebuilt a 7-year content workflow into n8n agents tied to MCP servers, all driven through plain-English prompts. He never touched Cursor. The terminal-first stack let him describe outcomes in English and have the agent translate that into nodes and configurations. Cursor's IDE chrome would have made the same outcome harder, because IDE chrome assumes you already know what to do with a file tree. If you do not write code today and you want to ship a working tool in 30 days, Claude Code is the answer. If you already write code and want a faster IDE, Cursor is the answer. ## Where Cursor falls short Three things to know before you commit. First, Cursor is a single-surface tool. It lives inside the editor. There is no terminal-native experience, no native browser session, and the iOS story is thin. If you want to start a task on your laptop, check it on your phone, and finish on the desktop, Cursor cannot do that. Claude Code can. Second, the agent loses context faster on long tasks. I have seen Cursor's agent forget what it renamed two steps ago, reintroduce a bug it just fixed, or ask permission for a read it already had. On bigger jobs the babysitting tax is real. Third, Cursor is a fork. You are betting on a small team to keep up with VS Code releases, plus their own AI infrastructure. That is fine right now. It is a real risk over a five-year horizon, especially as Microsoft and Anthropic invest in their own competing surfaces. ## Where Claude Code falls short Three honest weaknesses. First, if you spend most of your day typing each line by hand inside a code editor, Cursor still feels more polished. Claude Code's IDE extension is closing that gap, but it is not all the way there yet. This matters for working developers and barely registers for non-coders shipping their first build. Second, the learning curve is steeper. The terminal, the slash commands, the permission prompts, the CLAUDE.md memory files, the MCP config, the skills folder. None of it is hard, but there are more concepts to learn than "open the editor and start typing." Most people who give up on Claude Code give up because they did not invest the first hour. Third, costs scale fast at the top tier. Agent teams plus xhigh effort plus parallel sessions can blow through Claude Max 5x in a busy week. The fix is to use the /effort low command for cheap work and reserve max for final review, but you have to learn that lever exists. > [CTA-BLUEPRINT] ## What Reddit says about Claude Code vs Cursor Search "cursor vs claude code reddit" and the pattern is consistent across the [r/ClaudeAI subreddit](https://www.reddit.com/r/ClaudeAI/) and r/cursor: heavy users move from Cursor to Claude Code for agent work and keep Cursor open for autocomplete. The threads I read for this post matched my experience almost exactly. The most upvoted complaint about Cursor is the per-request usage cap surprise. The most upvoted complaint about Claude Code is the learning curve. The most upvoted recommendation in both subs is the same: run them together. That is also where I land. The internet is split between team Cursor and team Claude Code. The truth is that the question is rarely either or for serious builders. ## Verdict: which one should you actually pick? Pick Claude Code if any of these are true: you are building automations, you are a non-coder shipping a tool, you want to drive your work from terminal or phone, you care about MCP and skills, you want plan mode and subagents, or you want one tool that lives in five places. Pick Cursor if any of these are true: you write production code by hand most of the day, you live in VS Code already, you prefer a polished IDE over a CLI, or you are pairing with teammates who already use Cursor. Pick both if you can afford $40 a month and want both lanes covered. That is what I do. Claude Code drives the agent work that matters. Cursor sits in the dock for the rare days I want to write each line by hand. If you want a closer look at the agent stack that pulls me toward Claude Code, the breakdown of the [10 features that just made Claude Code 10x more powerful](/blog/claude-code-10x-more-powerful) walks through insights, agent teams, hooks, batch, simplify, and remote control. That is the cluster Cursor has no obvious answer to. > [CTA-BLUEPRINT] ## Claude Code vs Cursor FAQ ### Is Claude Code an alternative to Cursor? Yes and no. Claude Code is a full alternative if you want an autonomous coding agent. It is not a direct alternative if you want an AI-first IDE, because Claude Code is a CLI and an extension, not an editor. The closest IDE-shaped Claude Code alternative inside Cursor's category is Windsurf or Codex, but most builders end up running Claude Code alongside their existing editor. ### Can I use Claude Code in Cursor? Yes. Install the Claude Code extension from the VS Code Marketplace and it works in Cursor (Cursor is a VS Code fork). You also get the CLI in Cursor's integrated terminal. Most builders run Cursor for autocomplete and Claude Code for agent work in the same window. ### Claude Code vs Cursor pricing: which is cheaper? They are nearly identical at the entry tiers. Both Pro tiers cost $20 a month. Both top tiers (Cursor Ultra and Claude Max 20x) cost $200 a month. Claude Code Max 5x sits at $100 a month and is the best mid-tier value if you want Opus access without the top-tier price. Cursor's $60 Pro+ has no direct Claude Code equivalent. ### Is Cursor or Claude Code better for beginners? It depends on what kind of beginner. If you are new to coding but already comfortable in a terminal, Claude Code is friendlier because you describe outcomes in English. If you are new to coding and want a familiar IDE, Cursor is friendlier because the editor does the heavy lifting and AI sits inside it. ### Does Cursor use Claude? Yes. Cursor lets you pick the model behind the agent and chat panel, including Claude (Sonnet and Opus), GPT models, and Gemini. Picking Claude inside Cursor gets you Anthropic's model with Cursor's IDE wrapping. It does not get you Claude Code's agent stack (no plan mode, no subagents, no skills, no hooks). Same model. Different harness. ### What about Cursor vs Claude Code vs Codex? Codex is OpenAI's terminal coding agent and is the closest direct competitor to Claude Code. Cursor sits in a different category as an IDE. Most three-way comparisons reduce to: Cursor for editor work, Claude Code for agent work in the Anthropic stack, Codex for agent work in the OpenAI stack. Codex vs Claude Code is the comparison worth running if you have already chosen agent over editor. ### Are there free alternatives to Cursor and Claude Code? Both have free tiers, but neither is genuinely free for daily use. Open-source Cursor alternatives include Void and Continue. Free Claude Code alternatives are scarce because the model behind the agent has to come from somewhere. Aider is the closest open-source equivalent if you bring your own API key. ## Ready to ship real work with Claude Code? If this comparison pushed you toward Claude Code, the fastest way in is the [free Claude Code Blueprint](/blueprint). 60 minutes, no coding required, and you walk out with a working setup and a first build under your belt. It assumes nothing about your background and gets you past the steep learning curve that stops most people. Want to go further? The [30-Day Claude Code Challenge](/challenge) is the cohort. Four live calls, a real build per week, and a deployed agent on a real schedule by the end. That is the version of Claude Code that actually replaces Cursor for serious work. The blueprint is the on-ramp. The challenge is the lane change. ## Frequently Asked Questions ### Is Claude Code better than Cursor? For agent work and end-to-end shipping, yes. After running both across 12 real projects, Claude Code plans further ahead and ships larger multi-file changes without losing the thread. Cursor still wins for hands-on-keyboard work where you want to write each line yourself, with the cleanest inline edit experience on the market. Different categories pretending to be the same tool. ### Can I use Claude Code inside Cursor? Yes. Cursor is a VS Code fork, so the official Claude Code extension from the VS Code Marketplace works in it. Install the extension, open the command palette, and you get inline diffs, plan review, and chat history inside Cursor. The CLI also runs in Cursor's integrated terminal, so you can pair Cursor's autocomplete with Claude Code's agent in one window. ### Claude Code vs Cursor pricing: which is cheaper? Nearly identical at the entry tiers. Both Pro plans are $20 a month. Both top tiers (Cursor Ultra and Claude Max 20x) are $200 a month. Claude Max 5x at $100 is the best mid-tier value if you want Opus access without paying the top-tier price. Cursor's $60 Pro+ has no direct Claude Code equivalent. ### Should a non-coder use Claude Code or Cursor? Claude Code, even though most reviewers say the opposite. Cursor is built for people who already write code and want AI to type it faster. Claude Code lets you describe outcomes in English. One of my students, Keven, rebuilt a 7-year content workflow into n8n agents through Claude Code without writing a line by hand. Cursor's IDE chrome would have made the same outcome harder. ### Does Cursor use Claude under the hood? Yes. Cursor lets you pick the model behind its agent and chat panel, including Claude Sonnet and Opus, GPT models, and Gemini. Picking Claude inside Cursor gets you Anthropic's model with Cursor's IDE wrapping. You do not get Claude Code's agent stack (no plan mode, no subagents, no skills, no hooks). Same model, different harness. ### Where does Cursor still beat Claude Code? Inline editing for working developers. Highlight code, hit Cmd+K, get a clean diff in seconds. Nothing else feels as polished for that specific workflow. Cursor's Tab autocomplete is also genuinely best in class. If you spend most of your day writing each line by hand inside a code editor, Cursor is the more refined experience. ### Can I run both Claude Code and Cursor at the same time? Yes, and it is what I do. Cursor sits in the dock for the rare days I pair-code a tricky component by hand. Claude Code is my default for planning, multi-file work, MCP integrations, and content. They cost $40 a month together and cover both lanes. No migration, no friction, the same file tree. ## Related guides - [Claude Code vs Copilot vs Codex: Three Tools, Three Jobs](/blog/claude-code-vs-copilot) - [Claude Code vs Codex: When I Use Each (Honest Take)](/blog/claude-code-vs-codex) - [Claude Code in Cursor: How I Run It (and Skip Cursor AI)](/blog/claude-code-in-cursor) --- # Claude Code Plan Mode: When and How to Use It in 2026 Source: https://theaiarchitects.com/blog/claude-code-plan-mode Published: 2026-05-11 Claude Code plan mode explained: the Shift+Tab shortcut, /plan open command, four scenarios where it wins, and how to save a plan to a file. Claude Code plan mode is a read-only mode where Claude reads your codebase, asks questions, and produces a step-by-step plan before it touches a single file. Write tools are disabled. You read the plan, approve it, and Claude runs it. I'm Tom. I run Claude Code every day across content tools, n8n workflows, and Next.js apps. Plan mode is the difference between Claude shipping a clean refactor in one shot and Claude shotgunning twelve files in the wrong direction. This post covers what plan mode is, the shortcut Anthropic does not advertise, four scenarios where it wins, the new /plan open command added in v2.1.119, and how to save a plan to a file for review. > [CTA-BLUEPRINT] ## What is Claude Code plan mode? Claude Code plan mode is a built-in mode that disables Claude's write and execute tools so it can analyze your code and propose a plan without making changes. You enter it with the /plan command or by pressing Shift+Tab. Claude then reads files, asks clarifying questions, and outputs a structured plan. You approve the plan and Claude carries it out. Anthropic introduces plan mode in the common-workflows doc as the recommended approach for any non-trivial change. Read, Grep, and Glob work in plan mode. Edit, Write, and Bash mutations are blocked. [Read the official docs here](https://docs.anthropic.com/en/docs/claude-code/common-workflows), and the v2.1.119 and v2.1.120 fixes are documented in the public [release notes on GitHub](https://github.com/anthropics/claude-code/releases). ## How does Claude Code plan mode work? Plan mode flips Claude into a constrained tool set. Edit, Write, and any mutating Bash command go away. Read, Grep, Glob, and read-only MCP tools stay. The model and context are the same. The system prompt is augmented to tell Claude it is planning, not executing. Claude walks the codebase, asks targeted questions, and produces a numbered plan in the terminal. Once you approve, plan mode exits and Claude runs the plan with the normal tool set restored. ### Why the restricted tool set matters With write tools disabled, Claude cannot get partway through a task and create a half-finished mess. It cannot misread a file and patch the wrong function. The cost is one extra confirmation step. The benefit is a plan you can edit before any code changes. ## How do I enable plan mode in Claude Code? There are three ways to enter plan mode. The slash command, the keyboard shortcut, and the new /plan open command added in v2.1.119. All three put you in the same state. Pick whichever fits your flow. ### Method 1: the /plan slash command Type /plan and hit enter, or follow it with a task description to seed the plan. Claude reads the task, scans the relevant files, and produces a plan. ### Method 2: the Shift+Tab keyboard shortcut This is the shortcut most people miss. Hit Shift+Tab in the Claude Code prompt to toggle plan mode on. Hit it again to toggle off. The status bar shows you which mode you are in. The Mac shortcut is identical to Windows and Linux. There is no separate Cmd combination. ### Method 3: /plan open on an existing plan Added in v2.1.119, /plan open re-enters plan mode on the plan Claude already drafted in the current session. The old behavior overwrote the existing plan. Now it picks up where you left off so you can edit or extend before approving. ## What's the keyboard shortcut for plan mode? The keyboard shortcut for Claude Code plan mode is Shift+Tab. It works on Mac, Windows, and Linux. There is no separate macOS variant. Press it once to enter plan mode, press it again to exit. The shortcut is the fastest way to toggle plan mode mid-session without breaking your flow. ## When should I use Claude Code plan mode? Use plan mode when the work spans multiple files, when one wrong edit is hard to undo, or when you do not yet have a clear path through the change. Do not bother with plan mode for one-line fixes or single-file edits. The overhead is not worth it for trivial work. Below are the four scenarios where I always run plan mode first. ## 4 scenarios where Claude Code plan mode wins ### Scenario 1: refactor across multiple files When I am renaming a core type or moving a shared utility, plan mode catches the import graph. Claude scans every file that references the target and lists each call site that needs updating. Without plan mode, Claude tends to fix the first three files, hit a build error, and start whack-a-mole patching. Concrete example. I had a Sanity helper called formatPostBody living in three places. Plan mode showed me twelve files referencing it, three import paths to update, and one duplicate to delete. Claude shipped the change in one pass with zero build errors. ### Scenario 2: schema migration Schema work is the highest-stakes refactor in any codebase. Get it wrong and you corrupt production data. Plan mode is non-negotiable here. Claude reads the schema, migration tooling, seed data, and consumers, then tells you the order of operations and the rollback path. Concrete example. I was adding a categories array to a Sanity post type. Plan mode flagged that existing posts had no category, the index page filtered by category, and the GROQ query would silently break without a fallback. None of that is obvious until you have shipped the broken version. ### Scenario 3: library upgrade The terrible version of a library upgrade is Claude bumps the version, runs the build, sees forty errors, and starts fixing them in the order they appear. The good version is plan mode. Claude reads the changelog, scans every file using the library, and lists each breaking change with the file location. Concrete example. I upgraded an n8n install from v1.x to v2.x and the node SDK had renamed three core helpers. Plan mode pulled the migration guide from the GitHub release, mapped each rename to the files that used it, and proposed the patch order. The actual upgrade took eight minutes. ### Scenario 4: debugging session Plan mode is underused for debugging. People reach for /debug or just describe the error and Claude jumps straight to a fix. Plan mode forces Claude to lay out the hypothesis, the evidence, and the verification step. You read the plan and can spot the wrong hypothesis before it ships. Concrete example. A Sanity ISR cache was not invalidating after a publish. Claude's first instinct in normal mode was to add a manual revalidate call. In plan mode, Claude listed three causes, the file paths to inspect for each, and the test to confirm. The actual cause was the second hypothesis, not the first. > [CTA-BLUEPRINT] ## How do I exit plan mode? There are two ways to exit Claude Code plan mode. Approve the plan and Claude exits automatically and starts executing. Or hit Shift+Tab to toggle out without running anything. The second method is useful when you want to refine the prompt before letting Claude run. There is no /plan close or /plan exit command. v2.1.119 made /plan open the canonical way to re-enter on an existing plan. Exiting is still done via Shift+Tab or by approving the plan in the terminal. ## What's the difference between plan mode and auto mode? Plan mode and auto mode are opposites. Plan mode disables write tools and asks Claude to draft a plan first. Auto mode keeps all tools enabled and tells Claude to execute without asking permission for routine work. Plan mode is for high-stakes work where one wrong edit costs you. Auto mode is for low-stakes batch work where speed matters more than caution. v2.1.120 fixed a bug where auto-mode instructions were overriding plan-mode behavior. If you saw Claude executing edits while it was supposed to be in plan mode in early v2.1.x builds, that was the bug. Update to v2.1.120 or later and plan mode will hold even when auto-mode prompts are in scope. ### Plan mode vs accept edits Accept edits mode is a third option. It keeps write tools enabled but pauses for human approval before each edit lands. It is the middle setting between plan mode and auto mode. Use accept edits when you trust the strategy but want to vet each individual change. ## How do I save a Claude Code plan to a file? Save a Claude Code plan to a file by asking Claude to write it. The most reliable method is to exit plan mode, then ask Claude to recreate the plan as a markdown file. You can also ask mid plan mode with a prompt like 'save this plan to plan.md before exiting'. Claude can write a plan file because writing markdown is not modifying the codebase. I save plans for any change that touches more than three files. The plan becomes the change record. If something breaks two days later, I re-read the plan, see the assumed call graph, and figure out which assumption was wrong. I save them to a gitignored .planning directory under the project root. ## Why is my Claude Code plan mode not working? Most plan mode issues come from one of three causes. You are on a build older than v2.1.120 where auto mode could override plan mode. You have a CLAUDE.md or skill instructing Claude to execute aggressively, which fights with plan mode. Or you are using /plan in a non-interactive context like a CI run, where Claude has no way to ask follow-up questions and the plan collapses into a single guess. ### Fix 1: update Claude Code Check your version with claude --version. If you are below 2.1.120, run the update. The auto-mode override fix is the load-bearing change. [Recent releases are documented on GitHub](https://github.com/anthropics/claude-code/releases). ### Fix 2: audit your CLAUDE.md and skills If you have system instructions that say 'execute immediately' or 'do not ask questions', plan mode is being told two contradictory things. Strip the aggressive auto-mode language from CLAUDE.md and any always-on skills. Move it to a /loop or /batch skill where it belongs. ### Fix 3: do not use plan mode in non-interactive runs Plan mode wants a human to approve. Running it in a CI job or a non-interactive prompt produces a degraded plan because Claude cannot ask the questions it needs to ask. For non-interactive runs, write a tighter spec up front and skip plan mode. ## Can I edit a plan mid-execution? Yes. After Claude produces a plan and before you approve, you can ask Claude to revise it. Add steps, remove steps, or change the order. Once you approve and Claude starts executing, you cannot edit the plan in flight in the strict sense, but you can interrupt with Esc, drop back into plan mode with Shift+Tab, and ask Claude to revise the remaining steps based on what just happened. This is the workflow I use most often on long migrations. Approve the first three steps, watch Claude run them, hit Shift+Tab when something surprises me, ask for a new plan that accounts for the surprise, approve, continue. v2.1.119 made this loop smoother by keeping the existing plan when you re-enter via /plan open. ## Where Claude Code plan mode falls short Plan mode is not magic. It produces worse plans on codebases it has never read. The first /plan in a fresh session always pulls more files than the second, because Claude is still mapping the territory. A CLAUDE.md with the architecture layout is the difference between a five-file plan and a fifty-file plan. It is also slow on huge repositories. On a 500-file Next.js project, the plan can take a minute or two to draft. The fix is to scope the prompt tightly. /plan refactor the email service is faster than /plan refactor the codebase. And plan mode does not catch external dependencies you have not surfaced. If the work depends on a Vercel env var or a Stripe webhook config, Claude will not know unless you tell it. > [CTA-BLUEPRINT] ## Claude Code plan mode FAQ ### What is the keyboard shortcut for plan mode on Mac? The keyboard shortcut for Claude Code plan mode on Mac is Shift+Tab. It is the same on Windows and Linux. There is no separate Cmd shortcut. ### Does plan mode work in VS Code? Yes. The VS Code extension supports plan mode the same way the terminal CLI does. The /plan command and the Shift+Tab shortcut both work inside the VS Code Claude Code panel. ### Can I use plan mode in non-interactive scripts? Plan mode is designed for interactive sessions where you can read and approve the plan. Running it in a CI script will produce a degraded plan because Claude has no way to ask follow-up questions. For automated runs, write a precise prompt and skip plan mode. ### Does plan mode count against my Claude Code rate limits? Yes. Plan mode runs the same model on the same context as normal mode. It costs the same tokens and counts against your usage. The /usage command shows your current spend regardless of mode. ### Is plan mode available on the free Claude tier? Plan mode is a Claude Code feature, so it is available wherever Claude Code is. As of mid-2026 that includes Pro and Max plans. The free Claude tier does not include Claude Code, so plan mode is not available there. ### Can I customize the plan mode system prompt? Not directly. Anthropic owns the plan mode system prompt and it ships baked in. You can shape the plans you get by writing a strong CLAUDE.md with architecture context and constraints. The model uses CLAUDE.md inside plan mode the same way it does in normal mode. ### Does plan mode work with subagents? Plan mode and subagents are separate concepts. You can ask Claude to plan a task that delegates to a subagent. The plan will include the subagent call as a step. The subagent itself runs in its own context with its own permissions when the plan executes. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Claude Code commands cheat sheet](/blog/claude-code-commands) - [Claude Code subagents vs skills](/blog/claude-code-subagents-vs-skills) - [How to use Claude Code](/blog/how-to-use-claude-code) ## Sources and official documentation Primary sources referenced in this guide: - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) - [Claude Code on GitHub](https://github.com/anthropics/claude-code) ## Ready to ship cleaner Claude Code work? If you are new to Claude Code, start with the [Claude Code Blueprint](/blueprint). It is a free 60-minute guide that walks you through installing, configuring, and shipping your first agent. [If you want to go deeper](/challenge), the 30-day challenge takes you from zero to running production automations. For the foundational tour, [read my full Claude Code guide](/blog/how-to-use-claude-code). For the difference between subagents and skills, [see the sibling post](/blog/claude-code-subagents-vs-skills). Plan mode is the cheapest insurance policy in Claude Code. Two seconds to hit Shift+Tab. Thirty seconds to read the plan. Hours saved on the work that would have gone wrong. ## Frequently Asked Questions ### What is Claude Code plan mode? Plan mode is a built-in read-only mode where Claude reads your codebase, asks clarifying questions, and produces a step-by-step plan before touching a single file. Write tools are disabled. Read, Grep, Glob, and read-only MCP tools stay on. You review the plan, approve it, and Claude runs it with the normal tool set restored. It is the cheapest insurance policy in Claude Code. ### How do I enter plan mode in Claude Code? Three ways. Type /plan and hit enter, optionally followed by a task description. Hit Shift+Tab to toggle plan mode on (same shortcut on Mac, Windows, and Linux). Or run /plan open (added in v2.1.119) to re-enter plan mode on the plan Claude already drafted in the current session. All three land in the same state. ### When should I actually use plan mode? Use it when the work spans multiple files, when one wrong edit is hard to undo, or when you do not yet have a clear path through the change. The four scenarios I always use it for are refactors across multiple files, schema migrations, library upgrades, and tricky debugging. Skip plan mode for one-line fixes or single-file edits. The overhead is not worth it for trivial work. ### What is the keyboard shortcut for plan mode? Shift+Tab. Same shortcut on Mac, Windows, and Linux. There is no separate Cmd combination. Press it once to enter plan mode, press it again to exit. The status bar shows you which mode you are in. It is the fastest way to toggle plan mode mid-session without breaking your flow. ### What is the difference between plan mode and auto mode? They are opposites. Plan mode disables write tools and asks Claude to draft a plan first. Auto mode keeps all tools enabled and tells Claude to execute without asking permission for routine work. Plan mode is for high-stakes work where one wrong edit costs you. Auto mode is for low-stakes batch work where speed matters more. v2.1.120 fixed a bug where auto-mode instructions could override plan mode, so update if you are on an older build. ### Why is my plan mode not working? Three usual causes. You are on a build older than v2.1.120 where auto mode could override plan mode (check with claude --version and update). You have a CLAUDE.md or always-on skill telling Claude to execute aggressively, which fights with plan mode. Or you are running /plan in a non-interactive context like a CI job, where Claude cannot ask follow-up questions and the plan degrades to a single guess. ### Does plan mode cost extra tokens or count against my rate limit? Yes. Plan mode runs the same model on the same context as normal mode. It costs the same tokens and counts against your usage. The /usage command shows your current spend regardless of mode. The trade-off is that the planning step often saves you from a 50-file whack-a-mole patch loop later, which is the much more expensive failure mode. - [Claude Code Plan Mode Checklist Before Production Edits](/blog/claude-code-plan-mode-checklist) --- # Paperclip AI Review: How to Use It, Set It Up + Pricing Source: https://theaiarchitects.com/blog/paperclip-ai-review Published: 2026-05-11 Hands-on Paperclip AI review and setup tutorial. What it does, how to install it, pricing, alternatives, and whether it's worth the hype. Paperclip AI is a free, open-source orchestration platform that lets you build autonomous AI teams. You hire AI employees, give them job titles, assign them tasks, and they run operations on their own. Think of it as the company that wraps around tools like Claude Code or Codex. Those tools are the individual workers. Paperclip AI is the org chart, the CEO, the management layer, and the Kanban board that ties them together. Quick disambiguation before we go further. Not to be confused with the indie game *Universal Paperclips*, or Nick Bostrom's paperclip-maximizer thought experiment in AI safety. Paperclip AI is an actual software product you can install and run today. It's the orchestration layer that sits above coding agents like Claude Code and lets you run a whole team of them on autopilot. If you searched for "paperclip ai" or "ai paperclip" expecting a game or a philosophy paper, this is the other one. I'm Tom. I've been in the automation space for over eight years, and I tested Paperclip AI over a few days on a VPS to figure out whether it's a real productivity tool or another hype cycle. Below is a hands-on Paperclip AI tutorial, my honest review, the standout features, where it falls short, pricing, alternatives, and the full setup walkthrough. ## What is Paperclip AI? Paperclip AI is an open-source AI orchestration platform that lets you build what its creators call "zero human companies." Instead of running a single AI agent, you spin up a whole organisation: a CEO at the top, C-suite below, engineers and staff under those. Each agent gets a job title, system prompt, skills, and tasks. They communicate, delegate, and report back to you. https://www.youtube.com/watch?v=ESUKpCDxLuo Free, open source, and over 44,000 developers on GitHub. The simplest way to think about it: if Claude Code or Codex are individual AI employees, Paperclip AI is the company those employees work inside. ## How does Paperclip AI work? Paperclip AI runs as a self-hosted application. You can install it on your own machine, a Mac Mini, or a VPS. Once it's running, you log into a web interface that looks like a project management tool crossed with an org chart. From there, the structure works top-down. ### The hierarchy: company, project, agent, task Everything is structured top-down. You set a company mission. Inside the company you create projects. Each project has a goal. You then hire agents, starting with a CEO, and assign them issues, which are essentially tasks. The CEO orchestrates the other agents and delegates work down the chain. ### Heartbeats and autonomy Only the CEO has a heartbeat, a recurring trigger that runs on whatever interval you set (default 3,600 seconds, one hour). When the heartbeat fires, the CEO checks for new issues and decides what to do. You or other agents create the issues, the CEO assigns them, and the system runs without you manually triggering every step. That's where the "autonomous" claim starts to hold up. ### Adapters: the LLM behind each agent Each agent runs on an adapter: Claude Code, Codex, or any LLM you plug in. Under the hood every agent is essentially an instance of that adapter with its own system prompt, AGENTS.md file, skills, and configuration. Five agents plus a CEO is six concurrent Claude Code instances running. ## What I tested with Paperclip AI I deployed Paperclip AI on a Hostinger VPS using their one-click install (KVM2 plan, $8.99/month). Deploy took a couple of minutes. Then I ran the full setup: connected Claude via SSH, named the company "AI Growth Lab," wrote the mission and goal, hired a CEO, and told it to hire a founding engineer. From there I built a real workflow: an autonomous social media content pipeline. Four specialist agents (content researcher, hook writer, post writer, quality checker), each loaded with the system prompts, MD files, and copywriting principles I already use manually inside Claude Code. I gave the CEO an issue: pull research from Reddit and YouTube, narrow to three ideas, generate hooks, write the posts, run every draft through the humanizer pass. Then I ran the heartbeat. The CEO picked up the issue, delegated to each agent in order, and the agents talked to each other through the system. The output was a usable LinkedIn hook, which tracks because the skill files are the same ones I use to write content that pulls millions of views. The orchestration worked. I saved the whole thing as a daily routine, so it now runs in the background automatically. ## Standout Paperclip AI features Five things stood out from the test: 1. The org chart is the product. You're not building one agent, you're building a company. CEO at the top, C-suite below, engineers underneath. The org chart isn't decorative. It's how delegation actually flows. 1. Heartbeats turn agents into background workers. The CEO can run on a schedule, check for new issues, and dispatch work without you. It's the closest thing I've seen to a true "set it and forget it" agent system. 1. Routines for daily workflows. You can save any process (like my content pipeline) as a routine, set it on a daily trigger, and Paperclip AI will run the whole multi-agent workflow on schedule. Mine now ships content options into my inbox every day. 1. Skills and MCPs work across agents. You can install Claude Code skills inside the VPS terminal, paste them into Paperclip AI, or pull them from a skills marketplace. Once installed, agents can use them. Same for MCPs. This is also where the Paperclip AI plugins ecosystem will eventually live: anything that already works with Claude Code or the broader MCP standard plugs in here. 1. Import and export companies. You can export a working organisation and someone else can import it. That means the most useful thing about Paperclip AI might end up being a marketplace where people sell pre-built AI companies that already work for a specific use case. > [CTA-BLUEPRINT] ## Where Paperclip AI falls short I'll give you the criticism straight, because anyone telling you this is plug-and-play hasn't actually used it. First, the setup is not for beginners. The marketing makes it sound like "define the goal, hire the team, approve, and run." In reality you need to be comfortable with a VPS, SSH, Docker, environment files, and the basics of Claude Code skills and MCPs. If you've never opened a terminal, you'll struggle. Second, the outputs are only as good as the context you put in. Paperclip AI orchestrates, it doesn't write your content or do your research. Every system prompt, every AGENTS.md file, every skill has to be built and tuned by you. Garbage in, garbage out, with extra steps. Third, security is your problem. The platform doesn't wrap your VPS in best practices. Use Tailscale to lock down access so only you can connect, and keep API keys in the .env file, never pasted into chat. Fourth, costs scale fast. Each agent is its own instance of Claude Code. Five agents plus a CEO is six concurrent instances burning tokens. Autonomous routines running in the background will hit Claude subscription limits quickly. Fifth, and this is important: Anthropic's updated rules say you cannot connect your Anthropic subscription to third-party harnesses like Paperclip AI or Open Claude. Use an Anthropic API key instead. ## Is Paperclip AI free? Yes. Paperclip AI is free and open source, with over 44,000 developers on GitHub. There's no licence fee for the platform itself. You pay for two things. First, the infrastructure: a VPS like Hostinger starts around $6.50 to $8.99 a month for the KVM plans that comfortably handle Paperclip AI plus a handful of agents. A Mac Mini you already own runs it for $0. Second, the LLM you plug in. Each agent burns API tokens, so a CEO plus five specialists on a Claude adapter is six concurrent Claude Code sessions every time the heartbeat fires. So the honest answer to "is Paperclip AI free?" is this: the software is free, the running costs are not. Budget $10 to $20 a month for hosting plus whatever your LLM provider charges. A serious production setup with multiple agents on daily routines runs $50 to $200 a month in API spend until you've tuned the workflows. ## Paperclip AI vs other AI tools ### Paperclip AI vs Claude Code Claude Code is one AI agent doing one job at a time, in your terminal. Paperclip AI is a layer above Claude Code. It spawns multiple Claude Code agents, gives them roles, lets them communicate, and runs them on schedules. You don't pick one or the other. Paperclip AI uses Claude Code as its workforce. ### Paperclip AI vs ChatGPT ChatGPT is a chat interface for prompting one model. Paperclip AI is an orchestration platform for running an autonomous AI team in the background, with delegation, heartbeats, routines, and a Kanban board. They're not the same category. If you want a conversation, use ChatGPT. If you want a system that runs while you sleep, use Paperclip AI. ### Paperclip AI alternative: Open Claude and other harnesses If you're hunting for a Paperclip AI alternative, the closest is Open Claude, another harness that sits closer to Claude Code itself. Paperclip AI sits above harnesses like Open Claude as the orchestration layer. Adjacent tools include CrewAI and AutoGen on the Python side, but those are libraries you wire up yourself rather than a hosted UI with a Kanban interface and built-in heartbeats. If you want to see what serious orchestration looks like before you go full Paperclip AI, this [case study with Keven Elison](/case-studies/kevin) walks through how he stitched together n8n, RAG, and MCP servers to run a real B2B marketing operation. Same orchestration mindset, different layer of the stack. My take: Paperclip AI is a step up from Claude Code and Open Claude. It's the next layer of the AI automation stack. > [CTA-HOSTINGER] ## How to install Paperclip AI Here's how to install Paperclip AI from scratch. Don't worry if you've never used a terminal. Follow each phase in order. ### Phase 1: Choose where to run it You have three options: your own laptop, a Mac Mini, or a VPS. I don't recommend running it on your daily-driver laptop because it has access to all your files. A Mac Mini works as a sandboxed environment but you need to keep it running 24/7. A VPS is the cheapest and cleanest way to get started. I used a Hostinger KVM2 at $8.99 a month, with a one-click Paperclip AI install in their Docker catalog. ### Phase 2: Deploy Paperclip AI Inside Hostinger (or any VPS provider with Docker support), go to Docker Manager, then Catalog, search for Paperclip, set your admin email and password, and hit deploy. Takes a couple of minutes. If you're using your own VPS, install via Docker manually using the official Paperclip AI documentation. ### Phase 3: Add your API keys to the environment file Do not paste API keys into the Paperclip AI chat or comments. That exposes them. Find the .env file in your Docker manager, add ANTHROPIC_API_KEY and any other keys you want Paperclip AI to use, and save. This is also how you give it access to additional services. ### Phase 4: SSH into your VPS and install Claude Code SSH into your VPS as root using the password from the hosting dashboard. Run docker ps to find the Paperclip container ID, then docker exec -it [CONTAINER_ID] /bin/bash to drop into the container. Run claude to install and authenticate Claude Code. This is what makes skills and MCPs available across all your Paperclip AI agents. ### Phase 5: Lock down security Before you put anything serious in there, secure the VPS. Ask Claude how to set this up. Most people end up using Tailscale so the VPS is only reachable when connected to their Tailscale network. Don't skip this. ### Phase 6: Set up the company, mission, and CEO Open Paperclip AI in your browser, log in, name your company, and write a concise mission and goal (I asked Claude Code to draft mine from my full company context). Create your first agent: the CEO. Pick the Claude Code adapter, test it, confirm it goes green, and set the heartbeat interval (one hour is fine to start). ### Phase 7: Hire your team and start small Don't try to build a 10-agent org on day one. Start with the CEO plus one engineer. Give the CEO "hire a founding engineer" as a starter task. Approve the hire from your inbox. Then add a project, hire the specialists you need, and give each a tuned system prompt and AGENTS.md file. ## How to use Paperclip AI in a real workflow Setup is one thing. Knowing how to use Paperclip AI day to day is another. Here's the loop I now run every week. Monday morning I open the Kanban board, review what shipped over the weekend, leave comments on three to five drafts that need rework, and approve the rest. Approved items go to publishing. Rejected items go back to the agent with a comment, the same way you'd manage a junior on Slack. When a workflow drifts, I edit the AGENTS.md file for the agent that's misfiring and re-run the routine. Almost every problem I've hit traces back to a fuzzy system prompt rather than a Paperclip AI bug. The Paperclip AI Reddit threads and the project's GitHub discussions are the best place to see how other people are wiring up their orgs. ## Verdict: is Paperclip AI worth it? Paperclip AI is the most exciting orchestration tool I've seen in a while. Running a full AI team that delegates work, checks outputs, and runs around the clock is a real step up from working with single agents. I'm bullish on where this goes, especially the import/export marketplace angle. Who Paperclip AI is for: people already comfortable building with Claude Code, with specific workflows they want to automate end-to-end. If you've already got skills, prompts, and processes dialled in, Paperclip AI is the missing orchestration layer. Who it's not for: beginners who haven't touched a terminal, or anyone expecting a no-code drag-and-drop builder. Get comfortable with Claude Code first. > [CTA-BLUEPRINT] ## Paperclip AI FAQ ### What is Paperclip AI? Paperclip AI is a free, open-source AI orchestration platform that lets you build autonomous AI teams. You set a company mission, hire AI agents (CEO, engineers, specialists), assign tasks, and the system runs delegation and execution on its own. ### How does Paperclip AI work? Paperclip AI runs as a self-hosted Docker app. You set a company mission, hire a CEO agent, then specialists. The CEO's heartbeat fires on a schedule, picks up new issues, and delegates them. Each agent runs on an LLM adapter like Claude Code or Codex. ### Is Paperclip AI free? Yes. Paperclip AI itself is free and open source, with over 44,000 developers on GitHub. You'll pay for the infrastructure you run it on (a VPS like Hostinger starts around $6.50 to $8.99 a month) and for whatever LLM you plug in via API. ### How do I install Paperclip AI? The fastest path is a VPS with a Docker one-click install (Hostinger has it in their catalog). You can also self-host on a Mac Mini or your own machine via Docker. After deploy, log in, add API keys to the .env file, SSH into the container to install Claude Code, and start building. ### What can I use Paperclip AI for? Anything you currently run as a multi-step workflow with Claude Code or another AI tool, where you want it to run on a schedule without you: content pipelines, research and summarisation, lead enrichment, code review on PRs, support triage, ops reporting. The pattern is always the same: break the workflow into roles, hire one agent per role, and let the CEO orchestrate. ### Is Paperclip AI better than ChatGPT? They're not the same category. ChatGPT is a chat interface. Paperclip AI is an autonomous orchestration platform that runs multiple AI agents on a schedule. If you want a conversation, use ChatGPT. If you want a system that delegates and ships work in the background, use Paperclip AI. ### Where can I find Paperclip AI documentation? The official Paperclip AI documentation lives on the project's GitHub repo and project site, covering install, adapter configuration, and the API reference. Community discussion happens on Reddit and in GitHub discussions. ### Is Paperclip AI safe to run? Running an autonomous AI organisation on your daily-driver laptop is not the best idea, because it has access to your files. Use a VPS or a sandboxed Mac Mini, lock it down with something like Tailscale so only you can connect, and keep API keys in the environment file rather than pasted into the chat. ### Can I connect my Claude subscription to Paperclip AI? No, and this is important. Anthropic's updated rules state you cannot connect your Anthropic subscription to third-party harnesses like Paperclip AI or Open Claude. Use an Anthropic API key instead. You'll be able to track costs in Paperclip AI directly. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [How to install Claude Code](/blog/how-to-install-claude-code) - [Best Claude Code skills](/blog/best-claude-code-skills) - [Claude Code vs Cursor](/blog/claude-code-vs-cursor) ## Sources and official documentation Primary sources referenced in this guide: - [Paperclip AI on GitHub](https://github.com/paperclip-ai/paperclip) - [Anthropic usage policies](https://www.anthropic.com/legal/aup) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) ## Ready to build production-ready AI systems? If you want to go deeper than "I installed a tool" and actually build production-ready AI systems for your business, the [30-Day Claude Code Challenge](/challenge) takes you through an interactive Claude Code course inside Claude Code. You'll build your first web app and your first automation. Applications are live if the cohort is open. Not ready for the challenge yet? Grab the [free Claude Code Blueprint](/blueprint). It's the starting point most people use before they commit to building. It's the foundation Paperclip AI sits on top of, so going through the Blueprint first will make every Paperclip AI workflow you build hit harder. ## Frequently Asked Questions ### What is Paperclip AI? Paperclip AI is a free, open-source AI orchestration platform that lets you build autonomous AI teams. You set a company mission, hire AI agents (CEO, engineers, specialists), assign tasks, and the system runs delegation and execution on its own. Think of it as the company that wraps around tools like Claude Code or Codex. Those tools are the individual workers. Paperclip AI is the org chart, the Kanban board, and the management layer that ties them together. ### Is Paperclip AI free? The software is free and open source, with over 44,000 developers on GitHub. The running costs are not. Budget $10 to $20 a month for VPS hosting (Hostinger's KVM2 plan is $8.99) plus whatever your LLM provider charges. A serious production setup with multiple agents on daily routines runs $50 to $200 a month in API spend until you have tuned the workflows. ### Can I connect my Claude subscription to Paperclip AI? No, and this is important. Anthropic's updated rules say you cannot connect your Anthropic subscription to third-party harnesses like Paperclip AI or Open Claude. Use an Anthropic API key instead. You will be able to track costs in Paperclip AI directly. Pasting your Claude subscription credentials into a third-party harness risks getting your account flagged. ### Is Paperclip AI for beginners? No. The marketing makes it sound like 'define the goal, hire the team, approve, and run', but in reality you need to be comfortable with a VPS, SSH, Docker, environment files, and the basics of Claude Code skills and MCPs. If you have never opened a terminal, you will struggle. Get comfortable with Claude Code first before layering Paperclip AI on top. ### How does Paperclip AI work? Paperclip AI runs as a self-hosted Docker app. You set a company mission, hire a CEO agent, then specialists. Only the CEO has a heartbeat, a recurring trigger that runs on whatever interval you set (default 3,600 seconds, one hour). When the heartbeat fires, the CEO checks for new issues and delegates them. Each agent runs on an LLM adapter like Claude Code or Codex. ### How is Paperclip AI different from Claude Code? Claude Code is one AI agent doing one job at a time, in your terminal. Paperclip AI is a layer above Claude Code. It spawns multiple Claude Code agents, gives them roles, lets them communicate, and runs them on schedules. You do not pick one or the other. Paperclip AI uses Claude Code as its workforce. ### Is Paperclip AI safe to run on my main computer? Running an autonomous AI organisation on your daily-driver laptop is not a great idea, because it has access to all your files. Use a VPS or a sandboxed Mac Mini, lock it down with Tailscale so only you can connect, and keep API keys in the .env file rather than pasted into chat. The platform does not wrap your VPS in best practices. Security is your job. --- # How to Succeed in AI Without Grinding 24/7 Source: https://theaiarchitects.com/blog/succeed-in-ai-without-grinding Published: 2026-05-10 You don't need to grind 17-hour days to succeed in AI. The people winning are not the ones working the most hours. They are the ones using leverage. You do not need to grind 24/7 to succeed in AI. The people who actually win in this space are not the ones putting in 17-hour days. They are the ones building the right systems, finding the right problems, and using leverage to multiply every hour they do work. I am Tom. I have been in the automation and AI space for years, and I have done the chronically online, 14-hour-a-day version of this game. I burned out. I want to walk you through what I actually believe works, why grinding is a trap, and the calmer path most creators will not tell you about because it does not sell coaching programs. > [CTA-BLUEPRINT] ## Do you need to grind 24/7 to learn AI? No. You do not need to grind 24/7 to learn AI or to build a career in it. Hours do not equal money. Volume does not equal results. The single most expensive lie sold in the AI space right now is that you have to outwork everyone else to make it. In the video below I lay out the case directly. It is not a tutorial. It is a position piece on what hustle culture is actually doing to your output, and what the alternative looks like. https://www.youtube.com/watch?v=uYXpZWSaKIs > Every creator, every guru telling you to wake up at 4 a.m. to grind it out all day, they only want you to believe one thing. That the only way to make it in AI is to outwork everyone else. And I am here to tell you that is complete nonsense. That is straight out of the video. I stand behind every word of it. The AI tools you are using exist precisely so you do not have to throw raw hours at every problem. Using leverage tools and then ignoring the leverage they give you is the most common mistake I see new builders make. ## What hustle culture actually does to your output You wake up at 5 a.m., open X first thing, see a 19-year-old posting a 100K screenshot, and feel that pit drop in your stomach. You have been doing 14-hour days. You are vibe coding five different apps a week. None of it is making any money. You feel guilty closing the laptop. You feel guilty sleeping eight hours. You feel guilty seeing friends. That feeling is not a sign you are behind. It is a sign the loop you are in is broken. I have been in it. I know exactly what it feels like. And I want to tell you what is actually happening underneath it. When you sustain low sleep over months, your cognitive function tanks. You will not feel it because you normalize it. But if you tested current-you against eight-to-nine-hours-of-sleep-you, the gap would be embarrassing. There is real science on this. Matthew Walker's work in [*Why We Sleep*](https://en.wikipedia.org/wiki/Why_We_Sleep) lays out the cognitive cost of sleep debt in clinical detail. You cannot out-grind biology. > If you start throwing hours at a problem, you are going to be thinking that volume equals results when that is really not the case. You will eventually hit diminishing returns. Then there is the comparison trap. If you are making a few grand a month, the goal is 10K. Hit 10K, the goal becomes 50K. Hit 50K, it becomes 100K. Nothing is ever enough. When your identity is welded to that number, a single bad month or one unexpected expense can destroy you. I have invested heavily in mentors and programs over the years. Some hit, some did not. The bank account is not a stable place to store your self-worth. ## How long does it take to learn AI? Long enough that grinding 17 hours a day for two weeks will not get you there, and short enough that you do not need to ruin your health for it. In my experience, three to four focused hours a day across three to six months is enough to go from beginner to building real workflows that solve real problems. The bottleneck is not raw time. It is the quality of the problems you point your hours at. In [*Deep Work*](https://www.calnewport.com/books/deep-work/), Cal Newport argues that nobody can do real cognitive work for more than around four hours a day. He himself does two two-hour deep blocks and stops. That is the ceiling, not because he is lazy, but because that is how human focus works. Anything past that is busywork dressed up in a Pomodoro timer. So when somebody tells you they are putting in 17-hour days to learn AI, two things are usually true. They are lying about the hours, or they are doing four hours of work and 13 hours of low-grade scrolling, refactoring, and tab-switching that feels productive. ## What is the sustainable way to learn AI? You pick one tool, one problem, and one outcome. You spend two to four focused hours a day on it. You go to bed on time. You see your friends. You let ideas percolate while you walk, train, cook, or sleep. The percolation is where the high-leverage decisions actually come from. You cannot solve a problem you have stared at for ten hours straight. You can solve it after a night of sleep and a coffee. Naval Ravikant has the cleanest framing for this. The corner shop owner works as hard, often harder, than the tech CEO. The difference is not effort. It is leverage. The shop owner trades hours for money. The CEO uses code, capital, and media to decouple earnings from hours. Same effort, different tools. You can read his [How to Get Rich](https://nav.al/rich) series for the long version. To succeed in AI, you want to be on the leverage side of that equation, not the hours side. > Output equals volume times leverage. Time has a ceiling, but your leverage does not. So focus on the one without a ceiling. Practically, that means automation, content, productized services, and tools you build once and sell or use a hundred times. It does not mean five-app-a-day vibe coding sprints that never ship. I do believe in seasons. There are weeks where I am in a sprint and the hours are long. That is fine when it is bounded and pointed at a clear goal. The danger is when the sprint becomes the lifestyle. Bounded sprints, then real recovery. That is the rhythm. Watch how an athlete trains. Nobody is in race condition all 52 weeks. And do not underestimate the social cost. Grinders are isolated. The only human contact most of them get is via screen, which is mostly other people performing fake versions of themselves. I do West Coast Swing twice a week. Hugging, high-fiving, being physically near other humans. That is not a luxury. That is required hardware for a working brain. ## Verdict: the anti-hustle path to succeed in AI My honest position. Grinding 17 hours a day to succeed in AI is not the smart move. It is the lazy one. It is easier to throw raw hours at a problem than to sit still and figure out which problem is actually worth solving. The lazy option looks productive. It is not. This path is for you if you want freedom, time with the people you care about, and a working body and brain at age 60. It is not for you if you want to be the next Elon Musk and you are willing to torch every relationship and organ in your body to get there. Both are valid choices. Pick one with your eyes open. For everyone else, the answer is the same. Fewer hours. Better problems. More leverage. More sleep. More humans. > [CTA-BLUEPRINT] ## Frequently asked questions ### Do you need to grind 24/7 to succeed in AI? No. The people who win in AI are not the ones with the most hours logged. They are the ones who pick the right problem, build the right system once, and use leverage to scale the output. Volume of hours hits diminishing returns fast. Leverage does not. ### How long does it take to learn AI to a useful level? Three to six months of focused, three-to-four-hour daily work is enough for most people to go from zero to building real workflows that solve real problems. The bottleneck is not the hours. It is whether the problem you are solving actually matters. ### Is AI burnout real? Yes. AI burnout is the same shape as any other knowledge-work burnout, but it gets accelerated by hyper-online culture and the constant feeling that a new tool is dropping every 12 hours. Sleep loss, social isolation, and identity tied to revenue screenshots are the three biggest accelerants. Cap your hours, defend your sleep, and stop measuring yourself against curated X feeds. ### What is the sustainable way to learn AI in 2026? One tool, one problem, one outcome at a time. Two to four focused hours a day. Eight hours of sleep. Real human contact. Bounded sprints when you need to push, real recovery when you do not. Build leverage assets like automations, content, and small products instead of trading raw hours for raw cash. ### How do I avoid the AI comparison trap? Most of the revenue screenshots you see online are either fake, cherry-picked, or attached to a much darker private life than the post implies. Treat the timeline as entertainment, not as a benchmark. Run your own race against your own numbers from last month. That is the only honest comparison. ### Should I take weekends off when I am learning AI? Yes, in almost every case. Real cognitive work needs recovery. The good ideas surface in the gaps, not in hour 14 of staring at a screen. Take the weekends. See people. Move your body. Come back Monday with a clearer brain and you will out-ship the seven-day grinder every time. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [The Claude Code Ralph loop](/blog/claude-code-ralph-loop) - [The best Claude Code skills](/blog/best-claude-code-skills) - [How to use Claude Code](/blog/how-to-use-claude-code) ## Sources and official documentation Primary sources referenced in this guide: - [Claude Code on GitHub](https://github.com/anthropics/claude-code) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) ## Ready to succeed in AI without burning out? If you want the leverage path, start with the [Claude Code Blueprint](/blueprint). It is a free 60-minute walkthrough that shows you how to build your first real automation without writing code. If you want the structured version, the [30-Day Claude Code Challenge](/challenge) runs once a month and is built around the exact opposite of grind culture. Three to four focused hours a day, real outputs, no all-nighters. If you want to see what one of these systems looks like in practice, my [Paperclip AI review](/blog/paperclip-ai-review) walks through how I run an autonomous AI team without sitting at the keyboard for 17 hours a day. --- # Is Claude Code Free? What You Pay in 2026 Source: https://theaiarchitects.com/blog/is-claude-code-free Published: 2026-05-09 Claude Code is not free. You need a Pro, Max, Team or API account. Here's what each tier costs in 2026 and the cheapest way to actually use it. Claude Code is not free. As of May 2026, you need a paid Anthropic plan to run it, starting at Pro for $20 a month, or you bring your own API key and pay per token. The free Claude.ai chat plan does not include Claude Code access, and Anthropic's own setup docs say so directly. If you read an article from 2025 saying Claude Code was free with the Pro plan, that's still mostly true, but the messaging got messy in April 2026 when Anthropic ran a test that briefly removed Claude Code from Pro for a slice of new users. [The Register covered it on April 22, 2026](https://www.theregister.com/2026/04/22/anthropic_removes_claude_code_pro/). The test was reverted. Existing Pro subscribers were never affected. But the search results haven't caught up. I'm Tom. I've been on a paid Anthropic plan since Claude Code launched, I've shipped real client work on Pro, Max 5x and Max 20x, and I've watched my own usage spike and crash with the rate limits. Here's exactly what you pay, what you get on each tier, and which path is actually cheapest for the way you work. > [CTA-BLUEPRINT] ## Is Claude Code free? No. Claude Code requires a paid plan. [Anthropic's setup documentation states it plainly](https://code.claude.com/docs/en/setup): "Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access." The cheapest legitimate route is Pro at $20 a month, or $17 a month if you pay annually. The other route is a pay-as-you-go Anthropic API key, billed per token through the Console. There is no free tier, no free trial that lasts beyond your first session, and no "free with limits" mode like ChatGPT's free chat. If you saw a screenshot from earlier this year showing Claude Code as a Pro feature, that screenshot is correct again today. The April 2026 test that pulled it for a small percentage of new users was rolled back. The pricing page now lists Claude Code as included with Pro, Max, Team and Enterprise. ## What plan do I need to use Claude Code? You need one of five accounts: Pro, Max 5x, Max 20x, Team, or an Anthropic Console account with an API key. Each one unlocks Claude Code in the terminal, the desktop app, the VS Code extension, the JetBrains plugin, and the iOS app. The same login works across all surfaces, so you only pay once. Pro at $20 a month is the entry point. You get Claude Code on Sonnet, weekly usage caps that Anthropic tunes against the average Pro developer, and access to the desktop, terminal and IDE clients. Max 5x at $100 a month bumps the cap roughly five times higher and unlocks Opus access. Max 20x at $200 a month is twenty times the Pro cap and is the only plan that supports the highest effort tier, useful if you're doing long agentic runs across a big codebase. Team and Enterprise are seat-based for orgs that want SSO and central billing. The API key path is different. You don't pay a flat fee. You add a credit card to the Anthropic Console, generate a key, point Claude Code at it with ANTHROPIC_API_KEY, and you get charged per token. Cheap if you barely use it, brutal if you run agents all day. ## How much does Claude Code cost? Pro is $20 a month, or $17 a month billed annually. Max 5x is $100 a month. Max 20x is $200 a month. Team is $25 per seat per month, or $20 per seat on annual billing. Enterprise is $20 per seat plus usage. The API path has no monthly fee but you pay per million tokens, with Sonnet 4.6 priced lower than Opus 4.7. Anthropic publishes the full breakdown on the [official pricing page](https://claude.com/pricing), but the page hides the most important detail behind a hover. The Pro plan is rate-limited weekly, not just per-session. If you push hard for two days, you can burn through your weekly cap and get throttled until the cycle resets. That's the real cost on Pro for power users, and it's the reason most people I know on Pro upgrade to Max within a couple of months. ## Did Anthropic change Claude Code pricing in 2026? Yes, briefly. Between April 21 and April 22, 2026, Anthropic updated the Pro plan feature list to show an X next to Claude Code instead of a checkmark. New users signing up to Pro saw Claude Code disabled. Developers spotted it within hours and the forums lit up. Anthropic confirmed it was a test affecting roughly 2% of new users, said existing subscribers were not affected, and reverted it shortly after. Anthropic's growth lead said at the time: "When we do land on something, if it affects existing subscribers you'll get plenty of notice before anything changes." The [full Register report](https://www.theregister.com/2026/04/22/anthropic_removes_claude_code_pro/) is worth reading for context. The takeaway: the official pricing page is the source of truth on any given day, and right now Claude Code is included with Pro again. ## Can I use Claude Code with the Pro plan? Yes. Pro at $20 a month includes Claude Code on Sonnet 4.6 across the terminal, desktop, IDE and web. You log into Claude Code with the same email you use for claude.ai and your subscription is detected automatically. No extra step, no separate billing, no API key needed. Pro is genuinely useful for solo developers, side projects and content work. I built three internal tools and shipped two client projects on Pro before I hit the weekly cap. Where Pro starts to hurt is if you're running long agent loops, refactoring across hundreds of files, or you sit in plan mode for hours generating large outputs. The cap arrives faster than you expect because agentic work consumes far more context than chat. > [CTA-BLUEPRINT] ## Is Claude Code free for developers? Not in the way most tools mean it. There is no free tier for individual developers. Students don't get a discount on Claude Code specifically, though Anthropic occasionally runs Claude for Education promotions on the chat product. Open source maintainers, hackathon entrants and indie hackers all pay the same $20 a month. The closest thing to free is the Anthropic API trial credit, which Anthropic hands out occasionally when you create a Console account. That credit, if you get it, runs through the same key you'd use with Claude Code. So technically you can run Claude Code for free until the credit runs out, but it's small and it doesn't refresh. Treat it as a tasting menu, not a free tier. ## Does Claude Code use my API credits? Only if you tell it to. By default, Claude Code authenticates to your Pro or Max subscription, so usage counts against your subscription's weekly cap, not your API balance. If you set the ANTHROPIC_API_KEY environment variable, Claude Code switches to API billing and every prompt, file read and tool call eats your token credit. This is the trap most teams fall into. They set the API key for one experiment, forget to unset it, and a week later their Console balance is half drained. If you're on Pro or Max, do not export ANTHROPIC_API_KEY in your shell profile. Use it only when you genuinely need API billing, like agent SDK work or running Claude Code in CI through GitHub Actions. ## What's the cheapest way to use Claude Code? For most people, Pro at $17 a month on annual billing. That's the floor. If you use it for under an hour a day on side projects, Pro is plenty and the $204 a year is cheaper than almost any developer tool you'll buy. For heavy users, Max 5x at $100 a month is cheaper than spinning up the same workload on the API. The math: a single hour of agent time on Opus 4.7 with serious context can cost $5 to $15 in API tokens. Twenty hours of that a month and you're already at Max territory. The flat fee buys predictability. For occasional users with bursty workloads, the API key route can be cheapest, especially if you only use Claude Code once a week. Set a budget alert in the Console and it stays under control. ## Is Claude Code free vs ChatGPT? ChatGPT has a free chat tier. Claude Code does not. That's the core difference. OpenAI's free ChatGPT plan lets you talk to GPT-5 with limits, no card on file. Anthropic's free Claude.ai plan lets you talk to Claude Sonnet, also no card. Neither free plan gives you a coding agent that runs in your terminal. If you want a comparable free agentic coding experience, the closest options are GitHub Copilot's free tier for verified students, OpenAI's Codex CLI through a paid ChatGPT Plus or Pro subscription, or open-source agents you run against a local model. Each has trade-offs and none of them match Claude Code's multi-surface UX. I covered the gap between Claude Code and the rest of the field in [Claude Code just got 10x more powerful](/blog/claude-code-10x-more-powerful) if you want the feature-by-feature breakdown. ## Where the "Claude Code is free" pitch falls apart I see this line on Twitter and LinkedIn most weeks: "Claude Code is basically free if you already pay for Claude Pro." That's true today. It's also fragile. The April 2026 test proved Anthropic can pull the bundle on a whim, and the next time it might not be a 2% experiment. If you're building a business around Claude Code being included with Pro, you're building on a feature that's bundled at Anthropic's discretion. The honest framing: Claude Code is included with Pro right now. Treat it as a $20 a month standalone tool that happens to bundle a chatbot, not a free add-on to your chatbot subscription. Price your work that way, and you don't get caught out if the bundling changes. ## Verdict: is paying for Claude Code worth it? Yes for anyone shipping code or building automations weekly. No for anyone who hasn't actually written a project with it yet. Pro at $20 buys you a real engineering teammate that reads your codebase, edits files, runs commands and ships work in the background. If you use it for an hour a day for a month, the cost-per-hour is under a dollar. If you're a beginner, start on Pro for one month. Don't jump to Max until you hit the weekly cap twice. Most people never hit it. If you're a heavy agent user running long autonomous tasks across multiple repos, go straight to Max 5x. You'll save money over the API route and you'll stop worrying about token budgets every prompt. If you're testing Claude Code for a specific project and won't touch it again for weeks, the API key route is fine. Set a $20 budget cap in the Console and forget about it. > [CTA-BLUEPRINT] ## Claude Code pricing FAQ ### Is there a Claude Code free trial? Not as a published feature. Anthropic occasionally seeds new Console accounts with a small API trial credit you can spend on Claude Code through an API key, but it's not advertised, it doesn't refresh, and it's small. The closest thing to a trial is the Pro plan's monthly billing. Cancel inside 30 days and you've spent $20 to take Claude Code for a real test drive. ### Is Claude Code free with Max? It's included, not free. Max 5x at $100 and Max 20x at $200 a month both bundle Claude Code along with higher rate caps, Opus 4.7 access and the highest effort tier on Max 20x. You're paying for the model and the cap, and Claude Code rides along. ### Is Claude Code free in VS Code? The VS Code extension itself is free to install from the Marketplace. The agent inside it is not. The extension authenticates to the same Pro, Max, Team or API account you use everywhere else, and usage counts against that plan. There's no separate VS Code-only tier. ### How does Claude Code billing actually work? If you're on Pro, Max, Team or Enterprise, usage is metered against your plan's weekly cap and you don't see line-item costs. If you're on the API path, every prompt and tool call is billed per token to the credit card on your Console account. You can track real-time spend with the /usage command inside Claude Code. ### Does Claude Code charge per request? Only on the API path. Subscription users (Pro, Max, Team, Enterprise) pay a flat monthly fee and run against a weekly usage cap, not per-request billing. Once you exceed the cap, you're throttled until the next weekly window resets. API users pay per million tokens of input and output, billed continuously. ### Can I switch from API billing to Pro mid-month? Yes. Sign up for Pro, log into Claude Code with claude /login, and unset ANTHROPIC_API_KEY from your shell. Claude Code will route through your subscription instead of your API key. The reverse also works. Start the month on Pro, hit the cap, export the API key for the rest of the month, and Claude Code switches over instantly. ### Is Claude Code free for students? Not as a dedicated student plan. Anthropic has run Claude for Education promotions on the chat product, but Claude Code itself doesn't have a student discount published. The cheapest student route is the same as anyone else: Pro at $17 a month annual, or the API path with a tight Console budget cap. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Claude Code pricing explained](/blog/claude-code-pricing) - [Claude Code rate limits](/blog/claude-code-rate-limits) - [How to install Claude Code](/blog/how-to-install-claude-code) ## Sources and official documentation Primary sources referenced in this guide: - [Anthropic pricing page](https://www.anthropic.com/pricing) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) ## Ready to actually use Claude Code instead of just reading about it? Pricing is the easy part. The hard part is figuring out what to build with it. The free [Claude Code Blueprint](/blueprint) is a 60-minute walkthrough that takes you from install to your first shipped automation, no coding required. If you want a structured 30 days with weekly live calls, the [Claude Code Challenge](/challenge) runs in cohorts. And if you're curious what real students have built with this, [Kevin's case study](/case-studies/kevin) is the one I send to anyone asking whether $20 a month is worth it. ## Frequently Asked Questions ### Is Claude Code free to use? No. Claude Code requires a paid plan. Anthropic's setup documentation says it plainly: Claude Code requires a Pro, Max, Team, Enterprise, or Console account, and the free Claude.ai plan does not include access. The cheapest legitimate route is Pro at $20 a month ($17 annual). The other path is a pay-as-you-go API key billed per token through the Console. ### What plan do I need to use Claude Code? One of five accounts. Pro at $20 a month is the entry point with Claude Code on Sonnet. Max 5x at $100 bumps the cap roughly 5x and unlocks Opus. Max 20x at $200 is 20x the Pro cap and unlocks the highest effort tier. Team is seat-based for orgs. Or use an Anthropic Console account with an API key for pay-per-token billing. ### Does Claude Code use my API credits? Only if you tell it to. By default Claude Code authenticates against your Pro or Max subscription, so usage counts against your plan's weekly cap. If you set ANTHROPIC_API_KEY in your environment, Claude Code switches to API billing and every prompt and tool call eats your token credit. This is the trap most teams fall into. Do not export the key in your shell profile if you are on a subscription. ### What is the cheapest way to actually use Claude Code? For most people, Pro at $17 a month on annual billing. That is the floor. For heavy users running long agent loops on Opus, Max 5x at $100 a month is cheaper than the same workload on the API (one hour of Opus agent time can cost $5 to $15 in tokens). For occasional bursty use once a week, the API key with a $20 budget cap in the Console is cheapest. ### Is there a Claude Code free trial? Not as a published feature. Anthropic occasionally seeds new Console accounts with a small API trial credit you can spend on Claude Code through an API key, but it is not advertised, does not refresh, and is small. The closest thing to a trial is Pro's monthly billing. Cancel inside 30 days and you have spent $20 to take Claude Code for a real test drive. ### Did Anthropic remove Claude Code from the Pro plan in 2026? Briefly. Between April 21 and April 22, 2026, Anthropic ran a test that pulled Claude Code from Pro for roughly 2% of new users. Existing subscribers were not affected. Anthropic reverted the test within hours after backlash on the forums. The Pro plan now includes Claude Code again. The official pricing page is the source of truth on any given day. ### Is Claude Code free for students or open source maintainers? No dedicated discount. Anthropic has run Claude for Education promotions on the chat product, but Claude Code itself does not have a published student rate. Open source maintainers, hackathon entrants, and indie hackers all pay the same $20 a month. The cheapest student route is Pro on annual billing at $17 a month, same as anyone else. --- # Claude Code Skills Explained: SKILL.md, Triggers, Sharing Source: https://theaiarchitects.com/blog/claude-code-skills Published: 2026-05-08 Claude Code skills explained: how SKILL.md works, how to trigger them, share them, plus 3 of my real production skills with verbatim frontmatter. A Claude Code skill is a folder inside your project at .claude/skills// containing a SKILL.md file. The frontmatter has a name and a description. The body teaches Claude how to do a specific job. Claude loads the skill automatically when the description matches what you ask it to do. That is the whole concept. Quick disambiguation. Claude skills (the marketplace ones at claude.com/skills) and Claude Code skills are the same primitive on different surfaces. Anthropic launched Agent Skills in October 2025 as a single portable file format. Claude.ai uses them. Claude Code uses them. The API supports them. Same SKILL.md, same frontmatter, same activation rules. I'm Tom. I run AI Architects. I've shipped 17 production skills in my own .claude/skills/ folder. Three of them run dozens of times a week. Below: how skills actually work, the SKILL.md anatomy, the dynamic context injection trick almost nobody talks about, and three of my production skills with frontmatter copied verbatim. > [CTA-BLUEPRINT] ## What are Claude Code skills? Claude Code skills are reusable instruction folders Claude loads automatically when their description matches your request. Each skill is a folder at .claude/skills// with a SKILL.md file inside. The frontmatter has a name and a description. The body is plain markdown explaining how to do the job: what input to expect, what output to return, where to save files. The killer feature is the description field. It's not a label. It's a trigger. When you send Claude a prompt, the model scans every installed skill's description and decides whether to load it. If the description says "use whenever the user asks for a brief", and you say "give me a brief on Stripe", the skill fires. You don't invoke anything by hand. Anthropic's official docs at [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) call this "progressive disclosure". The model only pulls a skill into its context window when the task warrants it. So you can have 50 skills installed and Claude never wastes tokens loading the wrong one. The [October 2025 launch post on anthropic.com/news](https://www.anthropic.com/news/skills) framed it as the standard way to give an AI specialised expertise without retraining the model. ## Are Claude skills the same as Claude Code skills? Yes. Anthropic ships skills as a single portable format that runs in Claude.ai, Claude Code, the API, and the agent SDK. The SKILL.md file is identical across surfaces. What changes is the runtime. Claude.ai uses the marketplace at claude.com/skills. Claude Code uses .claude/skills/ folders. The API points a skills parameter at a directory. Same primitive, different installer. Caveat: some Claude.ai marketplace skills bundle tools (Document Suite, finance) that depend on the Claude.ai sandbox. Those won't run inside Claude Code unmodified. For instruction-only skills, which is most of them, it's a clean copy-paste from one surface to the other. ## How do Claude Code skills work? Skills work in three steps. Claude scans every installed skill's frontmatter at session start. When you send a prompt, the model decides whether any skill description matches your intent. If a match fires, Claude loads the full SKILL.md body into context and follows the instructions inside it. ### Where do Claude Code skills live? Claude Code skills live in three places, in this lookup order. Project skills sit at .claude/skills//SKILL.md inside the repo you're working in. User skills sit at ~/.claude/skills//SKILL.md and are available across every project on your machine. Plugin skills come bundled inside an installed Claude Code plugin. Project beats user beats plugin if names collide. ### What is a SKILL.md file? A SKILL.md file is a markdown document with a YAML frontmatter block at the top. The frontmatter holds the skill's metadata: name, description (the trigger sentence Claude reads), and optional fields like allowed-tools, model, and version. Below the frontmatter, you write the instructions in plain markdown. That's the body Claude follows when the skill fires. ## Three of my production skills (with verbatim SKILL.md frontmatter) Examples are worth more than theory. Below are three skills I run weekly. Each is in my .claude/skills/ folder. I've pasted the frontmatter verbatim so you can see the exact patterns that get skills to fire reliably. ### 1. humanizer Removes signs of AI-generated writing from text. Every blog post, email, and organic post I write runs through it before I read it. Catches em dashes, the rule of three, vague attributions, promotional language, and the other tells the Wikipedia "signs of AI writing" article catalogues. Frontmatter: --- name: humanizer version: 2.1.1 description: Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's comprehensive "Signs of AI writing" guide. Detects and fixes patterns including: inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases. allowed-tools: Read, Write, Edit, Grep --- Notice the description names trigger phrases ("editing or reviewing text") and lists the patterns it catches. That specificity is why Claude fires this skill when I say "clean this up" or "run the humanizer pass". A vague description like "helps with writing" would never trigger. ### 2. voice-analysis Reads a batch of my past posts and extracts the voice patterns: tone, common phrases, sentence structure, engagement hooks. The output is a structured voice profile I feed into other skills (content-create, sponsored-post, instagram-hook-writer). Ground truth for anything that needs to sound like me. Frontmatter: --- name: voice-analysis description: Voice Analysis Skill. Analyze provided posts and extract tone patterns, common phrases, sentence structure, and engagement hooks. Output as a structured voice profile document. Use when the user says "analyse my voice", "extract my brand voice", "build a voice profile", or pastes in a batch of past posts and asks what their voice sounds like. --- Canonical pattern for analysis skills. Trigger phrases in the description, specific output format (a profile document), specific input shape (a batch of posts). When all three are tight, the skill fires the moment I paste content. ### 3. presentation Builds a publication-quality slide deck from a topic, outline, or source notes. Uses my canonical design (ink/bone/orange, Fraunces + Geist, scroll-snap), runs a mandatory voice check, exports a PDF, saves to a destination folder I confirm at the start. Five hours of design work in five minutes. Frontmatter: --- name: presentation description: Build a slide deck in the canonical ink/bone/orange editorial design with mandatory voice enforcement and PDF export. Use when the user says "create a presentation", "build a deck", "make slides for", "turn this into a slide deck", "build a training deck", or provides an outline and asks for a presentation. Produces presentation.html + presentation.pdf + notes.md in an always-asked destination folder. --- Most-used pattern in my system. The description lists six exact phrases that trigger it. The output is concrete (three named files). The skill body holds the design system, the voice gates, and the PDF export logic. When I say "build me a deck on Y", it fires every time. ## How do I trigger a Claude Code skill? You don't trigger a Claude Code skill manually. You write a prompt that matches the skill's description, and Claude loads it automatically. The trigger lives entirely in the description field of the frontmatter. If the description says "Use when the user asks for a brief", and your prompt contains "give me a brief on X", the skill fires. If a skill isn't firing when you expect, the description is too vague. "Helps with email writing" is vague. "Use when the user says 'write me an email', 'draft an email', or pastes a thread asking for a reply" is specific. The model is matching strings, so give it strings to match. You can also force-load with /skill in modern Claude Code, but if you're typing that every time, the description needs work. ## How do I create a Claude Code skill? Three steps. Make a folder at .claude/skills//. Inside it, create a SKILL.md file. Write the frontmatter at the top (name, description, allowed-tools) and the instructions below. Claude reads the new skill at the next session start. ### Step 1: Pick a name and a folder The folder name and the name field in frontmatter should match. Use lowercase with hyphens. Examples: humanizer, voice-analysis, instagram-hook-writer. The folder lives at .claude/skills// if it's project-scoped or ~/.claude/skills// if it's user-scoped. ### Step 2: Write the frontmatter Most people get this wrong. The frontmatter is YAML, three dashes on the line above and below. The two required fields are name (a slug) and description (the trigger sentence). Optional fields: allowed-tools, model, version. A solid frontmatter for a fresh skill: --- name: company-brief description: Generate a structured research brief on a company. Use whenever the user asks for a brief, runs the /brief slash command, or pastes a company name or URL with intent to research. Output four sections: Summary, Recent News, Key People, Suggested Angles. allowed-tools: Read, Write, WebFetch --- ### Step 3: Write the body The body is the SKILL.md content below the frontmatter. Plain markdown. Tell Claude what to do, in what order, what each output looks like, what to skip, what to confirm with the user, where to save the result. My rule of thumb: if I had to write a Loom for a junior team member explaining the job, that's the SKILL.md. Skills are you turning your own brain into an SOP Claude can read. ## The dynamic context injection trick (almost nobody knows this) Inside a SKILL.md body, you can prefix a line with an exclamation mark and a backtick to run a shell command at the moment the skill loads. The output of the command gets injected into Claude's context as if it were written there at design time. The syntax is: backtick, exclamation mark, your shell command, backtick. So !`date` gives Claude today's date the moment the skill fires. !`git status --short` gives Claude the current git diff. !`ls .claude/skills/` gives Claude a live list of every other skill installed in the project. The trick I teach my mentorship students: when a skill needs context that changes between sessions (current date, active branch, latest CLAUDE.md, contents of a config file), don't hardcode it and don't make Claude run a tool call. Use the ! prefix. The shell runs at load time. The output lands in context. Claude reads it like normal markdown. Zero round-trips. My presentation skill uses this to inject today's date into the cover slide. My voice-analysis skill uses it to read the latest VOICE.md at load time. The shell does the work before Claude even sees the prompt. ## What's the difference between skills and commands? Skills load automatically when their description matches your prompt. Slash commands fire only when you type /. Skills are passive triggers, commands are active. Skills live in .claude/skills//SKILL.md, commands live in .claude/commands/.md. In practice you use both. A slash command is a one-shot prompt you type a hundred times a week. A skill is a reusable instruction set Claude loads when the topic comes up. They compose: a slash command can reference a skill, the command sets the verb, the skill provides the playbook. Anthropic recently merged custom commands and skills into a unified system. The Claude Code changelog at [github.com/anthropics/claude-code](https://github.com/anthropics/claude-code) documents the migration. Legacy .claude/commands/ files still work, but new ones are usually better written as skills with a /command-name in the description. ## How do I share a Claude Code skill? Commit the .claude/skills// folder to git. Anyone who clones the repo gets the skill automatically. That's the entire distribution model for project skills. No registry, no install command. Git is the package manager. For user-scoped or cross-project skills, push the folder to a GitHub repo and tell people to copy it into ~/.claude/skills/, bundle the skill inside a Claude Code plugin (the modern path), or submit it to claude.com/skills for the public marketplace. Anthropic maintains a reference repo of example skills at [github.com/anthropics/skills](https://github.com/anthropics/skills). Worth a clone before you ship your first skill of your own. ## How do I install a skill from a plugin? You install a skill from a Claude Code plugin by installing the plugin itself. Plugin skills come bundled. Once the plugin is installed, its skills appear under a plugin namespace (something like plugin-name:skill-name) and Claude treats them like any other installed skill. Run /plugin install or add the plugin to your settings.json under the plugins array, then restart your session. The advantage of plugin-distributed skills is versioning. When the plugin author ships a new version, you get the new skill body automatically. With raw .claude/skills/ folders committed to git, every project has a frozen snapshot of the skill that drifts over time. Plugins solve that. > [CTA-BLUEPRINT] ## Where Claude Code skills fall short Skills aren't free. Three things to watch. First, the description-as-trigger model means a poorly written description either fires too often or never fires. It takes a few iterations to dial in. Second, skills compete for the model's attention. With 30 skills installed and overlapping descriptions, the model sometimes loads the wrong one. The fix is hygiene: one job per skill, narrow descriptions, no duplication, delete skills you stopped using. Third, skills can't share state. Each one loads fresh. If skill A produces output skill B needs, you have to write it to a file or pass it through the prompt. For multi-step workflows where skills need to talk, use a subagent or a slash command that orchestrates the steps explicitly. ## Best Claude Code skills worth stealing Beyond the three above, a few patterns I've seen working well in the cohort and the wider community. Code review: reads the current git diff and produces a structured PR review (correctness, security, style). Anthropic ships a built-in version called /review that's a fine starting point. n8n validator: takes an exported n8n workflow JSON, validates node configurations, expression syntax, and credentials, returns a list of issues. Sponsored post: turns a product brief and a video transcript into a finished sponsored Instagram or LinkedIn post in my voice. Brief generator: the company-brief skill from my Blueprint walkthrough that spawns three subagents in parallel to research a company, then writes to Airtable. ## Verdict: are Claude Code skills worth using? Yes, if you've ever pasted the same instructions into Claude more than three times. Skills are the cheapest reusable infrastructure in Claude Code. Five minutes to write the first one. Pays back the next time you'd have copied your own SOP. Not worth it for one-off questions, but for any repeating workflow (writing, research, code review, deployment, content production), skills save more time than every other Claude Code feature combined. The mental model that locks it in: skills turn your brain into an SOP a model can read on demand. Every skill is a piece of you that you no longer have to be in the room to deliver. Ten of them in, your Claude Code feels like a small team you trained. ## Claude Code skills FAQ ### What are Claude Code skills? Reusable instruction folders Claude loads automatically when their description matches your request. Each is a folder at .claude/skills// with a SKILL.md file containing frontmatter (name, description) and a markdown body. ### How do I create a Claude Code skill? Make a folder at .claude/skills//, add a SKILL.md, write YAML frontmatter (name, description) at the top, write instructions below in plain markdown. Restart the session. The description is the trigger, so name the exact phrases you'll use. ### Where do Claude Code skills live? Project skills at .claude/skills//SKILL.md. User skills at ~/.claude/skills//SKILL.md, available across every project. Plugin skills come bundled with installed plugins. Project beats user beats plugin on name collision. ### What is a SKILL.md file? A markdown document with a YAML frontmatter block on top. The frontmatter sets the skill's name and description (the trigger). The body is the instruction set Claude follows when the skill fires. Canonical format Anthropic shipped in October 2025 as part of Agent Skills. ### How do I trigger a Claude Code skill? You don't trigger one manually. Write a prompt that matches the skill's description, Claude loads it automatically. If a skill isn't firing, the description is too vague. Force-load with /skill in modern versions, but if you're typing that every time, rewrite the description. ### What's the difference between skills and commands? Skills fire automatically when their description matches your prompt. Slash commands fire only when you type /. Skills are passive, commands are active. Skills live in .claude/skills/, commands in .claude/commands/. Modern Claude Code merges them into a unified registry. ### How do I share a Claude Code skill? Commit the .claude/skills// folder to git for project skills. Push to GitHub and copy into ~/.claude/skills/ for user skills. Bundle inside a plugin for versioned distribution. Or submit to claude.com/skills for the public marketplace. ### Are Claude skills the same as Claude Code skills? Yes. The SKILL.md format runs across Claude.ai, Claude Code, the API, and the agent SDK. Only the runtime changes. Some Claude.ai marketplace skills bundle tools that depend on the Claude.ai sandbox and won't run in Claude Code unmodified. ### How do I install a skill from a plugin? Install the plugin with /plugin install or add it to settings.json under plugins. Restart. The plugin's skills appear under a namespace and fire automatically when descriptions match. Run /plugin list to confirm it loaded. ### Where can I find good Claude Code skills examples? Anthropic's official examples live at [github.com/anthropics/skills](https://github.com/anthropics/skills). The Claude Code docs at [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) include reference SKILL.md files. The wider community curates lists at agentskills.io and at awesome-claude-skills repos on GitHub. My own .claude/skills/ folder ships 17 production skills you can lift directly. ## Ready to build your first Claude Code skill? If you've followed this far, you have what you need. The fastest way to internalise it is to build the company-brief skill from my [Blueprint](/blueprint) walkthrough end to end. 60 minutes, free, and the skill you write is genuinely useful. For multiple skills chained together (humanizer, voice-analysis, content-create), the [30-Day Challenge](/challenge) is where I take people next. For the surrounding mental model, my [Claude Code beginner guide](/blog/how-to-use-claude-code) covers the rest. ## Frequently Asked Questions ### What is a Claude Code skill? A Claude Code skill is a folder inside your project at .claude/skills// containing a SKILL.md file. The frontmatter has a name and a description. The body teaches Claude how to do a specific job. Claude loads the skill automatically when the description matches what you ask it to do. That is the entire concept. ### How do I trigger a Claude Code skill? You do not trigger a skill manually. You write a prompt that matches the skill's description and Claude loads it automatically. The trigger lives entirely in the description field of the frontmatter. If a skill is not firing, the description is too vague. 'Helps with email writing' is vague. 'Use when the user says write me an email or drafts a reply' is specific. The model is matching strings, so give it strings to match. ### What is the difference between skills and slash commands? Skills load automatically when their description matches your prompt. Slash commands fire only when you type /. Skills are passive triggers, commands are active. Skills live in .claude/skills//SKILL.md, commands live in .claude/commands/.md. In practice you use both. A slash command sets the verb. A skill provides the playbook. ### Are Claude.ai skills the same as Claude Code skills? Yes. Anthropic ships skills as a single portable format that runs in Claude.ai, Claude Code, the API, and the agent SDK. The SKILL.md file is identical across surfaces. Only the runtime changes. The one caveat: some Claude.ai marketplace skills bundle tools (Document Suite, finance) that depend on the Claude.ai sandbox and will not run inside Claude Code unmodified. ### How do I share a Claude Code skill with my team? Commit the .claude/skills// folder to git. Anyone who clones the repo gets the skill automatically. That is the entire distribution model for project skills. No registry, no install command. Git is the package manager. For user-scoped skills, push to GitHub and have people copy into ~/.claude/skills/, or bundle inside a Claude Code plugin for versioned distribution. ### What is the dynamic context injection trick in SKILL.md? Inside a SKILL.md body, you can prefix a line with a backtick and exclamation mark to run a shell command at load time. The output gets injected into Claude's context as if it were written there. So !`date` gives Claude today's date the moment the skill fires. !`git status --short` gives Claude the current diff. Zero round-trips. The shell does the work before Claude even sees the prompt. ### Are Claude Code skills worth using? Yes, if you have ever pasted the same instructions into Claude more than three times. Skills are the cheapest reusable infrastructure in Claude Code. Five minutes to write the first one. Pays back the next time you would have copied your own SOP. Not worth it for one-off questions. For any repeating workflow (writing, research, code review, deployment), skills save more time than every other Claude Code feature combined. ## Related guides - [24 Claude Code Skills, Subagents and Hooks Worth Stealing in 2026](/blog/best-claude-code-skills) - [Claude Code Subagents vs Skills: When to Use Each](/blog/claude-code-subagents-vs-skills) --- # Claude Code Memory: CLAUDE.md, Auto Memory, and Path Rules Source: https://theaiarchitects.com/blog/claude-code-memory Published: 2026-05-08 How Claude Code remembers things between sessions. The four CLAUDE.md scopes, Auto Memory (v2.1.59+), and path-specific rules. Claude Code remembers things between sessions by reading plain markdown files called CLAUDE.md every time it starts a new conversation. There is no hidden database, no embedding layer, no vector store. It is text on disk, loaded into the system prompt, scoped by four predictable rules. I'm Tom. I run 37 CLAUDE.md files across 14 active projects, and I have been shipping with Claude Code since the public preview. Most of the teams I mentor are getting one of the four scopes wrong, and it is the single biggest reason their agent feels forgetful. > [CTA-BLUEPRINT] ## What is Claude Code memory? Claude Code memory is the persistent context that survives between sessions. When you close your terminal and reopen it the next morning, Claude does not remember your previous chat. It remembers the markdown files that describe your project, your style, your stack, your rules. That distinction matters. Memory in Claude Code is not conversational state. It is project knowledge you author once and reuse forever. People searching for the Claude Code memory tool, the Claude Code memory plugin, or the Claude Code memory command are usually looking for the same underlying thing: how to make Claude remember stuff. The answer in every case is CLAUDE.md plus the four scopes below. There is no separate plugin to install, no special mode to enable. Memory ships in the box. ## How does Claude Code remember things between sessions? The mechanism is boring on purpose. At the start of every session, Claude Code walks up from your current directory looking for files named CLAUDE.md. It also reads a user-level file at `~/.claude/CLAUDE.md`, and a managed policy file if your org admin pushed one. The contents get stitched into the system prompt before your first message lands. That means every rule you write in CLAUDE.md is enforced on every prompt, in every session, without you ever quoting it again. Write it once. It applies forever. The flip side is that Claude has zero recall of what you actually said yesterday. If you want a decision to persist, it goes into CLAUDE.md. If you want a fact to persist, it goes into a doc Claude can read. The session log is throwaway. The markdown is forever. ## The four CLAUDE.md scopes Most teams I audit are only using one scope. Anthropic ships four, and they layer in a predictable order from most general to most specific. ### Managed policy Managed policy lives at `/Library/Application Support/ClaudeCode/managed-settings.json` on macOS, or the equivalent path on Windows and Linux. This is the org-level scope, and only an IT admin can push to it. Use it when you need to lock in security rules across an entire company, like "never run destructive shell commands" or "always require approval before pushing to main". ### Project Project scope is the file at the root of your repo, just called `CLAUDE.md`, checked into git. Every developer who clones the repo gets the same context. This is where the project's mission, the stack, the conventions, and the non-negotiable style rules live. If your team is bigger than one person, this file is the most valuable artifact in your repo. ### User User scope lives at `~/.claude/CLAUDE.md` and follows you across every project on your machine. Mine has my preferred languages, my refusal to use semicolons in copy, the fact I am UK-based, and the way I want commit messages written. None of that belongs in a team repo. All of it belongs in my user file. ### Local Local scope is `.claude/CLAUDE.md.local`, sat inside the repo but gitignored. This is the per-developer override. Use it for personal preferences that only apply to your work on this specific project. A common pattern is pointing Claude at your own scratch folder, or overriding the project default model from Sonnet 4.6 to Opus 4.7 for harder sessions. The layering matters. Managed loads first, then project, then user, then local. A rule in your local file wins over a rule in the project file, which wins over your user file. Most teams I review have the priority backwards, which is why their style rules keep getting ignored. There is also a Claude Code memory shortcut worth knowing. Typing `#` at the start of a prompt opens the memory editor inline, so you can append a rule mid-session without leaving the terminal. It is the fastest way to capture a decision the moment you make it. Most of my own CLAUDE.md entries started life as a hashtag prompt at 11pm during a hard debug. ## Auto Memory: what changed in v2.1.59 Auto Memory shipped in [Claude Code v2.1.59 in October 2025](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md), and it changed the workflow in a quiet but important way. Before v2.1.59, every line in CLAUDE.md had to be authored by hand. You noticed a pattern, you opened the file, you wrote the rule. After v2.1.59, Claude proposes additions for you. When it notices a recurring instruction in your session ("always run prettier before committing", "this project uses pnpm not npm"), it suggests appending it to your CLAUDE.md, scoped to whichever level makes sense. You approve, reject, or edit the proposal inline. The reason this matters is friction. The hardest part of memory is remembering to write things down. Auto Memory turns that into a one-keystroke confirmation, so the file actually grows with your project instead of going stale by week three. I leave it on for every project. Read the official [Anthropic memory documentation](https://code.claude.com/docs/en/memory) if you want the full surface area. One nuance from the field. Auto Memory is good at capturing rules, less good at deciding scope. By default it tends to propose project-level additions, which means your team repo can quietly fill up with your personal preferences. I now scan the proposals for anything that should really live in `~/.claude/CLAUDE.md` instead, and reroute on approval. Thirty seconds of triage saves a quarterly cleanup. ## Path-specific rules with .claude/rules This is the feature most teams I mentor have never opened. Inside any repo, you can drop markdown files into `.claude/rules/`, and each one accepts a `paths:` field in its frontmatter that scopes the rule to certain files or folders. Claude only loads the rule when the active file matches the glob. In a monorepo this is the difference between a 400-line CLAUDE.md that contradicts itself and four 80-line rule files that load on demand. Concrete example. I have a project with a Next.js frontend in `apps/web` and a Python backend in `services/api`. The frontend rule file has `paths: ["apps/web/**"]` and says "use TanStack Query, never fetch directly in components". The backend rule file has `paths: ["services/api/**"]` and says "all endpoints must have pytest coverage before merging". Claude loads the right one based on where I am working, and ignores the other. The other place path rules earn their keep is migrations. When I am moving a project from one library to another, I drop a rule file scoped to the legacy folder that says "do not extend this code, propose a port to the new module instead". The agent stops accidentally entrenching code I want gone. It is the cheapest refactor guard rail I have ever shipped, and it took 30 lines of markdown to set up. ## How to write a good CLAUDE.md (5 patterns I steal from) After 14 projects, the same five patterns keep showing up in the CLAUDE.md files that actually work. ### 1. Lead with project context, not commands Open the file by telling Claude what the project is, who it is for, and what success looks like. A two-paragraph mission statement at the top changes every downstream decision Claude makes. Commands and conventions come after. ### 2. Use sections, not paragraphs (Claude scans) Claude reads CLAUDE.md the same way you read a README: it scans headings and lists first. Use H2s and H3s. Use bullet points. A wall of prose buries your most important rules and Claude will under-weight them. ### 3. Bake in your style rules ("always do X / never do Y") Hard rules belong in unambiguous "always" and "never" lists. Mine has "never use em dashes", "always write commit messages in imperative mood", "never start a function without a docstring". Claude treats these like first-class constraints. ### 4. Reference, don't duplicate (point to /docs/X.md) If your project has a 600-line API spec, do not paste it into CLAUDE.md. Write one line that says "for endpoint shapes, read `/docs/api.md`" and Claude will load it on demand. Referencing keeps CLAUDE.md short and your docs single-sourced. ### 5. Keep it under 200 lines or it gets compressed Past roughly 200 lines, CLAUDE.md starts losing fidelity in the system prompt. Long files get summarised. Important rules get dropped. If yours is bigger, split it: project rules in CLAUDE.md, path rules in `.claude/rules/`, reference docs in `/docs/`. If you are still wiring up the basics, my [60-minute beginner guide](/blog/how-to-use-claude-code) walks through the directory layout end to end. > [CTA-BLUEPRINT] ## Claude Code memory FAQ ### What is CLAUDE.md? CLAUDE.md is a plain markdown file Claude Code reads at the start of every session. It is how you tell the agent what your project is, how it should write code, and what rules it must follow. There is one per scope, four scopes total, and they layer from managed policy down to local overrides. ### Where does Claude Code store memory? Claude Code stores memory in markdown files on your disk, not in a database. Project memory sits in `CLAUDE.md` at the repo root. User memory sits in `~/.claude/CLAUDE.md`. Local memory sits in `.claude/CLAUDE.md.local` inside the repo. Path-scoped rules sit in `.claude/rules/`. Everything is human-readable, version-controllable, and editable in any text editor. ### Does Claude Code memory persist between sessions? Yes, fully. Anything you put in a CLAUDE.md file is reloaded every single time you start a new Claude Code session. Conversational state from your previous chat is not preserved, but any rule, fact, or instruction you saved to CLAUDE.md will apply automatically the next morning, next week, and next year. ### What's the difference between memory and skills? Memory is passive context that gets loaded into every prompt. [Claude Code skills](/blog/claude-code-skills) are active capabilities Claude can invoke on demand to perform a specific task. Think of memory as "what Claude knows about your project" and skills as "what Claude can do on your behalf". You can also build [slash commands](/blog/claude-code-commands) for repeated workflows that need a single keystroke trigger. ### Why is Claude Code using so much memory? This question usually means one of two things, and they are completely different problems. If you mean the CLAUDE.md memory feature, the answer is your files are probably fine and the system prompt is doing its job. If you mean RAM consumption, that is a different beast, sometimes called a Claude Code memory leak, and it has been reported in older versions running long sessions with many open tools. The fix is usually upgrading to the latest release and restarting the CLI. The two issues share a word and nothing else. ## Ready to build your CLAUDE.md? The four scopes are not advanced. They are the price of entry. Once your managed, project, user, and local files are layered correctly, Auto Memory keeps them fresh, and path rules keep them sharp. That is the entire memory model. Most teams treat CLAUDE.md as a README they wrote once and forgot about. The teams that ship faster treat it like a living contract between themselves and the agent. Every time Claude does something off, they ask one question: was the rule in the file. If not, they add it. If yes, they sharpen it. That feedback loop is how a forgetful agent becomes a reliable one. If you want my exact CLAUDE.md templates, the path-rule starter kit, and the 14-project audit checklist I run before any client engagement, that is what the [Blueprint](/blueprint) is for. Build the foundation once. Reuse it forever. ## Frequently Asked Questions ### What is CLAUDE.md? CLAUDE.md is a plain markdown file Claude Code reads at the start of every session. It is how you tell the agent what your project is, how it should write code, and what rules it must follow. There is no hidden database, no embedding layer, no vector store. Text on disk, loaded into the system prompt, with four predictable scopes. ### What are the four CLAUDE.md scopes? Managed policy (org-level, pushed by IT admins), project (CLAUDE.md at your repo root, checked into git), user (~/.claude/CLAUDE.md, follows you across every project), and local (.claude/CLAUDE.md.local, gitignored, per-developer overrides). They layer in that order from most general to most specific. A rule in your local file beats a rule in the project file. ### Does Claude Code memory persist between sessions? Yes, fully. Anything in a CLAUDE.md file gets reloaded every time you start a new session. The conversation log itself is throwaway, but any rule, fact, or instruction saved to CLAUDE.md applies automatically the next morning, next week, and next year. Write it once, it applies forever. ### What is Auto Memory and what changed in v2.1.59? Auto Memory shipped in October 2025 and lets Claude propose additions to your CLAUDE.md when it notices a recurring instruction. Before, every line had to be authored by hand. Now you get a one-keystroke confirmation when Claude spots a pattern like "always run prettier before committing". One field nuance: it tends to propose project-level additions, so scan the proposals and reroute personal preferences to ~/.claude/CLAUDE.md. ### What are path-specific rules in .claude/rules/? Path rules are markdown files inside .claude/rules/ that scope to certain files or folders via a paths: frontmatter field. Claude only loads the rule when the active file matches the glob. In a monorepo, this is the difference between a 400-line CLAUDE.md that contradicts itself and four 80-line rule files that load on demand. Cheapest refactor guard rail I have ever shipped. ### How long should my CLAUDE.md be? Under 200 lines. Past that, CLAUDE.md starts losing fidelity in the system prompt. Long files get summarised, important rules get dropped. If yours is bigger, split it: project rules in CLAUDE.md, path-specific rules in .claude/rules/, reference docs in /docs/ linked by name. ### What's the difference between memory and skills? Memory is passive context loaded into every prompt. Skills are active capabilities Claude can invoke on demand to perform a task. Memory is what Claude knows about your project. Skills are what Claude can do on your behalf. Slash commands sit alongside both, for repeated workflows that need a single keystroke trigger. ## Related guides - [Karpathy's CLAUDE.md: 4 Rules That Fix Claude Code](/blog/karpathy-claude-md-rules) --- # Claude Code Pricing 2026: Pro, Max, Team and API Source: https://theaiarchitects.com/blog/claude-code-pricing Published: 2026-05-07 Claude Code pricing for Pro, Max, Team and API. Compare the current plan costs, usage limits and the right tier for daily work. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. I'm Tom. I run Claude Code on Max 5x most days and have stress-tested API billing for bursty agent work. I've also lived through the April 2026 pricing scare, when Anthropic briefly removed Claude Code from Pro for a slice of users before reversing the decision. This post is the version of pricing I wish someone had handed me before I made the wrong choice twice. Specific numbers, real receipts, and a calculator to help you pick a plan instead of guessing. ## How much does Claude Code cost? Claude Code costs $0 to install and from $20 a month to use seriously. Pro costs $20 monthly or $200 annually. Max 5x costs $100 monthly and Max 20x costs $200 monthly. Team starts at $25 per Standard seat monthly, or $20 with annual billing, and requires at least five seats. There is no separate Claude Code licence. You pay for a Claude plan or use API billing. Here is the at-a-glance table I keep in my notes. Free: $0. Limited Claude chat and coding assistance, but no included Claude Code plan access. Pro is the realistic starting point for the CLI. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. Max 20x: $200 a month. It includes roughly twenty times Pro's usage per session and is built for long daily sessions, parallel agents, and heavier Claude Code workloads. Team Standard: $25 per seat monthly or $20 per seat with annual billing. Team Premium: $125 monthly or $100 annually. Team requires five to 150 seats, and organizations can mix Standard and Premium seats. Enterprise: $20 per seat plus model usage billed at API rates on the current self-serve plan. Sales-assisted contracts can add custom procurement, security, and support terms. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ## What happened to the Fable 5 promotion? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access.The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access.The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ## What's the difference between Claude Pro and Max? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ## How much is Claude Max? Claude Max comes in two flavours. Max 5x is $100 a month and gives you roughly five times Pro's usage per session. Max 20x is $200 a month and gives you roughly twenty times Pro's usage per session. Both add higher output limits, priority access during busy periods, and early access to advanced Claude features. The $100 jump from Pro to Max 5x is the useful upgrade for daily Claude Code work. Max 20x is for people running agent teams or multi-hour parallel sessions. ## Pricing calculator: which plan fits your use? Use this decision matrix to pick a plan in under a minute. The useful questions are how often you run Claude Code, how quickly you hit the included limits, and how expensive an interrupted build feels to you. Curious tinkerer, under five hours a week, mostly content and one-off scripts: Free or Pro. Pro is the right answer if you want to actually finish anything. Solo builder, five to fifteen hours a week, building real projects: Pro if you can stay inside the regular allowance, Max 5x if you keep hitting it. I recommend Max 5x to almost everyone in this bracket because losing momentum mid-build usually costs more than the $80 difference. Daily operator, fifteen to thirty hours a week, agent teams and parallel sessions: Max 5x for most weeks, Max 20x if you regularly hit the higher limit. This is where I sit. Max 5x covers most weeks, and I lower effort before paying for capacity I will not use every month. Hardcore agent team, thirty plus hours a week, running Claude Code on the web and in the terminal in parallel, building products: Max 20x. Below that, you will hit the cap on Tuesday afternoon and spend the rest of the week regretting it. Team of five to 150 people sharing one bill: Team Standard at $25 per seat monthly or $20 annually. Premium costs $125 monthly or $100 annually and gives power users more capacity. You can mix seat types while keeping one invoice, SSO, and central administration. Bursty workloads with quiet weeks: API. If you run hot for three days then go quiet for ten, pay-as-you-go on the API often beats any subscription. Build a small budget alarm into your dashboard and you will not get caught out. > [CTA-BLUEPRINT] ## Is Claude Max worth it for Claude Code? Yes for daily Claude Code users, no for casual ones. Max 5x at $100 a month is worth it when Pro interrupts normal work. Max 20x at $200 is worth it when you run parallel agents, long sessions, or product work that regularly exhausts Max 5x. If you are still testing Claude Code, start on Pro and upgrade when the usage screen gives you a reason. Here is the test I use. Open /usage in Claude Code on a normal week. If you are above 60% of your weekly cap by Wednesday, Max 5x will pay for itself in saved time. If you are above 80% of Max 5x's cap by Wednesday, Max 20x will pay for itself in saved time. The math is rarely about the dollars. It is about the cost of stopping mid-build because the agent ran out of room. ## Does Claude Code count against my API credits? Only if you are billing Claude Code through the API. By default, Claude Code uses your subscription quota (Pro, Max, Team), not your API credit balance. If you log in with claude login on a Pro or Max account, every token comes out of your weekly subscription cap. If you set ANTHROPIC_API_KEY in your shell or run claude login --api, every token comes out of your API credit balance instead. This trips up almost everyone the first time. You buy $50 of API credit, never set the env var, and wonder why your balance never moves. The credit only burns when you tell Claude Code to use it. Run claude config get authMode to check which mode you are in. The two valid values are subscription and api. ## What is Claude Code's weekly usage limit? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. Claude also applies session limits that normally reset every five hours. If you reach an included limit, Claude does not silently bill your card. You can wait for the reset, switch models where available, upgrade your plan, or use separately billed usage credits if you have enabled them. ## What does xhigh effort cost on Claude Code? Effort does not cost extra dollars on a subscription. It costs tokens against your weekly cap. The /effort command lets you set the level for the current session: low, medium, high, xhigh, or max. Higher effort means more extended thinking on every turn, which means more tokens per response, which means you hit the cap faster. On API billing, higher effort directly increases your per-turn token spend. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ## How do I switch from API billing to Pro mid-month? Two steps. Buy a Pro or Max subscription on claude.com, then change your auth mode in the CLI. Open Claude Code, run /logout, then /login, and pick the subscription option when prompted. The CLI swaps from API to subscription billing immediately. Any unused API credits stay on your account and do not expire for twelve months. If you want to make the switch programmatic, set the env var explicitly. CLAUDE_AUTH_MODE=subscription in your shell will pin Claude Code to your subscription regardless of the API key in your environment. Drop that into your .zshrc or .bashrc and you will never burn credits by accident again. ## Pro vs Max for Claude Code: which should I pick? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. Most people regret going to Max too late, not too early. The reason is that Pro's cap is generous on paper but feels small the moment you start running agents in the background or kicking off plan mode on a real refactor. The first week you hit the cap mid-build and wait two days for it to reset, you will know it is time to upgrade. ## Is Claude Code cheaper than Cursor? At the same tier, they are basically identical. Pro is $20 against Cursor Pro at $20. Max 20x is $200 against Cursor Ultra at $200. Cursor has a $60 Pro+ tier with no Claude Code equivalent, and Claude has Max 5x at $100 with no Cursor equivalent. The decision is not price. It is what each tool actually does, which I cover in the deep comparison below. If you are deciding between the two, [my full Claude Code vs Cursor breakdown](/blog/claude-code-vs-cursor) walks through twelve real projects in both tools. The short version: Claude Code wins on agentic work, Cursor wins on inline autocomplete, and the smart move is to run them together for $40 a month total at the entry tier. ## The April 2026 Pro pricing scare In April 2026, Anthropic ran a quiet test that removed Claude Code from the Pro tier for about 2% of users. [The Register covered the change](https://www.theregister.com/2026/04/22/anthropic_removes_claude_code_pro/) within hours of users noticing. The pushback was loud, and Anthropic reversed it inside a week. If you saw the news and assumed Pro no longer covers Claude Code, that was true for a sliver of users for a few days, and is no longer true for anyone. The bigger lesson is that pricing here is still being calibrated. Anthropic ships Claude Code on subscription billing as a strategic bet, not a profit centre. They want serious builders inside the surface and will move tiers around to find the right line. Plan for one to two pricing changes a year and it will not catch you off guard. ## Verdict: which Claude Code plan should you actually buy? Pro at $20 if you are starting out and want to test Claude Code on real work for a month before committing. Max 5x at $100 if Claude Code is in your daily stack. Max 20x at $200 if it is your primary surface for shipping software. Team if you are three or more devs sharing one bill. Enterprise if you have an IT team negotiating contracts. API if your usage is bursty enough that a flat monthly subscription does not fit. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. > [CTA-BLUEPRINT] ## Claude Code pricing FAQ ### Is Claude Code free? The Claude Code CLI is free to install. Real usage requires a Claude account, and the free tier on Claude is too capped to do meaningful work. Pro at $20 a month is the realistic floor. The full breakdown of what "free" actually gets you lives in [my deep dive on whether Claude Code is free](/blog/is-claude-code-free). ### Is Claude Code free with Pro? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### Which models can I use on Claude Code Pro? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### Can students get a Claude Code discount? Anthropic does not currently offer a standing individual student discount for Pro or Max. Universities can buy the separate Claude for Education plan, and Anthropic occasionally runs limited promotions. Check the official pricing page rather than relying on old discount posts. ### What is the difference between Claude Pro and the API? Pro is a flat monthly subscription with a weekly usage cap. The API is pay-per-token with no cap. Pro is cheaper for steady daily use. The API is cheaper for bursty workloads. Both run the same Claude models. The difference is billing, not capability. ### How much does Opus 4.7 cost on the API? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### What is Cursor Ultra vs Claude Code Max? Cursor Ultra is $200 a month with roughly 20x Cursor Pro's usage. Claude Code Max 20x is $200 a month with roughly 20x Pro's usage. The headline price is identical. The difference is the tool around the model. Cursor Ultra is an AI-first IDE. Claude Code Max 20x is a multi-surface agent that runs in your terminal, IDE, desktop, browser, and phone. ### Is the Team plan worth it for a small dev team? For teams of five to 150 people, Team is the right starting point. Standard seats cost $25 monthly or $20 with annual billing. Premium seats cost $125 monthly or $100 annually and provide more usage. Organizations can mix the two seat types. ### Will Claude Code pricing change again in 2026? Almost certainly. Anthropic adjusted pricing twice in the last year, ran the Pro test in April, and is still calibrating where Claude Code sits in the lineup. Plan for one or two changes a year and check the pricing page when something feels off. The CLI itself does not change. The plan tiers around it do. ## Related guides If this guide was useful, these go deeper on adjacent topics: - [Is Claude Code free?](/blog/is-claude-code-free) - [Claude Code rate limits](/blog/claude-code-rate-limits) - [Claude Code vs Cursor](/blog/claude-code-vs-cursor) ## Sources and official documentation Primary sources referenced in this guide: - [Anthropic pricing page](https://www.anthropic.com/pricing) - [Claude Code documentation](https://docs.claude.com/en/docs/claude-code) The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. [Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing) ## Ready to pick a plan and start shipping? Pricing is the easy part. Picking a plan takes ten minutes. Actually using Claude Code well takes a weekend. The fastest way in is the [free Claude Code Blueprint](/blueprint). Sixty minutes, no coding required, and you walk out with a working setup, your first build, and a clean answer to which tier fits your workflow. If you want a longer reference for the tool itself, the [complete Claude Code guide](/blog/how-to-use-claude-code) covers every concept the pricing page assumes you already know. If you want the version where you actually ship something in a month, the [30-Day Claude Code Challenge](/challenge) is the cohort. Four live calls, a real build per week, and a deployed agent on a real schedule by the end. By the time you are done, you will know your real Claude Code bill, your real plan, and your real workflow. Not the hypothetical version on a comparison post. ## Frequently Asked Questions ### Has the Fable 5 promotion ended? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### How much does Claude Code cost? Claude Code costs $0 to install and from $20 a month to use seriously. Pro costs $20 monthly or $200 annually. Max 5x costs $100 monthly and Max 20x costs $200 monthly. Team starts at $25 per Standard seat monthly, or $20 with annual billing, and requires at least five seats. There is no separate Claude Code licence. You pay for a Claude plan or use API billing. ### Is Claude Code free with Pro? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### What is the difference between Claude Pro and Max for Claude Code? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### Which Claude Code plan should I actually buy? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. ### Does Claude Code count against my API credits? Only if you are billing Claude Code through the API. By default, Claude Code uses your subscription quota (Pro, Max, Team), not your API credit balance. If you log in with claude login on a Pro or Max account, every token comes out of your weekly cap. If you set ANTHROPIC_API_KEY in your shell or run claude login --api, tokens come out of your API balance. Run claude config get authMode to check which mode you are in. ### Is Claude Code cheaper than Cursor? At the same tier, basically identical. Pro is $20 against Cursor Pro at $20. Max 20x is $200 against Cursor Ultra at $200. Cursor has a $60 Pro+ tier with no Claude Code equivalent, and Claude has Max 5x at $100 with no Cursor equivalent. The decision is not price, it is what each tool does. Claude Code wins on agentic work. Cursor wins on inline autocomplete. The smart move is to run them together for $40 a month at the entry tier. ### What is the Claude Code weekly usage limit? The Fable 5 promotion described in older versions of this article has ended. Do not use its former eligibility, cap or pricing claims to choose a plan. Check Anthropic's current pricing and model documentation for present model access. --- # Claude Code MCP: Setup, Scopes & The 4 Servers I Use Source: https://theaiarchitects.com/blog/claude-code-mcp Published: 2026-05-05 Claude Code MCP setup guide: install Playwright, GitHub, Postgres, and custom servers. Scope tradeoffs, .mcp.json config, OAuth, and remove commands. Claude Code MCP is the connector layer that lets Claude Code read from and write to outside tools like Postgres, GitHub, Figma, Airtable, Stripe, and Playwright through a single open standard. It is the difference between Claude doing work inside your repo and Claude actually running your business systems. Quick disambiguation: MCP stands for Model Context Protocol. It is not a Claude Code feature, it is an open standard Anthropic published in November 2024 that any AI client can speak. Claude Code happens to support it natively, but the same MCP servers also work in Cursor, Claude Desktop, and a growing list of clients. I'm Tom. I run AI Architects and have ten MCP servers wired into my own setup right now. This post covers the three scopes, the four servers I'd install first, and the install/remove commands that actually work in 2026. > [CTA-BLUEPRINT] ## What is Claude Code MCP? Claude Code MCP is Anthropic's implementation of the Model Context Protocol inside the Claude Code CLI and desktop app. It connects Claude to external data sources and tools through a standardised JSON interface, so Claude can read your Google Drive docs, query your Postgres database, post in Slack, or drive a browser through Playwright without you writing custom integration code. Anthropic describes MCP as "an open standard for connecting AI tools to external data sources. With MCP, Claude Code can read your design docs in Google Drive, update tickets in Jira, pull data from Slack, or use your own custom tooling." It launched in late 2024 and has been GA in Claude Code since 2025, with one-click registry installs added in 2026. Two things to know up front. MCP is not Claude-specific. The official spec lives at [modelcontextprotocol.io](https://modelcontextprotocol.io), and Cursor, VS Code, OpenAI Codex, and dozens of other clients all speak it. And MCP servers are just programs that expose tools, resources, and prompts over a standard transport. Most are Node, Python, or Go binaries you install with npx or pipx. ## How do I install an MCP server in Claude Code? You install an MCP server in Claude Code by running claude mcp add with the name and command, or by editing the .mcp.json file in your project root directly. Both methods write to the same place. The CLI is faster for one-off installs. Editing the JSON is faster when you're copy-pasting from a docs page. The fastest install command looks like this. Run it from inside any project directory: That writes the server config into the current scope (project by default). Type /mcp inside Claude Code to confirm the server connected and see its tool count. If the server is HTTP-based (managed servers like GitHub's hosted MCP), point at a URL instead of a command and add an authorization header: Three transports are supported: stdio (a local process Claude talks to over stdin/stdout), SSE, and HTTP. Almost every server you install in your first week is stdio. The hosted ones from GitHub, Atlassian, and Linear are HTTP. ## How do I add an MCP server to Claude Code? You add an MCP server to Claude Code by writing a JSON object into the mcpServers section of .mcp.json, or by running claude mcp add. Both produce the same result. Pick whichever has less friction for the task. Here is the .mcp.json from my AI Operator OS project, sanitised. It runs ten servers across knowledge base, business systems, and Google: The type field is either "stdio" or "http" (sse is also valid). For stdio, command and args spawn a local subprocess. For http, url is the endpoint and headers go in their own object. Secrets always go in env (stdio) or headers (http), never in args, which can leak via process listings. After saving the file, type /mcp inside Claude Code. You'll see a list of every server with a connection status and a tool count. If a server shows zero tools or a red status, jump to the troubleshooting section below. ## What's the difference between project, user, and local MCP scope? Claude Code supports three MCP config scopes: project, user, and local. Project scope lives in .mcp.json in your repo root and is shared with the whole team via git. User scope lives in ~/.claude.json and applies to every project on your machine. Local scope is per-user, per-project, also in ~/.claude.json, and overrides the project file for just you. ### Project scope (.mcp.json) Use project scope when the server is part of how the project itself works. Examples: a Postgres MCP pointing at the dev database, a Stripe MCP scoped to a test mode key, a Playwright MCP for the test suite. Commit .mcp.json so the next person to clone the repo gets the same tools. ### User scope (~/.claude.json) Use user scope for servers you want everywhere: Obsidian, Google Workspace, GitHub (with your personal token), an LLM memory store. These are tools tied to you, not to the codebase. They follow you across every project you open. ### Local scope (per-user, per-project) Use local scope when you need to override or add to project scope without touching the shared file. Common case: the project's .mcp.json points at a staging Postgres, but you personally want to point your local copy at production for a one-off audit. Add a local-scope override that gets ignored by everyone else. The CLI lets you set scope at install time with --scope flag. The default is project. Run claude mcp add --scope user github ... to install GitHub at user scope instead. ## How do I set up the GitHub MCP server in Claude Code? You set up the GitHub MCP server in Claude Code by adding the hosted endpoint at api.githubcopilot.com/mcp/ with a personal access token in the Authorization header. The hosted version requires a GitHub Copilot subscription. If you don't have one, run the open-source local server from the github/github-mcp-server repo instead. Hosted version, the one I run, looks like this in .mcp.json: Generate the token at github.com/settings/tokens with repo, workflow, and read:org scopes. Paste, restart Claude Code, type /mcp. You should see GitHub with around 60 tools (issue read/write, PR review, branch create, file get, search code). The local open-source server is a Go binary you build yourself. It works without a Copilot subscription but you maintain it. For most people the hosted route is faster, since it's the one Anthropic and GitHub keep in sync with new endpoints. ## How do I set up the Postgres MCP server in Claude Code? You set up the Postgres MCP server in Claude Code by installing the official @modelcontextprotocol/server-postgres package via npx and passing your connection string as an argument. It exposes read-only tools for listing tables, describing schemas, and running SELECT queries. It deliberately blocks writes so Claude can't drop your database. Drop this in .mcp.json (project scope, since the connection string is environment-specific): Never commit a real connection string. Use an env var and reference it via shell expansion in the args, or load it from .envrc with direnv. Once connected, ask Claude things like "show me the schema for the users table" or "how many subscriptions were created last week." It picks the SELECT tool and returns the result inline. Pair it with a hook to log every query if you need an audit trail (Claude Code v2.1.118 supports hooks calling MCP tools). ## How do I set up the Playwright MCP server in Claude Code? You set up the Playwright MCP server in Claude Code by installing Microsoft's @playwright/mcp package and adding it to .mcp.json with stdio transport. It gives Claude a real browser it can drive: navigate, click, fill forms, take screenshots, run accessibility audits, and scrape rendered DOM. It's the most popular MCP server on the registry, with around 14,800 monthly searches alone for the term Playwright MCP. Config block: First launch downloads Chromium (around 200MB) and warms up the browser context. Then ask Claude things like "open theaiarchitects.com and screenshot the hero" or "go to my Stripe dashboard and tell me MRR." Claude picks the navigate tool and the result lands in your context. Two things people miss. Playwright MCP can run headless or headed. Headed mode is useful for debugging. Headless is for production and CI. Set it via PLAYWRIGHT_HEADED=1 in the env block. And you can chain Playwright with other servers. I have a setup that uses Playwright to scrape, Airtable to store, and Stripe to verify. Three MCP servers, one prompt. > [CTA-BLUEPRINT] ## How do I remove an MCP server from Claude Code? You remove an MCP server from Claude Code by running claude mcp remove , or by deleting the server's entry from .mcp.json (project scope) or ~/.claude.json (user/local scope). The CLI is the safer option because it confirms which scope it's editing. Hand-editing the JSON is fine if you know which file owns the server. CLI: If the server exists in multiple scopes, the command will ask which one to remove. Pass --scope project|user|local to skip the prompt. Manual edit. Open .mcp.json, delete the key for the server, save. Restart Claude Code. Run /mcp to confirm it's gone. If it still shows up, it's defined in another scope. Run claude mcp list with --scope all to see every config the CLI is reading. Use claude mcp disable to keep the config but stop loading. Useful when debugging which server is hogging context. ## Why is my Claude Code MCP server not connecting? Most Claude Code MCP connection failures fall into four buckets: missing credentials, wrong transport type, port collision, or a broken server. Run claude mcp logs first. The error is usually at the top. "command not found" or "npm error" means the binary isn't installed or npx can't reach the registry. Pre-install with npm install -g and point Claude Code at the absolute binary path instead of npx. 401 or 403 on an HTTP server means the bearer token is wrong, expired, or missing scopes. Regenerate, re-add, confirm /mcp shows green. A hang or timeout on stdio usually means a missing env var. Many Postgres and database servers silently wait for a connection string. Cross-check the server's README and add the missing env entry. Last gotcha: scope conflicts. If a project .mcp.json and a user-scope config both define a server with the same name, the project one wins. The other is silently ignored. Rename or remove the duplicate. ## What's the best Claude Code MCP server? If you only install one, install Playwright. It is the highest-leverage server for the broadest set of tasks: scraping rendered pages, automating SaaS dashboards, debugging your own deployed app from inside a Claude session. After Playwright my second pick is GitHub, third is Postgres or Airtable depending on where your data lives. Honest take: most MCP servers are over-engineered. Many wrap a SaaS API you could just hit with curl from Claude Code's Bash tool. The reason to install an MCP server is when the tool exposure is structured (typed inputs, schema-aware) or when you don't want Claude reading your raw API key. Otherwise, give Claude an OpenAPI spec instead. For business operators, the four servers I run every week are Airtable (CRM, accounting), Apollo (lead enrichment), Stripe (revenue queries), and Tokscript (TikTok/Instagram transcripts). None are on the front page of the official MCP registry. ## Claude Code MCP tutorial: a 10-minute end-to-end walkthrough Here is the fastest path from zero to a working MCP server. Spin up a fresh project. Install Claude Code. Run the install command. Verify. Move on. ### Step 1. Confirm Claude Code is up to date Run claude --version. You want anything in the v2.1.x range from late 2025 onward. If you're on an older v1, the .mcp.json schema and the CLI command syntax both differ. Update with brew upgrade --cask claude-code on macOS, or rerun the curl install script. ### Step 2. Create or open a project MCP servers attach to project context, so cd into a real folder. If you don't have one, mkdir mcp-test && cd mcp-test. Run claude inside it. Type /mcp. The list will be empty. ### Step 3. Install your first server The Filesystem server is the simplest install (no API key, no transport gotchas). Drop this in a new .mcp.json: ### Step 4. Verify Restart the Claude Code session. Run /mcp. You should see filesystem with around 8 tools. Ask Claude "list the files in this folder." It picks the read_directory tool from the filesystem server and returns the listing. If you want to be sure it's the MCP server doing the work and not the built-in tools, run /tools and look for the mcp__filesystem prefix. ### Step 5. Layer on the real ones Add Playwright. Add GitHub. Add whatever production system you want to drive. Each new server is a four-line JSON entry. Restart, /mcp, confirm green, move on. Under 60 seconds per server once you have your tokens. ## Claude Code MCP OAuth: how to authenticate hosted servers Some MCP servers (notably Google Workspace, Atlassian, Linear) require OAuth instead of a static API key. Claude Code handles this with the claude mcp authenticate command, which opens a browser, lets you grant scopes, and writes the token back into the config file. The flow looks like this: Refresh tokens rotate automatically while the original session stays valid. If a server starts failing with 401 weeks after install, run claude mcp authenticate again to refresh manually. ## Where Claude Code MCP falls short MCP is genuinely good but it has three rough edges I run into every week. First, cold starts. Every new session spins up every stdio server in your config. With ten servers locally, that's a 4-6 second wait on your first prompt. The alwaysLoad option (v2.1.121) lets you pre-warm critical ones, but first launch of the day is still slow. Second, tool discovery overhead. If you run 200+ tools, Claude has to read every description to pick one. That eats context. The /mcp panel shows tool counts (v2.1.128) precisely because people install too many servers. Audit yours and disable the ones you don't use day-to-day. Third, security model. MCP servers run with whatever credentials you hand them. Give a server a database admin token and Claude has admin on that database. Scope tokens to read-only when possible, and use PreToolUse hooks to confirm destructive operations. ## Verdict: is Claude Code MCP worth setting up? Yes, for anyone using Claude Code on real work. Even one MCP server (Playwright or GitHub) makes Claude meaningfully more capable than the same model running with just Bash and Edit. Skip it if you're using Claude Code purely as a code generator and you never want it touching outside systems. Otherwise, install Playwright today and add servers as you hit the next bottleneck. Cost is zero unless you pick a server that wraps a paid API. ## Claude Code MCP FAQ ### Where is the Claude Code MCP config file? Project scope: .mcp.json in the project root. User scope: ~/.claude.json (look for the mcpServers key). Local scope: also in ~/.claude.json under a per-project section. On Windows, the user file is at %USERPROFILE%\.claude.json. The CLI claude mcp list --scope all prints every active config. ### How do I list MCP servers in Claude Code? Type /mcp inside Claude Code to see all connected servers, their connection status, and the number of tools each exposes. From the terminal outside Claude, run claude mcp list. Add --scope user, --scope project, or --scope all to filter. ### Can I add an MCP server globally in Claude Code? Yes. Use claude mcp add --scope user . That writes the entry to ~/.claude.json, which loads in every project. Use this for personal tools (Obsidian, GitHub with your token, knowledge bases). Keep project-specific servers in .mcp.json so the team can share them. ### How do I connect Figma MCP to Claude Code? Install the official figma/mcp package via npx and pass your Figma personal access token in the env. The config block looks similar to the Playwright one, with a single env var FIGMA_API_KEY. The server exposes read tools for files, comments, and components. Editing Figma files via MCP is currently restricted to specific node operations. ### Is Claude Code MCP free? Yes, the protocol and the Claude Code MCP support are both free. You only pay for the underlying services your servers wrap. A Postgres MCP costs nothing. A Stripe MCP costs nothing on top of your Stripe account. The hosted GitHub MCP server requires a Copilot subscription, but the open-source local equivalent is free. ### What is the difference between MCP and Claude Code skills? MCP servers are external tools Claude can call. Skills are markdown files that extend Claude's instructions. MCP gives Claude the ability to do new things (query a database, drive a browser). Skills give Claude a procedure to follow when it does them. Most production setups use both. See the deep-dive at [/blog/how-to-use-claude-code](/blog/how-to-use-claude-code) for a worked example. ### Can hooks call MCP tools in Claude Code? Yes, since v2.1.118. You can configure a hook with type "mcp_tool" so a lifecycle event (e.g. SessionStart, PostToolUse) automatically invokes a specific MCP tool. Common pattern: a SessionStart hook that calls a knowledge-base MCP to load relevant context into the session. Full hook reference at [docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code). ### Where can I find a list of available MCP servers? The official MCP server registry lives at [github.com/anthropics](https://github.com/anthropics) (search for mcp) and at modelcontextprotocol.io. Anthropic's registry now supports one-click install from inside Claude Code as of 2026. Third-party registries like mcp.so and Smithery list community servers too, but vet anything you install with credentials. > [CTA-BLUEPRINT] ## Ready to wire Claude Code into your real systems? I built a free 60-minute walkthrough called the [Blueprint](/blueprint) that gets a non-developer from a fresh Claude Code install to a public URL with at least one live MCP server connected. If you'd rather work through it with weekly accountability, the [Claude Code 30-Day Challenge](/challenge) runs a four-week cohort that ends with a portfolio of three working automations. Either way, MCP is the layer where Claude Code stops being a coding tool and starts being an operator. ## Frequently Asked Questions ### What is Claude Code MCP? Claude Code MCP is Anthropic's implementation of the Model Context Protocol inside Claude Code. It connects Claude to external data sources and tools (Postgres, GitHub, Stripe, Playwright, Airtable, Google Drive) through a standardised JSON interface, so Claude can read and write outside your repo without you writing custom integration code. MCP launched in late 2024 as an open standard, so the same servers also work in Cursor, VS Code, and Codex. ### How do I install an MCP server in Claude Code? Run claude mcp add with the name and command, or edit .mcp.json in your project root directly. Both write to the same place. The CLI is faster for one-off installs. Editing the JSON is faster when you are copy-pasting from a docs page. After saving, type /mcp inside Claude Code to confirm the server connected and see its tool count. ### What is the difference between project, user, and local MCP scope? Project scope lives in .mcp.json in your repo root and is shared with the whole team via git. Use it for servers tied to the project (test-mode Stripe, dev Postgres, Playwright for the test suite). User scope lives in ~/.claude.json and applies everywhere on your machine. Use it for personal tools (Obsidian, GitHub with your token). Local scope overrides project scope for just you, useful for one-off audits without touching the shared file. ### Which MCP server should I install first? Playwright. It is the highest-leverage server for the broadest set of tasks: scraping rendered pages, automating SaaS dashboards, debugging your own deployed app from inside a Claude session. Around 14,800 monthly searches a month go to 'Playwright MCP' alone. My second pick is GitHub, third is Postgres or Airtable depending on where your data lives. ### Why is my MCP server not connecting? Run claude mcp logs first. The error is usually at the top. Four common causes: 'command not found' means the binary is not installed (pre-install with npm install -g and point to the absolute path), 401 or 403 means the bearer token is wrong or expired, a stdio hang usually means a missing env var, and scope conflicts mean a duplicate server in both project and user scope (project wins silently). ### Is Claude Code MCP free? Yes. The protocol and Claude Code MCP support are both free. You only pay for the services the servers wrap. A Postgres MCP costs nothing. A Stripe MCP costs nothing on top of your Stripe account. The hosted GitHub MCP requires a Copilot subscription, but the open-source local equivalent is free. ### What is the difference between MCP servers and Claude Code skills? MCP servers are external tools Claude can call (query a database, drive a browser, post in Slack). Skills are markdown files that extend Claude's instructions and give it a procedure to follow. MCP gives Claude new abilities. Skills give Claude a playbook for using them. Most production setups use both together. ## Related guides - [Best MCP servers for Claude Code (my stack)](/blog/best-mcp-servers-for-claude-code) - [GitHub MCP for Claude Code (my setup)](/blog/github-mcp-claude-code) --- # Claude Code Hooks: 9 Production Hooks That Actually Work Source: https://theaiarchitects.com/blog/claude-code-hooks Published: 2026-05-04 Claude Code hooks tutorial: 9 production PreToolUse, PostToolUse, Stop and SessionStart hooks with real JSON config and runnable shell scripts. Claude Code hooks are user-defined shell commands that fire automatically at specific points in the Claude Code lifecycle, like before a tool runs, after a file is edited, or when the session ends. They turn Claude Code from an AI assistant into a programmable workflow runner that you can trust with destructive commands, secrets, and your CI pipeline. I'm Tom. I run AI Architects and have nine hooks wired into my own Claude Code setup right now. Every one of them exists because Claude did something stupid once and I wrote a hook so it could never happen again. This post walks through all nine with the real JSON config and the shell script you can copy. > [CTA-BLUEPRINT] ## What are Claude Code hooks? Claude Code hooks are shell commands the harness runs automatically at lifecycle events: before tool use, after tool use, on session start, on session stop, on user prompt, on notification, and a few others. The harness pipes a JSON payload into the hook on stdin, and the hook can either pass through (exit 0) or block the action (exit 2 plus a message). The official reference lives at [docs.anthropic.com/en/docs/claude-code/hooks](https://docs.anthropic.com/en/docs/claude-code/hooks). The page is dense, but the model is simple. You add a hooks block to your settings.json, give it a matcher (like Edit|Write or Bash), and point it at a command. Claude runs that command at every matching event. The hook gets a few hundred milliseconds, returns, and Claude proceeds, retries, or stops based on the exit code. Anthropic added a few important capabilities in 2026. Hooks can now call MCP tools directly (v2.1.118), and the PostToolUse payload includes a duration_ms field (v2.1.119) so you can profile slow tools. The CHANGELOG on [github.com/anthropics](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) tracks the rest. ## How do I create a Claude Code hook? You create a Claude Code hook by adding a hooks object to your settings.json file under the matching event name (PreToolUse, PostToolUse, Stop, SessionStart, etc.). Each entry has a matcher and one or more command hooks. Save the file, restart your Claude Code session, and the hook is live. The smallest possible hook looks like this. It runs an echo every time Claude finishes a session: Restart Claude Code. End a session. Check claude-sessions.log. You'll see a timestamp. That is the entire mental model. Everything from here is just choosing the right event, writing a slightly fancier shell script, and remembering to restart Claude Code after every settings.json change. ## Where do hooks live in Claude Code? Hooks live in three places: ~/.claude/settings.json (user scope, applies to every project), .claude/settings.json in your project root (project scope, shared with your team via git), and .claude/settings.local.json in your project root (local scope, gitignored). The harness merges all three at session start. Use user scope for personal safety nets like the rm -rf blocker. Use project scope for team-shared rules like a lint hook that runs on every Edit. Use local scope for one-off testing and anything project-specific you don't want in git. If two scopes define the same matcher, both fire. They are additive, not overriding. ## What's the difference between PreToolUse and PostToolUse hooks? PreToolUse hooks fire before Claude Code runs a tool and can block it by exiting with code 2. PostToolUse hooks fire after the tool completes and cannot block, but they can read the result, log it, or trigger follow-up work. Use PreToolUse for safety gates. Use PostToolUse for automation. Concrete example. A PreToolUse hook on Bash can intercept the command Claude is about to run, scan it for rm -rf, and refuse. A PostToolUse hook on Edit can run prettier on the file Claude just changed. PreToolUse is your veto. PostToolUse is your janitor. Both events get a JSON payload on stdin. PreToolUse gets tool_name and tool_input (the arguments Claude wants to pass). PostToolUse gets the same plus tool_response and duration_ms. Pull whichever fields you need with jq. ## The 9 production hooks I run in Claude Code Every hook below is in my real settings.json. Each one is a real problem I solved by writing the hook. Copy them, adjust paths, drop them into ~/.claude/settings.json or .claude/settings.json. Restart Claude Code after each addition. ### 1. Block dangerous rm -rf commands (PreToolUse on Bash) The day Claude wiped a node_modules folder I didn't want it touching, I wrote this hook. It scans every Bash command before execution and refuses anything matching rm -rf or rm -fr targeting an unsafe path. It is the single most important hook in my setup. Add this to ~/.claude/settings.json: And the script at ~/.claude/scripts/block-dangerous-bash.sh: Make the script executable with chmod +x ~/.claude/scripts/block-dangerous-bash.sh. Restart Claude Code. Try to make Claude run rm -rf ~/Documents. The harness blocks the call before it leaves the model. You'll see the BLOCKED message in your terminal. ### 2. Auto-format on every Edit (PostToolUse on Edit) Claude writes valid code, but it doesn't always match your project's formatter. This hook runs prettier (or rustfmt or gofmt, take your pick) on whatever file Claude just edited, immediately after the Edit lands. It saves the lint dance later. Add to your project .claude/settings.json: Script at .claude/scripts/auto-format.sh: PostToolUse can't block, so even if prettier fails the Edit still lands. That is the right behaviour. You don't want a busted formatter taking down Claude's whole workflow. ### 3. Slack notification when Claude Code finishes a session (Stop hook) When I run Claude Code on a long task in another terminal, I want to know when it's done without checking. This hook posts a Slack message the second the Stop event fires. The message includes the project name and the last prompt summary. Settings: Script. Set SLACK_WEBHOOK_URL in your shell profile first. Slack delivers in under a second. If your firewall blocks outbound webhooks, swap curl for any other notifier. The pattern is identical. ### 4. Lint code Claude wrote (PostToolUse on Edit) Format-on-save is the easy half. Linting catches actual mistakes Claude makes: unused imports, dead code, type errors. This hook runs eslint with --fix on TypeScript and JavaScript files immediately after Edit. Script: Lint output goes to stderr, which Claude Code surfaces back into the session. Claude reads its own lint warnings on the next turn and fixes them. The loop closes itself. ### 5. Load project context at session start (SessionStart hook) Every project I open has a context file with the current sprint focus, the open bugs, and the do-not-touch list. SessionStart fires once per Claude Code session and lets me pipe that context straight into the conversation before Claude reads anything else. Script: Anything the script writes to stdout becomes context Claude sees on its first turn. Keep it under 1000 tokens or you'll burn budget on every session start. ### 6. Block secrets from leaving the machine (PreToolUse on Bash) Claude occasionally tries to curl a payload that contains an API key from a .env file. This hook scans every Bash command for the patterns API keys take (sk-, ghp_, xox, AKIA, eyJ for JWTs) and blocks the call if it spots one. Script: I keep this in user scope so it runs in every project. The patterns list is what I've seen in the wild. Add your own internal token prefixes too. False positives are rare and easy to fix by parameterising the command. ### 7. Auto-generate conventional commit messages (PreToolUse on Bash) When Claude runs git commit -m, half the time the message is fine, the other half it's a one-word log entry. This hook intercepts git commit calls, reads the staged diff, and rewrites the message to follow conventional commits format if it doesn't already. Script: Claude reads the BLOCKED message, retries the commit with a proper prefix, and the hook lets it through. You get a clean git log without ever opening it. ### 8. Run tests when source files change (PostToolUse on Edit) When Claude edits a file in src/, this hook runs the matching test in tests/. If the test file doesn't exist, the hook is silent. If it exists and fails, Claude sees the failure on its next turn and patches the code without being asked. Script: Switch vitest for jest, pytest, go test, cargo test, whatever your stack uses. The mapping logic is the only part you need to adapt. ### 9. Desktop notification when Claude needs your input (Notification hook) When I leave Claude Code running and walk away, I want to know when it's blocked on a permission prompt. The Notification event fires every time Claude wants approval. This hook pops a desktop notification on macOS or Linux. Script: Install terminal-notifier on macOS with brew install terminal-notifier for the cleanest output. Linux uses notify-send (preinstalled on most desktops). Windows: pipe to a PowerShell BurntToast call instead. ## How do I block dangerous commands with a hook? Block dangerous commands by writing a PreToolUse hook on the Bash matcher that exits with code 2 when the command matches a dangerous pattern. Exit 2 tells Claude Code to refuse the tool call and surface your stderr message back to the model. Hook 1 above is the canonical example. Three patterns are worth blocking by default: rm -rf with an unbounded path, sudo of any kind, and curl piped to bash from an untrusted domain. Add team-specific blocks for things like dropping the production database or pushing to main directly. ## Can a Claude Code hook send a Slack notification? Yes. A Claude Code hook is just a shell command, so it can curl a Slack webhook, post to Discord, send an email through sendmail, or call any other API. Hook 3 above shows the exact pattern. Set SLACK_WEBHOOK_URL in your environment, drop the script in ~/.claude/scripts/, point a Stop hook at it, and you're done. The hook receives the full transcript on stdin. You can extract the last message, the total token count, the duration, or any other field you want and include it in the notification. jq is your friend here. ## How do I run a script when Claude Code finishes a session? Use the Stop hook event. The Stop event fires once when Claude Code completes a turn and stops accepting tools. Add a hooks block under Stop in settings.json with a command that points at your script. The script runs synchronously, so keep it under a couple of seconds or set a timeout. Hook 3 (Slack) and the example at the very top of this post both use Stop. The other common pattern is logging session metadata to a file for analytics. Tail that file later and you have a complete history of every Claude session you've run. ## Why isn't my Claude Code hook firing? Most Claude Code hook failures fall into four buckets: forgot to restart Claude Code, matcher doesn't match the tool name, script isn't executable, or jq isn't installed. Diagnose them in that order. Run claude --debug to see hook execution in real time. The harness prints every hook it tries to run plus the exit code. If you don't see your hook in the debug log, the matcher is wrong. If you see it run but the action goes through anyway, you returned the wrong exit code (PostToolUse can't block, only PreToolUse can, and only with exit 2 plus a stderr message). Test your hook script directly by piping a sample JSON payload into it. Copy the payload format from [the hooks docs](https://docs.anthropic.com/en/docs/claude-code/hooks). If the script works in isolation but not via Claude Code, the problem is the settings.json wiring. Check that the matcher is the literal tool name (Bash, Edit, Write, MultiEdit, etc.) and that the JSON is valid. ## Are Claude Code hooks safe? Claude Code hooks are as safe as the shell scripts you write for them. The harness runs every hook with your user permissions, so a malicious or buggy hook can do anything you can do from a terminal: delete files, post to the internet, drop databases. Treat hooks like any other shell automation. Read every hook before you install it. The two genuine risks are: (1) a hook from someone else's repo doing something destructive on first session, and (2) a hook that calls an MCP tool with credentials it shouldn't have. Mitigate both by code-reviewing every hook in .claude/settings.json (it's checked into git), and by scoping any tokens MCP hooks use to the minimum permissions they need. > [CTA-BLUEPRINT] ## Claude Code hooks FAQ ### What events trigger Claude Code hooks? Claude Code supports PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, SessionEnd, Notification, and a handful of others documented at docs.anthropic.com/en/docs/claude-code/hooks. PreToolUse and PostToolUse are the two most useful in practice. ### Can hooks call MCP tools in Claude Code? Yes, since Claude Code v2.1.118. Set the hook type to mcp_tool and pass the server name, tool name, and arguments. The classic use case is a SessionStart hook that calls a knowledge-base MCP server to inject project context. The full payload schema is in the changelog at github.com/anthropics/claude-code. ### How do I write a Claude Code hook in Python instead of bash? Point the command at python3 /path/to/script.py instead of bash. The script reads JSON from stdin, prints any output to stderr, and exits 0 to allow or 2 to block (PreToolUse only). Python is fine for any hook that does more than basic string matching. Use bash for one-liners and Python for anything you'd otherwise pipe through five awk calls. ### Where can I find more Claude Code hook examples on GitHub? Search github.com for claude-code-hooks or browse the awesome-claude-code repos. Quality varies. The most useful collections are the ones tied to a specific stack (Next.js, Rails, Django) where the hooks reflect real workflow choices. Read every hook before you install it. ### Can I disable a hook temporarily without deleting it? Yes. Comment-style disable doesn't work in JSON, so the cleanest way is to wrap the command in a guard. Set CLAUDE_HOOKS_OFF=1 in the shell where Claude Code is running and the hook becomes a no-op: ### What's the difference between Claude Code hooks and skills? Hooks are deterministic shell commands the harness runs at lifecycle events without asking the model. Skills are markdown instructions Claude reads when relevant and decides whether to apply. Hooks enforce. Skills suggest. Use a hook when the rule must always run. Use a skill when the rule is contextual. ### Do Claude Code hooks work in the desktop app and on the web? Hooks work in the Claude Code CLI on macOS, Linux, and Windows. The desktop app picks them up too because it's a thin wrapper over the CLI. Claude Code on the web runs in a managed sandbox and supports a restricted hook set as of late 2025. Check the docs for the current web-supported event list. ### Can hooks see the user's prompt? Yes, via the UserPromptSubmit event. The hook payload includes the prompt text. You can use this to scrub sensitive info before it hits the model, log every prompt for audit, or trigger a context loader based on prompt content. Just don't let your hook modify the prompt without telling the user. ## Ready to harden your Claude Code setup? I built a free 60-minute walkthrough called the [Blueprint](/blueprint) that gets a non-developer from a fresh Claude Code install to a working setup with their first hook installed. If you'd rather work through it with weekly accountability, the [Claude Code 30-Day Challenge](/challenge) runs a four-week cohort that ends with a portfolio of three working automations, all guarded by the hooks above. The full Claude Code primer lives at [/blog/how-to-use-claude-code](/blog/how-to-use-claude-code) if you want the broader setup before going deep on hooks. ## Frequently Asked Questions ### What are Claude Code hooks? Claude Code hooks are user-defined shell commands that fire automatically at lifecycle events: before a tool runs, after a file is edited, when the session ends, on user prompt, on notification. The harness pipes a JSON payload to the hook on stdin and the hook either passes through (exit 0) or blocks the action (exit 2 plus a message). They turn Claude Code into a programmable workflow runner you can trust with destructive commands. ### How do I create a Claude Code hook? Add a hooks object to your settings.json under the matching event name (PreToolUse, PostToolUse, Stop, SessionStart). Each entry has a matcher and a command. Save the file, restart your Claude Code session, and the hook is live. The smallest possible hook is a Stop hook with an echo command appending to a log file. Once that works, the rest is choosing the right event and writing a fancier shell script. ### Where do Claude Code hooks live? Three places. ~/.claude/settings.json for user scope (every project). .claude/settings.json in your project root for project scope (shared via git). .claude/settings.local.json for local scope (gitignored). The harness merges all three at session start and they are additive, not overriding. Use user scope for personal safety nets, project scope for team-shared rules, local scope for one-off testing. ### What is the difference between PreToolUse and PostToolUse hooks? PreToolUse fires before Claude runs a tool and can block it by exiting with code 2. PostToolUse fires after the tool completes and cannot block, but it can read the result, log it, or trigger follow-up work. Use PreToolUse for safety gates like blocking rm -rf or sudo. Use PostToolUse for automation like running prettier after every Edit. ### Can a hook send a Slack notification when Claude finishes? Yes. A hook is just a shell command, so it can curl a Slack webhook, post to Discord, send an email, or call any other API. Set SLACK_WEBHOOK_URL in your environment, drop a bash script in ~/.claude/scripts/, and point a Stop hook at it. The hook receives the full transcript on stdin so you can pull the last message, token count, or duration with jq. ### Why is my Claude Code hook not firing? Four buckets cover most failures. Forgot to restart Claude Code after editing settings.json. Matcher does not match the actual tool name (Bash, Edit, Write, MultiEdit). Script is not executable (chmod +x it). Or jq is not installed. Run claude --debug to see hook execution in real time. The harness prints every hook it tries and its exit code, which tells you exactly which problem you have. ### Are Claude Code hooks safe to install from other people's repos? As safe as the shell scripts you trust. The harness runs every hook with your user permissions, so a malicious hook can do anything you can do from a terminal. Read every hook before you install it. The two real risks are a hook from someone else's repo doing something destructive on first session, and a hook calling an MCP tool with credentials it should not have. Code-review settings.json the same way you code-review any other commit. ## Related guides - [Claude Code Settings: The settings.json Guide](/blog/claude-code-settings) - [Claude Code Memory: CLAUDE.md, Auto Memory, and Path Rules](/blog/claude-code-memory) - [Claude Code Notifications: Get Alerted When It's Done](/blog/claude-code-notifications) --- # Case studies # Case study: Kyle Rucker Source: https://theaiarchitects.com/case-studies/kyle-rucker Operations Lead — Industrial Manufacturing / Fabrication **Outcome:** Replaced manual ops, projecting six figures year-one savings Kyle runs ops at a ~115-person industrial manufacturer. He shipped two production systems with his mentorship cohort: a fabrication workflow that gave one admin back 4-5 hours every day, and a fully autonomous employee evaluation engine that pulls from Zoho, ADP, SharePoint and Ford Pro into a single dashboard. Plus a Zoho-to-Intacct integration in flight. **Key metrics:** - Admin time recovered: 4-5 hours per day saved on packing/invoicing - Year-one savings: Several hundred thousand projected - Headcount freed up: 3 people redirected from manual work to high-level ## What they built Kyle had tried n8n on his own before joining the mentorship and couldn't get past the third node without an error. Four months in, he's running two fully deployed production systems and a third in active build. ### The fabrication ops system The fabrication floor used to run on paper: workers wrote down which widgets they completed, the admin re-typed everything into the system, then manually generated packing slips and invoices in the format their customer KAIS demanded. Kyle put iPads on the floor with a submit form that flows straight into the system. Now packing slips and invoices are one-click generation. The admin who used to retype paper all day gets 4-5 hours back, every day. No more transcription errors. Their manager started looking at new customers because the team finally has the bandwidth. ### The autonomous employee evaluation engine Roughly ten sub-workflows orchestrated together. Every Monday it checks Zoho for new hires, builds their SharePoint folder structure, then for any employee with an eval in the next two weeks it pulls the last 12 months of data: driving stats from Ford Pro, attendance from ADP, education and licensures, project history, write-ups. PDFs get auto-summarised by Claude into one or two sentences so the manager never has to open the underlying documents. Output is a per-employee dashboard that gives the manager a 5-minute glance instead of 5 hours of digging. Security is handled inside n8n so nobody touches the raw SharePoint, supervisors only see their own reports. ### What changed Three people inside the business have been redirected from low-level manual work to high-level work that actually uses their skills. Kyle now hands Claude Code briefs to his own team and tells them to build. By his own estimate he's looking at several hundred thousand in year-one savings before counting compounding gains in year two. > Hundreds of thousands of dollars would be the quick and easy in year one. And once you learn a skill set like this, it's just really, really powerful. --- # Case study: Cal Hewitt Source: https://theaiarchitects.com/case-studies/cal-hewitt Service & Project Manager, Maintenance Contracting — Construction / Facilities Maintenance **Outcome:** Built agentic work-order dispatch, became company's head of AI Cal runs the maintenance division of a Toronto contracting business. Four months into the mentorship he shipped an end-to-end work order triage and dispatch system, walked into a quarterly town hall to introduce himself as the company's de facto head of AI, and started fielding requests from subcontractors who want him to build it for them too. **Key metrics:** - Work order acknowledgement: From up to 48 hours to minutes - Dispatch handoff: Auto-classified, matched, SMS dispatched - Internal positioning: Introducing as head of AI at quarterly town hall ## What they built ## The before Cal lives in Toronto, originally from Yorkshire. He works as a service manager and project manager inside the maintenance division of a contracting business, with a prior life across tech startups and accelerator programs going back to 2016. He had been towing the line between the built world and the digital world for the best part of a decade, and the digital side kept calling him back. The day-to-day was full of work orders. Every time a key account sent in a request, Cal was copying and pasting the description, title and job number into Google Sheets, deciding whether it was a warranty job, a project, a critical service call or a priority service call, then chasing down a subcontractor. The job itself was **15 minutes of admin** per work order. The reality was that 15 minutes got smeared across two or three hours, and on a bad day a Friday night request might not get opened until Monday. ### The admin tax "If the customer says that we have an emergency and we need a plumber here within 4 hours, if it took me 4 hours to even open that email and figure out if they need someone, we've already let them down." In this industry, customer complaints almost always trace back to the same root cause: nobody picked up the phone in time. He had dabbled in Airtable and Zapier going back to 2021, even written custom scripts to push them further. He was decent at it. He also remembered working until midnight on what was effectively the earliest version of vibe coding, thinking, "man, I wish that this could be a job." What he had not done was wire actual AI agents into any of it. Before joining, he sat down with the change management consultant on retainer at his company and pitched the idea of replacing what wasn't truly required of him. He got buy-in. That gave him the conviction to invest in the mentorship. ### The legacy software trap He almost talked himself out of joining anyway. "Is this just another shiny object? Am I being a sucker here?" The cynicism was real. Then he flipped it. > The one sure way to make sure that it doesn't work is to be cynical and not do anything, and just give the ball a kick. ## What we built The system Cal shipped is a full work order triage and dispatch pipeline. A Google Apps Script sits on his inbox and watches for work order emails. When one matches the criteria, it applies a label, which fires the n8n workflow. From there, an LLM agent reads the description and classifies the request — warranty, project, critical service call, priority service call — and creates the matching record in Airtable. Photos were a fight in their own right. The industry runs on visual evidence, but the formats coming off site phones don't play nicely with most tools. "I needed a way to handle photos, which was a whole thing, if you remember, Tom." Dropbox didn't work. Google Drive permissions didn't work. Cal eventually routed images through Convert API to generate clean URLs that the rest of the workflow could actually use. ### The intake pipeline To keep his team comfortable while the system earned trust, he layered in a human-in-the-loop step. An agent posts into Google Chat with the work order, the description and its proposed classification, and waits for a thumbs up. Once approved, the workflow cascades through Airtable, filters the labourers and technicians by trade and availability, and surfaces the best matches. Cal picks one. The dispatch goes out by email and a Twilio text message lands on the subcontractor's phone. That classification step was the moment the whole abstraction clicked. "Until that point, anything on the internet was apparently agentic. I didn't really understand what they were talking about. But now I do." ### Human in the loop Mid-build problems were where the mentorship paid for itself the most. The photo handling problem alone could have stalled the project for weeks. Working through it together meant try, fail, try again, ship. Cal called this out by name as part of the value: "I believe in you, let's get through this together, let's try this. Okay, it didn't work, okay, let's try something else." ## The shift A category of work that could take **up to 48 hours** to even acknowledge now flows through in minutes. The dispatch bottleneck has moved up the funnel. Cal can now point at customer acquisition as the next thing to automate, rather than fighting the inbox. For a contracting business, where service complaints almost always trace back to nobody picking up the phone, that is a competitive lever the company can sell on. The bigger shift is positional. Construction and maintenance companies do not have CTOs. They are starting to need a head of AI. Cal is presenting at the quarterly town hall this week as exactly that: the person interviewing every department, prototyping inside their workflows and freeing them up for the work that actually requires a human. The subcontractors he dispatches to — small plumbing companies, hood cleaners, the guys with a Debbie in the office — are already asking him whether he can build a version of the system for their own shops. > Probably for one of the first times in my life, I feel like I'm in control. I have the agency to make that happen. ### A new role He frames the investment as a vote towards the future he wants. The 15-minute work order was never the prize. The prize was being the operator who can stand in front of the owners with a working agentic system, and use that as the leverage to walk into the next set of rooms. "Whereas I was working on a 15-minute thing here, I'm now working on something that could unlock tens of millions in revenue on the next project." > A vision, unless it's backed up by action, it's just a hallucination. ## Why this works Cal called out three things specifically: that I'm on every single call, that the calls don't get cut short when something juicy comes up, and that the group is small enough that you don't have to fight for five minutes of attention. He compared it directly to a startup incubator he and a buddy went through during COVID, where everyone was scrapping for their pitch slot and the rest was prerecorded. "That was not it. But this was not that." The other thing he keeps coming back to is the **1% marginal gains** mindset. Not the big breakthroughs. The boring daily wins: figured out the LLM, figured out the system prompt, figured out Convert API. He pushed momentum over perfection from week one, and that was the shape of what got shipped. If Cal had not joined, in his words, he would still be on the diving board. "You're petrified to jump in and you're just running this over in your head, like, is this the thing? Is this what I should be doing? Meanwhile, everyone else has gone into the shallow end and they're progressively working their way to the deep end." The mentorship was the kick into the water. > A vision, unless it's backed up by action, it's just a hallucination. --- # Case study: Chris Cole Source: https://theaiarchitects.com/case-studies/chris-cole Civil Engineering Business Owner — Civil Engineering / Construction Management **Outcome:** Cut a 2-day document workflow to under 2 minutes Chris runs a civil engineering firm in the San Francisco Bay Area with no coding background. A document workflow that used to swallow two days of his week now finishes in under two minutes, and he renewed the mentorship for another three months on the day of his case study call. **Key metrics:** - Manual document process: From 2 days to under 2 minutes - PM sync runtime: Roughly 80 seconds end to end ## What they built ## The before Chris runs a small civil engineering business focused on program, project and construction management out of the San Francisco Bay Area. He has spent years inside project controls, working with data across BigQuery, SQL and Tableau, with Adaptive Work by PlanView as the project management layer underneath everything. The problem he kept hitting was simple to describe and brutal to live with. Government agencies sent **25 to 30 page PDF reports** that took days to manually parse. Word files were worse. Clients had archives of 30 or 40 documents, each seven or eight pages long, with no clean way to track changes across them. The data existed. Nobody could actually use it. ### Spreadsheets and sticky notes He had been tracking n8n on YouTube for about a month before joining. Tutorial after tutorial, but nothing practical was getting built. The CRMs he had worked with for a decade all carried the same trap: every renewal got more expensive, all the data sat inside someone else's database, and switching tools meant abandoning years of records. "That's always really scary for me, because if I want to switch, how do you make the switch? You're basically stuck in one system forever." That data-ownership anxiety was the thing that finally pushed him to try **n8n** properly, instead of watching another tutorial. ## What we built The first build was a project management sync, version 26 by the time it shipped. A webhook trigger fires the workflow, which clears the relevant BigQuery table, then pulls fresh data from Adaptive Work across project names, tasks, resource links, non-labour costs, mileage, timesheets, expenses and time-phased projections. A series of code nodes parses each object into the right shape and writes it into BigQuery, where Tableau picks it up so clients can filter and explore the data themselves. End to end, the sync runs in roughly **80 seconds**. Whatever Chris updates in Adaptive Work flows through to the client-facing Tableau view in the same minute. The Tableau view is the part that wins clients over, because they can drill into their own data without him sitting on the other end of an email thread. ### The /brief command The second build is a Gmail-triggered document intake workflow, which is the one he calls his most fun build, the genesis of why he wanted n8n in the first place. The workflow checks a dedicated processing inbox every five to ten minutes, handles up to 20 attachments per email, and routes each one by file type. DOCX files copy across to Drive. PDFs get parsed, with Claude Sonnet 4.0 doing the extraction. The structured output lands in Google Sheets, and the email gets marked as read so it does not get reprocessed. Chris layered quality checks on top. Totals get cross-referenced in two different places inside each parsed document. If they do not match, the workflow flags it as an error and waits for him to investigate, rather than silently writing bad data into the sheet. The result is a system that gets better as it runs, instead of one that quietly poisons his database. ### Document intake automation Mid-build, the n8n 2.0 release dropped. Workflows he had been running on the older version started running noticeably faster on the new one. He stopped fighting performance and started shipping. ## The shift A two-day manual document process now runs in under two minutes, with fewer errors and a built-in path to data quality checks. "You've got 29 different documents that are 7 pages long with all this different data. The manual entry would be enormous, and meanwhile, I don't have to do anything, it just runs in the background." > I just renewed today for another 3 months. I need to keep myself in these classes, keep going, see what everybody else is doing. The deeper shift is data ownership. Chris is no longer locked into any one CRM or project tool. If he wants to swap a database, he writes a workflow that moves the data. If a client throws a new file format at him, he extends the intake workflow. The freedom from vendor lock-in is, in his words, the part that surprised him most. ### Time back, every week There is a quieter shift underneath all of that. Chris stopped being the consultant who manually pushes data around and became the operator who can sit between every system in his client's stack. "You just need one operator, which is what you're training us to do, who can connect those dots, and no one else has to get involved." ## Why this works Chris sees the mentorship as a forcing function for ideas. Every time he ships a workflow it spawns the next one. The group calls are the place those ideas surface, because somebody else's problem is usually his next build. He renewed the same day his case study was recorded, and the reason was not the technical content. It was the queue of new problems waiting for him in the next cohort. > Anyone looking to save some time, especially as a business owner, you have so many extra things you have to do after hours and on weekends. Why wouldn't you automate those tasks to the best of your ability? > I just renewed today for another 3 months. I need to keep myself in these classes, keep going, see what everybody else is doing. --- # Case study: Keven Elison Source: https://theaiarchitects.com/case-studies/keven Marketing Leader, 30+ Years in Tech — B2B Tech Marketing **Outcome:** Rebuilt a 7-year content workflow into a system that runs in minutes Keven's been working in marketing for over 30 years. Non-technical, never coded, age 63. Three months in, he rebuilt his content manager's seven-year workflow inside n8n end-to-end, runs the same job in minutes that used to take days at an agency, and is mapping the AI infrastructure for his entire org chart. **Key metrics:** - Content workflow speed: From days/weeks to minutes ## What they built ## The before Keven has been marketing tech companies for 30 to 35 years. He is not a coder. He is 63. He had dabbled in workflow automation with Make and could see exactly where the world was heading, and he was not going to wait for it to arrive. The stumbling block was the unknown. "I have a pretty good idea on the workflows and how to map that out, but translating that to a tool like n8n or building the modules and nodes and configuring them, that's something I needed to learn." He could map a process on a whiteboard better than most people half his age. The translation to nodes was a different skill. ### 35 years of marketing intuition, no n8n He had been pulled into the LinkedIn algorithm and was watching plenty of people post n8n agents. Building agents looked easy from the highlight reels. What he could not find was someone willing to teach the fundamentals before jumping to the flashy build. There was also a self-doubt loop running underneath all of it. "I'm 63 years old and I've never been coding or never been doing anything that was, you know, this technical." Building the first agent was the test of whether the next ten years of his career was going to look like the last ten or like something different. ## What we built Keven's first real build was the lead qualification workflow that anchors the early curriculum. Boring by design. He used it to learn each node, each configuration step, each common failure mode. He breaks things on purpose, which makes him a fast learner once he gets the right scaffolding to break things inside of. From there, he built a full content management system. He took his content manager's **seven-year** workflow and rebuilt it inside n8n. Creative brief in, then keyword strategy, content calendar, AEO and SEO blog content, images for each blog, all dropped into the right Google Drive folders so the rest of the organisation can pick them up. End to end, in minutes, instead of the days or weeks an agency would take to ship the same job. ### Content workflow rebuilt Alongside the content system, he started building an AI advisory board. RAG agents trained on the writings and decisions of business minds he respects, from Steve Jobs and Warren Buffett to Elon Musk and Sun Tzu. He started small with a handful, with a plan to scale it as a productised tool other operators can use. He is also planning the wider AI infrastructure for his org chart, mapping where MCP servers, RAGs and agents will live across the business. "I'm building something here, that it's going to be good for my organization or good for, say, even for myself, I know it's going to be a marketable tool that others are going to want to use as well." That is the operator brain talking, not the n8n student. ## The shift A workflow that previously chewed up days or weeks of agency time now runs in minutes. Keven's framing of the investment is the cleanest version of the ROI math anyone in the program has put on record. > I would say I'm getting it back twofold or threefold or fivefold. I don't even look at what the cost is of this because I am getting so much in return. The bigger shift is identity. He is bringing **35 years of business experience** to the build, layering it on top of the technical methodology, and producing agents that actually have judgement behind the prompts. Most operators are doing one or the other. He is doing both, which is precisely the gap most agencies are missing. ### Identity reframe "People learn how to do prompts, but they haven't learned how to do it correctly. I'm lucky to have had 30 years of business experience which I can inject into these agents. Now I'm learning the fundamentals from you on how to build them right." > If you're going to want to be in the workforce in the future for any sustainable amount of period of time, you need to learn how to build agents. ## Why this works Keven praised three things specifically: the patience to teach fundamentals before tactics, the iterative approach that ships v1 before adding bells and whistles, and the working agents being shared into the program as gifts. The last one matters more than it sounds. He learns by reverse-engineering working systems and breaking them. The mentorship gives him the working systems to break. > I would say I'm getting it back twofold or threefold or fivefold. I don't even look at what the cost is of this because I am getting so much in return. --- # Case study: Tim King Source: https://theaiarchitects.com/case-studies/tim Founder, AI Agency — Marketing / Paid Media **Outcome:** Launched solo AI agency, 7 demos and first client in 30 days Tim spent years on the agency side running paid media, including a stint as COO of a Facebook and Google Ads agency. Three months into the mentorship he killed his old business, launched a solo AI agency from a standing start on September 1st, ran 7-8 demos and closed his first client by the end of the month, with two more verbally agreed and four more demos already booked. **Key metrics:** - Demos run in 30 days: 7-8 - Clients signed / verbally agreed: 1 closed, 2 verbal, 4 booked - Time saved for ecom client: 80-90% on content management ## What they built ## The before Tim spent the last few years on the agency side, running paid media and performance marketing. Most recently he was COO of a Facebook and Google Ads agency, with a separate role as COO of an HVAC company. He had operator instincts in his bones. He could see AI eating into his world, and he could not find anyone teaching it the way he needed to learn it. Six months of his year disappeared into the noise. "There's like obviously a million and one YouTube videos, there's a million and one people talking about n8n and here's 2000 workflows that you can download and all of this stuff." Plenty of demo videos. Very little business logic underneath. Plenty of automations for automation's sake. ### The agency hunt He had built things in Zapier for years and assumed n8n was just a clone. He'd used Zapier across agency work, media-buying, and across the HVAC business he runs as COO. When he finally opened n8n about two weeks before joining the mentorship, he realised in 24 hours it was a different category of tool. The problem wasn't the platform anymore. It was the fact that nobody around him was teaching it from the perspective of someone who had actually run a business. He had been burned by the mentor space before. He paid for his first mentor in 2015 selling t-shirts on Teespring. "There's been a couple of ones since then that haven't been" good. What pulled him in this time was the consistency between what was getting posted and what an operator would actually need to know. ## What we built The first build was a Lead Recovery offer for AI agency clients, run through Go High Level on the front end with n8n handling the workflow logic underneath. It is a system that pulls dormant leads back into a sales conversation automatically. He scoped it specifically to be the kind of build that opens a relationship, not the kind that takes six months to deliver. The bigger unlock was the offer architecture, not the tech. Tim already had the operator instinct from running agencies. What he needed was the mental model for translating an automation into a benefit a client would pay for, not a technical feature. That meant pricing, scoping, demo structure and the specific conversational nuggets that close the deal. We worked through them on a call a couple of days after he made the call to wind down his media-buying business. ### Lead Recovery as a product "There are a few nuggets of information there that I wouldn't have been aware of myself on day one. I'd probably have found them out like two, three weeks into working with the client." That compounds. Two or three weeks is the difference between a paying client and a refund email. From there, the upsell ladder opened up. One of his existing clients is an eight-figure ecommerce brand where one of the co-founders spends most of her week reviewing creator content. She runs 15-20 whitelisted creators and 2-3 creative agencies, and she spends days every week receiving, reviewing, organising and passing content to the media buying team via Loom. The next build is automated content review and routing, projected to save her 80 to 90 percent of that time. ## The shift From a standing start on September 1st to **seven or eight demos, one signed client, two more verbally agreed** with contracts in the inbox, and another four demos booked for the same week. All built around the Lead Recovery offer. > I would say just join. It's as simple as that. There's other people offering less for ten times the money who don't have the understanding and the background that you've got. The deeper shift is that Tim stopped treating AI as a topic and started treating it as a delivery layer for the operational expertise he already had. He can now look at clients verging on nine figures, see them running 200-plus creatives a week manually, and price the saving in months not minutes. Not pitching AI. Pitching XYZ time saved or XYZ dollars per month. > It's actually coming from your knowledge of what works in the real world and what has worked for your clients, for your agency partners and all of this. ## Why this works Tim is the kind of student who already had the business judgement. He needed someone further ahead of him on the technical curve who had also actually run an agency. The mentorship wasn't teaching him how to run a business. It was closing the gap between his operator brain and the n8n canvas, and giving him the offer architecture that turned automations into pricing he could defend on a sales call. > I would say just join. It's as simple as that. There's other people offering less for ten times the money who don't have the understanding and the background that you've got. --- # Case study: Andrew Bybee Source: https://theaiarchitects.com/case-studies/andrew-bybee Hospitality **Outcome:** Built his first software in 2 weeks with zero coding experience Andrew worked at an all-you-can-eat Korean BBQ restaurant and had never written a line of code. One month into the Claude Code Challenge he built FixMyShift, a tool that catches payroll mistakes before they cost the restaurant money by pulling its Homebase and Clover data into one clean daily view. **Key metrics:** - Idea to working MVP: 2 weeks - Prior coding experience: Zero - Payroll visibility, down from once every two weeks: Daily - Real shifts FixMyShift was built and tested on: 500+ ## What they built ## The problem Andrew's restaurant runs on Clover, the POS system that captures every sale. On top of it they used Homebase, a Clover add-on, to clock staff in and out and tally hours for each pay period. One problem. Homebase showed everything in 7-day windows, but the restaurant pays every two weeks. So at the end of every pay period his boss was stuck converting values by hand and cleaning up the numbers before sending them to the CPA. It was slow, it was manual, and the mistakes only surfaced right at the deadline. ## What Andrew built Tom's brief in the challenge was simple. Take something repetitive you deal with every day and make it better. Andrew picked payroll. He built FixMyShift, a tool that catches payroll mistakes before they cost you. It connects to the Homebase API, auto-fills the sales figures from Clover, and lays everything out on one clean interface he designed himself. Instead of waiting two weeks to find out something is off, the team now sees it daily. FixMyShift breaks the period into day, pay-period and range views, so the bi-weekly mismatch that started this whole thing is gone. It shows labor cost as a percentage of sales against a healthy 25-30% target, then flags the things that quietly inflate payroll. Missed clock-outs. Open shifts that were never closed in Homebase. New hires missing a role so they group correctly. Staff are split into front of house and back of house, and once it looks clean Andrew exports to Excel or PDF, or syncs straight to Google Sheets. He didn't stop at the dashboard. He built a full landing page for it too, the kind of thing you would expect from a real product, not a first build. The first working version took about two weeks. Everything after that was him refining the interface because he wanted it to feel good to use, not just work. ## Where he is now Before the challenge Andrew was using ChatGPT and Claude Desktop for basic questions. He'd never thought about opening a terminal and building something real. He found Tom on YouTube, watched enough to trust the process, and joined with no real hesitation. Things clicked halfway through the first module. The shift he describes is the one that matters most. He stopped asking where do I even start and started asking what should I build next. He's now weighing whether to sell FixMyShift to other businesses or build his next tool, a dashboard that ties together the legacy systems at the gym he just moved to. > Take the leap. Ground yourself in a strong foundation and find a community of people who are just as interested. Then you feel ready for whatever AI brings next. > I literally had no experience. I still don't write code, but I understand it so much more, and I know how to operate Claude Code. --- # Case study: Doug Loud Source: https://theaiarchitects.com/case-studies/doug-loud Attorney, Fraud Investigations — Fraud Investigations & Finance **Outcome:** Built a one-click web dashboard that hides Claude, n8n and Qdrant from non-technical users Doug is an attorney who runs fraud investigations and security analysis work. His users are people for whom copy and paste is a major issue. He built a simple web interface that routes their button clicks through Claude skills, n8n workflows and a Qdrant RAG, so they never have to see a node graph or type a slash command. **Key metrics:** - End-user experience: One button, no Claude, no n8n - Backend orchestration: Claude skills + n8n + Qdrant RAG - Time previously lost solo: 14-15 hour debug sessions, gone ## What they built ## The before Doug is an attorney by training, working in fraud investigations, security analysis and finance. He has been around long enough to remember Fortran and punch cards, has written HTML by hand before CSS existed, and still has a senior developer friend from AWS and Microsoft on speed dial. So he is not afraid of the tooling. The problem was the same one every operator runs into eventually. Half of his users cannot reliably copy and paste. Find and replace is a major event. A regular database exposes too much information at once for the kind of sensitive fraud work he handles, so he needed controlled, button-driven access for people who were never going to learn the underlying system. ### The YouTube halfway problem Before joining, Doug had done what every self-taught operator does. A vast pile of YouTube videos and articles. Each one got him about halfway to where he needed to be. Then the tutorial would end, the use case would not match, and he would be stuck. He had also lost the kind of weekend you do not want to lose to LLM hallucinations, including the famous incident a year ago where Claude wrote him beautiful documentation for a command that did not exist. His rule, from a long career in serious work: you can read all the books you want, but you cannot fly a plane or ride a horse from a manual. At some point you need someone next to you who has been there before and knows the one keystroke the book has not gotten to yet. ## What we built The build is a clean white web page called the ISI Web Assistant. From the user's side, it is a list of buttons. Behind the buttons is a routing layer Doug built with Claude Code, n8n workflows and a Qdrant vector database, all wired together so the user never has to know any of it is there. ### The button layer Claude Code wrote the front end through the interview workflow Doug picked up in the course. Each button maps to a specific job. One says hello world by running a Claude skill. Another says hello from n8n by triggering an n8n workflow. A third pulls today's appointments out of Google Calendar. The most useful one is the financial information button. It is built for stock traders who need to see the cost basis of their positions after writing options against them, with the rest of the table locked down. Two buttons run from Claude into n8n, pull the right slice of the portfolio, and display only what the user is allowed to see. ### The RAG layer Doug also wired the Andrej Karpathy wiki into the dashboard as a question-answer interface. Ask a question, the workflow reads the wiki, the answer comes back inside the same simple page. He has the same content sitting in Qdrant for the heavier lifting. His framing on which to use: sometimes you need a Ford F-150 to take three bales of hay to the barn, and sometimes you need a sand truck for all of New York City. Qdrant is the sand truck. ### The orchestration Underneath the page is a router workflow that decides which downstream workflow handles each request. Calendar questions go one way. Financial queries go another. Business card scans get parsed and loaded into Coda, where they feed a corporate information system tracking every company the firm deals with. The user never sees any of it. They click. Something appears. ## The shift Doug is doing things now he could not even conceive of on day one of the course. The same web page he was sketching on a napkin in week one is live, cranking away, and serving users who were never going to learn n8n if their day depended on it. > Because of this course and the Claude course together, I'm able to do things I couldn't even conceive of before the beginning of the course. The deeper shift is the second person in the room. Doug is the kind of operator who can lose fourteen or fifteen hours to a problem before he gives up. That stubbornness is a strength when there is someone he can finally call. The course turned those fourteen-hour solo sessions into one good question on a group call, where someone else had already hit the same wall the week before. > Run, do not walk to sign up for the course. You may not know it yet, but you need it. > You can read about it and learn about it, but you can't fly a plane, you can't ride a horse without somebody teaching you. It is not the same thing as reading about it. --- # Case study: Chris Hawes Source: https://theaiarchitects.com/case-studies/chris-hawes Content Marketer / Former Journalist — Brand Content & Storytelling **Outcome:** Built and pitched a RAG storytelling product, signed first client Chris is a former journalist and brand storyteller with no technical background. Inside two months he conceived, built and pitched a RAG-based product that turns a brand's content archive into an interactive audience experience, signed his first client off the back of the demos, and reframed himself from writer worried about being replaced to consultant brands actually call. **Key metrics:** - Clients won: First client signed after demos - Use case: Repurpose dormant brand archive as RAG ## What they built ## The before Chris spent his career as a writer. A few years as a journalist, then a move into content marketing, helping brands tell stories across articles, videos and animations. He had worked with some big names. He had never written a line of code. AI was the obvious next layer for his work, but he was not interested in using it to manufacture content. He wanted to use it on the **process side**: find insights, shape stories, and surface the right material for a writer to put their tone on. The problem was the on-ramp. ### The writer's leverage problem "I've done other courses where you jump in and you're immediately out of your depth because the language people are using doesn't compute." The vocabulary around APIs, payloads and webhooks meant nothing to someone whose tools were Google Docs and a notebook. He needed someone who could explain it from a marketing brain, not a coder's brain. There was also a quiet professional anxiety. Writers and marketers are always the first ones told they're going to be automated away. He went into the course half-expecting to learn the thing that was going to replace him. ## What we built A few weeks in, Chris landed on a use case that fit his world perfectly. Most brands he had worked with were sitting on archives of dormant content. Articles, podcasts, videos that delivered their value once and then went quiet. He wanted to wake that content up. He built RAG agents that ingest a brand's archive and turn it into an **interactive audience experience**. The user gets to converse with the brand's accumulated thinking. On the back end, Chris layered an insights workflow that pulls themes and questions out of those interactions, so the brand learns what its audience actually cares about. The content becomes both a product and a research surface in the same workflow. ### RAG meets storytelling He pitched the system to potential clients, got his foot in the door, and started his first build. The pitch wasn't "I built a chatbot." The pitch was "your archive is undermonetised, here's how to turn it into a customer-research engine." "AI can kind of give your brand more. It can turn unused content, unused data into really valuable workflows and equity." That framing is the bridge between writer and consultant. ## The shift Chris went from a non-technical writer worried about being replaced to a consultant who can walk a brand leader through what AI can and cannot do for their business. He can take a company's data, see what's underused, and design a workflow that turns it into an asset. > Your course is everything that you say it was. People will come away with a foundational understanding of AI and n8n, but also how they can apply it in their own careers. The shift he didn't expect was the breadth. He came in to learn n8n. What he got was a moving target of platforms, models and capabilities, with someone sitting on top of the changes and translating them into the workflow. "That's not like, you know, if I was to go on a writing course or a public speaking course, the information you get always remains quite static, whereas with AI, you know, we're kind of on the forefront of what can be done." ### From writer to consultant The deeper reframe is about his own value. Writers were supposed to be the first against the wall when AI arrived. He looked at it the other way. "By learning the technical side of AI, you realize that those skills actually, if you combine them with AI, you're not going to be automated, but you're one of the ones that's going to kind of lead the change." > It's another pen, it's another way to create more engaging stories, and it's a much more powerful one. ## Why this works Chris said it directly. The difference between a YouTube playlist and the mentorship was the unblock loop. He could send a workflow template or a video of where he was stuck, get a specific answer back, and stop trying to debug his way through a tutorial that was already six months out of date. For a non-technical writer, that responsiveness was the difference between giving up and shipping. > Your course is everything that you say it was. People will come away with a foundational understanding of AI and n8n, but also how they can apply it in their own careers. --- # Case study: Lisa Avvocato Source: https://theaiarchitects.com/case-studies/lisa Fractional CMO & Go-to-Market Advisor — SaaS Marketing **Outcome:** Shipped ad, blog and SEO workflows from a non-technical start Lisa is a fractional CMO advising pre-seed to Series B SaaS companies. She spent a month trying to learn n8n on her own before joining. Inside the mentorship she shipped an ad generator, a blog content workflow and an SEO strategy system, with a PR pitch tool next on the list. **Key metrics:** - Workflows shipped: Ad generator, blog generator, SEO strategy - Time stuck before joining: ~1 month solo - Next build: PR pitch tool for client outreach ## What they built ## The before Lisa works as a fractional CMO and go-to-market advisor for early-stage SaaS companies, mostly pre-seed to Series B. Many of her clients are AI-native, so the topic was already in her daily orbit. The question was whether she could build with the tools, not just talk about them. She tried for about a month on her own. The simple use cases, "like, you know, having an email manager or an autoresponder for a form", were not going to move the needle for the brands she advises. She wanted ad generators, blog systems, real workflows. So she went straight at the complex stuff and got stuck. ### A week and a half on webhooks One of the worst rabbit holes was a **week and a half** spent trying to wire an Airtable form to n8n via webhooks, because that is what the tutorials told her to do. She isn't a coder. The whole detour disappeared the moment someone pointed her at the Airtable trigger node. "I was like, well, yeah, that would probably be a lot easier now, wouldn't it?" That is the cost of trying to learn rapidly-evolving software in public. The tutorial was already six months old. The tooling had moved. She was paying the gap with her time. ## What we built Lisa's first shipped build was an ad generator for a B2C client. The workflow side is solid. She is holding back from rolling it into live brand work because the image models still produce one or two tells that her trained eye picks up. That is a quality bar choice, not a build problem. She has worked too long in AI not to spot a hallucination. Alongside the ad generator she built a blog content generator and an SEO strategy workflow. The SEO one ran into scraping reliability issues, which is now a recurring conversation. The build philosophy across all three is the same: sweat the prompts, let the technical layer get easier as the tooling commoditises. ### Ad, blog and SEO workflows "You can have the technical setup. If your prompt sucks, you're going to get the AI slop that everybody talks about. I think that's a lot of where the value is going to be is somebody that really knows how to write and structure prompts." Next on the list is a PR pitch tool that generates personalised outreach to journalists and podcast hosts for the brands she represents. She has just been given access to the n8n AI builder and is rebuilding the same tool inside it as a comparison. ## The shift Lisa's bet is on prompt engineering as the differentiator, not the technical wiring. As the n8n AI builder and similar tools push the build layer towards drag-and-describe, the operators who can write the prompt structure that makes the agent actually useful are the ones who win. > You're going to learn a lot faster, and you're going to get more confident in your skills. The faster you can learn, the more relevant your skills are going to be. The shift for her isn't time saved on a single workflow. It is the speed at which she can now learn a new pattern, ship something testable, and stay current in a field where everything she learned six months ago risks going stale. "I'd be concerned if I was trying to learn on my own, that everything I'm learning is becoming outdated." ## Why this works Lisa got the most value out of the on-demand modules and the looms-back-and-forth feedback loop. As a parent of two with no patience for stuck-on-webhooks weekends, the format had to fit her schedule. "You'd sit and help troubleshoot with us, even if it was just online sending looms back and forth. It wasn't necessarily you had to be on a call." That flexibility, paired with someone slightly further ahead on the curve, was the thing that broke her solo plateau. > I'd be concerned if I was trying to learn on my own, that everything I'm learning is becoming outdated. > You're going to learn a lot faster, and you're going to get more confident in your skills. The faster you can learn, the more relevant your skills are going to be. --- # Case study: Steven Source: https://theaiarchitects.com/case-studies/steven Automation Builder — Lead Generation / Agency Services **Outcome:** Shipped first paid lead-gen build in 3 weeks from zero Steven came in from crypto video editing with zero automation experience. Three weeks after joining, he shipped a personalised cold email lead generation system for a TikTok agency, then walked into another company's office and mapped the 10-20% of their manual sales process he could automate before he had even started. **Key metrics:** - First client shipped: 3 weeks from start - New use case spotted: Automate 10-20% of a manual sales process ## What they built ## The before Steven was editing videos for crypto projects, doing graphic design on the side, and watching the floor fall out from under that whole industry. He could see AI was the next skill worth owning, so he went hunting for a way in. What he found instead was the n8n template firehose. Three or four days of downloading **30, 40, 50-node JSON files** from people who never explained how any of it actually worked. The templates looked impressive. None of them translated into real-world skill, because he never knew what data was passing through which node, or why. ### Drowning in templates He hit the end of the third day and realised he was spinning. "I just want to learn how to do maybe things that involve five nodes." He didn't need more JSON. He needed someone to show him how to build five-node workflows properly before touching anything fancy. He had not planned to invest right away. Normally he'd spend weeks researching a mentor before parting with money. He skipped that and joined as one of the first cohort, partly off the strength of the marketing results visible publicly, partly because the noise from other places had already proven that more research wouldn't help. ## What we built Steven came into the mentorship with no prior building experience. The first thing he had to unlearn was the urge to chase complex templates. The framework we worked through forces you to sit down with pen and paper, sketch the actual problem, and then build the simplest version that solves it. "It's probably best I sit down with a pen and paper and actually try and understand myself first rather than go to AI or try and not build that part of my mind." Once that mental model was in place, the n8n canvas stopped being intimidating. ### Pen and paper first Three weeks in, he met a TikTok agency in person and pitched himself for a workflow build. He took the job and threw himself in the deep end. The brief was a personalised cold email lead generation system. Boring on the surface, high friction underneath, exactly the kind of build that pays. Three weeks of focused work to ship it. The breakthroughs came in two waves. First, error handling and fallbacks, because once an agent runs in production it will break, and an unhandled error takes the whole workflow down. Second, wrapping the n8n back end in a clean front-end interface so the client wasn't poking around inside an ugly node graph. The front-end was the perceived-value lever. The error handling was the survival lever. ## The shift Three weeks from start to a shipped client build, with no prior automation experience. From there, Steven started seeing automation use cases everywhere. A separate company approached him for unrelated work, and within one in-person conversation he had already mapped out which **10 to 20 percent** of their manual sales process he could automate. > The simple builds actually for the most part generate a lot of the output in terms of solving problems. You can have all these flashy n8n templates, but if you don't understand how it works it doesn't matter. That is the identity shift. He stopped collecting templates and started thinking like a systems builder. Friends and family businesses, drowning in manual work. Companies running entirely off spreadsheets and email. Everywhere he looked, leverage. His brain literally started rejecting manual work as a default. > I'm just seeing tons of opportunities and I'm seeing tons of people that need this skill, but there's just not enough people out there to serve client demand. ## Why this works Steven kept coming back to one thing: the direct feedback loop. He could send a Loom of a broken workflow and get a specific nudge back. As a beginner, he often did not know how to even articulate the problem. The patience to sit through that, and the framework of building simple before complex, were what got him from JSON-hoarding to shipped client work in three weeks. > The simple builds actually for the most part generate a lot of the output in terms of solving problems. You can have all these flashy n8n templates, but if you don't understand how it works it doesn't matter.