• Claude Code runs in JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, Android Studio and more) through the official Claude Code plugin from the JetBrains Marketplace.
• Install two things: the Claude Code CLI first, then the plugin, then restart the IDE. The plugin does not include its own copy of Claude Code. It runs claude in the IDE's terminal and connects to it. Any paid Claude plan or a Claude Console account works, no API key needed.
• Cmd+Esc (Mac) or Ctrl+Esc opens Claude Code from the editor. Edits show in the IDE's diff viewer, your selection is shared automatically, and Claude can read the IDE's lint and syntax errors. If you do not already work in a JetBrains IDE, start with the desktop app instead.

How Claude Code works in JetBrains IDEs

Claude Code connects to JetBrains IDEs through an official plugin published on the JetBrains Marketplace. The official docs list IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm and GoLand, and say it works with most JetBrains IDEs. Once it is connected, Claude shows its proposed edits in the IDE's own diff viewer, sees the file or code you have selected, and can read the inspection warnings your IDE already shows, like lint and syntax errors.

The big difference from the [Claude Code VS Code extension](/blog/claude-code-vscode-extension) is how it is built. The VS Code extension gives you a chat panel with Claude Code bundled inside. The JetBrains plugin does not bundle anything. It runs the regular claude command in the IDE's integrated terminal and wires it into the editor. So you are using the same terminal Claude Code, with the IDE doing the parts it is good at: diffs, navigation and inspections.

NOTE: If you are not a JetBrains user already, do not switch editors for this. The [Claude Code desktop app](/blog/claude-code-desktop-app) is still where I tell most people in the club to start. This guide is for people who already have IntelliJ, PyCharm or WebStorm open all day.

How to install the Claude Code JetBrains plugin

1. Install the Claude Code CLI first. The plugin needs the claude command on your PATH, and without it you get a "Cannot launch Claude Code" notification. Check it worked by running claude --version in any terminal.
2. Install the plugin. In your IDE open Settings, then Plugins, then Marketplace, search for "Claude Code" and install the one published by Anthropic. Restart the IDE.
3. Open your project from its root folder, so Claude sees the same files your IDE does.
4. Open the IDE's integrated terminal and run claude. The first time, you are asked to log in. Any paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account works, and you do not need an API key.
5. Press Cmd+Esc (Mac) or Ctrl+Esc (Windows/Linux) from the editor, or click the Claude Code button, to jump straight to Claude from now on.

Not sure which plan to sign in with? [Which Claude plan for Claude Code](/blog/which-claude-plan-for-claude-code) walks through it. On Windows, read [Claude Code on Windows](/blog/claude-code-on-windows) before you install the CLI.

TIP: Already run Claude Code in a separate terminal app? You can keep doing that. Start claude from your project root, type /ide, and it connects to the running JetBrains IDE. If the IDE does not have the plugin yet, /ide offers to install it and asks you to restart.

What you get once it is connected

• Diffs in the IDE: proposed changes open in the JetBrains diff viewer instead of scrolling past in the terminal. You can switch this with the Diff tool setting in /config: auto shows diffs in the IDE, terminal keeps them in the terminal. That setting only appears while Claude Code is connected to the IDE.
• Selection context: the code you highlight, or the tab you have open, is shared with Claude automatically. Files blocked by a Read deny rule in your permissions are not shared.
• File references: Cmd+Option+K (Mac) or Alt+Ctrl+K (Windows/Linux) drops a precise reference like @src/auth.ts#L1-99 into your prompt.
• IDE diagnostics: Claude can read the lint and syntax errors your IDE's inspections already found. It asks for them when it needs them, not automatically after every edit, so if you want a check, tell it to look at the IDE's errors before it finishes.

The diagnostics part is the one I like most. JetBrains IDEs are strong at inspections, and letting Claude read those warnings directly beats copying error text into the chat. A prompt like "fix the change, then check the IDE errors for this file and clean up anything you introduced" puts that to work.

Fixes for the common snags

On a Mac there is also an optional setting to use Option+Enter for new lines in your prompt. If the Option key starts behaving oddly in the terminal, that setting is the first thing to turn off.

One security setting to change

The official docs flag a specific risk for JetBrains users. In acceptEdits mode, and in auto mode, Claude can edit files in your project without asking, and that can include IDE configuration files your IDE runs automatically. In plain terms, an edit to one of those files could run commands without the usual permission prompt.

My recommendation: in a JetBrains IDE, use Manual mode for edits, so you approve each change in the diff viewer. You already have a good diff viewer open, so the cost is small. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers the modes, and [Claude Code settings.json](/blog/claude-code-settings-json) shows where to set them.

JetBrains plugin, VS Code extension or desktop app

My take: the JetBrains plugin is the most "terminal" of the editor options, because it really is the terminal Claude Code with the IDE plugged in. That suits people who already know their IDE well and want Claude to fit their workflow, not replace it. If that is not you, the desktop app is less to learn and does the same work. All of them share the same settings file, so moving between them later is easy.

TIP: Whatever you pick, the first hour matters more than the tool. [Claude Code day one setup](/blog/claude-code-day-one-setup) covers the CLAUDE.md file, permissions and the habits that keep sessions clean.

NOTE: Inside Claude Code Club, members share the setups they actually use day to day, in JetBrains IDEs, VS Code, the desktop app and the terminal. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through the desktop app step by step.

FAQ

Is there an official Claude Code plugin for JetBrains?

Yes. Anthropic publishes the Claude Code plugin on the JetBrains Marketplace. It works with most JetBrains IDEs, including IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm and GoLand.

Do I need to install Claude Code separately for the JetBrains plugin?

Yes. The JetBrains plugin does not bundle Claude Code. Install the Claude Code CLI first so the claude command is on your PATH, then install the plugin and restart the IDE.

Do I need an API key to use Claude Code in IntelliJ or PyCharm?

No. Any paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account works. You log in the first time you run claude.

How do I connect Claude Code to a JetBrains IDE from an outside terminal?

Start claude from your project root and run /ide. It connects to the running IDE, and if the plugin is missing it offers to install it and asks you to restart the IDE.

Why won't the Esc key stop Claude Code in the JetBrains terminal?

The IDE's terminal uses Esc to jump back to the editor. In Settings, Tools, Terminal, untick "Move focus to the editor with Escape" or remove the "Switch focus to Editor" shortcut.

• Price a custom booking system on what it fixes for the business: the hours spent booking by phone, text and email, the slots that sit empty, and the no-shows that cost money. Not on the number of screens or your hours.
• Use the CCC Booking Quote: a base build priced on that value, plus a line for payments and deposits, a line for scheduling rules (staff, rooms, locations, buffers), a line for each connection like calendars and reminders, and a monthly Keep plan.
• Ask first whether an off-the-shelf booking tool already fits. If it does, say so. A custom build earns its price when the business has rules those tools cannot handle, and those rules are what you are really pricing.

How much to charge for a booking system

How much to charge for a booking system comes down to one question: what does an empty or missed appointment cost this business, and how much time goes into filling the calendar today? A salon, a clinic, a studio or a rental business does not want a calendar. It wants fewer gaps, fewer no-shows, and nobody stuck on the phone moving bookings around. Price the build on a share of that value, add lines for payments, scheduling rules and each system it connects to, and quote a monthly plan for upkeep. Do not price it on the number of pages or on hours.

Booking systems are good work to sell with Claude Code because a working first version comes together fast. You can show a client their own services, staff and time slots early. The trap is that a booking page looks done the moment someone can pick a time. The hard part is everything behind it: double bookings, time zones, cancellations, refunds, and the owner's rule that one service needs a specific room. That is where the unpaid work hides if you priced the screen.

NOTE: This post is part of the pricing series. If you have not built one yet, [how to build a booking system with Claude Code](/blog/build-a-booking-system-with-claude-code) walks through the build so you know what you are quoting.

Should they buy a booking tool instead?

Ask this before you quote anything. Plenty of businesses are well served by an off-the-shelf scheduling tool, and if one fits, telling the client so builds more trust than any proposal. I would rather lose that build and keep the client for the next one.

A custom booking system earns its price when the business has rules those tools handle badly. Bookings that need a specific person and a specific room at the same time. Prices that change by day, season or customer type. Packages and memberships that use up sessions. Deposits that depend on the service. A booking flow that has to sit inside their existing site, app or customer records. When you hear those, you are not pricing a calendar. You are pricing their rules, and that is where the value sits.

The CCC Booking Quote

Base build. Work out what booking costs the client today: the hours someone spends answering calls and messages to book and move appointments, and what an empty slot or a no-show is worth to them. Price the build at a fraction of one year of that value, so they can see it pay for itself.

Payments and deposits. Taking money is its own line, because it brings refunds, partial refunds, failed payments and cancellation rules with it. Deposits are often the feature that cuts no-shows, so this line is easy to justify. Any payment key lives on the server, never in the page, and the client's payment account is in their name, not yours.

Scheduling rules. This is the line builders forget and clients never mention until launch. Ask what has to be free for a booking to work: a person, a room, a piece of equipment. Ask about buffers between appointments, different hours per location, and time zones if customers book from elsewhere. Every rule is a place for a double booking, so price them on what you find.

Connections. Each outside system is its own line: staff calendars, email or text reminders, their CRM or customer list. Each one has its own access and its own way of changing. If the bookings need to land in customer records, [how to build a CRM with Claude Code](/blog/build-a-crm-with-claude-code) shows what that side involves.

TIP: When a client says the number is too high, do not cut the price. Start with one location, take payment at the visit instead of online, or launch reminders by email first, and show which line moved. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Ask these before you quote

• Walk me through one booking from first message to the appointment. Every step they describe is a step the system has to handle.
• What happens when someone cancels or moves a booking? Late-cancel rules and refunds change the payments line.
• Who can book what? Customers booking themselves, staff booking for customers, and admins overriding the rules are three different jobs.
• Where does it live? On their current website, in an app, or as a standalone page. Settle it before you quote.
• Who owns the accounts? Payment, email and hosting should be in the client's name, so the system keeps working if you part ways. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers the checklist.

More questions that save a bad quote are in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

Always quote the Keep plan

A booking system is live revenue. When it breaks, the business finds out from an angry customer at the front desk, or from a quiet weekend that should have been full. Reminder services change, calendar connections expire, payment settings get updated, and the owner adds a new service with a new rule.

Quote a monthly plan in the original proposal. Say what it covers: checking bookings and payments go through, fixing breaks when a connected service changes, keeping access current, and small changes like new services or new hours. Say what it does not cover: new locations, new payment types and new features, which are quoted separately. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure. Few clients argue with paying to keep the thing that fills their calendar working.

How to present the booking system quote

• Lead with the outcome in their words. One line on fewer phone calls and fewer empty slots, then the price.
• Itemize it. Base build, payments and deposits, scheduling rules, each connection, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate payments on proof. A deposit to start, a payment when real test bookings and payments go through end to end, and the final payment once customers are booking live. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Write the rules into the proposal. A short list of the scheduling, cancellation and refund rules, signed off by the client, ends the "it should have known that" argument before it starts.

And skip hourly. Claude Code makes the build fast, so hourly pricing turns that speed into a pay cut. I covered why in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). If the client's team mostly needs to manage work inside the tool rather than take bookings, [how much to charge for an internal tool](/blog/how-much-to-charge-for-an-internal-tool) is the better guide.

NOTE: Inside Claude Code Club, members share the booking and scheduling quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for a custom booking system?

Price it on what it fixes: the admin hours spent booking by hand, the empty slots and the no-shows. Charge a fraction of one year of that value for the build, add lines for payments, scheduling rules and each connection, and quote a monthly plan for upkeep.

Should I build a custom booking system or recommend an existing tool?

If an off-the-shelf booking tool fits the business, recommend it. A custom build is worth it when the business has rules those tools handle badly, like bookings that need a person and a room at once, packages, or pricing that changes by day or customer.

Should I charge a monthly fee for a booking system?

Yes. Bookings are live revenue, and reminders, calendar connections and payment settings change over time. A monthly plan covers checking bookings and payments go through, fixing breaks and small changes like new services or hours.

Should payments and deposits be priced separately?

Yes. Taking money brings refunds, failed payments and cancellation rules with it. Put it on its own line so the client can see what it costs and choose to start without it if needed.

Should I charge hourly for a booking system?

No. Claude Code makes the build fast, so hourly pricing punishes you for that speed. Price on the value of the bookings and admin time it fixes, with each part itemized.

• The Claude Code VS Code extension is the official way to use Claude Code inside VS Code. Search "Claude Code" in the Extensions view, install it, sign in with any paid Claude plan or a Claude Console account, and open it from the Spark icon. No API key is needed.
• Claude sees the file you have open and the code you select. Option+K (Mac) or Alt+K (Windows/Linux) drops an exact file-and-line reference into your prompt, and Cmd+Esc or Ctrl+Esc jumps between the editor and Claude.
• Use it if you already live in VS Code. If you do not, the desktop app is the simpler home. Some features stay CLI-only, like the ! Bash shortcut and the full command list, so install the standalone CLI too if you want claude in the integrated terminal.

What the Claude Code VS Code extension is

The Claude Code VS Code extension is Anthropic's own graphical panel for Claude Code, built into VS Code. Instead of chatting in a separate window, you talk to Claude in a panel next to your code. It reads the file you have open, sees the lines you highlight, and shows every edit it wants to make as a side-by-side diff you can accept or reject. It is the same Claude Code underneath: the extension bundles its own copy of the CLI, and it shares your settings, MCP servers, plugins and conversation history with the rest of Claude Code.

My default advice to most people in the club is still to start in the [Claude Code desktop app](/blog/claude-code-desktop-app). But a lot of people already have VS Code open all day, and for them the extension is the better fit, because the code and the conversation sit in one window.

NOTE: The extension also installs in VS Code forks such as Cursor. If you are deciding between editors rather than adding Claude to the one you have, read [Claude Code vs Cursor](/blog/claude-code-vs-cursor) first.

How to install and sign in

1. Check your VS Code version. The official docs list VS Code 1.94.0 or later as the minimum.
2. Open the Extensions view with Cmd+Shift+X (Mac) or Ctrl+Shift+X (Windows/Linux), search for "Claude Code", and click Install. Make sure the publisher is Anthropic.
3. Open the panel. Click the Spark icon in the top-right of the editor (it only shows when a file is open), the Spark icon in the left Activity Bar, or "Claude Code" in the bottom-right status bar.
4. Sign in. Click Sign in and finish in your browser. Any paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account works, and you do not need an API key.
5. Open a project folder, not a single file, so Claude can see the whole codebase. Then run "Claude Code: Open Walkthrough" from the Command Palette if you want the built-in tour.

If the extension does not appear after installing, restart VS Code or run "Developer: Reload Window" from the Command Palette. Not sure which plan to sign in with? [Which Claude plan for Claude Code](/blog/which-claude-plan-for-claude-code) walks through the choice.

The features that make it worth using

The reason to use the extension instead of a separate window is context. You stop explaining where things are, because Claude already knows what you are looking at.

• Selection and open file: Claude sees the file you have open and any code you highlight. You can turn the open-file part off in the extension settings if you only want the selection sent.
• @-mentions: type @ and part of a file or folder name to pull it in. Fuzzy matching means @auth finds auth.js or AuthService.ts.
• @terminal: reference a terminal by its title, like @terminal:name, so Claude sees the error output without you copying it.
• Diffs you can edit: in Manual mode every proposed edit opens side by side. You can accept or reject it, accept or reject one change at a time, or edit the proposal before accepting, and Claude is told you changed it.
• Plan mode: Claude writes the plan as a full document you can comment on before it touches a file. Type /plan to switch into it. More on why that matters in [Claude Code plan mode](/blog/claude-code-plan-mode).
• Checkpoints: hover over any message to rewind the code, fork the conversation, or both. [Checkpoints and rewind](/blog/claude-code-checkpoints-and-rewind) covers how far you can trust them.
• Several conversations: open extra tabs or windows for side tasks while your main session runs in the sidebar.

Shortcuts worth learning

If you learn one, make it the selection shortcut. Highlighting the broken function and pressing Option+K gives Claude an exact reference like @app.ts#5-10, which beats describing the code in words every time.

What the extension cannot do

The extension covers most of what you need, but the official docs are clear that some features are CLI-only. Knowing them saves you a confused half hour.

• Commands and skills: the extension shows a subset. Type / to see which ones are available.
• The ! Bash shortcut and tab completion are CLI-only.
• Installing the extension does not put claude on your PATH. To run claude in VS Code's integrated terminal, install the standalone CLI as well. After that, terminal sessions connect to VS Code for diffs and diagnostics.
• The extension and the CLI share history, so you can start in the panel and pick the same conversation up in a terminal with claude --resume.

The settings file at ~/.claude/settings.json is shared between the extension and the CLI, so your allowed commands, hooks and MCP servers carry over. [Claude Code settings.json](/blog/claude-code-settings-json) explains what goes in it, and you can manage MCP servers from inside the panel with /mcp.

VS Code extension or desktop app: which I would use

My take: the extension shines when you are reading the code with Claude, not just asking for it. If you open the files, check the diffs and nudge the work as it goes, the extension is the best seat in the house. If you mostly describe the outcome and test the result, an editor full of panels is more than you need, and the desktop app keeps it simpler. Neither is a downgrade. They share the same engine, the same settings and the same history, so you can move between them on the same project.

TIP: Whichever you pick, the first hour matters more than the tool. [Claude Code day one setup](/blog/claude-code-day-one-setup) covers the CLAUDE.md file, permissions and the habits that keep sessions clean.

NOTE: Inside Claude Code Club, members share the setups they actually use day to day, in VS Code, the desktop app and the terminal, and what they changed after the first week. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through the desktop app step by step.

FAQ

Is there an official Claude Code extension for VS Code?

Yes. Anthropic publishes the Claude Code extension for VS Code. Search "Claude Code" in the Extensions view and install the one from Anthropic. It also installs in VS Code forks such as Cursor.

Do I need an API key to use Claude Code in VS Code?

No. You sign in with any paid Claude plan (Pro, Max, Team or Enterprise) or a Claude Console account. An API key is only one option, not a requirement.

Why does claude say command not found in the VS Code terminal?

The extension bundles a private copy of Claude Code for its chat panel and does not add claude to your PATH. Install the standalone CLI once and the claude command works in the integrated terminal and any other terminal.

Can I switch between the VS Code extension and the terminal mid-project?

Yes. They share conversation history and the same settings file. Run claude --resume in a terminal to pick up a conversation you started in the extension.

Should I use the VS Code extension or the Claude Code desktop app?

Use the extension if you already work in VS Code and like to review code and diffs as Claude works. Use the desktop app if you are newer to code and mostly describe outcomes. Both run the same Claude Code underneath.

• Price a custom dashboard on what it changes for the business: the hours someone spends building reports by hand today, and the better decisions that come from seeing the numbers sooner. The number of charts and your hours are the wrong yardsticks.
• Use the CCC Dashboard Quote: a base build priced on that value, plus a line for each data source, a line for cleaning the data and agreeing what each number means, and a line for access and sharing. Then a monthly Keep plan, because data sources change and someone has to notice when a number goes wrong.
• Settle the definitions before you quote. If the client cannot tell you exactly what counts as a sale, an active customer or a lead, that work is the real project, and it belongs on the quote.

How much to charge for a dashboard

How much to charge for a dashboard comes down to one question: what decisions will the client make with it, and what does getting the numbers cost them today? Nobody buys a dashboard for the charts. They buy it so the owner stops waiting until the end of the month to see which channel is losing money, so a manager stops spending Monday morning pasting exports into a spreadsheet, or so the team argues about what to do instead of whose numbers are right. Price the build on a share of that value, add lines for each data source and for the work of cleaning and defining the data, and quote a monthly plan for upkeep. Do not price it on the number of charts or on hours.

Dashboards are good work to sell with Claude Code because the first version comes together fast. Point Claude at the data, describe the views, and you can show something real early. That is also the trap. A dashboard looks finished the moment the charts render, so builders price it like a quick job, and then the client finds a number that does not match their accounting software and the real work starts, unpaid.

NOTE: This post is part of the pricing series. If the client's team needs to do work inside the tool, approving, editing or entering data, rather than just reading numbers, it is an internal tool, and [how much to charge for an internal tool](/blog/how-much-to-charge-for-an-internal-tool) is the better guide.

Why the charts are the wrong yardstick

A dashboard with three charts can be worth far more than one with thirty. If those three numbers tell an owner where to spend next month's budget, they matter. Thirty charts nobody opens matter to nobody. Charging per chart rewards you for clutter and punishes you for doing the hard thinking about what actually needs to be on the screen.

Hours are worse. Claude Code makes the build itself quick, so pricing on hours turns every bit of speed into a pay cut. I covered why in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The real costs of a dashboard sit around the charts: getting access to the data, fixing it, agreeing what each number means, and keeping it right when a source changes.

The CCC Dashboard Quote

Base build. Work out with the client what the reporting costs today: how many hours someone spends pulling exports and building the report, multiplied by what their time costs. Then ask what they would decide differently if they saw the numbers daily instead of monthly. Price the build at a fraction of one year of that value, so the client can see it pay for itself.

Data sources. Each place the data comes from is its own line: the payment system, the CRM, the ad accounts, a shared spreadsheet. Each one has its own access, its own limits and its own way of changing without warning. Ask for access before you send the final number. If a source needs a paid API, the key lives on the server, never in the page, with a spending limit, and that setup is part of the quote. [How to connect Claude Code to a database](/blog/connect-claude-code-to-a-database) shows what one connection involves.

Cleaning and definitions. This is the line builders forget and clients never expect. The same customer appears twice under different emails. Refunds are counted in one system and not the other. Two managers mean different things by "active customer". Agreeing those definitions in writing and making the data match them is often the biggest part of the job, so price it on what you find, not on a guess.

TIP: When a client says the number is too high, do not cut the price. Drop a data source, start with a weekly refresh instead of a live one, or ship the owner's view first and the team views later, and show which line moved. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Ask these before you quote

• Which three numbers would you check first every morning? If they cannot name them, the first paid step is working that out with them, not building.
• How fresh do the numbers need to be? Daily, hourly and live are different jobs with different costs. Most owners need daily.
• Who sees it? One owner is simple. A team where each person should only see their own region or clients adds an access line.
• Where does it live? A hosted page with a login, a view inside a tool they already use, or a scheduled email report. Settle it before you quote.
• Who owns the data accounts? Access should run through accounts in the client's name, so the dashboard keeps working if you part ways. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers the checklist.

More questions that save a bad quote are in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

Always quote the Keep plan

Dashboards break quietly. A software tool renames a field, an ad platform changes what it reports, the client adds a new sales channel, or a login expires. The page still loads, the charts still render, and the numbers are wrong. That is worse than a dashboard that is down, because people make decisions on it.

Quote a monthly plan in the original proposal. Say what it covers: checking the numbers against the sources, fixing breaks when a source changes, keeping access current, and small changes to existing views. Say what it does not cover: new data sources and new dashboards, which are quoted separately. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure. A dashboard the owner checks every morning is one of the easiest retainers to justify, because they notice the first day it is wrong.

How to present the dashboard quote

• Lead with the decision in their words. One line on what they will be able to see and decide, then the price.
• Itemize it. Base build, each data source, cleaning and definitions, access and sharing, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate payments on proof. A deposit to start, a payment when the numbers match their own records for an agreed period, and the final payment once the team is using it. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Put the definitions in the proposal. A short list of what each number means, signed off by the client, ends the "this number is wrong" argument before it starts.

If you have not built one yet, [how to build a dashboard with Claude Code](/blog/how-to-build-a-dashboard-with-claude-code) walks through the build so you know what you are quoting.

NOTE: Inside Claude Code Club, members share the dashboard and reporting quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for a custom dashboard?

Price it on what it changes for the business: the reporting hours it replaces and the better decisions that come from seeing the numbers sooner. Charge a fraction of one year of that value for the build, add a line for each data source, a line for cleaning and defining the data, and quote a monthly plan for upkeep.

Should I charge per chart for a dashboard?

No. A few charts that drive real decisions are worth more than dozens nobody opens. Per-chart pricing rewards clutter and ignores the data access, cleaning and upkeep that make up most of the work.

Should I charge a monthly fee for a dashboard?

Yes. Data sources change, fields get renamed, logins expire and the client adds new channels. A monthly plan covers checking the numbers, fixing breaks and small changes, with new data sources and dashboards quoted separately.

What is the difference between a dashboard and an internal tool?

A dashboard is mostly for reading numbers and making decisions. An internal tool is where the team does work: entering, approving or editing data. If the client's team needs to act inside it, price it as an internal tool.

What if the client's data is a mess?

That is common, and it is part of the job. Look at the data before you send the final number, price the cleaning and definitions as their own line, and get the client to sign off on what each number means.

• Ultrareview is the deep version of /code-review. Type /code-review ultra (or /ultrareview) and Claude Code sends your branch or pull request to a cloud sandbox where a fleet of reviewer agents looks for bugs and verifies each one before reporting it.
• It takes roughly 5 to 10 minutes and runs in the background. Pro and Max accounts get three free runs, one time only. After that, the official docs put a typical review at $5 to $25 in usage credits, and the launch dialog shows the estimate before you confirm.
• Use the normal /code-review while you work and save ultrareview for the merge that would hurt if it broke: payments, logins, data changes, or a big client release. Do not wire it into every pull request in CI, because every run costs money.

What Claude Code ultrareview is

Claude Code ultrareview is a deep code review that runs in the cloud instead of on your computer. You type /code-review ultra, and Claude Code launches a group of reviewer agents in a sandbox on Anthropic's infrastructure. They work through your changes in parallel, and every bug they report has been reproduced and checked first, so what comes back is a short list of real problems rather than style notes. It takes roughly 5 to 10 minutes, it runs in the background while you keep working, and after three free runs it costs usage credits.

The plain way to think about it: the regular /code-review is a quick second pair of eyes you use all day. Ultrareview is the careful senior reviewer you book before a release that matters. Both look for bugs. They differ in depth, where they run, and who pays.

NOTE: Everything in this post comes from the official Claude Code ultrareview and commands documentation, checked on the date at the bottom. Ultrareview is a research preview, so the command, pricing and limits can change. If something does not match what you see, check the docs and your Claude Code version.

Ultrareview vs /code-review

If you have not used the regular review yet, start there. [Claude Code code review](/blog/claude-code-code-review) explains the local command and the managed pull request reviewer, and in the desktop app the local review comes back as a card you can step through and fix line by line. Ultrareview sits on top of that, for the moments when a quick pass is not enough.

How to run ultrareview

1. Sign in with your claude.ai account. Ultrareview runs as a cloud session, so an API key on its own is not enough. Run /login if you need to switch.
2. Open your project and make sure you are on the branch with your work. With no arguments, ultrareview compares your current branch to the default branch, and it includes uncommitted and staged changes.
3. Type /code-review ultra and send it. /ultrareview is an alias for the same thing.
4. Read the confirmation dialog. It shows what will be reviewed, how many free runs you have left and the estimated cost. Nothing runs until you confirm.
5. Keep working. The review runs in the background. Use /tasks to see it, open its details, or stop it. When it finishes, the verified findings arrive in your session with the file and an explanation for each, and you can ask Claude to fix them.

A few useful variations from the docs. To compare against a branch other than the default, pass it: /code-review ultra develop. To review a pull request on GitHub instead of your local branch, pass its number: /code-review ultra 1234. And you can add a note in plain words, such as /code-review ultra check my auth changes, which still reviews your current branch but tells the reviewers what you care about.

TIP: The docs describe ultrareview as a command you type, and the desktop app takes slash commands in its prompt box. If ultrareview is not available on your account, /code-review ultra quietly runs a normal local review instead, so check the confirmation dialog: if it does not show free runs or a cost estimate, you did not get the cloud review. [The Claude Code desktop app](/blog/claude-code-desktop-app) covers the prompt box and sessions.

What ultrareview costs

Ultrareview does not come out of your plan's normal usage. Pro and Max accounts get three free runs, and those three are a one-time allowance per account that does not refresh. After that, each review bills as usage credits. The official docs say a typical review lands between $5 and $25 depending on the size of the change, and the launch dialog shows the estimate for your specific diff before you confirm.

• A run counts as soon as the cloud session starts. If you stop it early or it fails, it still uses a free run. A paid review that stops early bills only for the part that ran.
• Usage credits have to be turned on before you can launch a paid review. If they are off, Claude Code blocks the launch. /usage-credits opens the setting.
• Claude Code asks you to confirm usage-credits billing once per conversation, so after /clear you confirm again.

My rule on this: spend the three free runs on real releases, not on testing what the feature does. And before you turn on usage credits, know how they are capped on your account. A $5 to $25 review is a good deal before a client launch. The same review fired off out of habit on every small change adds up fast.

Limits to know before you run it

• Size: a branch review covers up to 500 changed files and 8,000 changed lines by default. Those values can change, and if your diff is too big ultrareview refuses and tells you which files are the largest.
• Where it works: it needs a claude.ai sign-in. It is not available through Amazon Bedrock, Google Cloud or Microsoft Foundry, or for organizations with Zero Data Retention or the HIPAA configuration.
• Pull request reviews need the repository on github.com, and the GitHub account connected to your Claude account needs read access to it.
• Branch reviews upload a bundle of your repository to the cloud sandbox. Pull request reviews upload nothing from your machine, because the sandbox clones the pull request from GitHub instead. If your repository is too big to bundle, push the branch, open a draft pull request and review that.
• If you stop a review before it finishes, you get nothing back. Claude Code does not return partial findings.

Post the findings to the pull request

On a GitHub pull request you can have Claude post the finished findings as one plain comment from your own GitHub account. It is not an approval, and it ends with a note that Claude Code generated it. Nothing is posted unless you choose it for that run: pick Run and post the findings to the PR as me in the launch dialog, or add --post to the command to preselect it. Keep the session open until the review finishes, because if the session ends first, nothing gets posted.

For client work this is the part I like most. The findings sit on the pull request where the client or their developer can see them, which makes [handing off the project](/blog/how-to-hand-off-a-claude-code-project) cleaner and shows the work was checked, without you writing a review summary by hand.

When ultrareview is worth it

Here is how I would use it. Keep /code-review as the everyday habit, the thing you run before every commit. Book ultrareview for the changes where a missed bug costs real money or trust:

• Anything that touches payments, sign-in, permissions or customer data.
• Database changes that are hard to undo.
• A big release to a client, right before you send them the link.
• Code Claude wrote across many files in one long session, where you could not read every line yourself.

There is also a claude ultrareview command for scripts and CI that waits for the review and prints the findings. It is tempting to run it on every pull request. I would not. Each run past the free three bills usage credits, so an automatic review on every push is an open-ended cost. If you want automatic reviews on every pull request, the managed Code Review service is built for that, and [Claude Code security review](/blog/claude-code-security-review) covers the security-focused check. Treat ultrareview as the expensive specialist you call in on purpose.

NOTE: Inside Claude Code Club, members share how they check Claude's work before it ships to a client, and which reviews actually caught something. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through the desktop app step by step.

FAQ

What is Claude Code ultrareview?

A deep code review that runs in a cloud sandbox. You type /code-review ultra, a fleet of reviewer agents looks for bugs in your branch or pull request, and each finding is reproduced and verified before it reaches you. It takes roughly 5 to 10 minutes and runs in the background.

How much does Claude Code ultrareview cost?

Pro and Max accounts get three free runs, one time only. After that, each review bills as usage credits, typically $5 to $25 depending on the size of the change according to the official docs. The launch dialog shows the estimate before you confirm.

What is the difference between /code-review and /code-review ultra?

/code-review runs locally in your session, takes seconds to a few minutes and counts toward your normal plan usage. /code-review ultra runs in the cloud with a fleet of agents that verify every finding, takes roughly 5 to 10 minutes, and bills as usage credits after the free runs.

Can ultrareview review a GitHub pull request?

Yes. Pass the pull request number, for example /code-review ultra 1234. The repository has to be on github.com and the GitHub account connected to your Claude account needs read access. You can also choose to post the findings to the pull request as one comment from your account.

Why did /code-review ultra run a normal review?

When ultrareview is not available, for example when you are signed in with an API key only or using Amazon Bedrock, Google Cloud or Microsoft Foundry, /code-review ultra runs a local review instead. Sign in with your claude.ai account and check the launch dialog shows free runs or a cost estimate.

• Price a custom WordPress plugin on the problem it solves for the business: the hours it saves, the sales it unlocks, or the mistakes it stops. Lines of PHP and your hours are the wrong yardsticks.
• Use the CCC Plugin Quote: a base build priced on that value, plus a line for each plugin or outside system it has to work with, a line for the client's site setup, and a line for testing and going live. Then a monthly Keep plan, because WordPress, PHP and the plugins around yours keep updating.
• Settle where the plugin lives before you quote. A private plugin for one client is a different job from one listed on WordPress.org, which requires a GPL-compatible license and does not allow locked trial features in the code it hosts.

How much to charge for a WordPress plugin

How much to charge for a WordPress plugin comes down to one question: what problem does it solve for the business, and what is that problem costing them today? Nobody buys a plugin for the PHP. They buy it so orders stop getting copied by hand into their stock system, so members see the right content without someone checking every account, or so a booking form stops sending leads into a dead inbox. Price the build on a share of that value, add lines for the plugins and systems it has to work with and for the client's site setup, and quote a monthly plan for upkeep. Do not price it on lines of code or hours.

WordPress plugins are good work to sell with Claude Code because WordPress already gives you the login, the database, the admin screens and the theme. Your plugin only adds the missing behaviour. That is also the trap. The first version can be small and quick, so builders price it like a favour, and then a WordPress update, a PHP upgrade on the host or an update to another plugin breaks it, and nobody is paid to fix it.

NOTE: This post is part of the pricing series. If the client really needs a page that sells rather than new behaviour on their site, read [how much to charge for a landing page](/blog/how-much-to-charge-for-a-landing-page). If what they describe is a separate tool their team logs into, read [how much to charge for an internal tool](/blog/how-much-to-charge-for-an-internal-tool).

Why the code is the wrong yardstick

A plugin that adds one shortcode to a hobby blog and a plugin that sends every order from a busy shop into the warehouse system can be close to the same amount of code. Charging the same for both makes no sense. The shop is paying for what the plugin does to their business, not for how many files are in the folder.

Hours are worse. Claude Code makes the first build fast, so if your price follows your hours, every bit of speed you gain becomes a pay cut. I covered this in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The real costs of a plugin sit around the code: fitting it into a site you did not build, testing it next to everything else installed there, and keeping it working as WordPress moves.

The CCC Plugin Quote

Base build. Work out with the client what the problem costs today. That is the hours someone spends doing the task by hand multiplied by what their time costs, plus the sales lost or the mistakes made when it goes wrong. Price the build at a fraction of one year of that value, so the client can see it pay for itself early.

Integrations. Every plugin or system yours has to work with is its own line. A plugin that only adds something to a page is one job. One that hooks into the shop plugin, the membership plugin and an outside CRM is three more lines, each with its own updates and its own way of breaking. If it calls a paid API, the key lives in the server settings, never in the page, with a spending limit, and that setup is part of the quote. [How to build a WordPress plugin with Claude Code](/blog/build-a-wordpress-plugin-with-claude-code) shows what a single integration involves.

Site setup. You are building inside someone else's house. An old theme, a crowded plugin list or a host that limits what you can change all add work you will not see until you look. Ask for access to a copy of the site before you send the final number, and price this line on what you find.

TIP: When a client says the number is too high, do not cut the price. Drop an integration, start with the manual version of one step, or skip the settings screen for version one, and show which line moved. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Private plugin or WordPress.org listing

Settle where the plugin will live before you quote, because it changes the job. Most client work is a private plugin: it is installed on their site only, and nobody else ever sees it. That is the simple case.

• Listing on WordPress.org: the plugin directory's guidelines require GPL-compatible licensing for everything hosted there, and they do not allow trialware, meaning locked or expiring features inside the plugin. Paid features have to live in a separate service or add-on. If the client wants a public listing, quote that as its own line, along with answering support questions from the public.
• Ownership: the code and any listing should be the client's. Hand over the code in their repository and any accounts in their name. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers the checklist.
• Selling it to others: if the client wants to sell the plugin to other businesses, it is no longer a plugin job. It is a product, and [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp) is the right post.

Always quote the Keep plan

Plugins break for reasons that have nothing to do with your code. WordPress releases updates. Hosts move sites to newer versions of PHP. The shop or membership plugin yours depends on changes how it works. None of that is your fault, and all of it can take the client's site or checkout down.

Quote a monthly plan in the original proposal. Say what it covers: checking the plugin after WordPress and major plugin updates, fixing breakages from those updates, keeping it working on newer PHP versions, and small tweaks. Say what it does not cover: new integrations and new features, which are quoted separately. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure. A plugin that sits in the middle of a client's orders or bookings is one of the easiest retainers to justify, because they feel it the first day it stops working.

How to present the WordPress plugin quote

• Lead with the problem in their words. One line on what it costs them today, then the price.
• Itemize it. Base build, each integration, site setup, testing and launch, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate payments on proof. A deposit to start, a payment when it works on a copy of their site, and the final payment once it is live. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Name what breaks it. Say plainly that WordPress, PHP and plugin updates will break it at some point, and that the Keep plan is how it gets fixed fast.

NOTE: Inside Claude Code Club, members share the plugin and website quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for a custom WordPress plugin?

Price it on the problem it solves: the hours it saves, the sales it unlocks or the mistakes it stops. Charge a fraction of one year of that value for the build, add a line for each plugin or system it works with, add site setup and testing, and quote a monthly plan for upkeep.

Should I charge hourly for a WordPress plugin?

No. Claude Code makes the first build fast, so hourly pricing turns every gain in speed into a pay cut, and it ignores the site setup, testing and upkeep that come with the code. Price on the value of the problem instead.

Should I charge a monthly fee for a WordPress plugin?

Yes. WordPress updates, hosts move to newer PHP versions, and the plugins yours depends on change. A monthly plan covers checks, fixes and compatibility updates, with new integrations and features quoted separately.

Can a client's plugin be listed on WordPress.org?

Yes, if it follows the directory's guidelines. Everything hosted there has to be GPL-compatible, and locked or expiring trial features are not allowed in the plugin itself. Most client plugins stay private and are installed on the client's site only.

Who owns a custom WordPress plugin I build for a client?

Agree it in writing before you start. The usual setup is that the client owns the code once they have paid, it lives in their repository, and any accounts or listings are in their name.

• Claude Code Remote Control connects a session running on your computer to the Claude mobile app or claude.ai/code, so you can keep steering it from your phone or another browser. In the desktop app, type /remote-control in the session's prompt box.
• Nothing moves to the cloud. Claude keeps running on your machine with your files, MCP servers and project setup, and the phone is a window into that session. Your computer has to stay on and the app has to stay open.
• It needs a Pro, Max, Team or Enterprise plan and a claude.ai login, not an API key. On Team and Enterprise an Owner has to switch it on first. Turn on push notifications so the phone tells you when Claude finishes or needs an answer.

What Claude Code Remote Control does

Claude Code Remote Control connects a Claude Code session running on your computer to the Claude app on your phone or to claude.ai/code in any browser. You start a task at your desk, walk away, and keep reading, answering and redirecting it from another device. The session never leaves your machine: Claude keeps running locally with your files, MCP servers, tools and project configuration, and the phone or browser is just a second screen into it.

This is the feature for the long task that does not need you every minute but does need you sometimes. A build that will ask for a permission halfway through, a refactor you want to check before it touches the next folder, or a test run you want to hear about the moment it fails. Without Remote Control, that session sits waiting at your desk until you come back. With it, you answer from wherever you are and it keeps going.

NOTE: Everything in this post comes from the official Claude Code Remote Control and desktop documentation, checked on the date at the bottom. Remote Control is still changing quickly, so if a menu name does not match, check the version of the app you are on.

How to turn on Remote Control in the desktop app

1. Open the Claude desktop app, go to the Code tab and start or open a local session on your project.
2. Type /remote-control (or the short form /rc) in the prompt box and send it. The first time, a dialog asks you to confirm. Select Enable Remote Control.
3. On your phone, open the Claude app, tap Code in the navigation and find the session in the list. Remote Control sessions show a computer icon with a green dot when they are online. In a browser, go to claude.ai/code instead.
4. Send a message from the phone. It lands in the same conversation on your computer, and Claude's replies show up on both screens.

To turn it off for that session, run /remote-control again. In the desktop app you can also see whether a session is connected from the laptop icon before the session title in the toolbar: it is highlighted while the session is connected, and clicking it opens the session's Remote Control switch.

If you want every new session to be reachable from your phone without typing anything, turn on Connect new sessions to Remote Control in Settings, under Claude Code. My recommendation is to leave that off at first and turn Remote Control on per session. It keeps your session list on the phone short, and it makes you decide which work you actually want to be reachable. [The Claude Code desktop app](/blog/claude-code-desktop-app) covers the rest of the app.

TIP: Prefer the terminal? Run claude --remote-control to start a normal session that is also reachable remotely, or claude remote-control to run a server that waits for connections and shows a QR code you can scan with your phone. Both lead to the same place as /remote-control in the desktop app.

What you can do from your phone

The phone is not a reduced view. You can send messages, answer permission prompts and questions, and watch progress as it happens. Typing @ autocompletes file paths from the project on your computer. You can attach a photo or a file from your phone too: Claude sees photos directly, and other files are downloaded to your machine and passed in as file references. That makes it easy to send a screenshot of a bug you spotted on your phone straight into the session working on it.

• Change the model or effort for the session, for example /model sonnet or /effort high, with the value typed as part of the command.
• Run text commands such as /compact, /clear, /context and /usage. [Claude Code clear vs compact](/blog/claude-code-clear-vs-compact) explains which to reach for.
• See the diff of your changes when the project is in a git repository.
• Watch subagents and workflows the session already has running, and stop one from the phone, which stops it on your computer.

A few commands only work at the computer itself, including /plugin and /resume. If you need one of those, it waits until you are back at the desk.

Turn on push notifications

Remote Control is only half useful if you have to keep checking the app. With push notifications on, Claude sends a notification to your phone, usually when a long task finishes or when it needs a decision from you. You can also ask for one directly in your prompt, such as notify me when the tests finish.

1. Install the Claude app on your phone and sign in with the same account and organization you use for Claude Code.
2. Allow notifications when your phone asks.
3. Run /config in the session and turn on Push when Claude decides, Push when actions required, or both. The second one covers permission prompts and questions, which is the one that saves the most waiting.

TIP: If /config shows No mobile registered, open the Claude app on your phone so it can refresh, then reconnect. On iPhone, Focus modes and notification summaries can hold pushes back. On Android, battery optimization can delay them.

Remote Control vs cloud sessions vs Dispatch

Claude Code has a few ways to work when you are away from the desk, and they are easy to mix up. The difference is where Claude runs and what starts the work.

My rule: if the work depends on something only your computer has, such as a local database, a private MCP server or a client repo you have not pushed, use Remote Control. If the work can run anywhere and you want your laptop closed, use a cloud session. [Claude Code on the web](/blog/claude-code-on-the-web) covers cloud sessions, and [Claude Code scheduled tasks](/blog/claude-code-scheduled-tasks) covers the timer option.

Requirements and limits to know first

• Plan: Pro, Max, Team or Enterprise. API keys are not supported. On Team and Enterprise, Remote Control is off by default and an Owner turns it on in the Claude Code admin settings.
• Login: you need to be signed in with your claude.ai account. If an API key is set in your environment or settings, Remote Control refuses to start and names the key it found. Remove it, then sign in again.
• Your computer stays on: Claude runs locally, so if you quit the app or shut the laptop down, the session goes offline until you bring it back. If the laptop sleeps or the network drops, it reconnects on its own when the machine is back online.
• One remote session per session window: each open session connects as its own remote session. To run many from one place, the terminal's server mode is built for that.
• Gateways and other providers: Remote Control does not work through Amazon Bedrock, Google Cloud, Microsoft Foundry or a custom API base URL. It has to talk to Anthropic's API directly.

If something does not connect, run claude doctor. It reports which eligibility check failed instead of leaving you to guess. [Claude Code doctor](/blog/claude-code-doctor) walks through reading its output.

Is Claude Code Remote Control safe?

The connection is outbound only. Your computer makes HTTPS requests to Anthropic and never opens an inbound port, so nothing on the internet can reach into your machine through it. Traffic runs over TLS through the Anthropic API, using short-lived credentials that each do one job and expire on their own. A session that connects automatically uses your own claude.ai account, so it only appears in your own Claude apps.

Two things to weigh for client work. While Remote Control is connected, the session transcript is stored on Anthropic's servers so it can stay in sync across devices, under Anthropic's data usage policy. And a phone is easier to lose than a laptop. If you are on a Pro or Max plan, turn on Require trusted devices in your account settings, which makes each phone or browser enroll and ties access to a recent sign-in or a Face ID, Touch ID or passkey check. [Is Claude Code safe for client work?](/blog/is-claude-code-safe-for-client-work) covers the wider question.

WARNING: Approving a permission prompt from your phone is still approving it. Read what Claude is about to run before you tap, the same as you would at the desk. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers which actions to keep behind approval.

NOTE: Inside Claude Code Club, members share how they run long sessions while away from the desk, and which setups kept them out of trouble. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through the desktop app step by step.

FAQ

What is Claude Code Remote Control?

It connects a Claude Code session running on your computer to the Claude mobile app or claude.ai/code, so you can keep working in it from your phone or another browser. Claude keeps running on your machine with your files and tools the whole time.

How do I use Claude Code Remote Control in the desktop app?

Open a local session in the Code tab and type /remote-control or /rc in the prompt box. Then open the Claude app on your phone, tap Code, and pick the session from the list, or open claude.ai/code in a browser.

Does Claude Code Remote Control work with an API key?

No. Remote Control needs a Pro, Max, Team or Enterprise plan and a claude.ai login. If an API key is set in your environment or settings, remove it and sign in with your claude.ai account.

Does my computer need to stay on for Remote Control?

Yes. The session runs on your computer, so it goes offline if you quit the app or shut down. If the laptop sleeps or the network drops, Claude Code reconnects automatically when the machine comes back online.

What is the difference between Remote Control and Claude Code on the web?

Remote Control runs on your computer and gives you a remote window into it, with your local files, MCP servers and settings. A cloud session runs on Anthropic's infrastructure, so it keeps going with your laptop closed but does not see anything that only exists on your machine.

• Price a Chrome extension on the workflow it speeds up: how many people use it, how often, and how much time or how many mistakes it saves them. The size of the code and your hours are the wrong yardsticks.
• Use the CCC Extension Quote: a base build priced on that value, plus a line for each site the extension has to work on, a line for each system it connects to, and a line for getting it through the Chrome Web Store. Then a monthly Keep plan, because the sites it runs on will change.
• Settle who owns the store listing before you quote. Publishing under the client's own developer account keeps the extension theirs, and the store's review can take anywhere from a few days to a few weeks, so it belongs in the timeline.

How much to charge for a Chrome extension

How much to charge for a Chrome extension comes down to one question: how much faster or cleaner does this make the work the client's people already do in the browser? Nobody buys an extension for the popup. They buy it so a sales rep stops copying details from a profile into the CRM, so a support agent gets the right reply with one click, or so a team stops making the same mistake on a web form. Price the build on a share of that value, add lines for the sites it runs on, the systems it connects to and the store publishing, and quote a monthly plan for upkeep. Do not price it on the size of the code or on hours.

Extensions are good work to sell with Claude Code because the result is right there in front of the user every day. The trap is that a first version can be small and fast to build, so builders price it like a weekend job. Then the client's CRM changes its page layout, the button the extension depends on moves, and the extension quietly stops working with nobody paid to fix it.

NOTE: This post is part of the pricing series. If the client really needs a screen their team logs into rather than a tool inside their browser, read [how much to charge for an internal tool](/blog/how-much-to-charge-for-an-internal-tool). If the extension is meant to be sold to the public as a product, read [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp), because that is what it is.

Why the popup is the wrong yardstick

An extension that tidies one page for one person and an extension that every rep on a sales team uses dozens of times a day can be close to the same amount of code. Charging the same for both makes no sense. The client is paying for what the extension does to their team's day, not for how many files it has.

Hours are worse. Claude Code makes the first build fast, and if your price follows your hours, every bit of speed you gain becomes a pay cut. I covered this in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The real costs of an extension sit around the code: getting it through the store, rolling it out to the team, and keeping it working when the sites underneath it change.

The CCC Extension Quote

Base build. Work out with the client what the workflow costs today. That is people multiplied by how often multiplied by how long multiplied by what their time costs, plus whatever the mistakes cost when someone copies a field wrong. Price the build at a fraction of one year of that value, so the client can see it pay for itself early.

Sites. Every site is its own line. An extension that reads and changes a page depends on how that page is built, and each site has its own layout and its own way of breaking. One that works on a single CRM is a different job from one that has to work across a CRM, an inbox and a support desk. Pricing per site makes the quote easy to trim. [How to build a Chrome extension with Claude Code](/blog/build-a-chrome-extension-with-claude-code) shows what a single site involves.

Connections. An extension that only changes the page in front of the user is one thing. One that pulls data from the client's database, writes it into their CRM and calls an AI model on the way is three more lines, each with its own keys, permissions and failure points. If it calls a paid API, the key never ships inside the extension. It goes behind a server the client controls, with a login and a spending limit, and that server is part of the quote.

TIP: When a client says the number is too high, do not cut the price. Drop a site, remove a connection, or replace the live AI call with a simple template, and show which line moved. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Price the Chrome Web Store work

Getting an extension into the client's browsers is real work, and builders forget to quote it. Publishing through the Chrome Web Store needs a developer account with a one-time registration fee, a listing, and a review by Google before anything goes live. Google's own guidance is that most reviews finish within a few days but some take a few weeks, and that extensions asking for broad access to websites or sensitive permissions can take longer to review.

• Visibility: the store offers public, unlisted (anyone with the link can install it) and private (only named testers or a group the client manages). Most client tools for one team should be private or unlisted. Every option goes through the same review.
• Ownership: publish under the client's own developer account, or move it to them at handoff. An extension living in your account is a problem for both of you the day the project ends. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers the checklist.
• Permissions: ask for only the sites and permissions the extension really needs. It is safer for the client's team, and it keeps the review simpler.
• Timeline: put the review window in the schedule, and never promise a go-live date that depends on the store answering in a day.

Always quote the Keep plan

Extensions break for reasons that have nothing to do with your code. The site the extension runs on changes a page, renames a field or moves a button. A connected tool changes how its data comes back. Chrome itself changes how extensions are allowed to work, which it has done before. None of that is your fault, and all of it stops the tool the team relies on.

Quote a monthly plan in the original proposal. Say what it covers: checking it still works on each site, fixing breakages from site changes, pushing updates through the store, and small tweaks. Say what it does not cover: new sites, new connections and new features, which are quoted separately. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure. An extension the whole team uses every day is one of the easiest retainers to justify, because they feel it the first morning it stops working.

How to present the Chrome extension quote

• Lead with the workflow in their words. One line on what the team does today and what it costs them, then the price.
• Itemize it. Base build, each site, each connection, store and rollout, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate payments on proof. A deposit to start, a payment when a working version is running in the team's own browsers, and the final payment once it is live through the store. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Name what breaks it. Say plainly that changes to the sites underneath will break the extension at some point, and that the Keep plan is how it gets fixed fast.

NOTE: Inside Claude Code Club, members share the extension and browser-tool quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for a Chrome extension?

Price it on the workflow it speeds up: how many people use it, how often, and the time and mistakes it saves them. Charge a fraction of one year of that value for the build, add a line for each site and each connected system, add the store publishing, and quote a monthly plan for upkeep.

Should I charge hourly for a Chrome extension?

No. Claude Code makes the first build fast, so hourly pricing turns every gain in speed into a pay cut, and it ignores the store work and the upkeep that come after the code. Price on the value of the workflow instead.

Should I charge a monthly fee for a Chrome extension?

Yes. The sites the extension runs on change their pages, connected tools change, and Chrome changes its rules for extensions. A monthly plan covers checks, fixes and store updates, with new sites and features quoted separately.

Who should publish a client's Chrome extension?

The client, under their own Chrome Web Store developer account, or you move it to them at handoff. For a tool used by one team, publish it as private or unlisted rather than public. Every visibility option goes through the same Google review.

How long does Chrome Web Store review take?

Google says most extensions are reviewed within a few days, but it can take up to a few weeks, and extensions that ask for broad access to websites or sensitive permissions can take longer. Build that window into the timeline you quote.

• To use Claude Code across multiple repos, start in the main project and add the second one with /add-dir followed by its path. Claude can then read and edit files in both for the rest of that session.
• An added folder gives file access, not full setup. Its skills, commands and subagents load, but its CLAUDE.md only loads if you turn that on, and most of its settings never apply. Put shared instructions in the main project.
• In the desktop app, cloud sessions have a + button next to the selected repository to add more repositories, each with its own branch. For a folder you always need, add it to permissions.additionalDirectories in your settings so you stop re-adding it.

How Claude Code works across multiple repos

Claude Code works across multiple repos by adding extra working directories to a session. Every session has one primary folder, the project you opened. You can add more with the /add-dir command, the --add-dir flag at launch, or the permissions.additionalDirectories setting. Once a folder is added, Claude can read and edit files in it alongside the main project, so one conversation can change a shared library and the app that uses it.

This comes up the moment real work spans two codebases: a frontend and a separate API, a website and the shared component kit it pulls from, or a client app plus the internal tool that feeds it. Without an added directory, Claude stays inside the folder you opened and asks before reaching outside it. With one, the cross-project change happens in a single pass instead of two sessions copying notes to each other.

NOTE: Everything in this post comes from the official Claude Code command, permissions and desktop documentation, checked on the date at the bottom. If one codebase holds several apps in one repository, that is a different setup: read [Claude Code in a monorepo](/blog/claude-code-monorepo) instead.

Option 1: /add-dir for one session

1. Open the project you will spend most of the time in. That becomes the primary folder, and its CLAUDE.md, settings and hooks are the ones that apply.
2. In the prompt box, type /add-dir followed by the path to the second project, for example /add-dir ../api. Start typing a partial path and Claude Code suggests matching folders.
3. Confirm the folder when asked. From then on Claude can read and edit files there for the rest of the session.
4. Tell Claude what lives where in your first message: which folder is the app, which is the API, and which one the change starts in. It does not guess the relationship between two folders on its own.

If you start sessions from the terminal, the same thing at launch is claude --add-dir ../api, and you can pass more than one path. Added directories are remembered with the session too: resuming from the added folder still finds a session that added it with /add-dir.

TIP: Two limits worth knowing: the path has to be a real folder that exists, and most network paths, such as a Windows \\server\share location, cannot be added. Clone the second repo locally first.

Option 2: make the extra folder permanent in settings

If you add the same folder every day, stop typing it. Add the path to permissions.additionalDirectories in a settings file, and every new session in that project gets file access to it automatically. The desktop app reads the same settings files as the terminal, so this works in both. [Claude Code settings.json explained](/blog/claude-code-settings-json) covers where those files live and which one to use.

Put it in the project's local settings file if the path only makes sense on your machine, and in the shared project file only if every teammate keeps the repos in the same place. One catch: folders listed in this setting get file access only. Unlike /add-dir, they do not load the added folder's skills, commands or subagents.

What an added folder loads, and what it does not

This is where most cross-repo confusion comes from. Adding a directory widens where Claude can read and write. It does not turn that folder into a second project with its own full setup.

My recommendation: keep the instructions that matter for the joint work in the main project's CLAUDE.md, including a short line on what the second repo is and its rules. That way the context loads every time without an environment variable, and it is obvious which project is in charge. [The Claude Code CLAUDE.md file](/blog/claude-code-claude-md-file) covers what to write.

Multiple repos in the desktop app's cloud sessions

Cloud sessions in the desktop app support several repositories directly. After you pick a cloud environment, click the + button next to the selected repository to add more. Each repository gets its own branch selector, so you can work on a feature branch in the library and a matching branch in the app that consumes it. This is the desktop equivalent of --add-dir for work that runs in the cloud rather than on your machine.

Cloud sessions suit long, cross-repo jobs you want running while you do something else, such as updating a shared package and every project that depends on it. [Claude Code on the web](/blog/claude-code-on-the-web) covers how cloud sessions work, and [the Claude Code desktop app](/blog/claude-code-desktop-app) covers the rest of the app.

When to open a parent folder or move the session instead

• Open the parent folder when both repos sit side by side and you want each one's CLAUDE.md to count. Claude loads a subfolder's CLAUDE.md when it reads or edits a file in that subfolder, so each repo's rules apply when Claude works there. The tradeoff: settings, hooks and the dev server preview come from the parent folder you opened, not from each repo.
• Use /cd when the work is finished in one repo and continues in another. It moves the session to the new folder and keeps the conversation, then applies that folder's CLAUDE.md, settings and hooks, asking you to trust the folder first if it is new.
• Use two separate sessions when the projects belong to different clients. Keeping client code, keys and history apart matters more than saving a few minutes. [Claude Code worktrees](/blog/claude-code-worktrees) covers the related case of two sessions in the same repo.

WARNING: An added folder is fully writable for the session. Before adding a repo you only need to read, commit or back up its current state, and check the diff in both projects before you ship. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers how to keep edits behind approval.

A simple cross-repo routine

1. Open the project where the change starts. Add the other with /add-dir.
2. Say in plain words which folder is which and what has to change in each.
3. Ask for a plan first and check that it names files in both folders. [Claude Code plan mode](/blog/claude-code-plan-mode) is built for this.
4. Let Claude make the change, then run each project and its tests separately.
5. Commit in each repo on its own, with a message that mentions the other, so the two changes can be traced together later. [Use Claude Code with Git](/blog/use-claude-code-with-git) covers the commit habit.

NOTE: Inside Claude Code Club, members share how they lay out frontend, backend and shared code across repos, and which setup kept their sessions clean. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through project setup step by step.

FAQ

Can Claude Code work on multiple repos at once?

Yes. Open one project, then add the other with /add-dir and its path, or start with the --add-dir flag. Claude can read and edit files in both folders for the rest of the session.

How do I permanently add a directory in Claude Code?

Add the folder path to permissions.additionalDirectories in a settings file. New sessions in that project get file access to it automatically. It grants file access only and does not load the folder's skills, commands or subagents.

Does Claude Code read the CLAUDE.md in an added directory?

Not by default. A folder added with --add-dir or /add-dir only loads its CLAUDE.md and rules when the CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD environment variable is set to 1. The simpler route is to describe the second repo in the main project's CLAUDE.md.

How do I add multiple repositories in the Claude Code desktop app?

In a cloud session, pick a cloud environment and click the + button next to the selected repository to add more. Each repository gets its own branch selector. For local sessions, use /add-dir or the additionalDirectories setting, which the desktop app reads from the same settings files as the terminal.

What is the difference between /add-dir and /cd in Claude Code?

/add-dir keeps your current project as the main one and adds file access to another folder. /cd moves the whole session to a new folder, keeps the conversation, and applies that folder's CLAUDE.md, settings and hooks.

• Price a web scraper on what the data does for the client: the hours of manual copying it replaces, the decisions it feeds, and how fresh it needs to be. The length of the script and your hours are the wrong yardsticks.
• Use the CCC Data Feed Quote: a base build priced on the value of the data, plus a line for each source site, plus a line for each place the data has to land. Then a monthly Keep plan, because sites change their pages and scrapers break.
• Make the client confirm they are allowed to collect the data before you quote. Public data, the site's terms and robots.txt, and no logins you are not entitled to. That check protects both of you.

How much to charge for a web scraper

How much to charge for a web scraper comes down to one question: what is this data worth to the client, delivered on time, every time? A client never wants a script. They want competitor prices every morning, new listings before anyone else sees them, or a clean list they stop building by hand. Price the build on a share of that value, add a line for each source and each delivery, and quote a monthly plan for upkeep. Do not price it on lines of code or hours.

Scrapers are good work to sell with Claude Code because the result is easy to see: a spreadsheet or dashboard that fills itself. The trap is that the first version can be quick to build, so builders price it like a small one-off job. Then a site changes its layout, the feed goes quiet, and the client blames you for a breakage nobody priced.

NOTE: This post is part of the pricing series. If the job is moving data between tools the client already owns rather than pulling it from websites, read [how much to charge for an AI automation](/blog/how-much-to-charge-for-an-ai-automation). If the scraper feeds a screen the team works in every day, read [how much to charge for an internal tool](/blog/how-much-to-charge-for-an-internal-tool).

Why the script is the wrong yardstick

A scraper for one simple page and a scraper behind a pricing decision worth a lot to the business can be close to the same amount of code. Charging the same for both makes no sense. The client is paying for what the data lets them do, not for what the code looks like.

Hours are worse. Claude Code makes the first build fast, and if your price follows your hours, every bit of speed you gain becomes a pay cut. I covered this in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The real cost of a scraper sits after launch, in keeping it running, and an hourly quote never sees that coming.

The CCC Data Feed Quote

Base build. Work out with the client what the data is worth. If someone copies it by hand today, that is people multiplied by how often multiplied by how long multiplied by what their time costs. If it feeds a decision, such as pricing, sourcing or lead lists, ask what a better or faster decision is worth. Price the build at a fraction of one year of that value, so the client can see it pay for itself early.

Sources. Every site is its own line. Each one has its own page layout, its own rules and its own way of breaking. A scraper that reads one site is a different job from one that reads five and merges the results into one clean format. Pricing per source makes the quote easy to trim. [How to build a web scraper with Claude Code](/blog/build-a-web-scraper-with-claude-code) shows what a single source involves.

Deliveries. Clean data in a spreadsheet is one line. The same data written into the client's database, pushed to a team chat when something changes, and emailed as a weekly summary is three. Each delivery adds setup, permissions and another place to check. [Automate your spreadsheets with Claude Code](/blog/automate-your-spreadsheets-with-claude-code) covers the most common landing spot.

TIP: When a client says the number is too high, do not cut the price. Drop a source, run it less often, or replace a live alert with a weekly file, and show which line moved. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Frequency and freshness change the price

A scraper that runs once a week and one that runs every hour are different products. Running more often means more requests to the source site, more chance of being blocked, more storage and more monitoring. It also means the client is relying on it for something time-sensitive, which raises the stakes when it fails.

Ask how fresh the data really needs to be, and price faster schedules higher. Many clients ask for hourly and are happy with daily once they see the difference in the quote. Running slowly is also the polite way to scrape: it keeps load on the source site low, which keeps the scraper working longer.

Always quote the Keep plan

Every scraper breaks eventually. A site redesigns a page, renames a field, adds a cookie banner or starts blocking automated visits. None of that is your fault, and all of it stops the feed. If there is no plan for it, you either fix it for free or the client goes back to copying by hand. Both are bad outcomes.

Quote a monthly plan in the original proposal. Say what it covers: checking the feed is healthy, repairing breakages from site changes, and small tweaks to fields. Say what it does not cover: new sources, new deliveries and big changes, which are quoted separately. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure. Scrapers are one of the easiest projects to justify a retainer on, because the client can see why it exists.

Confirm the client can collect the data

Before you quote, ask the client to confirm they are allowed to collect what they are asking for. The safe default: public data only, the site's terms of use and robots.txt respected, no scraping behind logins they are not entitled to use, and no personal data they have no right to hold. Put that confirmation in writing and in the contract. [What to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) covers where it goes.

WARNING: If a source has an official API or a data export, quote that instead of scraping. It is more stable, usually within the rules, and cheaper for the client to keep running. A scraper is the fallback when no clean source exists, not the first choice.

How to present the web scraper quote

• Lead with the value in their words. One line on what the data does for them today, then the price.
• Itemize it. Base build, each source, each delivery, the schedule, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate payments on proof. A deposit to start, a payment when the first full run lands clean data where they want it, and the final payment after a week of runs. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Name what breaks it. Say plainly that site changes will break the scraper at some point, and that the Keep plan is how it gets fixed fast.

NOTE: Inside Claude Code Club, members share the scraper and data-feed quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for a web scraper?

Price it on what the data is worth to the client: the manual work it replaces and the decisions it feeds. Charge a fraction of one year of that value for the build, add a line for each source site and each delivery, and quote a monthly plan for upkeep.

Should I charge hourly for a web scraper?

No. Claude Code makes the first build fast, so hourly pricing turns every gain in speed into a pay cut, and it ignores the real cost of keeping the scraper running after launch. Price on the value of the data instead.

Should I charge a monthly fee for a web scraper?

Yes, every time. Sites change their pages and start blocking automated visits, and each change can stop the feed. A monthly plan covers monitoring and repairs, with new sources and big changes quoted separately.

Does a scraper that runs more often cost more?

It should. Running hourly instead of weekly means more requests, more chance of being blocked, more storage and more monitoring, and the client is relying on it for something time-sensitive. Price the schedule as its own line.

Is it legal to build a web scraper for a client?

It depends on the data and the site. Stick to public data, respect the site's terms of use and robots.txt, avoid logins the client is not entitled to use, and get the client to confirm in writing that they are allowed to collect the data. When in doubt, the client should get legal advice before you build.

• Claude Code security review is the built-in /security-review command. It analyzes the changes on your current branch, compared with your origin remote's default branch, and flags risks such as injection, authentication problems and data exposure.
• Run it in the desktop app by typing /security-review in the prompt box, after the feature is finished and before you merge or deploy. It only reviews the branch diff, not your whole codebase and not your live site.
• If it fails with an "ambiguous argument 'origin/HEAD'" error, your clone is missing the origin/HEAD ref. Run git fetch origin, then git remote set-head origin --auto, and try again.

What Claude Code security review is

Claude Code security review is a built-in command, /security-review, that analyzes the changes on your current branch for security vulnerabilities. It looks at the difference between your branch and your origin remote's default branch, then reports risks such as injection, authentication and authorization problems, and data exposure. You run it on demand, once, when the work is ready. It is not a background scanner and it does not touch your deployed app.

I treat it as the security half of the final check before anything goes to a client. [Claude Code code review](/blog/claude-code-code-review) catches correctness bugs. /security-review asks a different question: if someone hostile used this, what could they get? Those are different reviews, and on client work I want both.

NOTE: Everything in this post comes from running the command and from the official Claude Code command reference. If you are new to the app itself, start with [the Claude Code desktop app](/blog/claude-code-desktop-app) and come back.

How to run /security-review in the desktop app

1. Finish the feature on its own branch. The review compares your branch with the default branch on your origin remote, so the work you want checked needs to be on a branch, not committed straight to main. [Use Claude Code with Git](/blog/use-claude-code-with-git) covers the branch habit if it is new to you.
2. Make sure the project has an origin remote and that you have fetched from it recently. The review needs that remote to know what "before" looks like.
3. In the desktop app, type / in the prompt box (or click the + button and choose Slash commands) and pick security-review. You can send it on its own; it already knows to look at the branch diff.
4. Read the findings. Each one should name the file, the risk and why it matters. Ask Claude to explain any finding you do not understand in plain words before you touch it.
5. Fix what is real, one finding at a time, then run the review again on the updated branch. Stop when it comes back clean or when what remains is a decision you have made on purpose and written down.

The terminal works the same way: type /security-review in a session. The desktop app is just where I run it, because I can keep the findings open next to the diff view and work through them in order.

What it covers, and what it does not

The most common mistake with this command is assuming it reviewed more than it did. It reads the changes on your branch. It does not audit the code that was already on main, it does not test the running site, and it does not check your hosting settings, your database rules or your API key dashboard.

To check code that already exists rather than new changes, ask Claude in a session to review a specific file or folder for vulnerabilities. For anything that is live, the review only ever sees source code in your checkout, so settings that live in a dashboard are still yours to check by hand.

When I run it

• Before merging anything that touches login, sign-up, passwords or user roles. [Add authentication with Claude Code](/blog/add-authentication-with-claude-code) covers building those pieces; this is the check after.
• Before shipping any form, upload or search box that takes input from strangers. Input from outside is where injection risks live.
• Before deploying anything that holds a paid API key. A key on the server is not safe if the endpoint around it has no authentication, no rate limit and an open origin policy. Our free guide on [keeping API keys safe with Claude Code](/free-resources/keep-api-keys-safe-claude-code) covers the setup side.
• Before handing a client build over. It goes into the same pre-flight list as [reviewing Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship).

WARNING: A clean review is not a guarantee. It is one pass by one tool over one diff. Treat it as a strong filter, not a sign-off, and keep anything that can spend money behind authentication and limits regardless of what the review says.

Fixing the "ambiguous argument 'origin/HEAD'" error

If /security-review stops straight away with an error mentioning origin/HEAD and "unknown revision or path not in the working tree", the command could not find your remote's default branch. It builds its context by diffing against a local ref called origin/HEAD, and some setups never create it: single-branch or CI checkouts, a repository with no origin remote, or one you never fetched.

1. Run git fetch origin, then git remote set-head origin --auto. That asks the remote which branch is its default and records it.
2. If that fails, name the branch yourself: git remote set-head origin main (use your real default branch name).
3. If the project has no remote at all, add one with git remote add origin followed by the repository URL, fetch, then set the head.
4. Run /security-review again.

You can also just ask Claude in the desktop app to run those commands for you and explain each one. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers how to approve them without opening the floodgates.

How to act on the findings without breaking the build

Do not paste the whole findings list back and say "fix all of this". That produces one large change that is hard to check. Take the findings one at a time, highest risk first. For each: ask Claude to restate the risk in one sentence, ask what the smallest fix is, apply it, and run the app to confirm nothing else broke. Commit after each fix so you can roll back a single change if needed.

Some findings will be about risk you accepted on purpose, such as an internal tool that only runs on a private network. Write that down in your project notes or CLAUDE.md so the next review and the next person understand the decision. If you are handing the project to a client, the same note belongs in the handover. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers what to include.

NOTE: Inside Claude Code Club, members post their /security-review findings and get a second pair of eyes on which ones are real before they ship. It is $9 a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) walks through the full pre-ship checklist step by step.

FAQ

What does /security-review do in Claude Code?

It analyzes the changes on your current branch for security vulnerabilities. It reviews the difference between your branch and your origin remote's default branch and reports risks such as injection, authentication problems and data exposure.

Does /security-review work in the Claude Code desktop app?

Yes. Type / in the prompt box, or click the + button and choose Slash commands, then pick security-review. Built-in commands are available in the desktop app as well as the terminal.

Does Claude Code security review scan my whole codebase?

No. It reviews only the changes on your current branch compared with origin's default branch. To check existing code, ask Claude to review a specific file or folder for vulnerabilities, or use a deeper scanning tool across the repository.

Why does /security-review say ambiguous argument origin/HEAD?

Your clone is missing the origin/HEAD ref that records the remote's default branch. Run git fetch origin and then git remote set-head origin --auto, or name the branch directly with git remote set-head origin main, then run the review again.

Is /security-review enough before shipping client work?

It is a strong filter, not a guarantee. Pair it with a correctness review, test the running app yourself, and check settings that live outside the code, such as hosting, database rules and API key limits.

• Price an internal tool on what it gives back to the team: the hours of repetitive work it removes every week, the errors it prevents, and the person it frees up. The number of screens and the hours it takes you to build are the wrong yardsticks.
• Use the CCC Team-Week Quote: a base build priced on the value of the job it replaces, plus a line for each system it connects to, plus a line for each kind of user with different access. Then a monthly plan for upkeep, because internal tools live as long as the business process does.
• Anchor the quote to the client's own numbers. Ask how many people do the job, how often, and how long it takes, and let those answers carry the price.

How much to charge for an internal tool

How much to charge for an internal tool comes down to one question: what is this job costing the team right now? An internal tool replaces a spreadsheet, a shared inbox, a copy-paste routine or a person double-checking someone else's work. Price the build on a share of what that job costs the business over a year, add a line for every system it has to connect to and every kind of user it has to handle, and quote a monthly plan on top. Do not price it on screens or on your hours.

Internal tools are some of the best work you can sell with Claude Code. The users are a known group, the job is already being done badly by hand, and the client can see the result inside a week. The trap is that they look small, an admin panel, a form and a table, so builders price them like a small website. That leaves most of the value on the table.

NOTE: This post is part of the pricing series. If the tool runs on its own in the background rather than being used by people, read [how much to charge for an AI automation](/blog/how-much-to-charge-for-an-ai-automation). If it is a product for outside customers, read [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp).

Why screens and hours are the wrong yardstick

A tool with two screens that ends an afternoon of manual reconciliation every week is worth more than a tool with twelve screens nobody opens. Screens measure your effort, not their outcome. Clients do not care how many pages you built. They care that the Friday report now takes minutes, or that orders stopped going out with the wrong address.

Hours are worse. Claude Code makes the build fast, and if your price follows your hours, every improvement in your speed is a pay cut. I covered this in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The client is buying the job gone, not the time it took you to remove it.

The CCC Team-Week Quote

Base build. Work out the yearly cost of the job with the client: the number of people doing it, multiplied by how often, multiplied by how long it takes, multiplied by what that time costs the business. Then price the build at a fraction of one year of that cost. The client should be able to see the tool pay for itself well inside the first year. Add the cost of mistakes if the job is error-prone, such as wrong invoices, missed orders or double bookings, because a tool that stops those is worth more than one that only saves time.

Connections. Every system the tool talks to is a line item: the CRM, the accounting software, a shared spreadsheet, the email service, the database. Each one adds setup, permissions, edge cases and a new way for things to break later. Pricing them separately makes the quote easy to understand and easy to trim. [Connect Claude Code to a database](/blog/connect-claude-code-to-a-database) gives a sense of what a single connection involves.

Access levels. A tool everyone sees the same way is simpler than one where managers see every record and staff see only their own. Each distinct kind of user means login rules, permission checks and testing as that user. [Add authentication with Claude Code](/blog/add-authentication-with-claude-code) covers the build side; on the quote, it is its own line.

TIP: When a client says the number is too high, do not cut the price. Remove a connection or an access level, and show them which line it came off. [The "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the wording.

Always quote the Keep plan

An internal tool is not finished at launch. The team changes how they work, a connected system updates, someone new needs access, a report needs a new column. If there is no plan for that, the tool slowly drifts out of step with the business and people go back to the spreadsheet. That is the worst outcome for both of you: the client stops getting value, and you lose the account.

Quote a monthly plan as part of the original proposal, not as an afterthought. State what it covers (monitoring, fixes, small changes up to an agreed size) and what it does not (new features, new connections, quoted separately). [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the structure, and [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) covers the conversation if the client declines at first.

The questions to ask before you quote

1. Who does this job today, and how many of them are there?
2. How often does the job happen, and roughly how long does each round take?
3. What goes wrong when it is done by hand, and what does a mistake cost?
4. Where does the information come from, and where does the result go?
5. Who needs to see what? Are there people who should not see some of it?
6. Who on your side will own the tool after launch, and who reports problems?

Write their answers into the proposal word for word. A quote that says "this replaces the work your team described as taking most of every Monday" sells itself far better than one that lists features. [Client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote) has the wider list, and [how to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project) turns the answers into a scope.

How to present the internal tool quote

• Lead with their job, in their numbers. One line on what the job costs today, then the price, so the price reads as smaller than the problem.
• Show the line items. Base build, each connection, each access level, then the Keep plan. Itemized quotes get trimmed, not rejected.
• Gate the payments on proof. A deposit to start, a payment when the team can use the main job on their own data, and the last payment on acceptance. [How to structure milestone payments for an AI project](/blog/how-to-structure-milestone-payments-for-an-ai-project) covers the schedule.
• Name the owner. Every internal tool needs a person on the client side who owns it. Put that name in the proposal.

NOTE: Inside Claude Code Club, members share the internal tool quotes they actually sent and how clients responded to each line. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to sanity-check a number before it goes out.

FAQ

How much should I charge for an internal tool?

Price it on what the job it replaces costs the business each year: the people doing it, how often, how long it takes, and what mistakes cost. Charge a fraction of one year of that cost for the build, add a line for each system it connects to and each kind of user, and quote a monthly plan for upkeep.

Should I charge hourly for an internal tool?

No. Claude Code makes the build fast, so hourly pricing means every gain in speed lowers your pay. Price on the outcome for the team, and keep the hours as your own private measure of whether the project was worth it.

Is an internal tool cheaper than a customer-facing app?

Often it is simpler to build because the users are a known group and the job is already defined. That does not make it cheaper to buy. If it removes a weekly chore for a whole team, its value can be higher than a public app nobody uses yet.

Do I need to charge a monthly fee for an internal tool?

Quote one every time. Teams change how they work and connected systems change too, and a tool without upkeep drifts out of step with the business. Say what the plan covers and what is quoted separately.

How do I lower the price without discounting?

Remove scope, not margin. Take out a connection, merge two access levels into one, or move a secondary feature into a later phase, and show the client which line changed.

• A client demo is a sales call, not a code review. Show one real job from start to finish on the client's own example data, on a live link, in under fifteen minutes of screen time. The client is judging whether their problem is gone, not how it was built.
• Prepare the demo the day before: deploy it, load their data, reset it to a clean state, and walk the exact path once. Never demo from localhost and never demo a path you have not run that morning.
• End every demo with a specific ask: the sign-off, the next milestone, or the date for going live. A demo that ends with "let me know what you think" ends with silence.

How to demo a Claude Code build to a client

To demo a Claude Code build to a client, open a link that is already deployed, load the client's own example data, and walk through one real job from the first click to the finished result. Say what the job is before you start, show the result, and stop. Keep the code, the prompts and Claude itself off the screen. The client hired you to remove a problem. The demo is the moment they see the problem gone.

Everything else in this post is about making that moment reliable. Building with the [Claude Code desktop app](/blog/claude-code-desktop-app) makes it easy to get something working fast, which is exactly why demos go wrong: the build works on your machine, in your session, with your test data, and then falls over in front of someone else. The fix is a short preparation routine, a fixed structure, and a plan for when something breaks.

NOTE: This post covers the demo itself. Getting the client to a yes comes from the proposal and the milestones around it: [a one-page AI proposal that closes](/blog/one-page-ai-proposal-that-closes) covers the proposal, and [how to write a statement of work for an AI project](/blog/how-to-write-a-statement-of-work-for-an-ai-project) covers what the demo is measured against.

Why showing the code loses the room

Showing the code feels like proof of work. To a non-technical client it is noise, and worse, it hands them a reason to start asking questions about things that do not matter to them: which framework, why that database, whether it is "real" code. Every minute spent there is a minute not spent on whether their business problem is solved.

The same goes for showing Claude Code working live. Watching an agent write files is interesting to builders. For a client it raises the question "so why am I paying you?" The answer is perfectly good, because the value is in knowing what to build, how to scope it, and how to check it, but a demo is a bad place to argue it. [How to sell AI to non-technical clients](/blog/sell-ai-to-non-technical-clients) covers how to frame that value in the conversation where it belongs.

The rule I use: the client sees their own world, working. Their data, their words, their workflow. If a screen would make sense to a stranger but not to them, it does not belong in the demo.

The prep routine the day before

1. Deploy it. A demo runs on a real link, not localhost. If you have not deployed this build yet, [how to deploy an app with Claude Code](/blog/how-to-deploy-an-app-with-claude-code) is the walkthrough. A live link also lets the client open it themselves afterwards.
2. Load their data. Use the client's own example records, names and wording, with their permission. A demo with "Test User 1" asks them to imagine; a demo with their real product list does not.
3. Pick one job. Decide the single path you will show, the thing the client does most often or complains about most. One path done well beats a tour of every screen.
4. Run that path end to end, twice, the morning of the call. Once to check it works, once to time it. Then reset the data to a clean starting state so the demo does not begin with your leftover tests.
5. Prepare the failure fallback. Record a short screen capture of the working path as a backup, and have it ready in another tab. Connections drop and services time out; the backup keeps the call alive.
6. Check the account state. Make sure any logins, API keys and third-party services the path touches are active and not close to a limit. [Review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship) has the pre-flight list I run before anything goes in front of a client.

The demo structure: outcome, path, result, ask

Run every demo in the same four beats. It keeps you calm, and it keeps the client oriented.

• Outcome (one sentence, before you share your screen). "Last time you told me that taking bookings by email costs you an evening each week. I am going to show you a booking request arriving and being confirmed without you touching it." You restate their problem in their words so the demo has a yardstick.
• Path (the live walkthrough). Narrate what the person using it does, not what the software does. "A customer picks a time, gets a confirmation, you get a notification." Go slowly and stop talking while something loads.
• Result (the payoff moment). Show where the outcome lands: the confirmation, the report, the spreadsheet row, the message sent. Then be quiet for a few seconds. Let them react.
• Ask (the close). Tie the demo to the next step in the agreement: "If this matches what we scoped, the next step is signing off this milestone so I can move on to the second part." Name the date or the action. [How to close an AI client over email](/blog/close-an-ai-client-over-email) is useful for the follow-up message that goes out the same day.

TIP: Hand them the mouse near the end. Ask the client to run the path themselves on the live link. People believe what they have clicked far more than what they have watched, and it surfaces confusions you would otherwise hear about next week.

What to do when something breaks on screen

Something will break eventually. How you handle it matters more than the break. Say what happened in plain words, once, without panic: "That did not load. I am going to reload and try that step again." If the second try fails, switch to the recorded backup and keep going: "Let me show you the recording of that path, and I will fix the live version and send you the link today." Then actually do it.

Do not debug live in front of a client. Do not open the terminal, do not start talking to Claude about the error while they watch, and do not explain the technical cause at length. Note the issue, move to the next part of the demo, and fix it after. Clients forgive a break that is handled calmly and followed by a quick fix. They do not forgive a long silent debugging session or a vague excuse. If the break reveals a real defect, [how to debug with Claude Code](/blog/how-to-debug-with-claude-code) is the process for finding it after the call.

Handling feedback during and after the demo

Clients almost always ask for something new during a demo, usually starting with "could it also...". Do not agree on the spot and do not refuse. Write it down visibly and say: "Good idea, I will note that and tell you what it would involve." Then sort every request into one of two buckets afterwards: part of what was agreed (fix it as part of the current milestone) or new (quote it separately). [How to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects) has the wording, and [how many revisions to include in an AI project](/blog/how-many-revisions-to-include-in-an-ai-project) explains how to keep feedback rounds finite.

Within the same day, send a short written recap: what you showed, what they confirmed, what they asked to change, and the next step with a date. That message is also your record that the milestone was shown and accepted. If you plan to hand the finished build over, [how to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) is the step after sign-off.

Common demo mistakes

• Demoing from localhost or a laptop-only setup. If it only works on your machine, it is not ready to show.
• Using fake data. It forces the client to translate your demo into their reality, and they usually do not.
• Showing every feature. A tour makes the build feel generic. One real job makes it feel like theirs.
• Talking while the thing loads. Silence feels long to you and normal to them. Let it finish.
• Explaining how it was built. Unless they ask, skip it. If they do ask, give one sentence and move back to the result.
• Ending without an ask. The last minute of the call should name the next step and the date.

NOTE: Inside Claude Code Club, members share the demos that moved a client to sign-off and the ones that stalled, and what they changed afterwards. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the quickest way to get a second pair of eyes on your demo path before the call.

FAQ

How long should a client demo of an AI build be?

Keep the live walkthrough short, under fifteen minutes, with the rest of the call for questions and the next step. One real job done start to finish lands better than a long tour of every screen.

Should I show the client the code or Claude Code during a demo?

No, unless they ask. Clients are judging whether their problem is solved, not how it was built. Showing code or an agent working invites questions that do not help the decision. Keep the screen on their world: their data, their workflow, the result.

Should I do a live demo or send a recorded video?

Do the live demo on a deployed link, and keep a short recording of the working path as a backup in case something fails. Send the recording afterwards along with a written recap so the client can review it and share it with others.

What if the demo breaks in front of the client?

Say plainly what happened, try the step once more, and if it fails switch to the recorded backup and continue. Do not debug live. Fix it after the call and send the working link the same day.

How do I end a client demo so it leads to a sign-off?

Tie it to the next step in the agreement and name a date. For example, ask them to sign off the milestone so you can start the next part. Follow up the same day in writing with what was shown, what they confirmed and what they asked to change.

• Tie every payment to something the client can see and approve: a deposit to start, a working preview in the middle, and acceptance at the end. Never tie payments to calendar dates or hours worked, because neither proves anything to the client.
• Use the CCC Proof-Gated Schedule: Start (deposit), Show (a working preview on their data), Ship (acceptance and go-live), and an optional Keep (the monthly plan). The final access and handover stay with you until the Ship payment clears.
• Write down what counts as accepted, how long the client has to respond, and what happens if they go quiet. A milestone with no acceptance rule is just a suggestion.

How to structure milestone payments for an AI project

To structure milestone payments for an AI project, split the fee into a few payments and attach each one to a visible, checkable event: the project starts, the client sees it working, the client accepts it. Do not attach payments to dates, because the client can stall a date, and do not attach them to hours, because hours are an argument. A payment that unlocks when the client approves a working preview is one nobody has to chase.

This protects both sides. The client never pays for something they cannot see, which is the real fear behind most hesitation on AI work. You never deliver the whole thing on trust and then wait. The number of payments is not the point; the proof behind each one is.

NOTE: This post is the schedule. [How much deposit to charge before an AI project](/blog/how-much-deposit-to-charge-before-an-ai-project) covers the first payment in depth, and [how to handle a client who won't pay](/blog/how-to-handle-a-client-who-wont-pay) covers what to do when the schedule is ignored.

Why dates and hours are the wrong triggers

Payments tied to dates ("first of the month") feel tidy but they break the moment the project slips for any reason, including the client being slow to send material. Then you are asking for money for work they cannot yet see, and they are right to resist.

Payments tied to hours turn every invoice into a negotiation about whether it really took that long. With AI builds that is especially bad, because the speed of the tool means clients assume the work was easy and push back on the time. I price AI work on the outcome, as covered in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds), and the payment schedule follows the same logic: pay for outcomes you can point at.

The CCC Proof-Gated Schedule

Start is the deposit. It commits the client and covers the work of getting going. It is paid before any work begins, and the project does not start until it clears.

Show is the payment that matters most, and the one people skip. When you have the core job working on a link the client can open, with their own example data in it, you request the next payment. It proves progress, gives the client a real look before most of the money is spent, and gives you cash flow through the middle of the project instead of one big wait at the end. [How to demo a Claude Code build to a client](/blog/how-to-demo-a-claude-code-build-to-a-client) covers how to run that preview so it gets approved.

Ship is paid on acceptance, before you hand over the final access. The finished build is tested against the list in the agreement, the client confirms in writing that it matches, and the final invoice is due. Keep is optional but I always offer it: a monthly plan for fixes and small changes that begins at go-live. [How to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) covers that conversation.

TIP: For a small, short project, collapse the schedule to two payments: Start and Ship. Add the Show payment as soon as the build is big enough that you would be uncomfortable waiting until the end to be paid.

Define "accepted" before you start

A milestone only works if everyone agrees in advance what counts as done. Put three things in the statement of work. First, the checklist the build will be measured against, written in plain language as things the client can do or see. Second, the response window: the client has a set number of working days to accept or list the specific items that do not match the checklist. Third, the silence rule: if the window passes with no response, the milestone is treated as accepted and the invoice is due.

[How to write a statement of work for an AI project](/blog/how-to-write-a-statement-of-work-for-an-ai-project) has the full structure, and [how many revisions to include in an AI project](/blog/how-many-revisions-to-include-in-an-ai-project) covers how many rounds of fixes fit inside each milestone. Without these, acceptance becomes an open-ended conversation and your payment becomes a hostage to it.

What you hold back until the final payment

Give the client everything they need to judge the work, and hold back only what they need to run it without you. In practice that means: the preview link stays live throughout, but production access, the transfer of accounts and the source files are handed over after the Ship payment clears. State this in the agreement, in a sentence, before the project starts, so it reads as the process rather than as a threat.

Be fair about it. Do not hold back something the client already paid for, and do not hide a working build from them to force payment. The point is a sequence, not a standoff. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers the handover itself.

When a client stalls on a milestone

• Silent after a preview. Send a short message restating what was shown, the acceptance window and the date it ends. Most delays are simply someone being busy.
• Vague unhappiness. Ask them to list the specific items that do not match the checklist. Anything on the list gets fixed; anything not on it is new work, quoted separately. [How to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects) has the wording.
• Wants to pay later. Hold the schedule. If the cash situation is real, offer a smaller number of larger milestones in place of late payment on the existing ones, never open-ended delay.
• Won't pay at all. Pause work as the agreement allows and follow the steps in [how to handle a client who won't pay](/blog/how-to-handle-a-client-who-wont-pay). Having acceptance in writing is what makes that conversation short.

How to present the schedule so it closes

Put the schedule on the same page as the price, in the same plain language as the table above. When a client sees that money only moves when they have seen something working, the number feels safer, and the "what if you disappear" worry fades without you having to argue it. If they ask whether the fee can come down, [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) covers the answer, and the answer is almost never a discount: it is a smaller scope.

NOTE: Inside Claude Code Club, members share the payment schedules they actually put in proposals and how clients reacted to each. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the quickest way to pressure-test your own schedule before you send it.

FAQ

How should I structure milestone payments for an AI project?

Tie each payment to something the client can see and approve: a deposit to start, a working preview on their own data in the middle, and written acceptance of the finished build at the end. Avoid tying payments to dates or hours worked.

How many milestone payments should an AI project have?

Two for a small, short project (start and acceptance), three or four for anything larger or longer. Add a middle payment as soon as you would be uncomfortable waiting until the end to be paid.

What counts as a milestone being accepted?

Whatever the statement of work says. Write a plain-language checklist the build is measured against, a response window for the client, and a rule that silence after the window counts as acceptance. Without these, acceptance turns into an open-ended conversation.

Should I hand over access before the final payment?

Give the client a live preview throughout so they can judge the work, but hand over production access, account transfers and source files after the final payment clears. Put that sequence in the agreement before the project starts so it reads as process, not leverage.

What if the client wants to pay everything at the end?

Decline politely and explain that paying only at the end means you carry all the risk through the whole project. Offer the same schedule with fewer payments if the project is small, and keep a deposit in every case.

• The Claude Code goal command is /goal plus a condition. Claude keeps starting new turns on its own until a separate small fast model reads the conversation and confirms the condition is met, judges it impossible, or a turn fails on an error you have to fix. You can also stop it yourself with /goal clear.
• The evaluator does not run commands or read files. It only judges what Claude has shown in the conversation, so the condition has to be something Claude's own output can prove, like a test run or a build result.
• The CCC Finish Line Formula: one measurable end state, the check that proves it, what must not change on the way, and a ceiling such as or stop after 20 turns. Pair it with auto mode if you want the turns to run without approval prompts.

What the Claude Code goal command does

The Claude Code goal command is /goal followed by a completion condition, for example /goal all tests in test/auth pass and the lint step is clean. Setting it starts a turn straight away, with the condition as the instruction. After each turn, a small fast model checks whether the condition holds. If it does not, Claude starts another turn instead of handing control back to you. The goal clears on its own when the condition is met, when the evaluator judges it impossible, or when a turn fails on an error you have to fix. One goal can be active per session, and it works in the desktop app, in the terminal, and through Remote Control.

The part that matters to me is who decides the work is finished. Without a goal, Claude stops when Claude thinks it is done. With a goal, a fresh model that did none of the work reads the conversation and makes the call. That is the same reason I do not review my own pull requests. The builder is the worst judge of whether the build is complete, and /goal gives you a second opinion on every single turn without you having to be there.

NOTE: A goal is only as good as the setup underneath it. If your project has no tests and no build step, start with [test-driven development with Claude Code](/blog/claude-code-test-driven-development), because a goal needs something it can check.

How to set a goal in the Claude Code desktop app

Open a session on the project in the desktop app, type /goal followed by your condition, and send it. You do not need a separate prompt. The condition is the instruction, and Claude starts working as soon as it is set. While the goal is active, an indicator shows that it is running and for how long.

1. Commit your work first. A goal can run for many turns, and a clean commit is the cheapest undo you have. [Using Claude Code with git](/blog/use-claude-code-with-git) covers the habit.
2. Pick your permission mode on purpose. A goal does not change it. In Manual mode, Claude still asks before any tool call your settings do not already allow, so the goal will sit waiting for you. To let the turns run unattended, set the goal in [auto mode](/blog/claude-code-auto-mode-default).
3. Type /goal and the condition, then send. Setting a new goal while one is active replaces the old one.
4. Check in with /goal on its own. It shows the condition, how long it has been running, how many turns have been evaluated, the token spend so far, and the evaluator's most recent reason.
5. Stop it with /goal clear if you change your mind. The words stop, off, reset, none and cancel work too, and running /clear to start a new conversation also removes the goal.

If you close the session with a goal still active, resuming that session brings the goal back. The condition carries over, and the turn count, timer and token-spend figures start again from zero. A goal that was already achieved or cleared does not come back. [How to resume a Claude Code session](/blog/resume-a-claude-code-session) covers the resume routes.

The CCC Finish Line Formula: how to write a goal condition

A goal condition has to be something Claude's own output can prove. The evaluator does not run commands and does not read your files. It reads the conversation, and that is all. "All tests in test/auth pass" works because Claude runs the tests and the result lands in the transcript. "The code is clean" does not work, because nothing Claude prints can settle it. The CCC Finish Line Formula is the four parts I write every time.

Put together, that reads: /goal every call site uses the new payments client, npm test exits 0, no test file is modified, or stop after 20 turns. The condition can be up to 4,000 characters, so there is room to be exact. The ceiling is the part people skip. Claude reports progress against a turn or time clause each turn and the evaluator judges it from the conversation, which makes it the simplest way to bound a run you are not watching.

The guardrail line is the one I would not leave out. A model told to make the tests pass has two ways to get there, and one of them is editing the tests. Writing "no test file is modified" into the condition closes that door. If the work is big enough to need a page of acceptance criteria, write them down first. [How to write a technical spec for Claude Code](/blog/how-to-write-a-technical-spec-for-claude-code) is the format I use, and the goal then becomes "every acceptance criterion in the spec holds".

/goal vs /loop vs auto mode vs a Stop hook

These four get confused because they all make Claude Code do more without you. They answer different questions. /goal decides when the work is finished. /loop re-runs a prompt on a time interval. Auto mode removes the approval prompts inside a turn. A Stop hook is the permanent, scripted version of what /goal does for one session.

/goal and auto mode are built to be used together. Auto mode removes the per-tool prompts and /goal removes the per-turn prompts. Under the hood, /goal is a wrapper around a prompt-based Stop hook that lasts for the current session only. If you find yourself typing the same goal every day, that is the sign to make it a real hook. [Hooks that earn their keep](/blog/claude-code-hooks-that-earn-their-keep) covers which ones are worth it. For work that should run when no session is open at all, that is a [scheduled task in the desktop app](/blog/claude-code-scheduled-tasks), not a goal.

What stops a goal, and what only pauses it

A goal ends in one of three verdicts or one kind of error. The evaluator returns not yet met, met, or impossible, each with a short reason. Not yet met means Claude keeps going and uses the reason as guidance. Met clears the goal and records it as achieved. Impossible clears it and records the reason, so you are not left with a loop chasing something that cannot happen.

• Errors that clear the goal: an exhausted credit balance, a model that is not available, a context overflow that auto-compaction could not clear, and an authentication failure when Claude Code manages its own credentials. In the desktop app, which manages sign-in for you, an authentication failure leaves the goal active. When a goal is cleared this way, fix the cause and run /goal again.
• Errors that keep the goal: everything else. On Claude Code v2.1.269 or later, an interactive session retries on its own after things like an overloaded server or a dropped connection, and pauses after three automatic retries.
• Limits pause it. An API rate limit or a usage limit pauses the goal and names the cause. If the session is set to continue when the usage limit resets, Claude picks the goal back up then. [What to do when you hit usage limits](/blog/claude-code-usage-limits-what-to-do) covers your options in the meantime.
• Talking without working stops the loop. If Claude keeps answering the evaluator with no tool use for several turns in a row, Claude Code stops, prints a warning, and hands control back to you with the goal still set.
• Background work delays the check. If a subagent or a background command is still running when a turn ends, the evaluation is skipped for that turn and happens once nothing is running. After 30 minutes of waiting, Claude is asked to check on the running tasks and fix or stop any that are stuck.

What the goal command costs

The evaluator itself is cheap. It runs on your configured small fast model, which defaults to Haiku on the Claude API, and the official guidance is that evaluation tokens are typically negligible compared to what the main turns spend. The real cost of a goal is the turns. A goal with no ceiling on a vague condition can take a lot of turns, and every one of them is billed like any other work.

That is why the ceiling is in the formula, and why I check /goal partway through a long run. It shows the token spend so far. If the number is climbing and the evaluator's reason has not changed in a while, the condition is the problem, not the model. Clear it, tighten it, and set it again. [What actually eats your limit](/blog/claude-code-token-usage) explains where the rest of the spend goes.

The jobs I hand to /goal, and the ones I do not

A goal earns its place on substantial work with an end state you can verify. It is the wrong tool for anything where finished is a matter of taste.

• Good fit: moving a module to a new API until every call site compiles and the tests pass.
• Good fit: building out a written spec until every acceptance criterion holds.
• Good fit: splitting one oversized file into smaller ones until each is under a size you name.
• Good fit: working through a labelled backlog of issues until the queue is empty.
• Bad fit: "make the homepage look better". There is nothing in a transcript that proves it, so the evaluator is guessing.
• Bad fit: a job where the check lives outside the session, like a client signing off. Claude cannot show that result, so the condition can never be met.
• Bad fit: anything on a client's production system without limits in place first. A goal in auto mode is [Claude Code running unattended](/blog/claude-code-running-unattended), and the same rules about permissions apply. [Permissions explained](/blog/claude-code-permissions-explained) is where I would start.

Set your first goal today

Pick one job on your current project that has a test or a build you trust. Commit, switch to auto mode if the repo is yours to risk, and write the condition with all four parts: end state, proof, guardrails, ceiling. Then leave it alone and read the evaluator's reasons when you come back. They tell you more about how well you wrote the condition than about how well Claude worked. If a run goes somewhere you did not want, [checkpoints and rewind](/blog/claude-code-checkpoints-and-rewind) plus the commit you made at the start get you back.

NOTE: Inside Claude Code Club, members share the goal conditions they actually run, the ones that looped, and how they rewrote them. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to see what a well-written finish line looks like on real projects.

FAQ

What is the Claude Code goal command?

It is /goal followed by a completion condition. Claude keeps working turn after turn until a separate small fast model confirms the condition is met, judges it impossible, or a turn fails on an error you have to fix. One goal can be active per session.

Does /goal work in the Claude Code desktop app?

Yes. /goal works in the desktop app, in the terminal, in non-interactive mode, and through Remote Control. In the desktop app you type /goal and the condition into the prompt box and send it.

What is the difference between /goal and /loop in Claude Code?

/goal starts the next turn as soon as the previous one finishes and stops when a separate model confirms your condition is met. /loop re-runs a prompt when a time interval passes and stops when you stop it or Claude decides the work is done. Use /goal for a finish line and /loop for a repeat check.

How do I stop a Claude Code goal?

Run /goal clear. The words stop, off, reset, none and cancel are accepted as aliases, and running /clear to start a new conversation also removes an active goal. To limit a goal in advance, write a clause such as or stop after 20 turns into the condition.

Does /goal run without asking for permission?

Not by itself. A goal does not change your permission mode. In Manual mode Claude still asks before tool calls your settings do not already allow. To let goal turns run unattended, set the goal while in auto mode.

How much does /goal cost to run?

The evaluator runs on your configured small fast model, which defaults to Haiku on the Claude API, and its tokens are typically negligible compared to the main turns. The real cost is the number of turns the goal takes, which is why a turn or time ceiling in the condition matters.

• Price a mobile app as three separate things: the build, the store launch, and the upkeep. A client who only pays for the build gets an app that stops working the first time a phone update breaks it, and you get the call.
• Ask first whether it needs to be in the app stores at all. Plenty of clients need something that works well on a phone, which is a web app, and it is cheaper, faster and has no store review. Saying so wins more trust than the bigger quote.
• Quote the CCC Store-Ready Ladder: Pilot (a working app on the client's own phones), Store Launch (published on one store), and Launch and Run (both stores plus a monthly plan). Store fees sit on their own line and the accounts belong to the client: the Apple Developer Program is 99 USD per membership year and Google Play has a US$25 one-time registration fee.

How much to charge for a mobile app

How much to charge for a mobile app depends on three things, and you price each one on its own line: the build, the store launch, and the upkeep afterwards. Quote the build and the launch as a fixed fee in three tiers, sized against what the app is worth to the client's business, not against your hours. Quote the upkeep as a monthly fee. Keep the store accounts and their fees in the client's name. Do not quote build hours. With Claude Code, the first working version of an app can come together quickly, and a client who hears how quickly will price the whole thing like a weekend job, when the launch and the upkeep are where most of the real work sits.

This is where new builders lose money on apps. They price the part that got faster and give away the two parts that did not. Getting an app approved and listed, and keeping it working as phones and store rules change, takes the same patience it always did. If the quote is one number for "the app", the client assumes all of that is included forever. It needs to be written down and priced, or you are doing it for free a year from now.

NOTE: The fixed-fee logic under every number here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project). If the client is testing an idea rather than launching a finished product, read [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp) first, because that is a different quote.

A mobile app is not priced like a website

A website goes live when you say so. A mobile app goes live when a store says so, and that one difference changes the whole quote. There is a gatekeeper between you and the client's customers, there are accounts and fees that have to exist before anything ships, and there is no such thing as finished, because the phones keep changing underneath it.

Walk the client through this table on the call. Most have never shipped an app and assume it works like their website. Once they see the launch and the upkeep as real work with real steps, a quote with three lines stops looking padded and starts looking like you have done this before. For the website side of the comparison, [how much to charge for a landing page](/blog/how-much-to-charge-for-a-landing-page) has that quote.

Ask first: does it need to be in the app stores at all?

Often the honest answer is no. When a client says "we need an app", what they usually mean is "our customers are on their phones". A web app that works well on a phone covers that with no store account, no review and no waiting on anyone to publish a fix. It is a smaller quote and a faster delivery. Four questions tell you which one they need.

• Who will use it? If it is the client's own staff, a web app they open from a link is almost always enough. If it is the public, the store listing may matter.
• What must it do that a website cannot? Features that depend on the phone itself are the real reasons to go native. "It should have an icon" is not one.
• Do customers need to find it in a store? Some businesses get real value from being listed. Many will only ever send people a link, in which case the store is pure overhead.
• Who will look after it in a year? If the answer is nobody, the simpler option is the responsible one.

Telling a client they need the cheaper thing feels like leaving money on the table. It is the opposite. It is the moment they decide you are the person they trust with the budget, and when they do need the store version later, nobody else gets the call. The full question set is in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

The CCC Store-Ready Ladder: three tiers

Present three tiers for the same app and let the client choose how far they want to go. The tiers are not more screens. They are how close the app gets to the public, and how much of what comes after you take on.

Most clients land on Store Launch once they see the table, and that is fine, provided the upkeep conversation still happens. If they decline the monthly plan, write down what that means: updates and fixes after the handover period are quoted separately. The three-tier shape is the same one I use in [how much to charge for an AI agent](/blog/how-much-to-charge-for-an-ai-agent); the tiers change, the logic does not.

Store accounts and fees go on their own line, in the client's name

The store accounts belong to the client, and so do the fees. The Apple Developer Program is 99 USD per membership year. Google Play charges a US$25 one-time registration fee for a developer account. Neither number is large. The reason they go on their own line is ownership, not cost.

• The client opens the accounts in their own legal name and adds you as a team member. If the app is published under your account, the client does not really own their own product, and you cannot walk away without taking it down.
• Start the accounts on day one. Both stores ask for identity details before they let anyone publish, and that is time you do not control. It should never be the thing holding up the launch.
• List the fees on the quote as paid by the client directly. You are not marking them up and you are not fronting them.
• If the app sells anything through the store, tell the client that the stores take a commission on those sales and point them to the store's own current terms. Do not quote them a percentage from memory. That decision shapes their pricing, and it is theirs to make with the real numbers in front of them.

Put the ownership in writing along with the fees. [What to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) covers the clause, and [how to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers what the client should hold at the end: the accounts, the code, and the logins for anything the app depends on.

What moves a mobile app quote up or down

• One store or two. Two listings means two accounts, two sets of store requirements and two submissions. Quote the second store as its own line so the client can defer it.
• Accounts and logins. An app where people sign in needs sign-up, password reset, account deletion and somewhere safe to keep the data. It is never "just a login".
• Payments. Taking money inside an app brings the store's rules with it. Scope it as its own piece of work, and find out early which rules apply to what the client is selling.
• Working without a signal. If the app has to work offline and catch up later, that is a meaningful jump in the build and the testing.
• What it plugs into. An app that reads from the client's booking system or stock system is only as reliable as that connection. Every system it touches is a line.
• Notifications. Sending alerts to people's phones needs setup on each store and a plan for who writes and sends them.
• Design. A client with finished designs is a smaller quote than one who wants you to work out how it should look and feel.
• Who owns the upkeep. If the client has someone technical, the monthly plan is lighter. If that someone is you, it is in the price. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) covers the number.

The mistakes that leave you maintaining an app for free

• One number for "the app". If launch and upkeep are not separate lines, the client assumes both are included, for good.
• Publishing under your own developer account. It feels faster. It ties you to the app permanently and leaves the client without control of their own product.
• Promising a launch date you do not control. You control the day you submit. The store controls the day it goes live. Quote a submission date and say so plainly.
• Treating a store rejection as a surprise. Write into the quote that responding to review feedback is included, and how many rounds. [How many revisions to include in an AI project](/blog/how-many-revisions-to-include-in-an-ai-project) has the wording.
• No upkeep plan and no written alternative. An app with no monthly plan and no stated rate for later fixes becomes an argument the first time a phone update breaks something.
• Building for both stores before anyone has used it. Launch on one, learn what customers do with it, then add the second as a paid step.
• Letting the feature list grow mid-build. Apps attract "while you are in there" requests. [How to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects) has the reply.
• No deposit. [How much deposit to charge before an AI project](/blog/how-much-deposit-to-charge-before-an-ai-project) covers the number. An app is a multi-week commitment and gets paid like one.

How to present the mobile app number so it closes

Lead with the job the app does for the business, then put the three tiers under it with the store fees and the monthly plan written out beside them. "You said your regulars keep asking to rebook from their phones; here are three ways to give them that, depending on how public you want it on day one" is a sentence a client can say yes to on the call. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes) with the job in one line, the tiers, the submission date, who owns the accounts, and what happens after launch. If they push on price, the answer is the Pilot tier, not a discount, and [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the words.

An app that is live and looked after is the best retainer you will sign, because the client sees it on their own phone every day. [How to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) is what happens next. If you have not built one yet, [build a mobile app with Claude Code](/blog/build-a-mobile-app-with-claude-code) is the build side of this post.

NOTE: Inside Claude Code Club, members share the app quotes they actually sent, how they split launch and upkeep, and what the stores sent back on review. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the quickest way to see what real mobile app pricing looks like before you send your first number.

FAQ

How much should I charge for a mobile app?

Price three things separately: the build, the store launch, and the upkeep. Quote the build and launch as a fixed fee in three tiers sized against what the app is worth to the client's business, and quote the upkeep as a monthly fee. Do not quote build hours.

Who should pay for the Apple and Google developer accounts?

The client, in their own legal name, with you added as a team member. The Apple Developer Program is 99 USD per membership year and Google Play has a US$25 one-time registration fee. Put both on their own line of the quote as paid by the client directly.

Should I charge a monthly fee for a mobile app?

Yes, or state in writing what happens without one. Phone software, screen sizes and store requirements keep changing, and an app that is never updated eventually breaks. The monthly fee pays for updates, fixes and store changes. If the client declines, write down that later work is quoted separately.

Is a web app cheaper than a mobile app for a client?

Usually, yes. A web app that works well on a phone needs no store account, no store review and no resubmission for every fix, so both the build and the upkeep are smaller. Go to the app stores when the app needs features that depend on the phone itself or when being listed in a store matters to the business.

Should I quote iOS and Android together?

Quote them as separate lines. Two stores means two accounts, two sets of requirements and two submissions. Launching on one store first, then adding the second as a paid step once customers are using the app, is the lower-risk path for most clients.

• Claude Code doctor is the /doctor command (alias /checkup). It checks installation health, finds skills, MCP servers and plugins that cost context without being used, flags slow hooks, checks for a newer version, and trims a checked-in CLAUDE.md. It reports first and asks before it changes anything.
• /doctor prompt-audit is the new part. It needs Claude Code v2.1.283 or later and reads your CLAUDE.md files, rules, skills, commands, subagents and output styles for instructions written for older models, references to files that no longer exist, and files that contradict each other. You get proposed edits, and nothing changes until you say so.
• The CCC Checkup Cadence: run /doctor after a new model ships, after you install or remove a batch of skills or MCP servers, whenever a session starts feeling slow, and once a month regardless. With Sonnet 5.5 out this week, now is the first of those.

What Claude Code doctor does

Claude Code doctor is a built-in checkup you start by typing /doctor in a session (the alias is /checkup). It looks at your whole setup and tells you what is wrong or wasteful: duplicate or leftover installs, PATH problems, settings files that do not parse, skills and MCP servers and plugins that cost context without being used, hooks that are slow, and whether a newer version is out on your release channel. It also trims a checked-in CLAUDE.md by cutting content Claude could work out from the code itself. It reports its findings first and asks before it changes anything. Since Claude Code v2.1.283 there is a second mode, /doctor prompt-audit, that reads your instructions for rules written for older models and files that contradict each other.

I treat it the way I treat a service on a car. Nothing is broken today, but a Claude Code setup collects weight quietly. A skill you installed to try once. An MCP server for a client you finished in the spring. A CLAUDE.md that grew a paragraph every time something went wrong. None of it throws an error. It just makes every session a little slower and a little less focused, and you do not notice until the agent starts ignoring a rule you know is in there.

NOTE: This is the maintenance half of your setup. If you have not built the setup yet, start with [my day-one setup](/blog/claude-code-day-one-setup) and [the CLAUDE.md file](/blog/claude-code-claude-md-file), then come back here in a month.

How to run /doctor in the Claude Code desktop app

In the desktop app, open a local session on the project you want checked, type / in the prompt box, and pick doctor from the list, or just type /doctor and send. /doctor is a bundled skill, which means it is a prompt handed to Claude rather than a terminal-only panel, so it runs in a desktop session the same way it runs anywhere else. Claude reads your setup, writes up what it found, and then asks which fixes you want applied.

1. Open the project in a local session. The checkup looks at the project's own CLAUDE.md and .claude folder as well as your personal settings, so run it from the project, not from an empty folder.
2. Type /doctor and send. Let it finish before you reply. The report is the useful part.
3. Read the findings and answer the questions. It will ask before trimming a file, turning something off, or changing a setting.
4. Commit the changes to the project's CLAUDE.md and .claude folder in git, so a bad trim is one revert away. [How I use Claude Code with git](/blog/use-claude-code-with-git) covers the habit.

If you also live in the terminal, there is a separate command, claude doctor, typed at the shell rather than inside a session. It prints read-only installation and settings diagnostics without starting a session. That is the one to reach for when Claude Code will not start at all. Everything else in this post is the in-session /doctor.

The five things /doctor checks, and what to do with each

The report groups into five kinds of finding. Each one points at a different problem, and each one has a clear right answer most of the time.

The unused-extension check is the one that pays back fastest. Every skill in the skill listing adds to your context on every turn, whether Claude uses it or not. If you want the per-skill numbers on their own, /skill-doctor shows what each skill costs and how often it gets used. [What actually eats your limit](/blog/claude-code-token-usage) explains why this adds up over a long day.

What /doctor prompt-audit does, and why it matters this week

/doctor prompt-audit is a different job from the checkup. Instead of looking at your install, Claude reads your instructions: your CLAUDE.md, CLAUDE.local.md and AGENTS.md files, plus the rules, skills, commands, subagents and output styles under .claude in the project and in your home folder. It looks for three things: instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. You get a report and a set of proposed edits, and nothing in your files changes until you ask Claude to apply them.

The timing is the point. Claude Sonnet 5.5 landed in Claude Code this week, a week after Opus 5.5, and a lot of the instructions people carry around were written to push an older model into behaving. Shouting in capitals, repeating the same rule three times, warning it not to be lazy. An instruction written to push an older model can land differently on a newer one, and instructions written for older models are exactly what the audit is built to flag. It is the fastest way I know to find those lines, because it reads every file at once and I do not have to remember where I put them. [The Sonnet 5.5 post](/blog/claude-sonnet-5-5) covers what changed in the model itself.

• Audit everything: type /doctor prompt-audit with no path.
• Audit one thing: pass a path, for example /doctor prompt-audit .claude/skills/deploy, when you only changed one skill.
• Check your version first. The audit needs Claude Code v2.1.283 or later. The desktop app updates itself on launch on macOS and Windows, and you can check by hand from the Claude menu, then Check for Updates. In the terminal, claude --version tells you where you are.
• If the audit refuses to run, check whether you have turned off bundled skills. It runs through the bundled /claude-api skill, so it is unavailable when that skill is disabled in skillOverrides or with disableBundledSkills.

The CCC Checkup Cadence: when to run it

The CCC Checkup Cadence is four triggers. Any one of them means run /doctor, and the first one also means run /doctor prompt-audit.

1. A new model ships. Run the prompt audit on everything, read the proposed edits, and accept the ones that remove old coaching. Then run the normal checkup.
2. You installed or removed a batch of things. Three new MCP servers, a plugin, a folder of skills from a course. Run the checkup the same day so you see their context cost before you forget why you added them.
3. A session starts feeling slow or forgetful. Before you blame the model, run the checkup. Slow hooks, a crowded skill listing and an oversized CLAUDE.md all look like a slow or distracted agent from the outside. [Why Claude Code feels slow](/blog/why-is-claude-code-slow) covers the rest of that list.
4. It has been a month. Put it on the calendar, or better, make it a [scheduled task in the desktop app](/blog/claude-code-scheduled-tasks) that runs the checkup on the project and leaves the report for you to review.

How to read the CLAUDE.md trims without losing what matters

The trim is the one finding I read line by line, because it deletes words I wrote. The rule it follows is sound: cut what Claude can derive from the codebase, like directory layouts, dependency lists and architecture overviews, and keep pitfalls, reasons, and conventions that differ from tool defaults. The official guidance is to keep each CLAUDE.md under 200 lines, because longer files use more context and get followed less reliably. Claude Code also warns at startup, and in /status, when a file is over that length.

Where I push back is on anything that records why. "We use a queue here because the payment webhook times out" looks like architecture, but it is a pitfall, and it stays. If the trim proposes cutting a line like that, say no and keep going. Instructions that only matter in one part of the code are better moved than cut: [path-scoped rules in .claude/rules](/blog/claude-code-rules-directory) load only when Claude works on matching files, and the checkup will offer to move always-loaded guidance into skills and nested CLAUDE.md files for exactly this reason.

Run your first checkup today

Open your busiest project in the desktop app, run /doctor prompt-audit, then /doctor, and commit whatever you accept. It takes a few minutes, it asks before it touches anything, and it is the cheapest way I know to get a setup back to the size it was when it worked best. If you want the finished shape of a clean setup to compare against, [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) and [context engineering](/blog/claude-code-context-engineering) are where I would look next.

NOTE: Inside Claude Code Club, members post what their checkup and prompt audit flagged, which trims they accepted, and which ones they reverted. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the fastest way to see what a lean setup looks like on real projects instead of guessing.

FAQ

What is Claude Code doctor?

It is the /doctor command in Claude Code, also available as /checkup. It runs a setup checkup: install health, PATH problems, unparseable settings, unused skills, MCP servers and plugins weighed against their context cost, slow hooks, newer versions, and CLAUDE.md trims. It reports first and asks before changing anything.

What is the difference between /doctor and claude doctor?

/doctor runs inside a session and can fix what it finds after asking. claude doctor is typed at the terminal and prints read-only installation and settings diagnostics without starting a session, which makes it the right tool when Claude Code will not start.

What does /doctor prompt-audit do?

It has Claude read your CLAUDE.md, CLAUDE.local.md and AGENTS.md files plus the rules, skills, commands, subagents and output styles under .claude, and flag instructions written for older models, references to files or commands that no longer exist, and files that contradict each other. It proposes edits and changes nothing until you ask. It needs Claude Code v2.1.283 or later.

Does /doctor work in the Claude Code desktop app?

Yes. /doctor is a bundled skill, so you run it from the prompt box in a local desktop session by typing /doctor or picking it from the slash command list. The separate claude doctor command is terminal-only.

How often should I run the Claude Code checkup?

After a new model ships, after you install or remove a batch of skills or MCP servers, whenever sessions start feeling slow or forgetful, and once a month regardless. After a model release, run /doctor prompt-audit first.

• Price an AI agent like the role it fills, not the build. Find the job it takes off someone's desk, get the client to say what that job costs them now, and quote a setup fee plus a monthly fee that are an obvious fraction of it. Never quote build hours.
• An agent is not a chatbot and not an automation. A chatbot answers. An automation follows fixed steps. An agent decides its own steps and takes actions across the client's tools, which is why supervision is part of the product and part of the price.
• Quote three tiers by trust level: Assist (the agent drafts, a person approves every action), Operate (it acts alone inside written limits and escalates the rest), and Own (it runs a whole job end to end with a weekly review). Model usage is always its own line, passed through or capped, never buried in a flat fee.

How much to charge for an AI agent

How much to charge for an AI agent comes down to two questions: what job does it take off someone's desk, and how much is it trusted to do without a person checking? The job sets the value. The trust level sets the tier. Quote a fixed setup fee for building it and a monthly fee for running and supervising it, both sized as an obvious fraction of what that job costs the client today, and put model usage on its own line. Do not quote build hours. With Claude Code, the first working version of an agent can come together fast, and a client who hears how fast will price it like a quick job, even when it is doing the work of part of a person.

This is the CCC Role Pricing Method, and it exists because agents are the offer where new builders get the shape of the price wrong, not just the number. They quote a one-off build like a website, hand it over, and then spend the next six months answering messages about why the agent did something odd on a Tuesday. An agent is closer to a hire than a deliverable. It needs a job description, limits, someone checking its work, and a budget for what it spends. Price all four, or you end up providing the last three for free.

NOTE: The fixed-fee logic under every number here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project). If the client actually wants something that answers questions, that is [a chatbot](/blog/how-much-to-charge-for-a-chatbot); if it is a fixed sequence of steps, that is [an AI automation](/blog/how-much-to-charge-for-an-ai-automation). Both are simpler to price, and worth checking before you quote an agent.

An agent is not a chatbot or an automation, and the price shows it

The difference is who decides the steps. A chatbot answers questions from a fixed source. An automation runs the same steps every time: when a form comes in, add a row, send an email. An agent is given a goal and decides the steps itself, reading, choosing a tool, taking an action, checking the result, and going again. That is what makes an agent valuable, and it is also what makes it riskier, because it can take an action nobody wrote down in advance.

Say this out loud on the call. Plenty of clients ask for "an agent" when they need an automation, and the automation is cheaper, safer and faster to deliver. Telling them so is the fastest way to be trusted with the agent they will want next year.

Write the job description before you write a number

You cannot price an agent until you can describe its job the way you would describe a role you were hiring for. Five questions get you there, and the client should answer each one in their own words.

• What is the job? One sentence: triage the support inbox and resolve the routine tickets, qualify inbound leads and book the good ones, reconcile the weekly orders against the invoices. If it takes a paragraph, it is two agents.
• Who does it now, and how much of their week does it take? Let the client say it. That person's time is the number your quote sits next to.
• What is it allowed to do alone? Read only, draft for approval, or take the action. This answer picks the tier.
• What must it never do? Refund above an amount, email a customer about legal matters, delete anything. These become written limits, and the limits are part of the deliverable.
• Who checks its work, and how often? If the answer is nobody, the honest quote includes you doing it, or the agent stays in the lowest tier.

Say the job description back before you quote. "So the agent handles the routine support tickets your two coordinators spend most of their mornings on, it can close a ticket alone but cannot issue refunds, and your ops lead reviews its log on Fridays" is a sentence the client has to agree with. Once they have, your price is a fraction of a number they already accepted. The full question set is in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

The CCC Agent Price Ladder: three tiers by trust

Present three tiers for the same job, and let the client choose how much they want the agent to do alone. The tiers are not more features. They are more trust, with more limits, logging and review built to earn it.

Most clients land on Operate once they see the table, because Assist still keeps a person clicking all day and Own asks for a level of trust they have not built yet. That is fine. Start them there, show them the log for two months, and the move to Own becomes their idea. The three-tier shape is the same one in [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp) and [how much to charge for an AI workshop](/blog/how-much-to-charge-for-an-ai-workshop); the tiers change, the logic does not.

Put model usage on its own line

An agent spends money every time it works, and that spend moves with volume you do not control. Models are billed by usage. Claude Sonnet 5.5, for example, is priced at $2 per million input tokens and $10 per million output tokens on the Anthropic API. A busy month for the client is a busy month for the agent, and if usage is buried inside a flat monthly fee, their best month is your worst one.

• Best: the agent runs on the client's own API account, and they pay usage directly. You never carry the bill, and the key never leaves their control.
• Next best: you pass usage through at cost with a small handling margin, invoiced monthly with the numbers attached.
• If they insist on one flat fee: include a stated usage allowance and a written overage rate, and set a hard spend cap on the account so a runaway loop cannot become a surprise.

Whichever you choose, set a spend limit before the agent goes live and tell the client what it is. An agent with real access and no ceiling is the one thing in this business that can cost a client money overnight. [Is Claude Code safe for client work](/blog/is-claude-code-safe-for-client-work) covers how I explain access and limits to a client, and [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) covers the clause that makes the usage line binding.

What moves an agent quote up or down

• The access it needs. Read-only access to one inbox is a small line. Write access to billing, a CRM and customer email is a large one, because every system it can change needs its own limits and its own tests.
• The cost of a wrong action. An agent that can send a refund or email a customer needs approval paths, logging and a way to stop it. The more a mistake costs, the more of the price is the guardrails, and that is correct.
• Volume. Ten cases a day and a thousand are different agents. Volume changes usage, review time and how carefully the exception path has to be built.
• How messy the inputs are. Clean forms are cheap. Free-text emails in three languages with attachments are not.
• Who reviews it. If the client has someone to read the log, the monthly fee is lighter. If that someone is you, it is in the price.
• Handover. If the client wants to own and change the agent themselves later, the documentation and training are their own line. [How to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project) covers what that includes.

The mistakes that turn an agent into an unpaid on-call job

• Selling it as a one-off build. An agent with no monthly fee is an agent you support for free. The monthly fee is for supervision and limits, not for hosting.
• Unlimited usage in a flat fee. The client's growth becomes your cost. Usage goes on its own line, every time.
• No written limits. If what the agent may not do is not written down, every odd action becomes an argument about whose fault it was.
• No log. If you cannot show what it did and why, you cannot defend it, improve it, or move the client up a tier.
• No off switch. Agree how the agent gets paused and who can do it before it goes live, not after it does something at 2am.
• Starting at Own. Full autonomy on day one means the first mistake happens with nobody watching. Start at Assist or Operate and let the log earn the upgrade.
• No deposit. [How much deposit to charge before an AI project](/blog/how-much-deposit-to-charge-before-an-ai-project) covers the number. The setup fee is a real project and gets paid like one.

How to present the agent number so it closes

Lead with the job description you agreed on, then put the three tiers under it, with the usage line and the spend cap written out beside them. "You said the routine tickets take most of your coordinators' mornings; here are three ways to hand that job to an agent, depending on how much you want it doing alone" is a sentence a client can say yes to on the call. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes) with the job in one line, the limits, the review rhythm, and the setup and monthly fees. If they push on price, the answer is the Assist tier, not a discount, and [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the words.

The agent that works becomes the client's favourite thing you have built, and the log you have been sending them every month is the best case study you will ever have. [How to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) is what happens next, and usually the next job is a second agent.

NOTE: Inside Claude Code Club, members share the agent quotes they actually sent, the limits they wrote, and how they set up usage billing with clients. It is $9 a month at https://www.skool.com/claudecodeclub/about, and it is the quickest way to see what real agent pricing looks like before you send your first number.

FAQ

How much should I charge for an AI agent?

Price it against the job it takes off someone's desk, not your build hours. Get the client to say what that job costs them now, then quote a fixed setup fee and a monthly fee that are an obvious fraction of it, in three tiers by trust: Assist, Operate, and Own. Put model usage on its own line.

What is the difference between an AI agent and an AI automation for pricing?

An automation follows fixed steps, so you price the hours it removes. An agent decides its own steps and takes actions with real access, so you also price the limits, logging and supervision that make that safe. That is why an agent always carries a monthly fee.

Should AI agent pricing include the model usage costs?

Keep usage separate. Models are billed by usage, and a busy month for the client means more usage. The best setup is the agent running on the client's own API account; the next best is passing usage through at cost with a small margin. If you must include it, state an allowance, an overage rate, and a hard spend cap.

Should I charge a monthly fee for an AI agent?

Yes. The monthly fee pays for reviewing the agent's log, adjusting its limits as the business changes, and fixing what breaks when connected tools change. Without it, you are supporting the agent for free.

Which tier should a new AI agent client start on?

Assist or Operate. Assist has a person approve every action, which is the easiest yes. Operate lets the agent handle routine cases alone inside written limits. Move to Own only after a couple of months of logs show it can be trusted with the whole job.

• Claude Code computer use is a research preview in the desktop app on macOS and Windows for Pro and Max plans. It is off until you turn it on under Settings, General, Desktop app, and on a Mac you also grant Accessibility and Screen Recording. Then Claude can open apps, read the screen, click, type, and drag.
• Claude reaches for it last. A connector, a shell command, the Claude in Chrome extension, and the iOS Simulator pane all come first. Screen control is reserved for native apps and tools with no API, which is also where it earns its keep.
• Every app is approved per session, and the level of control is fixed by category: browsers and trading platforms are view-only, terminals and IDEs are click-only, everything else is full control. The CCC Blast-Radius Rule decides what I approve: only apps where the worst click is something I can undo in a minute.

Claude Code Computer Use

Claude Code computer use lets Claude open the apps on your machine, see your screen, and click, type, scroll, and drag the way you would. In the desktop app it is a research preview on macOS and Windows, it needs a Pro or Max plan, and it is off by default. You turn it on under Settings, General, in the Desktop app section, and on a Mac you grant two system permissions, Accessibility and Screen Recording, before the toggle takes effect. After that, the first time Claude needs a specific app in a session, it asks, and you click Allow for this session or Deny. It is not the Browser pane and it is not the Chrome extension. Those handle web pages. Computer use is for everything that has no web page, no command line, and no API: a native Mac app, a design tool's export dialog, a simulator, a settings window.

I turned it on the week I needed Claude to test a small native utility I had it build for the club's publishing queue, an app with no browser surface at all. Below is what it did, what it asked for, what I said no to, and the order Claude tries other tools before it touches the screen. That order is the most useful thing on this page, because it is why computer use is rarely the tool you end up using and always the one you are glad exists.

NOTE: This post assumes [the Claude Code desktop app](/blog/claude-code-desktop-app). The terminal version has computer use too, macOS only, enabled by switching on the built-in computer-use server in /mcp, and it shares the same engine. If your job is testing a web app, stop here and read [Claude Code browser](/blog/claude-code-browser) instead; that is the right tool and it needs none of this.

The CCC Last-Resort Ladder: what Claude tries before it touches your screen

Computer use is the broadest tool Claude has and the slowest, because every step is a screenshot, a look, and a click. So Claude tries the most precise tool first and only falls through to screen control when nothing else reaches the task. I call the order the CCC Last-Resort Ladder, and if you learn nothing else here, learn this, because it explains most of the moments where you enable computer use and then watch Claude not use it.

1. A connector. If the service has one, GitHub, Slack, Linear, or an MCP server you added, Claude uses that. Structured, fast, no screenshots.
2. A shell command. If the task is a build, a test run, a file operation, Claude uses Bash. The sandboxed one.
3. The Claude in Chrome extension. If the task is browser work and you have the extension set up, Claude drives your real browser as you.
4. The iOS Simulator pane. If the task is running or testing an iOS app, the desktop app opens its dedicated simulator pane, which works without computer use switched on at all.
5. Computer use. Only if none of the above apply. Native apps, hardware control panels, proprietary tools with no API.

The per-app tiers, covered next, reinforce the ladder on purpose. Browsers are capped at view-only and terminals at click-only even when computer use is on, so Claude is steered back to the Browser pane or the sandboxed shell rather than clicking around in a Chrome window. My first real prompt after enabling it was to check a page in the club site, and Claude told me it would rather do that in the Browser pane. It was right. [Claude Code skills vs MCP servers](/blog/claude-code-skills-vs-mcp-servers) is the same instinct one rung up: give Claude the precise tool and it stops needing the blunt one.

How to turn on Claude Code computer use in the desktop app

1. Update the desktop app first. The toggle only appears on a current build; download or update from claude.com/download, then restart.
2. Open Settings, General, and find Computer use under the Desktop app section. Turn it on. On Windows that is the whole setup. If you do not see the toggle, check that you are on macOS or Windows with a Pro or Max plan; it is not available on Team or Enterprise plans.
3. On a Mac, grant Accessibility, which lets Claude click, type, and scroll, and Screen Recording, which lets Claude see the screen. The Settings page shows the status of each, and clicking a denied badge opens the right System Settings pane.
4. Leave the desktop app running. Computer use needs it open, which matters if you are used to closing it and working from the terminal.
5. Ask for something only the GUI can do. If you ask while it is still off, Claude tells you it could do the task if you enabled computer use, which is a decent way to find out whether a task actually needs it.

Two settings live next to the toggle and both are worth setting on day one. Denied apps is a list of apps Claude will never be allowed to control, rejected without a prompt; mine has my password manager and my banking app in it. Unhide apps when Claude finishes controls whether the windows Claude hid while it worked come back on their own. More on the hiding below.

App permissions: three fixed tiers and a prompt per session

Enabling computer use does not hand Claude the whole machine. The first time Claude needs a given app in a session, a prompt appears in the chat naming the app, any extra access it wants such as the clipboard, and the level of control that app category gets. You click Allow for this session or Deny. Approvals last for that session and then expire; in sessions started from Dispatch on your phone they expire after 30 minutes and re-prompt. The tiers are fixed by category and you cannot raise them.

Apps with broad reach show an extra warning in the prompt. Terminals are flagged because approving one is equivalent to shell access. Finder on a Mac, or File Explorer on Windows, can read or write any file. System Settings can change the system. None of these are blocked; the warning is there so you decide whether the task justifies it. One catch to know: a denied app can still be affected indirectly by an action in an allowed app, so the denied list is a wall around direct control, not a wall around outcomes.

TIP: The CCC Blast-Radius Rule is the only approval policy I need: approve an app only if the worst thing a wrong click could do inside it is something I can undo in about a minute. A build I am testing, a design tool with version history, a simulator: yes. Finder, System Settings, anything with a Send or Pay button: no, and it goes on the denied list so I am never asked mid-task. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers the modes the Bash and file tools run under; computer use sits outside those and this rule is its equivalent.

What computer use caught on a real native build

The utility I mentioned is a small menu bar app that watches the club's publishing queue and shows a count. Claude wrote it, compiled it, and, once computer use was on, launched it and clicked through it before telling me it was done. That is the part I could not get any other way: there was no page for the Browser pane to load and no test harness worth writing for an app this small. It opened the preferences window, changed the refresh interval, and reported that the label updated. Then it found the thing I would have shipped. At the default window size, the Save button in that preferences window sat below the visible area, so the interval could be changed and never saved. Claude resized the window to reproduce it, screenshotted the clipped state, fixed the layout, and re-ran the check.

A few things about how it works on screen are worth knowing before you rely on it. While Claude is controlling the screen it hides your other windows so it only interacts with the app you approved, and restores them when the turn ends, unless you turned that setting off. On macOS there is also a background mode where Claude works in the approved apps while you keep using the machine. Screenshots are downscaled automatically before they reach the model, so you do not have to lower your display resolution on a Retina screen; if Claude cannot read small text, make the text bigger in the app, not the screen smaller. And the documented emergency stop in the terminal version is the Esc key, which aborts the current action from anywhere and is consumed so nothing on screen can use it to dismiss a dialog.

The cost is time and tokens. A screenshot-look-click loop is slower than a shell command by a wide margin, so I do not leave computer use running on a long session where nothing native changes. [Claude Code context management](/blog/claude-code-context-management) covers why screenshots in the context window add up, and [how to debug with Claude Code](/blog/how-to-debug-with-claude-code) is where I send people once computer use has shown them the failing state, because from there it is ordinary debugging.

The trust boundary is different from the sandbox, and that is the whole risk

The sandboxed Bash tool runs commands in an isolated environment. Computer use does not. It runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the boundary is a different shape, and the guardrails are the tiers, the per-session prompt, the sentinel warnings, the denied list, and the fact that in the terminal version Claude never sees its own terminal window in a screenshot, so a prompt inside your session cannot feed back into the model. Those are real, and I still treat computer use as the one Claude Code feature where my judgment is the main safety control rather than a backup.

Practically, that means three habits. I only approve the app the task is about. I never run computer use on a machine that is signed into a client's systems, which is the same line I draw in [is Claude Code safe for client work](/blog/is-claude-code-safe-for-client-work). And I keep the Browser pane and the Chrome extension set up so Claude has somewhere better to go for anything web-shaped, which the ladder above then enforces for me. [Claude Code's sandbox, explained](/blog/claude-code-sandbox-explained) is the other half of this picture: what the Bash tool isolates, and the short list of things it was never meant to cover, computer use being one of them.

What computer use will not do, and what to reach for instead

• Type into a browser or a terminal. Browsers are view-only and terminals are click-only, by design. Use the Browser pane or the Chrome extension for the web, and let the sandboxed shell run commands.
• Test an iOS app by clicking the simulator. In the desktop app that request opens the iOS Simulator pane, which does not use screen control and does not need computer use enabled. [How to build a mobile app with Claude Code](/blog/build-a-mobile-app-with-claude-code) is where that pane earns its keep.
• Run on Team or Enterprise plans, through a third-party provider like Bedrock or Foundry, or in non-interactive mode with the -p flag. It is a Pro and Max research preview signed in through claude.ai.
• Control an app on the denied list, or control any app without asking once per session. If you want fewer prompts, that is what a connector or an MCP server is for; [what are MCP servers and why they matter](/blog/what-are-mcp-servers-and-why-they-matter) explains the trade.

Turn it on, approve one app, and watch what Claude does first

Enable it, set the denied list before you run anything, then give Claude a task that genuinely has no other route: a native build to click through, a GUI-only export, a settings window to verify. Watch the first prompt, approve exactly one app, and read what it reports. You will learn in ten minutes whether computer use belongs in your workflow, and the answer for most builders is: rarely, and when it does, nothing else will do.

NOTE: Inside Claude Code Club, members post their denied-app lists, the native builds they let Claude click through, and the prompts that made Claude fall back to the Browser pane instead. It is $9 a month at https://www.skool.com/claudecodeclub/about, and once Claude can test the native side of a build, [Claude Code scheduled tasks](/blog/claude-code-scheduled-tasks) is how I make the checks run without me.

FAQ

What is Claude Code computer use?

A research preview in the Claude desktop app, on macOS and Windows, that lets Claude open your apps, see your screen, and click, type, scroll, and drag the way you would. It is for tasks with no command line, web page, or API, such as native apps, simulators, and GUI-only tools. It needs a Pro or Max plan and is off until you enable it in Settings.

How do I enable computer use in Claude Code?

In the desktop app, open Settings, General, and turn on the Computer use toggle under the Desktop app section. On Windows that completes setup. On macOS, also grant Accessibility and Screen Recording in System Settings; the Settings page shows the status of each. In the terminal version, run /mcp and enable the built-in computer-use server, macOS only.

Is Claude Code computer use safe?

It runs on your real desktop, not in the sandbox, so the trust boundary is different from the Bash tool. The guardrails are per-app approval each session, fixed control tiers that cap browsers at view-only and terminals at click-only, warnings on apps with broad reach like Finder and System Settings, a denied-apps list, and action checks that flag potential prompt injection from on-screen content. Approve only the app the task needs.

Why is Claude not using computer use even though I enabled it?

Claude tries more precise tools first: a connector or MCP server, a shell command, the Claude in Chrome extension, and the iOS Simulator pane. Screen control is the fallback for tasks none of those reach. If the job is a web page, Claude will prefer the Browser pane or the extension, and browsers are view-only under computer use anyway.

Does Claude Code computer use work on Team or Enterprise plans?

No. The docs list it as a Pro and Max research preview. It is also not available through third-party providers such as Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry, or in non-interactive mode with the -p flag.

• Price an AI workshop against the change it produces: one named workflow the team does with Claude Code after the session that they did by hand before. Get the client to say what that workflow costs them now, then quote a fixed fee that is an obvious fraction of it. Never quote a day rate.
• Define the workshop on paper as one workflow out the door: the team arrives with a task they do by hand and leaves with it running in the Claude Code desktop app on their own machines. Everything else is a second workshop or a retainer.
• Quote three tiers: Session (one workflow, one group, one sitting), Sprint (Session plus pre-work on their real files and two weeks of follow-up), and Rollout (Sprint plus a setup of their shared instructions and a second session for the next team). The Rollout tier is where the retainer starts.

How much to charge for an AI workshop

How much to charge for an AI workshop comes down to one question: what will this team do differently the week after, and what is that worth to the business? Nobody books a workshop because they want a workshop. They book it because a piece of work is slow, a manager has seen what Claude Code can do, and they want their own people doing it. That change has a price the client can already feel, in the hours a task takes or the backlog it creates. Quote a fixed fee that is an obvious fraction of that number, built around one workflow the team leaves with running, in three tiers. Do not quote a day rate. The moment you say "a full day is this much," you have told the client your ceiling and invited them to ask for a half day.

This is the CCC Change-Value Method, and it exists because the workshop is the offer that new Claude Code builders underprice the most. It feels like teaching, teaching feels like a day rate, and the day rate feels like it should be modest because you are not shipping code. But a room of people who go back to their desks and run one workflow with Claude Code every day is worth more to that company than most of the builds you will sell them, and the workshop is also the cheapest possible way for a company to find out whether it wants you on retainer. Price it like the front door it is.

NOTE: This is the pricing half. The fixed-fee logic under every number here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project), and the argument for never selling time is in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds). The curriculum half, what to actually teach, is what the club's classroom is for.

Find out what the team has to do differently before you say a number

You cannot price a workshop until you know what it is meant to change, so the first call is a measurement, not a pitch. Five questions get you there, in this order, because each one makes the next easier to answer honestly.

• What is the task you want this team doing with Claude Code by the end? Writing the internal tools they currently request from engineering, cleaning the weekly report, drafting the client proposals. If the answer is "using AI," the workshop is not defined yet and the price has to include defining it.
• How do they do it now, and what does that cost? Let the client say it. A task that takes someone most of a day each week has a cost in that person's salary, and the client knows it. Your quote is going to sit next to that number.
• Who is in the room, and are they all doing the same job? Ten people who share one workflow is a workshop. Ten people from four departments is four workshops, and the price should say so.
• What do they already have? Whether everyone has a Claude plan that includes Claude Code, whether the desktop app is installed, and whether anyone on the team has used it changes the day completely. The [day-one setup](/blog/claude-code-day-one-setup) is either pre-work or the first hour of your session, and it is priced either way.
• What happens on Monday? Who checks that people are actually using it, and what does the manager want to see in a month? If nobody owns this, the workshop will evaporate, and the honest quote includes the follow-up that stops that.

Say the answers back before you quote. "So the goal is that the ops team builds their own reporting scripts in Claude Code instead of waiting on engineering, and that wait is currently costing you roughly this a month" is a sentence the client has to agree with, and once they have, your price is a fraction of a number they already accepted. The full question set I run on every deal is in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

Define the workshop as one workflow out the door, or it becomes a demo

The CCC One-Workflow Rule: an AI workshop is one team, one task they do by hand today, and by the end of the session that task is running in the Claude Code desktop app on their own machines with their own files. That sentence is the scope. If the client cannot name the task, the workshop is not ready to be booked, and the price should cover the discovery that gets it there. If they can, everything outside that sentence is a second session, priced as one, and written on the proposal as a second session so nobody is surprised.

This rule is what makes the fixed fee safe, and it is also what makes the workshop work. A session that tours every Claude Code feature produces a room of impressed people who change nothing. A session where each person leaves with the desktop app open, a project folder set up, and one real task done in it produces a habit. Teach the desktop app, keep the terminal optional, and make the last hour hands-on with their actual work. [How to sell AI builds to non-technical clients](/blog/sell-ai-to-non-technical-clients) has the language for the room; the same rule applies to the manager who booked it.

The CCC Workshop Price Ladder: three tiers

Present three tiers, all built around the same workflow, and let the client pick how much change they want guaranteed. The bottom tier is for a manager who wants their team to see it work. The middle is for a manager who wants their team to keep doing it. The top is for a company that has already decided and wants the next team queued up.

The middle tier wins because of the follow-up. A session proves that Claude Code can do the task. Two weeks of questions and a working setup on everyone's machine proves that this team will keep doing it, and that is the change the manager is actually buying. Put the difference in the table and they will choose it themselves. The three-tier shape is the same one in [how much to charge for a chatbot](/blog/how-much-to-charge-for-a-chatbot), [how much to charge for an AI automation](/blog/how-much-to-charge-for-an-ai-automation), and [how much to charge for an MVP](/blog/how-much-to-charge-for-an-mvp); the tiers change, the logic does not.

What moves a workshop quote up or down

• Seats. More people means more hands-on time and more setup problems on the day. Price by group, with a cap, and quote a second group as a second session rather than squeezing thirty people into a room built for twelve.
• Pre-work on their real material. Building the workflow on the client's own files before the day is the single thing that separates a demo from a change, and it is priced as work, because it is. If they cannot share files in advance, say so on the quote and price the Session tier only.
• Setup state. A team with plans, the desktop app installed, and a shared folder ready is a workshop. A team with none of that is a setup engagement plus a workshop, and the setup has its own line. [Claude Code desktop app](/blog/claude-code-desktop-app) is what I send the client's IT contact a week before, so that line is as small as possible.
• On-site or remote. Travel is a line item, never absorbed. Remote sessions are shorter and more of them, and the price reflects the format, not the location.
• Who is in the room. Practitioners want the workflow. Leadership wants to know what to ask for and what it costs; that is a different, shorter session with a different price, and putting both groups in one room serves neither.
• Recording and material rights. If the client wants to reuse your recording and slides internally for people who were not there, that is a licence, and it is priced separately from the day.
• The follow-up window. Two weeks is the default. A month, or a second office-hours call, moves the Sprint price up, and it is worth it to the client because that is where the habit forms.
• Whether it feeds a build. If the workshop is the discovery for a project you will then quote, price it like [paid discovery](/blog/paid-discovery-phase-ai-projects), and say on the proposal that the fee is credited if they go ahead.

The mistakes that turn a paid workshop into a free lunch-and-learn

• Quoting a day rate. "A full day is this much" becomes the ceiling and the half-day request arrives within the hour. Talk about the workflow and the change, nothing else.
• Doing the first one free to "show value." A free session is a demo, and the company will treat the next one like a demo too. If you want a low-risk way in, sell the Session tier small, not free; [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the words.
• No pre-work. If the first hour is people installing the desktop app and finding their login, you have sold a setup session at workshop prices and delivered a bad one. Send the setup a week ahead, and check it.
• Touring features instead of doing the task. The room applauds, nobody changes. One workflow, on their files, running on their machines, or it did not happen.
• Letting the follow-up become free consulting. Two weeks of questions about the workflow is included. A new workflow, a build request, or a second team is a new line, and the retainer conversation, not a favour.
• Handing over the material without a licence. Your slides and recording are the product a second time. Price the internal reuse, or keep it.
• No deposit. A workshop is a date on a calendar and a room full of people whose time has been booked. [How much deposit to charge before an AI project](/blog/how-much-deposit-to-charge-before-an-ai-project) covers the number; for a dated session it is the full fee before the day.

How to present the workshop number so it closes

Lead with the change you agreed on, then put the three tiers under it. "You said the goal is that your ops team builds their own reports in Claude Code instead of waiting on engineering, and we agreed what that wait costs; here are three ways to make that happen" is a sentence a manager can say yes to on the call, and it is a sentence they can repeat to their director without you in the room. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes) with the workflow written in one line, the tier scope, the pre-work you need from them and the date you need it by, the date of the session, and the follow-up window with an end date. [How to package an AI service](/blog/how-to-package-an-ai-service) is how the same workshop becomes an offer you can sell to the next company without rewriting it.

The push-back you will hear is "can't they just watch some videos" or "our engineering team could run this internally." Both are answered by the change: videos do not put the workflow on anyone's machine, and engineering has the backlog the workshop exists to relieve. If the objection is really about budget, the honest answer is the Session tier, and ["let me think about it"](/blog/let-me-think-about-it-objection) covers the stall that follows a workshop quote more than any other, because a date on a calendar feels bigger than a build that starts whenever.

Quote your next workshop against the change, not the day

A workshop is the best front door in this business when it is priced right and the cheapest day you will ever sell when it is not. Get the workflow and its cost from the client, write it in one line, quote the ladder, take the fee before the date, and put an end date on the follow-up. The company whose team is now using Claude Code every day needs the shared instructions maintained, the next team trained, and the first real build scoped; [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) is what that conversation looks like, and [the memory engineering retainer](/blog/selling-claude-code-memory-engineering-retainer) is the shape it usually takes.

NOTE: Inside Claude Code Club, members share the workshop quotes they actually sent, which tier the client picked, and the pre-work checklist they now send a week before every session. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if the client wants a case study out of the workshop, [how to get testimonials for your AI agency](/blog/how-to-get-testimonials-for-your-ai-agency) is how to ask on the last day while the room is still warm.

FAQ

How much should I charge for an AI workshop?

Price it against the change it produces, not the hours. Find out the one task the team should be doing with Claude Code afterwards, get the client to say what that task costs them now, and quote a fixed fee that is an obvious fraction of that number, in three tiers: Session, Sprint, and Rollout. Never quote a day rate; it becomes your ceiling the moment you say it.

Should I charge per person or per session for an AI workshop?

Per group, with a cap on seats, and quote a second group as a second session. Per-person pricing invites the client to trim the list, and the value of the workshop is that a whole team changes how it works, which does not scale down neatly by headcount.

What should an AI workshop include?

One workflow out the door: one team, one task they do by hand today, running in the Claude Code desktop app on their own machines with their own files by the end. A setup check at the start, the workflow built live, a recording and a one-page recap. Pre-work on their real material and a follow-up window belong in the Sprint tier; shared instructions, templates, and a second team belong in Rollout.

Should I run the first AI workshop for free to win the client?

No. A free session is treated as a demo and the next one will be too. If you need a low-risk entry, sell the Session tier small rather than free, and if the workshop is really discovery for a build you will quote afterwards, price it as paid discovery with the fee credited if they go ahead.

How do I stop a workshop from turning into free consulting afterwards?

Put an end date on the follow-up window and write what it covers: questions about the workflow you taught, for that team, for that period. A new workflow, a build request, or a second team is a new line on a new proposal, and that is the start of the retainer conversation, not a favour you owe.

• Claude Sonnet 5.5 came out September 28, 2026. It costs the same as Sonnet 5 ($2 per million input tokens, $10 output) and runs over 30% faster.
• On Terminal-Bench 4.0, a test where the AI does a real job alone, Sonnet 5.5 scored 70.6%. Sonnet 5 scored 10.3%. Opus 5.5 scored 66.4%.
• Opus 5.5 still wins every other test on the scorecard. Use Sonnet 5.5 for everyday work and Opus 5.5 for big builds and hard problems. In Claude Code, type /model and pick Sonnet 5.5.

Claude Sonnet 5.5 Is Out Today

Claude Sonnet 5.5 came out today, September 28, 2026. Same price as Sonnet 5. Over 30% faster. And on a test of real jobs done alone, it went from 10.3% to 70.6%.

It's the second model in the Claude 5.5 family. Opus 5.5 came out September 22. Haiku 5.5 is coming in the next few weeks. I went through [Anthropic's announcement](https://www.anthropic.com/claude-sonnet-5-5) and pulled out the 10 things that matter if you build with Claude Code.

TIP: Want to see it instead of read it? Watch the old and new Sonnet race side by side on the [interactive Sonnet 5.5 page](/sonnet-5-5).

Sonnet 5.5 Wins the Race

Sonnet 5.5 writes its answers over 30% faster than Sonnet 5. It also needs far fewer tokens to finish a job, so each task costs up to 30% less.

Testers said it batches steps together, so it takes fewer of them. Balyasny ran it on 2,441 finance tasks. Sonnet 5.5 used about 121,000 tokens per answer. Sonnet 5 used 497,000. Zendesk got its support tickets processed 20% faster.

Speed is easier to feel than to read about. The interactive page runs the old and new Sonnet side by side so you can watch the gap. [Open the interactive page](/sonnet-5-5).

Sonnet 5.5 Costs the Same as Sonnet 5

The price didn't move. Sonnet 5.5 is $2 per million input tokens, $10 per million output tokens, and $0.20 per million for cache reads. That's the same as Sonnet 5.

Opus 5.5 is $4 in and $20 out, twice the price. So you get a faster, smarter model for the same money, and it uses fewer tokens per job on top of that.

How Much You Have to Babysit Sonnet 5.5

This is the number I care about most. Terminal-Bench 4.0 gives the AI a real job and lets it work alone. It only counts if the result works at the end.

Sonnet 5.5 scored 70.6%. Sonnet 5 scored 10.3%. Opus 5.5 scored 66.4%. Those are each model's best setting, where they cost about the same per job. Even on the default Medium effort, Sonnet 5.5 beats Sonnet 5's best score for less than a tenth of the cost per task.

Here's what those jobs look like:

• Fix a payments system so low-balance alerts arrive within 5 seconds.
• Fix a lead sign-up form so leads save correctly with no duplicates.
• Speed up a slow website under time limits.
• Audit medical insurance claims.

Companies saw the same thing. Base44 ran 118 real app builds. Sonnet 5.5 needed 3.6 tries per build. Opus 5 needed 7.7. It rarely stopped to ask the user questions. Box said it rechecks data in the source documents and catches errors Sonnet 5 missed. Testers also said it gets up to speed on big existing projects fast and handles tasks that run for hours.

Less babysitting means you hand it the job, go do something else, and come back to work that runs.

How Close Sonnet 5.5 Gets to Opus 5.5

Very close, for half the price. On GDPval-AA, which tests real work from 44 jobs, Sonnet 5.5 scored 1844. Opus 5.5 scored 1846. On OSWorld 2.1, Sonnet scored 80.1% and Opus 81.8%. On CursorBench 4.0, 55.5% vs 57.8%.

Opus still comes out ahead on those. But a 2 point gap at twice the price is why Sonnet 5.5 is the one I'd run most of the day.

Sonnet 5.5 Is Good at Gaming Now

Sonnet 5.5 is the first Sonnet to beat Pokémon Red working only from screenshots. It looked at the screen and played.

Creator Kevin Ngo put it this way: "When Claude Opus 5.5 sets the architecture and general framework for a game, I would feel confident in letting Sonnet 5.5 implement it." That's a good way to split the work. Opus plans, Sonnet builds.

Sonnet 5.5 Is a Design Genius

Anthropic gave Sonnet 5.5 a public company's earnings materials and a slide template. They asked for a 10-slide operating review. Two experts judged the first draft ready to send as is.

It also adds more polish to the screens and pages it builds, and it writes more clearly. Testers called it a better partner to work with. Every's Tyler Nishida summed it up in four words: "Claude Sonnet 5.5 cooks."

What People Built With Sonnet 5.5 on Day One

It came out today, so the builds are still rolling in. See what people made on day one on the [interactive Sonnet 5.5 page](/sonnet-5-5).

Every Sonnet 5.5 Score

Here's what this table says. Opus 5.5 wins every row except Terminal-Bench. Sonnet 5.5 wins that one, and it's the test closest to handing an AI a real job and walking away.

And here's what each model costs. Prices are per million tokens. In is what you send Claude. Out is what Claude writes back.

Where Opus 5.5 Still Beats Sonnet 5.5

Anthropic says Opus 5.5 is clearly stronger at complex, open-ended work that needs steady judgment over a long stretch. Two more things to know about Sonnet 5.5:

• Max effort runs for a very long time. Medium is the default for a reason.
• Higher-risk cybersecurity requests fall back to Sonnet 5, and you'll see it happen. Everyday coding and bug fixing are not affected.

On safety, Anthropic's containment tests found Sonnet 5.5 the least likely of any of their models to probe the limits of its test setup.

Here's how I'd split the work:

How to Switch to Sonnet 5.5 Today

1. In the Claude app, open the model menu and pick Sonnet 5.5.
2. In Claude Code, type /model and choose Sonnet 5.5.
3. Leave effort on Medium to start. Effort is how hard Claude thinks before it answers. Medium is the default in Claude Code and the apps.

If you're on Pro, Max or Team, you also got one free usage reset. Use it any time before October 22.

Then give it one real job you'd normally sit and watch. See how far it gets alone. And if you want the visual version, watch the old and new Sonnet race side by side on the [interactive page](/sonnet-5-5).

NOTE: Learn Claude Code. Earn income. Only $9. 👉 [Join Claude Code Club](https://www.skool.com/claudecodeclub/about)

FAQ

When did Claude Sonnet 5.5 come out?

September 28, 2026. It's the second model in the Claude 5.5 family, after Opus 5.5 on September 22. Haiku 5.5 is coming in the next few weeks.

How much does Claude Sonnet 5.5 cost?

The same as Sonnet 5: $2 per million input tokens, $10 per million output tokens, and $0.20 per million for cache reads. Opus 5.5 is $4 and $20, twice the price.

Is Sonnet 5.5 better than Opus 5.5?

On one test. Sonnet 5.5 scored 70.6% on Terminal-Bench 4.0 and Opus 5.5 scored 66.4%. Opus 5.5 wins every other test on Anthropic's scorecard, and Anthropic says Opus is clearly stronger at complex, open-ended work. Sonnet 5.5 is the better pick for everyday work at half the price.

How do I use Sonnet 5.5 in Claude Code?

Type /model in Claude Code and choose Sonnet 5.5. The default effort is Medium. In the Claude app, pick Sonnet 5.5 from the model menu.

What is the free usage reset?

Pro, Max and Team users got one free usage reset with the Sonnet 5.5 launch. You can apply it any time before October 22.

• The Claude Code browser is the Browser pane in the desktop app. Press Cmd+Shift+B on a Mac or Ctrl+Shift+B on Windows. Claude starts your dev server, opens the app, screenshots it, inspects the DOM, clicks and types, and fixes what breaks. Auto-verify does this after every edit unless you switch it off in .claude/launch.json.
• The pane is a clean browser profile with no logins. For anything that has to happen as you, in your Gmail, your CRM, your Notion, you use the Claude in Chrome extension instead, which shares your real browser's login state. The CCC Clean-or-Signed-In Rule picks between them in one question.
• External sites get two extra checks: a safety classifier reviews every click and keystroke in every permission mode, and outside Auto and Bypass a domain allowlist applies before Claude navigates anywhere new. Local dev servers need no approval at all.

Claude Code Browser

The Claude Code browser is a pane inside the desktop app's Code tab. Open it with Cmd+Shift+B on macOS, Ctrl+Shift+B on Windows, or from the Views menu. When Claude edits a web project it starts the dev server, opens the running app in that pane, and verifies its own change: it takes screenshots, checks for errors, inspects the DOM, clicks elements, fills forms, and fixes what it finds before it tells you it is done. That auto-verify step is on by default. The pane is also a tabbed browser you can use yourself, for docs or an issue tracker, and Claude can read and act on external pages there with extra safety checks. It runs in a clean profile with none of your saved logins, which is the single fact that decides when you use it and when you use the separate Claude in Chrome extension instead.

I turned the pane on for the club site the week it shipped and have not opened a second window to check Claude's work since. The interesting part is not that Claude can click a button. It is what auto-verify caught that I would have shipped, and where the clean-profile line sent me to the extension. Both are below.

NOTE: This post assumes you are in [the Claude Code desktop app](/blog/claude-code-desktop-app). The terminal version has the Chrome extension half of this story but not the pane. If you still hand Claude screenshots by hand, [Claude Code screenshots](/blog/claude-code-screenshots) is the older workflow this replaces.

The two browsers Claude Code has, and the one question that picks between them

Claude Code can drive a browser two ways, and people mix them up because both are called "browser" in the docs. The Browser pane lives inside the desktop app and uses its own clean profile. The Claude in Chrome extension lives in your real Chrome or Edge and shares your login state. The CCC Clean-or-Signed-In Rule is the whole decision: does the task need to happen as you? If no, use the pane. If yes, use the extension. I have not found a third case.

The extension has a few tricks the pane does not: it can attach files from your machine to an upload field, record a browser session as a GIF, and save screenshots to disk. The pane has one the extension does not: it is where auto-verify runs, next to the diff and the chat, without you switching windows. If you set both up, the desktop app routes browser work to the extension when the task calls for it and uses the pane for verifying your app.

How auto-verify works, and what it caught on a real build

When autoVerify is on, Claude verifies code changes after editing files. It screenshots the result, checks for errors, and confirms the change works before it finishes its response. You do not prompt for this. It is a setting in the .claude/launch.json file at the root of the folder you opened, and it defaults to on. Set "autoVerify": false in that file, or flip it from the server dropdown in the session toolbar, and the preview tools stay available but only run when you ask.

On the club site, the first change I watched it verify was a form. I asked for a required-field check on the email input. Claude made the edit, the pane reloaded, and instead of stopping there it submitted the form empty, read the page, and noticed the error message rendered but the submit button stayed disabled afterwards. It went back and fixed the button state. I would have merged the first version, because in the diff it looked complete. That is the pattern: auto-verify catches the class of bug that only exists once the page is running, and diffs never show those.

Two things to know before you rely on it. First, the pane can also open static HTML, PDFs, images, and videos from your project, so a landing page with no server still gets checked; click the file path in the chat to open it. Second, verification costs tokens and time on every edit. On a long refactor where I know the page does not change, I turn it off from the dropdown and ask for one verification at the end. [Claude Code context management](/blog/claude-code-context-management) covers why that matters on big sessions.

Set up the preview server once with .claude/launch.json

Claude detects your dev server the first time and writes the configuration to .claude/launch.json in the folder you selected when you started the session. If your project uses a different command, say yarn dev instead of npm run dev, or a non-default port, edit that file or click Edit configuration in the server dropdown. The file accepts comments. You can list more than one configuration, which is how I run the frontend and the API server side by side and let Claude test an endpoint and the page that calls it in the same pass.

• Start the session in the folder that owns the dev server. Preview uses the selected folder as its working directory, so if you opened a parent folder, a subfolder's server is not detected. Either open the subfolder directly or add its configuration by hand.
• Turn on Persist sessions in the server dropdown. Cookies and local storage then survive server restarts, so Claude is not logging into your own app again after every reload.
• Use the dropdown to stop all servers when you are done. A forgotten dev server on a laptop is a surprisingly good way to lose an afternoon to a port conflict.
• If you need to clear saved session data, or turn the Browser off entirely, both toggles are under Settings, Claude Code.

This is the same launch.json that the deploy step reads when you get to shipping, so getting it right here pays twice. [How to deploy an app with Claude Code](/blog/how-to-deploy-an-app-with-claude-code) picks up from a working preview.

Browsing external sites: the two extra safety checks

The pane is a real tabbed browser, so you can open documentation or an issue tracker next to your app, and you can sign in to sites in it, including popup flows like Google sign-in. Claude can read and act on those pages with the same tools it uses to verify your app, plus two checks that do not apply to localhost. Safety classifiers review Claude's write actions on external pages, clicking and typing, in every permission mode, and when one flags an action you get a prompt regardless of mode. And in every mode except Auto and Bypass permissions, a domain allowlist check runs before Claude navigates to a new site.

The first time Claude acts on an external site, a card appears with Allow once, Always allow, or Deny, and Claude waits. Always allow is saved per site on your device, subdomains count as separate sites, and you can revoke it in Settings. Your local dev servers and project files never need approval, which is why auto-verify keeps running without interrupting you. Even on an approved site, Claude will not buy things, create accounts, or get past a CAPTCHA without you. If you are doing client work in the pane, [is Claude Code safe for client work](/blog/is-claude-code-safe-for-client-work) covers what else to lock down.

WARNING: The clean profile cuts both ways. It means Claude cannot accidentally act inside your logged-in accounts from the pane, which is the point. It also means that if you sign into something inside the pane to save a step, you have just handed that session to the part of Claude Code that clicks things. Sign in there only for the app you are building. [Claude Code permissions explained](/blog/claude-code-permissions-explained) has the modes these checks sit on top of.

The prompts I run in the Browser pane

Auto-verify handles the edit you just made. These are the checks I ask for on purpose, usually before a commit, and they are short because the pane gives Claude the page, so I do not have to describe it.

1. "Open the signup page, submit it with a bad email and then with an empty password, and tell me exactly which error messages render." Form validation is where the diff lies most.
2. "Load the dashboard and check the console for errors on load. Only report errors and warnings, not every log line." Telling it what to look for keeps a noisy console out of the context window.
3. "Resize to a phone width, screenshot the pricing section, and fix anything that overflows." The pane screenshots at whatever size you set, and layout bugs are cheaper to find here than in a client's reply.
4. "Click every link in the footer and report any that do not return a page." Dead links after a route rename, every time.
5. "Walk the checkout from add-to-cart to the confirmation page and stop at the first step that fails." One prompt, one full user flow, and it stops where you need to look.

If a check fails and Claude's fix is not obvious, the pane is also where I debug, because it can read the failing state instead of my description of it. [How to debug with Claude Code](/blog/how-to-debug-with-claude-code) is the longer method; the short version is that a screenshot plus the DOM beats a paragraph of me explaining what I saw.

What the pane will not do, and what to reach for instead

• Act as you. That is the extension's job by design. Install Claude in Chrome, sign in to Claude Code with /login rather than an API key, and Claude uses it for browser work that needs your identity.
• Test an iOS app. The desktop app has a separate iOS Simulator pane on macOS for that, and it does not go through the browser at all.
• Drive a native desktop app. That is computer use, a different feature with its own permission tiers, and browsers are deliberately capped at view-only there so Claude is steered back to the pane or the extension.
• Run in the terminal version. The pane is a desktop-app feature. In the CLI you get the extension route with the --chrome flag, and nothing verifies your edits automatically.

Let Claude check its work before you do

Turn the pane on, leave auto-verify at its default for a week, and read what it fixes after each edit. Then decide where to switch it off. That order matters: most people turn it off first because it feels slow, and never learn which bugs it was quietly catching.

NOTE: Inside Claude Code Club, members post their launch.json for multi-server projects, the verification prompts they run before every commit, and the moment they moved a task from the pane to the Chrome extension and why. It is $9 a month at https://www.skool.com/claudecodeclub/about, and once Claude is testing its own changes, [Claude Code code review](/blog/claude-code-code-review) is the next check to hand it.

FAQ

What is the Claude Code browser?

The Browser pane inside the Claude Code desktop app's Code tab. Claude starts your dev server, opens the app in the pane, takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds. It is also a tabbed browser you can use yourself for documentation or any other site. Open it with Cmd+Shift+B on macOS or Ctrl+Shift+B on Windows.

What is the difference between the Browser pane and the Claude in Chrome extension?

The Browser pane runs in a clean profile with none of your logins and is meant for testing your own app and browsing sites that do not need your identity. The Claude in Chrome extension runs in your real Chrome or Edge and shares your login state, so Claude can act as you in Gmail, Notion, a CRM, or any site you are signed into. The extension needs version 1.0.36 or later and a direct Anthropic plan signed in with /login.

How do I turn off auto-verify in Claude Code?

Add "autoVerify": false to the .claude/launch.json file at the root of the folder you opened, or toggle it from the server dropdown in the session toolbar. Preview tools stay available when it is off; Claude just waits for you to ask before it verifies a change.

Does Claude Code ask permission before using the browser on other websites?

Yes. The first time Claude acts on an external site you get Allow once, Always allow, or Deny, saved per site including subdomains. Safety classifiers also review clicks and typing on external pages in every permission mode, and outside Auto and Bypass a domain allowlist check runs before Claude navigates somewhere new. Local dev servers and project files need no approval.

Why is my dev server not detected in the Browser pane?

Preview uses the folder you selected when you started the session as its working directory. If you opened a parent folder, a subfolder's dev server is not detected. Start the session in the subfolder, or add a configuration for it by hand in .claude/launch.json using Edit configuration in the server dropdown.

• Price an MVP against the decision it unlocks: a raise, first paying customers, or proof that a workflow is worth building. Get the founder to put a value on that decision, then quote a fixed fee that is an obvious fraction of it. Never quote by feature or by hour.
• Define the MVP on paper as one core loop: a user signs up, does the one thing, sees the result. Everything outside that loop is phase two with its own price.
• Quote three tiers: Prove (a working loop for demos), Launch (the loop with auth, payments, and a live deploy), and Traction (Launch plus a fixed post-launch iteration window). Claude Code making the build fast is your margin, not the founder's discount.

How much to charge for an MVP

How much to charge for an MVP comes down to one question: what decision is this build supposed to unlock, and what is that decision worth to the founder? Nobody wants an MVP. They want to know whether to raise, whether strangers will pay, or whether a process they run by hand deserves software. That decision has a price, and the founder usually knows it, because it is the cheque they are chasing or the cost they are carrying. Quote a fixed fee that is an obvious fraction of that number, built around one core loop, in three tiers. Do not quote by feature, and never by hour. Claude Code can get a working loop in front of users in days, and if you price by the day, the founder will pay you like a day.

This is the CCC Decision-Value Method, and it exists because the MVP is the job where new builders lose the most money in the most flattering way. The founder is excited, the idea is interesting, and the scope has no edges. So the quote comes out as a features list, the features multiply, and six weeks later you are a technical co-founder on a contractor's invoice. Priced against the decision, an MVP is a clean fixed-scope build with a high margin and the most natural retainer upsell in the business, because a founder who gets their answer needs the next thing built immediately.

NOTE: This is the pricing half. The build half, from blank folder to deployed product, is in [how to build a SaaS with Claude Code](/blog/build-a-saas-with-claude-code). The fixed-fee logic underneath every number here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project).

Find out what the MVP has to prove before you say a number

You cannot price an MVP until you know what it is for, so the first call is a measurement. Five questions get you there, and I ask them in this order because each one makes the next one easier to answer honestly.

• What happens if this works? A pitch to investors, a launch to a waiting list, a pilot with one named customer. That is the decision, and it is the thing you are actually building.
• What is that worth to you? Let the founder say it. A raise has a target. A first customer has a contract value. A workflow has a monthly cost in someone's salary. Your quote is going to sit next to this number, so get it from them.
• Who is the first user, by name if possible? If the answer is "everyone," the MVP is not defined yet and the price has to include defining it. Paid discovery covers this; [paid discovery for AI projects](/blog/paid-discovery-phase-ai-projects) is how I sell that week.
• When is the deadline, and what set it? A demo day, an investor meeting, or a customer's renewal date is a real deadline and it is worth money. "As soon as possible" is not a deadline and does not change the quote.
• What have you spent so far? A founder who has already paid an agency for a deck and a designer for screens has a sunk cost and a mental price for the next step. You want to know both before you name yours.

Say the answers back before you quote. "So this exists to close your first three pilot customers, and each pilot is worth roughly this to you" is a sentence the founder has to agree with, and once they have, the price of the build is a fraction of a number they already accepted. The full question set I run on every deal is in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote).

Define the MVP on paper as one loop, or you will build the whole product

The CCC One-Loop Rule: an MVP is one user, doing one thing, seeing one result, and that loop written down in three lines is the scope. A user signs up, uploads a contract, gets a summary. A customer books a slot, pays, receives a confirmation. If the founder cannot say the loop in a sentence, the product is not ready to be built and the price should cover the discovery that gets it there. If they can, everything outside that sentence is phase two, priced separately, and written on the proposal as phase two so nobody is surprised.

This rule is what makes the fixed fee safe. Claude Code will happily add an admin panel, a settings page, a second user role, and a referral system in the same afternoon, and the founder will happily ask for them, because from where they sit every one of those is "part of the MVP." The written loop is the line you point at. [How to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project) is the longer method, and [how to write a project brief for Claude Code](/blog/how-to-write-a-project-brief-for-claude-code) turns the loop into the brief you actually build from.

The CCC MVP Price Ladder: three tiers

Present three tiers, all built around the same loop, and let the founder pick how much of the decision they want proven. The bottom tier is for a founder who needs something to show. The middle is for a founder who needs something to sell. The top is for a founder who already knows the product is real and wants the first weeks of learning built in.

The middle tier wins because of payments and the deploy. A loop on a private URL proves the idea. A loop that a stranger can pay for proves the business, and that is the decision most founders are actually trying to make. Put the difference in the table and they will choose it themselves. The three-tier shape is the same one in [how much to charge for a landing page](/blog/how-much-to-charge-for-a-landing-page) and [how much to charge for a chatbot](/blog/how-much-to-charge-for-a-chatbot); the tiers change, the logic does not.

What moves an MVP quote up or down

• Payments. A loop that takes money is a business, and the price reflects it. Subscriptions, one-off charges, and marketplaces with payouts are three different amounts of work, so ask which one before you quote.
• Who the users are. One kind of user is an MVP. Two kinds who see different things, a customer and an admin, is two products sharing a database. Price the second role as its own line.
• Integrations. Every outside system the loop touches, a calendar, a CRM, an email tool, a data source, is its own line because each one is its own thing that can break on launch day.
• Design. A founder with brand assets and screens from a designer is a build. A founder with a napkin is a build plus a design pass they will want to revisit, and that pass is priced.
• Web or native mobile. A web app that works on a phone is the default MVP. A native app with store review is a different timeline and a different quote, and most MVPs do not need it yet.
• Data that already exists. If the founder has a spreadsheet of customers or a legacy tool to migrate from, the migration is a line item, not a favour.
• The deadline. A demo day in three weeks is worth more than the same build with no date on it, and the founder already knows it.
• Account ownership. Build on the founder's accounts, under their billing. It goes on the quote, and it is why you are never the hosting company when the startup runs out of money.

The mistakes that turn a paid MVP into an unpaid co-founder job

• Taking equity instead of a fee. The founder will offer, because the equity costs them nothing today. Unless you would invest cash in this company, take cash for the build. If you genuinely would, take a fee and negotiate the equity as a separate conversation.
• Quoting hours or days. "About a week with Claude Code" becomes the price ceiling the moment you say it. Talk about the decision and the loop, nothing else. [Why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds) is the longer argument.
• Starting without a deposit. Startups run out of money, and the ones that do not still have a board meeting to survive. [How much deposit to charge before an AI project](/blog/how-much-deposit-to-charge-before-an-ai-project) covers the number; for an MVP it is at the high end.
• Unlimited pivots. The founder will learn something on day four and want a different loop. That is healthy, and it is a change order. Write down what a pivot costs before the build starts. [How to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects) has the script.
• Building the roadmap. A founder's pitch deck has eighteen months of features on one slide. You are building the loop. Everything else is phase two with a price.
• No end date. An MVP without a handover date becomes a job. Even the Traction tier has a fixed window, and the retainer that follows is a new agreement, not a continuation.

How to present the MVP number so it closes

Lead with the decision you agreed on, then put the three tiers under it. "You said this exists to close your first pilot customers, and we agreed what a pilot is worth; here are three ways to prove it" is a sentence a founder can say yes to on the call, and it is a sentence they can repeat to a co-founder or an investor an hour later without you in the room. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes) with the loop written in three lines, the tier scope, the phase-two list, the deposit, and the handover date. [How to write a statement of work for an AI project](/blog/how-to-write-a-statement-of-work-for-an-ai-project) is the version I attach when the founder has a lawyer, and [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) covers who owns the code, which for an MVP is always the founder once the invoice is paid.

The push-back you will hear is "a no-code tool could do this" or "a developer friend said it would take a weekend." Both are answered by the decision: a weekend build that the friend abandons in week three does not close a pilot customer or survive an investor's technical question. If the objection is really about budget, the honest answer is often the Prove tier, and [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the exact words.

Quote your next MVP against the decision, not the feature list

An MVP is the best client project in this business when it is priced right and the worst when it is not. Get the decision and its value from the founder, write the loop in three lines, quote the ladder, take the deposit, and put the handover date on the proposal. The founder who gets their answer is the easiest retainer you will ever sell; [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) is what that conversation looks like.

NOTE: Inside Claude Code Club, members share the MVP quotes they actually sent, which tier the founder picked, and which line they forgot the first time, usually payments or the second user role. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you are weighing building your own MVP instead of a client's, [micro-SaaS vs client work with Claude Code](/blog/micro-saas-vs-client-work-with-claude-code) is the honest comparison.

FAQ

How much should I charge for an MVP?

Price it against the decision the MVP unlocks, not the features or the hours. Ask the founder what happens if it works, a raise, first paying customers, or proof that a workflow is worth software, and what that is worth to them. Then quote a fixed fee that is an obvious fraction of that value, in three tiers built around one core loop: Prove, Launch, and Traction.

Should I take equity for building an MVP?

Take a fee for the build. Equity costs the founder nothing today, and most MVPs do not become companies. If you would genuinely invest your own cash in the business, take the fee anyway and negotiate equity as a separate conversation with its own paperwork.

What should be included in an MVP?

One core loop: a user signs up, does the one thing the product exists for, and sees the result. Write it in three lines and that is the scope. Real sign-up, payments, a production deploy, and basic analytics belong in the Launch tier; a second user role, an admin panel, integrations, and native mobile are phase two with their own price.

How much deposit should I charge for an MVP?

The high end of whatever you normally charge, taken before any work starts. Startups run out of money, and the ones that do not still change direction. A deposit plus a written change-order price for pivots is what keeps an MVP a fixed-scope build instead of an open-ended job.

What if the founder says a no-code tool or a developer friend could do it cheaper?

Go back to the decision. A weekend build that gets abandoned in week three does not close a pilot customer or survive an investor's technical questions. If the objection is really about budget, offer the Prove tier: the core loop working end to end on a private URL, good enough to demo, with payments and launch as a priced next step.

• Claude Code scheduled tasks live on the Routines page in the desktop app's Code tab. Click New routine, choose Local, give it a name, instructions, a folder, and a schedule, and Claude Code starts a fresh session on that schedule with its own permission mode and model.
• They only fire while the desktop app is open and the computer is awake. If the machine sleeps through a run, Desktop skips it and does one catch-up run when it wakes, so write the prompt to cope with running late.
• Three things cost me time in week one: a stalled permission prompt, a run that reviewed my half-finished uncommitted work, and a laptop lid. The fixes are Run now with always-allow, the worktree toggle, and a prompt guardrail.

Claude Code Scheduled Tasks

Claude Code scheduled tasks are recurring jobs you create from the Routines page in the desktop app. Each task starts a brand-new Claude Code session at the time and frequency you set, in a folder you pick, with its own permission mode and model. When it fires you get a desktop notification and the session appears under a Scheduled section in the sidebar, where you can read what Claude did, review the changes, or answer a permission prompt. A local scheduled task runs on your machine with full access to your files and tools, which also means it only runs while the app is open and the computer is awake. The same Routines page can create a remote routine that runs in the cloud when your machine is off, but that is a different thing with different tradeoffs, and this post is about the local kind.

I set two up the day the feature landed: a weekday morning review of the previous day's commits on the club site, and a Monday dependency check. The setup took less time than writing this paragraph. The first week of runs is where I learned what the docs meant, and that is the useful part of this post.

NOTE: This is the scheduling half. If you have not yet let Claude Code work without you watching, read [running Claude Code unattended](/blog/claude-code-running-unattended) first, because a scheduled task is an unattended run with a clock on it. And if you are still in the terminal, [the Claude Code desktop app](/blog/claude-code-desktop-app) is where this feature lives.

The three ways to schedule Claude Code, and which one to pick

Claude Code has three schedulers and they are not interchangeable. The CCC Three-Clock Rule is how I keep them straight: pick the scheduler by what has to be true at the moment the task fires. If a session has to be open, use /loop. If your machine has to be on but nothing else, use a desktop scheduled task. If nothing at all has to be true, use a cloud routine. Anthropic's comparison table says the same thing in more columns.

The reason I chose desktop tasks for the daily review is the local-files row. The review needs the actual working copy, my MCP config, and the allow rules I already set up, and a cloud routine gets a fresh clone with none of that. The reason I did not use /loop is that it is session-scoped and recurring loops expire after seven days, which is fine for babysitting a deploy and wrong for something I want running next month.

How to create a scheduled task in the desktop app

In the Code tab, click Routines in the sidebar (or under the sidebar's More menu), then New routine, then Local. You need Claude Desktop 1.1.5368 or later; older builds do not show local tasks at all. There are four fields, and the Instructions box is the one that matters.

• Name. Converted to lowercase kebab-case and used as the folder name on disk, so keep it short and unique. Mine is daily-commit-review.
• Description. One line, shown in the task list.
• Instructions. Write this exactly as you would type a message in the prompt box. The pickers under it set the permission mode and the model, and below that you choose the working folder and whether each run gets its own isolated worktree.
• Schedule. Presets are Manual (only runs when you click Run now), Hourly, Daily at a local time, Weekdays, and Weekly with a day picker. For anything else, such as every 15 minutes or the first of the month, ask Claude in any Desktop session in plain language and it sets the schedule for you.

You need a trusted folder before the task will save; Desktop prompts you to trust it if you have not. You can skip the form entirely and just type the request into a session. "Set up a daily code review that runs every morning at 9am" creates a recurring task, and "remind me at 3pm tomorrow to check the deploy" creates a one-time task that disables itself after it fires. I used the form the first time so I could see every field, and I have used plain language since.

What happened in my first week of runs

Three things went sideways, and every one of them is covered in the docs if you read them the way I did not.

The lid. Desktop checks the schedule every minute while the app is open, adds a small deterministic delay to stagger API traffic, and starts a fresh session when a task is due. If the computer is asleep at that moment, the run is skipped. I closed the laptop on a Tuesday evening and the Wednesday review did not happen until I opened it that night, because Desktop then runs exactly one catch-up for the most recently missed time within the last seven days and throws the rest away. There is a Keep computer awake switch under Settings, Desktop app, General, but the docs are clear that closing the lid still sleeps the machine. My fix was in the prompt, not the settings: "Only review commits since the last run. If it is after 5pm, skip the review and post a summary of what was missed." Now a late run is a short run, not a wrong one.

The stall. The second run needed to execute a command I had not approved, and because the task was in a permission mode that asks, it sat in the sidebar waiting for me. That is the correct behaviour, but it is not what you want at 8am. The fix is the one the docs recommend: click Run now right after you create the task, watch for every prompt, and pick always allow on each. Future runs auto-approve the same tools, and you can review or revoke those approvals from the task's Always allowed panel.

The half-finished work. By default a scheduled task runs against whatever state your working directory is in, including uncommitted changes. My Thursday review cheerfully critiqued a feature I was midway through, because I had left it uncommitted overnight. The worktree toggle on the task fixes this: each run gets its own isolated Git worktree, the same way [Claude Code worktrees](/blog/claude-code-worktrees) isolate parallel sessions. Turn it on for anything that reads or edits code.

Permissions: how to keep a task from stalling

Each scheduled task has its own permission mode, set when you create or edit it, and the allow rules in your ~/.claude/settings.json apply to scheduled sessions too. So the boring answer is: put the commands the task needs into your allow rules once, run it manually with Run now, approve what is left with always allow, and it will not stall again. A task that runs in Manual mode and hits a tool it is not allowed to use waits for you, and the session stays open in the sidebar until you answer.

WARNING: MCP tools marked requiresUserInteraction prompt on every single call and never offer always allow. A scheduled task that calls one will stall every run. Either keep those tools out of scheduled prompts or accept that the task is really a reminder to go approve something. [Claude Code permissions explained](/blog/claude-code-permissions-explained) covers how the modes and allow rules fit together.

Where the prompt lives on disk, and how to manage a task

Every task gets a folder at ~/.claude/scheduled-tasks/<task-name>/ (or under CLAUDE_CONFIG_DIR if you set one) containing a SKILL.md. The file has YAML frontmatter for name and description, and the body is the prompt. Edit the body and the change applies on the next run, which is how I tuned the review prompt without touching the form. The schedule, folder, model, and enabled state are not in that file; change those through Edit on the task's page or by asking Claude.

• Run now starts the task immediately. Use it after every prompt edit so you see the result before the scheduled run does.
• Status toggles Active and Paused, so you can silence a task for a week without deleting it.
• History lists every past run, including skipped ones. Hover a skipped entry to see why: the computer was asleep, the previous run was still going, or other tasks were already running.
• Delete archives every session the task created, and a checkbox in the dialog also removes its SKILL.md and data from disk.
• A task can reschedule itself from inside a run using the update_scheduled_task MCP tool, for example moving a review earlier when it notices a release branch. I have not needed it yet, but it is there.

You can also do all of this by asking. "Show me my scheduled tasks" and "pause my dependency-audit task" both work from any Desktop session.

The two tasks worth setting up first

Start read-only. A scheduled task can edit files, run commands, commit, and open pull requests, and the temptation is to schedule the whole pipeline on day one. Do not. Schedule the two jobs that produce a report you would read anyway, run them for a week, then decide what to let them touch.

1. Weekday commit review. Weekdays preset, a morning time, worktree on. The prompt: review the commits since the last run, list anything that looks like a bug, a missing test, or a secret in the diff, and write the findings as a short summary. Do not push. If you want the deeper version, [Claude Code code review](/blog/claude-code-code-review) covers what a good review prompt asks for.
2. Weekly dependency audit. Weekly preset, Monday. The prompt: list outdated dependencies, flag anything with a known security advisory, and propose the upgrade order. Report only. Once it has been right for a few weeks, let it open a pull request for the safe ones.

If your project already runs in CI, the same two jobs can run there on a schedule trigger instead, which is what [Claude Code GitHub Actions](/blog/claude-code-github-actions) is for. I run mine on the desktop because the review needs my local MCP servers and my allow rules, and because I like opening the app in the morning to a session that has already done the reading.

Compare schedules with people running them

The right cadence and the right prompt come from watching a week of history, not from guessing. Set the two tasks up, leave the worktree toggle on, and read the skipped entries as carefully as the successful ones.

NOTE: Inside Claude Code Club, members post the scheduled prompts they actually run, what the first week of history looked like, and which permission they had to always-allow to stop the stalls. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you want the tasks to enforce rules rather than just report on them, [Claude Code hooks that earn their keep](/blog/claude-code-hooks-that-earn-their-keep) is the next step.

FAQ

What are Claude Code scheduled tasks?

Recurring jobs you create from the Routines page in the Claude Code desktop app. Each task starts a fresh Claude Code session at the time and frequency you set, in the folder you choose, with its own permission mode and model. When it runs, you get a desktop notification and the session appears under a Scheduled section in the sidebar so you can review what Claude did.

Do Claude Code scheduled tasks run when my computer is off?

No. Local desktop scheduled tasks only run while the desktop app is open and the computer is awake. If the machine sleeps through a scheduled time, that run is skipped and Desktop starts one catch-up run for the most recently missed time when it wakes. For work that must run with the machine off, create a remote routine from the same Routines page, which runs in the cloud.

How do I create a scheduled task in Claude Code?

In the desktop app's Code tab, click Routines, then New routine, then Local. Fill in a name, a description, the instructions, a trusted working folder, and a schedule preset such as Daily or Weekdays. You can also ask Claude in any Desktop session, for example "set up a daily code review that runs every morning at 9am." You need Claude Desktop 1.1.5368 or later.

Why did my scheduled task stall?

Usually a permission prompt. Each task has its own permission mode, and if it needs a tool it is not yet allowed to use, the run waits in the sidebar for your approval. Click Run now after creating the task, approve each prompt with always allow, and future runs auto-approve the same tools. MCP tools marked requiresUserInteraction prompt every time and cannot be always-allowed.

What is the difference between a scheduled task and /loop?

/loop runs a prompt on an interval inside an open session and stops when that session ends; recurring loops also expire after seven days. A desktop scheduled task runs without any session open, persists across restarts, and starts a fresh session each time. Use /loop for polling during a session and a scheduled task for anything you want running next week.

• Price a landing page against what a lead is worth to the client, not the hours it takes to build. Find out what a customer is worth and how many the page needs to produce, then quote a fixed fee that is an obvious fraction of that.
• Quote three tiers: the page, the page with copy and a wired-up form, and the page with tracking and a post-launch iteration window. Most clients buy the middle one.
• Copy, integrations, hosting, and revisions are separate lines, not favours. Claude Code turning the build into an afternoon is your margin, never the client's discount.

How much to charge for a landing page

How much to charge for a landing page comes down to one question: what is a lead worth to this client, and how many does the page need to produce? A landing page exists to turn a visitor into an enquiry, a booking, or a sale. That makes it the easiest thing in your service list to price on outcome. Work out what one new customer is worth, agree on how many the page should bring in over its first few months, and quote a fixed fee that is an obvious fraction of that number. Never quote hours. The page might take you an afternoon with Claude Code, and the moment the client hears "afternoon" they will price it like one.

This is the CCC Lead-Value Method, and it exists because the landing page is the job new builders underprice more than any other. It looks small. It is one page. So the quote comes out small, and then the copy, the form, the domain, the three rounds of "can we just move this" and the hosting question all land on you for free. Priced properly, a landing page is a clean, repeatable offer with a high margin and a natural upsell into the client's next page.

NOTE: This is the pricing half. The build half, from blank folder to a live URL, is in [how to build a landing page with Claude Code](/blog/build-a-landing-page-with-claude-code). The fixed-price logic underneath every number here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project).

Ask what a lead is worth before you say a number

You cannot price a landing page until you know what it is for, so the first conversation is a measurement, not a pitch. Four questions get you there: what should a visitor do on this page, what is a new customer worth to you, how many of them do you need this page to bring in, and what are you doing today instead? The answers give you a value for the page in the client's own numbers, which is the only kind of number they do not argue with.

• Pin the single action. A landing page has one goal: book a call, join a list, buy the thing. If the client wants three goals, that is a website, and it is priced as one.
• Get the customer value from them, not from you. A dentist, a wedding photographer, and a SaaS founder will each give you a very different number, and each number makes your quote look small next to it.
• Ask what they are doing now. A page that replaces nothing is priced against the leads it creates. A page that replaces an agency retainer or a broken template is priced against what that costs them.
• Say the value back before you quote. Once the client has agreed that one customer is worth what they said, the price of the page is a fraction of a number they already accepted.

If you want the full question set, [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote) has the version I run on every deal, landing page or not.

The CCC Landing Page Price Stack: three tiers

A landing page quote has three shapes, and you present all three. The bottom tier proves you are affordable, the top tier makes the middle look sensible, and the middle is the one you actually want to sell because it is the one that gets the client a result they will talk about.

The reason the middle tier wins is copy and the form. A page with the client's own copy pasted in and a form that emails nobody is a brochure. A page with copy written to the goal and a form that lands in their CRM or calendar is a lead machine, and clients can feel the difference even before they see numbers. Put the difference in the table and let them choose it. The three-tier logic is the same one in [how much to charge for a chatbot](/blog/how-much-to-charge-for-a-chatbot); the tiers change, the shape does not.

What moves a landing page quote up or down

• Who writes the copy. Copy is half the result and most of the revisions. If you write it, it is a line on the quote. If the client writes it, the quote says so and the revision round covers layout, not wording.
• Whether a brand exists. A client with a logo, colours, and photos is a build. A client with none of those is a build plus a design decision they will want to revisit, and that time is priced.
• Integrations. A form that emails them is included. A form that creates a lead in their CRM, books a slot in their calendar, or takes a payment is each its own line, because each one is its own thing that can break.
• Domain, hosting, and account ownership. Build on the client's accounts, under their billing. It costs a few minutes of setup, it goes on the quote, and it means the page survives if you two part ways.
• Revisions. Name the number. [How many revisions to include in an AI project](/blog/how-many-revisions-to-include-in-an-ai-project) covers where to set it; on a landing page the answer is fewer than the client expects and clearly written down.
• Speed. A page needed by Friday for a launch is worth more than the same page needed sometime next month, and the client already knows it.

The mistakes that turn a paid landing page into a free website

• Quoting hours. The instant you say it is a small job, you have priced it as a small job. Talk about what the page is for and what a lead is worth, nothing else.
• Not defining "landing page" on paper. One page, one goal, one call to action. The moment there is a navigation bar with five sections that each want their own page, it is a website, and the quote needs to change with it.
• Unlimited revisions, or worse, unstated ones. Every "can we just move this" is a revision. Number them.
• Hosting it on your own account. Now you are the hosting company, forever, for free.
• No line for changes after launch. Text changes, a new offer, a seasonal banner: they will ask, and you need a monthly line that already covers it. [How to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) has the shape.
• Letting them watch the build. Claude Code turning a day of work into an afternoon is your margin story. It is not the client's discount. The client is paying for the leads the page produces, and that number did not change because you built it fast. [Why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds) is the longer argument.

How to present the number so it closes

Lead with the value you already agreed, then put the three tiers underneath it. "You said a new customer is worth this much, and we agreed the page should bring in this many; here are three ways to build it" is a sentence a client can approve on the spot. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes), never as a list of technologies, and put the scope, the revision count, and who owns which account on the same page. The format in [how to write a statement of work for an AI project](/blog/how-to-write-a-statement-of-work-for-an-ai-project) is more than enough for a landing page.

The push-back you will hear is "we could do it on a page builder for free" or "that seems like a lot for one page." Both are answered by the number you measured together: a free page that converts nobody costs them every customer it did not bring in, and the price of yours is a fraction of one. If they push harder, [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the exact words, and the honest answer is often the Launch tier.

Put the price stack in front of a real client this week

A landing page is the easiest first sale in this business because every local service, every coach, and every small product launch needs one and most of them have a page they are quietly embarrassed by. Price it on what a lead is worth, quote three tiers, and the second page for the same client is a shorter conversation than the first.

NOTE: Inside Claude Code Club, members share the landing page quotes they actually sent, which tier the client picked, and which line item they forgot to include the first time. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you have not shipped the build side yet, start with [how to build a landing page with Claude Code](/blog/build-a-landing-page-with-claude-code) so you have a live URL to point at when you quote.

FAQ

How much should I charge for a landing page?

Price it against what a lead is worth to the client, not the hours it takes to build. Find out what a new customer is worth, agree how many the page should bring in, and quote a fixed fee that is an obvious fraction of that. Offer three tiers - the page, the page with copy and a wired-up form, and the page with tracking and a post-launch iteration window - and let the client choose.

Should copy be included in a landing page price?

Only if you are writing it, and then it is its own line. Copy is half the result and most of the revisions, so the quote should say clearly who writes it. If the client supplies copy, the revision round covers layout and not wording, and that should be written down before you start.

What makes a landing page more expensive?

Copy you write, a brand that does not exist yet, integrations that push leads into a CRM, calendar, or payment tool, a rush deadline, and extra revisions. Each is a separate line on the quote. Build effort is not the driver; what the page connects to and who has to write for it are.

Should I charge a monthly fee for a landing page?

Yes, a small one. Hosting, domain renewals, and text changes after launch will all come up, and a monthly line means the answer to "can we change the offer" is already paid for. Build on the client's accounts so the page survives if you part ways, and keep the monthly for the work of keeping it current.

What if the client says they can build a landing page for free?

Go back to the number you measured together. A free page that converts nobody costs them every customer it did not bring in, and your price is a fraction of one customer's value. If the objection is really about budget, offer the Launch tier: the page built from their own copy, deployed live, with one round of revisions.

• Claude Code has five effort levels - low, medium, high, xhigh, max - set with /effort. Opus 5.5 defaults to medium; every other model defaults to high. Effort is now the only thinking control on Opus 5.5 because adaptive thinking is always on.
• Leave it on medium and only step up when a task actually fails. Higher effort means more thinking tokens per turn, and Opus 5.5 already thinks more per turn than Opus 5 at the same level, so max on a routine edit is paying for reasoning you will never read.
• Two things bite people after the switch: an old effortLevel line in your user settings does not apply to Opus 5.5, and any skill or agent file that pins an older model keeps that model's default. Check both before blaming the model.

Claude Code Effort Levels

Claude Code effort levels are a five-step dial - low, medium, high, xhigh, and max - that tells the model how much reasoning to spend on each request. More effort means more thinking, more checking, more tokens, and a slower answer. You set it with the /effort command, and Claude Code remembers your choice per model. The one fact that matters this week: Claude Opus 5.5 defaults to medium, while Opus 5, Fable 5.1, and Sonnet 5 default to high. Adaptive thinking is always on for Opus 5.5, so effort is the only knob you have for how hard it thinks and what a request costs.

My rule is boring on purpose: stay on medium, step up one level when a task fails, and step back down the moment it succeeds. That is the whole method. The rest of this post is what each level actually changes, how to set it without a terminal, and the version of the CCC Effort Ladder I use now that the default moved.

NOTE: This post is about the effort setting. If you are still using the older thinking keywords in prompts, [Claude Code extended thinking](/blog/claude-code-extended-thinking) covers those, and the full model rundown lives in our [Claude Opus 5.5 guide](/free-resources/claude-opus-5-5).

What each effort level actually changes

Effort does not change which model answers. It changes how many tokens the model is allowed to spend thinking before it commits to an action or a reply. At low it scopes tightly to what you asked and moves fast. At max it has no ceiling on thinking and will reason around a problem for as long as it wants. Anthropic's own docs describe max as prone to overthinking with diminishing returns, which matches what I see: on small jobs it produces longer answers, not better ones.

One detail worth knowing before you carry a habit over from Opus 5: Anthropic notes that at the same effort level, Opus 5.5 tends to think more per turn than Opus 5, most of all at xhigh and max. So a level that felt fine on the old model can be noticeably slower and pricier on the new one. That is exactly why the default dropped a notch.

How to set the effort level in Claude Code

In the desktop app, type /effort into the message box and you get a slider. Pick a level and confirm. In the terminal it is the same command. You can also name the level directly - /effort high - or run /effort auto to clear your saved level for the current model and go back to its default. You can run it mid-task; Claude Code applies the new level to the next request.

• Claude Code saves the level per model, under modelSettings in your user settings. Switching from Opus 5.5 to Fable 5.1 and back keeps each one's level.
• max is the exception: unless you set it through the CLAUDE_CODE_EFFORT_LEVEL environment variable, it applies to the current session only. That is a sensible guardrail, not a bug.
• Changing effort in the middle of a long session can show a cache warning. Effort is part of what gets cached, so flipping it can mean re-reading context you had already paid for. Set it early in the session when you can.
• The /model picker also lets you choose effort alongside the model, which is the fastest way to set both at once when you start a session.

WARNING: If you set a top-level effortLevel in your user settings before Claude Code started saving levels per model, that line does NOT apply to Opus 5.5. Opus 5.5 starts at medium until you choose a level for it with /effort or the /model picker. A top-level effortLevel in project, local, or managed settings still applies to every model.

Why Opus 5.5 moved the default, and what that does to your bill

Anthropic priced Opus 5.5 at $4 per million input tokens and $20 per million output tokens, down from $5 and $25 on Opus 5, with cache reads at $0.20 per million, 60 percent less than before. Their published claim is that at default settings it costs about 40 percent less than Opus 5 on typical workloads, because the price per token dropped and the model uses fewer tokens per task. The medium default is part of how that 40 percent happens. If you push everything to high or max out of habit, you hand a chunk of that saving straight back.

The benchmark that convinced me to leave medium alone: on Anthropic's Terminal-Bench 4.0 results, Opus 5.5 at its default effort beats Opus 5 at max effort for roughly a fifth of the cost. The published numbers are theirs, not mine, and I treat launch charts as a strong signal rather than a promise. But the shape of it holds up in my sessions - medium finishes most builds cleanly, and the cases where I needed to go up were the ones I would have expected to be hard anyway. If you want the per-task view, [Claude Code token usage](/blog/claude-code-token-usage) shows how to read what a session actually consumed.

NOTE: Skills, agents, and settings files can pin a specific model by its full name. Anything pinned to an older Opus or Fable keeps running on that model and that model's default effort, no matter what you set in /effort. Search your project for a model line before assuming the whole setup moved.

The CCC Effort Ladder, recalibrated for Opus 5.5

The CCC Effort Ladder is the rule I run before touching /effort: match the level to how expensive it would be to get the answer wrong, not to how important the project feels. Importance is a feeling. Cost of a wrong answer is a number you can estimate. With the default now at medium, the ladder looks like this.

1. medium - the default and the home base. New features, refactors, test writing, documentation, and every prompt where a wrong first pass costs you one more prompt. Leave it here.
2. low - when the answer has one obvious shape and speed matters more than depth: renames, formatting, small edits, and subagents doing lookups on your behalf. Anthropic's docs call subagents out as the natural home for low, and I agree.
3. high - a bug that already beat one attempt at medium, a change that touches auth or payments, or a multi-file feature where the tradeoffs actually need weighing. Go here on the second attempt, not the first.
4. xhigh - anything you are about to let run without you watching. Long migrations, full-repo audits, and the unattended sessions from [running Claude Code unattended](/blog/claude-code-running-unattended). More reasoning per step is worth it when nobody is there to catch a bad step.
5. max - rare. A schema or architecture decision you cannot undo cheaply. It is session-only by design, so use it for the decision, then start a fresh session back on medium.

The half of the ladder people skip is the way down. Every time a high or xhigh task finishes, drop back to medium before the next prompt. The level is saved per model, so if you forget, every routine edit for the rest of the week pays for reasoning it does not need.

The two mistakes I made in the first week

First mistake: I assumed my old settings carried over. I had an effortLevel line in my user settings from months ago and expected Opus 5.5 to honor it. It did not, because that key only applies to the older models. Opus 5.5 was quietly on medium the whole time, which turned out fine, but I spent a morning wondering why two sessions on two models behaved differently. Run /effort with no arguments and look at the slider before you judge a new model.

Second mistake: I ran a routine cleanup at max because the repo felt important. The answers got longer and slower and the diff was no better than medium would have produced. The docs warn about overthinking at max, and that is exactly what it looked like. The fix was the ladder above: max is for the decision, not for the project.

Compare notes with people running the same dial

The right level for your work is something you find by running your three most common jobs at two levels and comparing cost and quality, not by reading charts. That takes an hour and it is the most useful hour you will spend on Opus 5.5 this month.

NOTE: Inside Claude Code Club, members post what effort level they landed on for real builds, with the token counts to back it up - which is how I found out low was good enough for more than I expected. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you have not set the model up yet, start with [Claude Code plan mode](/blog/claude-code-plan-mode) so the effort you pay for goes toward a plan you have already approved.

FAQ

What are the Claude Code effort levels?

Five settings - low, medium, high, xhigh, and max - that control how much the model thinks before answering. Higher effort means deeper reasoning, more tokens, and slower replies. Claude Code also offers an ultracode setting that plans a dynamic workflow for each substantive task with xhigh reasoning per message. You set the level with the /effort command.

What is the default effort level in Claude Code?

It depends on the model. Claude Opus 5.5 defaults to medium. Every other model that supports effort defaults to high, except Opus 4.7, which defaults to xhigh. A request that does not set effort runs at the model's default, so switching from Opus 5 to Opus 5.5 without touching /effort moves you one level down.

How do I change the effort level in Claude Code?

Type /effort in the message box of the desktop app or the terminal to open a slider, or name the level directly, for example /effort high. Run /effort auto to clear your saved level for the current model. Claude Code saves the level per model under modelSettings in your user settings. The max level is session-only unless set through the CLAUDE_CODE_EFFORT_LEVEL environment variable.

Does a higher effort level cost more?

Yes. Effort controls how many thinking tokens the model spends, and thinking counts as output, which is the expensive side at $20 per million tokens on Opus 5.5. Anthropic's docs also note that Opus 5.5 thinks more per turn than Opus 5 at the same level, especially at xhigh and max, so a high setting carried over from the old model costs more than it used to.

Should I use max effort for everything on Opus 5.5?

No. Anthropic's Claude Code docs describe max as prone to overthinking with diminishing returns, and it is session-only for that reason. Start on medium, step up to high when a task fails, use xhigh for long unattended runs, and reserve max for decisions you cannot undo cheaply. Drop back to medium afterward, because the level is saved per model.

• Price an AI automation against the hours it removes each month, not the hours it takes to build. Find the manual work, put a monthly value on it, and quote a fixed setup fee that is a clear fraction of the first year's saving.
• Every automation quote has three parts: a fixed setup fee, a monthly run fee, and a separate line for each system it connects to. Skip the monthly and you own every breakage for free.
• The number moves on integrations, error cost, and volume - not on how clever the build is. Claude Code compressing your build time is your margin, never the client's discount.

How much to charge for an AI automation

How much to charge for an AI automation comes down to one measurement: how many hours of someone's month does it remove, and what does an hour of that person cost the business? That monthly value is your anchor. Quote a fixed setup fee that sits well below the first year's saving, add a monthly run fee on top because automations do not stay working on their own, and price each connected system as its own line. Never quote build hours. A client who hears the build took a day will price it like a day's work, no matter how much it saves them.

This is the CCC Hours-Removed Method, and it exists because automation is the offer where builders undercharge most. The build looks small, so the price comes out small, and the client quietly pockets thousands in saved labour every month while you collected a one-time fee that did not cover the third support ticket.

NOTE: This is the pricing half. The build half - what a small automation actually looks like inside Claude Code - is in [automate your spreadsheets with Claude Code](/blog/automate-your-spreadsheets-with-claude-code), and the fixed-price logic underneath everything here is in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project).

Measure the hours before you say a number

You cannot price an automation you have not measured, so the first call is a measurement call, not a pitch. Four questions get you there: who does this task today, how often does it happen, how long does each one take, and what happens when it is done late or wrong? The answers give you hours per month and a cost per hour. Multiply them and you have the monthly value of the automation in the client's own numbers, which is the only kind of number they cannot argue with.

• Ask for a real week, not an estimate. "Walk me through last Tuesday" surfaces the copy-paste steps people forget they do.
• Count the error cost separately. A task that takes twenty minutes but occasionally costs a lost order is worth far more than its minutes.
• Note who is doing it. Two hours a week of the owner's time is priced very differently from two hours of an assistant's.
• Write the number down and say it back to them before you quote. Once the client has agreed on the value, the price is a fraction of a number they already accepted.

If you want the full question set, [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote) has the version I run on every deal.

The three parts of an automation quote

An automation is not a website. It runs every day, it depends on other people's software, and it fails silently when one of those tools changes. So the quote has to have three parts, and each one has a job.

The monthly fee is the part people drop, and it is the part that decides whether the deal makes money. Every connected app will change its login, its export format, or its API eventually. If there is no monthly, that fix is a free favour and the third free favour is where the relationship sours. The recurring logic is the same as [how to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer), with a harder floor underneath it because the automation really does stop working without you.

What moves an automation quote up or down

• Number of systems connected. This is the biggest driver. Each system is its own scope, its own failure mode, and its own line on the quote.
• Cost of an error. An automation that sends invoices or touches customer records carries a higher price than one that files reports, because being wrong costs the client real money and you will be asked to guarantee it.
• Human-in-the-loop steps. A review step before anything is sent is safer for the client and more work for you - price the approval flow, do not throw it in.
• Volume. Ten runs a day and ten thousand runs a day are different products. Put the covered volume in writing.
• Who owns the accounts. Build on the client's accounts, under the client's billing, so usage costs land where they belong and the automation survives if you part ways.
• Data sensitivity. Anything touching payment or personal data needs a scope document and a longer testing phase, and both belong in the price.

The pricing mistakes that kill automation margin

• Quoting the build, not the outcome. The moment you say "it is a small build" you have priced it as a small build. Talk about hours removed and nothing else.
• Writing "connects to your tools" in the scope. Every tool the client thinks of later is now included. Name each one, with a price.
• No monthly fee. You now own every breakage, every API change, and every "it stopped working" text, for free, forever.
• Letting them see the build speed. Claude Code turning a week of work into an afternoon is your margin story. It is not the client's discount. The client is paying for the hours they get back every month, and that number did not change because you built it fast.
• Skipping the one-page scope. What triggers the automation, what it does, what it does not do, what happens on failure, and who gets told. Use the format in [how to write a statement of work for an AI project](/blog/how-to-write-a-statement-of-work-for-an-ai-project) before you start.

How to present the number so it closes

Lead with the saving you already agreed on, then put the price next to it. "This removes about the hours we counted, every month, and here is the setup fee and the monthly to keep it running" is a sentence the client can approve on the spot. Offer three shapes - the single automation, a bundle of the three tasks they complained about most, and a monthly retainer where you keep adding to it - and most clients pick the middle one. Send it as [a one-page proposal](/blog/one-page-ai-proposal-that-closes), never as a menu of technologies.

When the push-back comes, it is nearly always "we could just do it ourselves" or "that seems like a lot for something small." Both are answered by the number you measured together: the price is a fraction of what the task costs them today. If they push harder, [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection) has the exact words.

Put the method in front of a real client this week

Pricing only earns money when it is in front of someone with a repetitive task and a budget. Local service businesses, agencies, and small e-commerce shops all have a spreadsheet someone updates by hand every Monday, and nobody has offered them a straight number for making it go away.

NOTE: Inside Claude Code Club, members share the automation quotes they actually sent, what closed, and which integration line caused the scope fight - real numbers from real deals. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you want the build side first, start with [5 Claude Code workflows that get you paid](/blog/5-claude-code-workflows-that-get-you-paid).

FAQ

How much should I charge for an AI automation?

Price it against the hours it removes from the client's month, not the hours it takes to build. Measure who does the task, how often, how long, and what errors cost, then quote a fixed setup fee that is a clear fraction of the first year's saving, plus a monthly run fee, plus a separate line for each connected system. Never quote build hours.

Should an AI automation have a monthly fee?

Yes, every time. Automations depend on other people's software and stop working when a connected app changes its login, export, or API. The monthly fee covers monitoring, fixing those breakages, usage costs, and small adjustments within a stated volume. Without it, every breakage is a free favour you are obliged to do.

What makes an AI automation more expensive to build?

The number of systems it connects to is the biggest driver, followed by the cost of an error (invoicing and customer records carry more risk than reporting), any human approval steps, run volume, and data sensitivity. Build difficulty is not the driver - what the automation touches is.

Should I tell the client the automation was built with Claude Code?

Be honest about your stack if asked, but keep the pricing conversation on the hours removed. Build speed is your margin story, not the client's discount. The client is paying for the labour they get back every month, and that number is the same whether the build took a week or an afternoon.

How do I price several automations for the same client?

Offer three shapes: a single automation, a bundle of the three tasks they complained about most, and a monthly retainer where you keep adding automations over time. Present all three on a one-page proposal with the saving you measured together at the top. Most clients pick the middle option, and the retainer is the natural upgrade once the first one is running.

• To build a CRM with Claude Code, define the data model first - contacts, deals, stages, notes - then delegate the build in three phases: foundation (database plus contact list), the pipeline board, then the touches that make it daily-drivable. Each phase ends with something you can run and review.
• A personal CRM is one of the best first real builds with Claude Code because you are the user, the client, and the tester. There is no requirements guessing - you already know exactly how you track deals.
• The mistake that sinks most CRM builds is starting with features instead of data. Nail four tables before any UI exists and every screen afterward is a view over data that already makes sense.

Build a CRM With Claude Code

To build a CRM with Claude Code, open the desktop app, describe your sales process in plain language, and let Claude Code generate the database, the contact views, and the pipeline board in phases you review as you go. You do not need to know how to code - you need to know how you track deals, and you already do. The whole point of building your own CRM is that it matches your actual process: your stages, your fields, your follow-up rhythm - not a vendor's idea of a sales team you do not have.

This is a genuinely good first real project. Unlike client work, there is no requirements risk - you are the user. Unlike a toy demo, you will open it every day, which means you will notice what is missing and feed that straight back into the next session. If you have not set up the app yet, start with [the Claude Code desktop app walkthrough](/blog/claude-code-desktop-app), then come back here.

NOTE: This build follows the CCC Phase-Build method - the same foundation-first order used in [how to build a SaaS with Claude Code](/blog/build-a-saas-with-claude-code): data model, then core loop, then polish, with something runnable at the end of every phase.

Start with the data model, not the screens

Every CRM, from a spreadsheet to an enterprise suite, is four things wearing different outfits: people, deals, notes, and stages. Define those before any UI exists and every screen Claude Code builds afterward is just a view over data that already makes sense. Skip this step and you will be renaming columns and migrating half-filled tables in week two.

Write your real stages down before you prompt. If your process is lead, contacted, call booked, proposal sent, won or lost - that is five columns and it is enough. The single highest-leverage field in the whole system is next action on the deal: one line that says what you do next and when. A CRM that always answers "who do I follow up with today" has already beaten most paid tools at the only job that matters.

The first prompt and the three-phase build order

Open Claude Code in a fresh project folder and hand it the data model as your first instruction, not a feature list. Something like: "Build me a personal CRM as a local web app. Data model: contacts, deals, notes, and pipeline stages - here are the exact fields and my five stages. Start with the database schema and a contact list page with add and edit. Do not build the pipeline board yet." Asking it to hold off on later phases is deliberate - you want a small, reviewable first slice, not a wall of generated screens.

1. Phase 1 - foundation. Database schema plus a contact list with add, edit, and search. Run it, add five real contacts from your actual pipeline, and fix anything that feels wrong now, while the system is small.
2. Phase 2 - the pipeline. A board view with your stage columns, deals as draggable cards, and a deal detail page showing its notes and next action. This is the core loop - the screen you will live in.
3. Phase 3 - daily drivability. A today view listing every deal whose next action is due, quick-add for notes, and won-lost totals per stage. Small touches, but they are what turn a demo into a tool you open every morning.

Each phase is one or two sessions. End every phase by actually using the thing with real data - your contacts, your live deals - because real usage surfaces the corrections a demo never will. If a phase went sideways, the fix is a clear follow-up instruction, and [how to prompt Claude Code](/blog/how-to-prompt-claude-code) covers the goal-context-constraints shape that keeps those corrections short.

TIP: Keep it local-first. A CRM on your own machine backed by a simple database file needs no hosting, no accounts, and no monthly bill. When you later want it on more than one device, that is a deployment phase - [connect Claude Code to a database](/blog/connect-claude-code-to-a-database) covers the upgrade path.

The mistakes that turn a weekend into a month

CRM builds fail in predictable ways, and almost all of them are scope decisions, not code problems. These are the ones worth avoiding on purpose.

• Building email integration first. Syncing your inbox is the hardest feature in any CRM and the least necessary in week one. Log touches as notes by hand for a while - if you feel real friction, that is the signal to build it later, with evidence.
• Copying a SaaS CRM's feature list. You are not building a competitor product - you are building your process. Every screen a vendor ships for a ten-person sales team is a screen you will never open.
• Twelve pipeline stages. If two adjacent stages get the same follow-up behavior from you, they are one stage. Fewer columns means the board tells you something at a glance.
• Skipping real data until the end. Five real contacts in phase 1 will catch a wrong field or a missing stage in minutes. Fake seed data validates nothing.

One more that deserves its own line: review what Claude Code produced before you pile the next phase on top. You do not need to read every line - run the app, click through the loop, and check the schema matches the model you wrote. [How to review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship) is the fuller checklist.

Where this build takes you next

The quiet bonus of this project: a working CRM is a portfolio piece and a sellable skill in one. Every freelancer, coach, and small agency runs on a spreadsheet that is quietly failing them, and the person who built their own pipeline tool is the obvious person to build one shaped around someone else's process. If that direction appeals, [how to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project) shows how to turn a build like this into paid work.

NOTE: Inside Claude Code Club, members ship builds like this every week and post the prompts, schemas, and stumbles that got them there - so your first CRM does not have to hit every mistake solo. It is $9 a month at https://www.skool.com/claudecodeclub/about, and [what I built in week one of the club](/blog/what-i-built-in-week-one-of-the-club) shows what the first week actually looks like.

FAQ

Can I build a CRM with Claude Code without knowing how to code?

Yes. You describe the system in plain language - your contacts, deals, pipeline stages, and the fields you care about - and Claude Code generates the database, pages, and logic. Your job is defining the data model, reviewing each phase by actually using it, and steering with follow-up instructions. The desktop app handles the technical setup, no terminal required.

How long does it take to build a CRM with Claude Code?

A personal CRM with the four core tables - contacts, deals, notes, stages - plus a pipeline board and a today view is a weekend-scale project across a handful of sessions. What stretches it into a month is scope: email sync, a dozen stages, or copying a vendor's feature list. Follow the three-phase order and each phase ends with something runnable.

Why build your own CRM instead of paying for one?

Because a built CRM matches your actual process - your stages, your fields, your follow-up rhythm - while a paid CRM makes you work inside a vendor's model built for sales teams. A local-first build also has no monthly bill and no accounts. The tradeoff is you maintain it, which is why the build stays deliberately small: four tables and the views you genuinely use.

What features should a first CRM build include?

Contacts with add, edit, and search; deals with value, stage, and a next-action field; notes attached to contacts and deals; a pipeline board with your real stages; and a today view of due follow-ups. That is the whole first version. The next-action field is the highest-leverage piece - a CRM that answers "who do I follow up with today" is already doing the job.

What database should Claude Code use for a personal CRM?

Start with a simple local database file - it needs no hosting, no configuration, and no cost, and Claude Code will set it up as part of the foundation phase. If you later want the CRM available on multiple devices or shared with a partner, move to a hosted database as a separate deployment phase rather than taking on that complexity on day one.

• Price chatbots by tier, not by hours: a scripted FAQ bot, an AI bot answering from the client's own content, or a bot integrated with live business systems. Each tier is a different deliverable at a different fixed price - integrations are what move a quote, not build effort.
• Every AI-powered tier needs a monthly fee on top of the build price. The bot consumes API usage every day it runs and someone has to keep its answers current - unpriced, both come out of your pocket.
• Quote the outcome, not the technology. The client is buying answered questions at midnight and captured leads - the fact that Claude Code compresses your build time is your margin story, not your pricing story.

How much to charge for a chatbot

How much to charge for a chatbot comes down to one question: what is it wired into? A scripted FAQ bot that answers from a fixed set of responses, an AI bot that answers from the client's own documents and site content, and a bot connected to live systems - booking, orders, a CRM - are three different products at three different prices, even if the client calls all of them "a chatbot." Price the tier as a fixed project fee, add a monthly fee on every AI tier, and never quote hours.

This is the CCC Chatbot Pricing Ladder: three tiers a client can point at, each described by what the bot can do rather than how it works. It kills the vague "how much for a chatbot" conversation, because the client stops pricing a mystery and starts choosing a deliverable - and most will talk themselves up a tier once they see what the next rung does.

NOTE: This is the pricing half of the picture. The build half - what actually goes into each tier - is covered in [how to build a chatbot with Claude Code](/blog/build-a-chatbot-with-claude-code), and the general fixed-price logic behind it lives in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project).

The three tiers, and what moves a quote

The tiers are separated by capability, and capability is separated by integrations. That is the honest cost driver: wiring a bot into a booking system or a CRM is where the real scope lives, so it is where the price moves.

• Integrations move the price most. Each connected system is a scoped line item with its own fee. Name them individually in the quote so adding one later is an upsell, not an argument.
• Content volume moves the mid tier. A bot grounded in ten pages and a bot grounded in three hundred support articles are different setup jobs - ask how much content exists before you quote.
• Channels multiply surface area. Website widget only is the default; the same bot on WhatsApp or Instagram is an add-on per channel, not a freebie.
• Who keeps answers current moves the monthly. If you update the bot's knowledge when their prices and policies change, that maintenance is priced in the monthly fee - never bundled silently into the build.

Why every AI tier carries a monthly fee

A chatbot is not a website - it costs money every day it runs. Every conversation on an AI tier consumes API usage, and every change to the client's business quietly makes some answer stale. If you hand over an AI bot for a one-time fee, you have either signed up to pay its running costs yourself or handed the client a bot that is slowly going wrong with your name on it.

So the rule is simple: every AI-powered tier ships with a monthly fee that covers usage within a stated conversation volume, a monthly review of what people actually asked, and knowledge updates when the business changes. Put the volume number in the agreement so a traffic spike becomes a plan upgrade conversation instead of a margin leak. This is the same recurring logic as [how to price a maintenance retainer](/blog/how-to-price-a-maintenance-retainer) - the chatbot version just has a hard cost floor underneath it, which makes the monthly fee easier to defend, not harder.

WARNING: Never quote an AI chatbot as one-time-only. The build fee without the monthly is not a smaller version of the deal - it is a different deal where you own the running costs and the reputation risk for free.

Quote the outcome, not the technology

The client is not buying a chatbot. They are buying questions answered at midnight, leads captured while they sleep, and fewer repetitive emails in their inbox. Every line of the quote should be written in that language. "Your visitors get instant answers from your own content, 24 hours a day, and every conversation that looks like a buyer gets captured with contact details" closes. "AI-powered conversational agent with retrieval over your knowledge base" gets you a confused pause and a price objection.

And keep the build mechanism out of the pricing conversation entirely. Claude Code compressing a chatbot build from weeks to days is your margin story, not the client's discount. Anchor the price against what the bot replaces - hours of answering the same questions, missed after-hours leads, a part-time hire they were considering - and the fixed fee sounds small next to the problem. If they push on price anyway, that conversation is handled in [the "can you do it cheaper" objection](/blog/can-you-do-it-cheaper-objection).

The pricing mistakes that kill chatbot margin

• Quoting before you have seen the content. The number one source of underwater chatbot projects is discovering after signing that the client's "docs" are forty contradictory PDFs. Ask for the content before the number leaves your mouth.
• Leaving integrations vague. "Connects to your systems" in a quote means every system they think of later is included. Name each integration as its own line with its own price.
• Skipping the scope document. A chatbot deal has more assumption gaps than most builds - channels, volume, who updates knowledge, what happens when the bot cannot answer. Put it on one page using [the statement of work format](/blog/how-to-write-a-statement-of-work-for-an-ai-project) before you start.
• Treating the FAQ tier as beneath you. The scripted bot is a fast, low-risk yes that opens the account - and the upgrade conversation to the AI tier starts the first time the client sees a question the scripts cannot handle.
• Unlimited revisions on the bot's personality. Tone and wording tweaks are the scope creep vector on chatbot projects. Include a set number of revision rounds, then bill per round.

Put the ladder in front of a real client

Pricing structure only earns money when it is in front of someone with a problem. The pitch is one paragraph: three tiers, each described by outcome, each with a fixed price and a clear monthly where it applies - sent as [a one-page proposal](/blog/one-page-ai-proposal-that-closes), not a menu of technologies. Local service businesses, coaches, and small e-commerce shops are the natural first market, because they feel the repeated-questions problem daily and nobody has offered them a straight answer on price.

NOTE: Inside Claude Code Club, members share the chatbot quotes they actually sent, what closed, and where the scope fights came from - real numbers from real deals, not theory. It is $9 a month at https://www.skool.com/claudecodeclub/about, and if you have not shipped the build side yet, start with [how to build a chatbot with Claude Code](/blog/build-a-chatbot-with-claude-code).

FAQ

How much should I charge for a chatbot?

Price by tier, not by hours. A scripted FAQ bot is a low fixed fee priced to close fast. An AI bot grounded in the client's own content is a mid fixed fee plus a monthly. A bot integrated with live systems - booking, orders, CRM - is the highest fixed fee, priced per integration, plus a monthly. The tier is set by what the bot is wired into, because integrations are where the real scope lives.

Should a chatbot have a monthly fee?

Every AI-powered tier should. The bot consumes API usage each day it runs, and the client's business changes make answers stale over time. The monthly covers usage within a stated conversation volume, a review of what people asked, and knowledge updates. A one-time-only AI bot deal means you own the running costs and the reputation risk for free.

What makes a chatbot project more expensive?

Integrations first - each connected system (booking, orders, CRM) is its own scoped line item. Then content volume for grounded bots, extra channels beyond the website widget, and who is responsible for keeping the bot's knowledge current. Build difficulty is not the driver; what the bot is wired into is.

Should I tell clients the chatbot is built with Claude Code?

Keep the pricing conversation on outcomes - answered questions, captured leads, fewer repetitive emails - and price against what the bot replaces. The build tooling is your margin story, not the client's discount. If asked directly, be honest about your stack, but do not lead the quote with technology the client cannot evaluate.

What should be in a chatbot project scope document?

The tier and what the bot can do, the named integrations with individual prices, the channels included, the conversation volume the monthly fee covers, who updates the bot's knowledge, what happens when the bot cannot answer, and a set number of revision rounds on tone and wording. One page, agreed before the build starts - chatbot deals have more assumption gaps than most projects.

• To build a booking system with Claude Code, hand it the core loop in one sentence - a visitor sees open slots, picks one, and that slot locks - and let Claude scaffold the calendar UI, the database, and the confirmation email while you review each phase.
• The one bug that separates a demo from a real product is double-booking: two people grabbing the same slot at the same second. Name it out loud in your very first prompt so Claude locks the slot at the database layer, not just in the interface.
• You can do the entire build from the Claude Code desktop app - no terminal required. The desktop app is the recommended starting point; the terminal is optional and only earns its place once you want scripted, repeatable runs.

Build a Booking System With Claude Code

To build a booking system with Claude Code, describe the outcome you want in plain language and let Claude handle the implementation across the calendar view, the database, and the confirmation flow - while you stay in charge of the decisions. The core loop is small: a visitor lands on a page, sees which times are open, picks one, and that slot locks so nobody else can take it. Everything else - reminders, cancellations, a dashboard for the owner - is a layer you add after that loop works.

The whole thing is a genuine weekend build. Not because the code is trivial, but because Claude Code writes the plumbing while you make the calls that actually matter: what a bookable slot is, what happens when two people want the same time, and what the owner sees on the other side. This walkthrough is the exact order I built one in, including the bug that will bite you if you skip a single sentence in your first prompt.

NOTE: You can do all of this from the Claude Code desktop app. The desktop app is the easiest place to start - the terminal is optional and only worth it later when you want scripted or scheduled runs. New to the tool? Start with the [curriculum](/curriculum) and [what is Claude Code](/what-is-claude-code) before you build.

Write the one-sentence brief before you write a prompt

The build goes fastest when you do the thinking first. Before you open Claude Code, write one plain sentence that names the user, the core loop, and the data. For a booking system that sentence is: a visitor picks an open time slot from a calendar, submits their name and email, and receives a confirmation - while the owner sees every booking in one place. That sentence is worth more than any prompt trick, because Claude can write code from vague instructions but it cannot decide what the product should be.

From that sentence, three data facts fall out, and these are the things you hand Claude first. A slot has a start time, a duration, and a status (open or taken). A booking links one person to one slot. An owner needs a read view of all bookings. Name those three shapes and you have given Claude the spine of the entire app. Everything Claude scaffolds after that hangs off this data model.

1. Name the user and the outcome: a visitor books an open time slot in under a minute and gets a confirmation.
2. Name the core loop: see open slots, pick one, submit details, slot locks, confirmation sent.
3. Name the data: a slot (start, duration, status), a booking (person plus the slot it belongs to), and an owner view of all bookings.
4. Name the one rule that must never break: no two people can hold the same slot.

The four phases of the build

Most builds with Claude Code go smoothest in phases, where each phase produces something you can actually run and review before moving on. A booking system splits cleanly into four. Ask Claude for one phase at a time. Do not ask for the whole app in one prompt - you will get a large pile of code you cannot review, and the first bug will be buried three layers deep.

Phase one is where you catch data mistakes cheaply. If Claude models a slot in a way that will not scale - say, storing the taken/open state somewhere fragile - you want to find that now, when the fix is one prompt, not after you have built the booking form on top of it.

The double-booking bug (name it in your first prompt)

Here is the mistake that turns a clean demo into an embarrassing live bug. In a demo, one person books one slot and it works perfectly. In the real world, two people open the same page and both click the 9am slot within the same second. If your system only checks that the slot is open when the page loads, both bookings go through - and now you have double-booked a slot that can only hold one person.

The fix is to make the lock happen at the database layer, not in the interface. The slot has to be claimed in a single operation that checks it is still open and marks it taken at the same moment, so the second person's request finds it already gone. This is the CCC Core-Loop-First method in action: you protect the one rule that must never break before you build any of the nice-to-haves around it.

WARNING: Put this exact instruction in your phase-two prompt: "Lock the slot at the database layer so two simultaneous bookings can never take the same slot - the second request should be rejected cleanly." If you leave it out, Claude will write the naive version that works in your test and fails the first busy Monday.

Test it the way a real user will

Reviewing Claude's output is not reading every line - it is running the app the way a stranger would and watching where it breaks. For a booking system there are five checks that catch almost everything, and you do them by hand in a couple of minutes.

• Book a slot, then reload the page. The slot you took should be gone from the open list.
• Open two browser windows and try to book the same slot in both. The second one must fail cleanly, not double-book.
• Submit the form with a blank name or a nonsense email. It should refuse politely, not save garbage.
• Book a slot, then check the owner view. The booking should be there with the right person and time.
• Try to book a slot in the past. It should not be offered at all.

When one of these fails, describe the failure to Claude in plain language - "I booked 9am in one window and it let me book 9am again in a second window" - and let it fix the specific behavior. You are steering by outcome, not by editing code. That is the whole point of building this way.

Ship it live from the desktop app

A booking system that runs on your laptop is a prototype. A booking system on a live URL is a product someone can actually use. Phase four is deployment, and you can drive the entire thing from the desktop app by asking Claude to walk you through connecting the project to a host and pushing it live. The [deploy an app with Claude Code](/blog/how-to-deploy-an-app-with-claude-code) post covers the exact flow end to end.

Once it is live, the same four-phase spine becomes a productized offer. A booking system is one of the most common things a local business will pay for - a clinic, a barber, a tutor, a photographer. You built it once for yourself; the second build for a paying client takes half the time because the shape is identical and only the details change. That is the difference between a weekend project and a repeatable service.

NOTE: Inside Claude Code Club, members share the exact builds they turned into paid work - booking systems, dashboards, small automations - and the prompts that got them there. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with [10 things you can build with Claude Code](/blog/10-things-you-can-build-with-claude-code) for more weekend-sized ideas.

FAQ

How do I build a booking system with Claude Code?

Describe the core loop in one plain sentence - a visitor sees open slots, picks one, and that slot locks - then let Claude scaffold the calendar, database, and confirmation flow in four phases: foundation, booking loop, confirmation plus owner view, and deployment. Review each phase before moving on, and name the double-booking rule in your first prompt so Claude locks slots at the database layer.

Do I need to know how to code to build a booking system with Claude Code?

No. You describe what you want in plain language and Claude writes the implementation. Your job is the decisions - what a bookable slot is, what happens when two people want the same time, and what the owner sees. You review by running the app like a real user, not by reading the code line by line.

How do I stop double-bookings in a Claude Code booking system?

Make the slot lock happen at the database layer, not in the interface. Instruct Claude to claim a slot in a single operation that checks it is still open and marks it taken at the same moment, so a second simultaneous request finds it already gone and is rejected cleanly. If you only check availability when the page loads, two people can book the same slot.

Can I build a booking system in the Claude Code desktop app without the terminal?

Yes. The desktop app handles the entire build - scaffolding, the booking loop, and deployment to a live URL - with no terminal required. The desktop app is the recommended starting point. The terminal is optional and only worth adding later when you want scripted or scheduled runs.

How long does it take to build a booking system with Claude Code?

A working booking system with a calendar, a locking booking loop, a confirmation, and an owner view is a weekend build for most people. The code is not the slow part - Claude writes that. The time goes into making clear decisions up front and testing the app the way a real user would before you ship it.

• A statement of work for an AI project is one page with five parts: the outcome in a sentence, what is included, what is explicitly excluded, a timeline, and payment terms. Sent before work starts, signed back before you write a single prompt.
• The excluded list is the load-bearing part. Most scope creep happens because the client genuinely thought a feature was included and you genuinely thought it was not. Writing down what is NOT in scope prevents that fight.
• The default payment terms that work almost everywhere for builds under $15K: 50% on signing, 50% on delivery. The SOW is a closing tool, not a legal shield - keep it to one page and lead with the outcome.

How to write a statement of work for an AI project

A statement of work for an AI project is a one-page document with five parts: one paragraph naming the outcome, a bulleted list of exactly what is included, a bulleted list of what is explicitly excluded, a single-line timeline, and a payment-terms line. You send it before any work starts and get it signed back before you write a single prompt. That one discipline saves more revenue than any rate increase, because it stops scope creep before it begins instead of arguing about it after.

The SOW does not need to be a twenty-page legal contract. For AI builds under $15K it is one page, plain language, sent as a document the client can read in two minutes and sign in one. Its job is not to win a lawsuit - it is to make sure you and the client are holding the exact same picture of what is being delivered before either of you commits time or money. This is the CCC One-Page-SOW method: the shortest document that still closes cleanly and protects your margin.

NOTE: The SOW is the last step before you build, not the first step in the relationship. It comes after a [discovery call for AI projects](/blog/discovery-call-for-ai-projects) and a [one-page AI proposal](/blog/one-page-ai-proposal-that-closes) - by the time you write the SOW, the client has already said yes to the direction.

The five parts of a one-page SOW

Every part earns its place. Cut any one of them and you reopen a gap the client will walk through later. Here is what each part does and why it is there.

Notice what is not on the list: your methodology, your tools, or how many hours you expect it to take. The client is buying an outcome, not your process. Lead every line with the result the client gets. The mechanism - that you built it with Claude Code in a weekend - belongs in your head, not on the SOW.

The outcome paragraph: sell the result, not the build

The outcome paragraph is the one part a non-technical client actually reads closely, so make it about them. Name the finished thing and the result it produces in their words. "A booking system on your site that lets clients pick an open time and book themselves, so your front desk stops playing phone tag" beats "a full-stack web application with a calendar component and a database." Same build, completely different document.

If a client later asks what they are really paying for, the honest answer should already be the first sentence of the SOW. Lead with the outcome on every line and the price stops feeling like an hourly rate and starts feeling like the cost of a solved problem. That reframe is worth more than any discount.

The excluded list does the heavy lifting

Most people write the included list and stop. That is the mistake. The excluded list is the load-bearing part of the entire document, because most scope creep does not come from a client trying to get free work - it comes from an honest mismatch. The client genuinely thought a feature was included; you genuinely thought it was not. The excluded list is where you resolve that before it becomes a fight over unpaid work.

• Name the obvious adjacent features you are NOT building. If you are building a booking system, exclude the payment integration, the SMS reminders, and the customer login unless they are in the included list. The client may have assumed all three.
• Put a price on the things you are excluding, not just a no. "SMS reminders are not included in this scope; they can be added for a fixed $600." This turns a future argument into a future upsell the client already expects to pay for.
• Exclude open-ended support. If maintenance is not in the SOW, every "quick fix" after launch is unpaid work eating your next project. Either bundle a defined support window ("30 days of bug fixes included") or quote a separate retainer.
• Exclude revision counts you have not agreed to. "Two rounds of revisions on the design are included; further rounds are billed at a fixed rate per round." Unlimited revisions is how a fixed-price project becomes an hourly project you forgot to bill for.

TIP: A good test: read your excluded list and ask "what is the most expensive thing a client could reasonably assume is included?" If it is not on the excluded list, add it. The excluded list should name the exact thing that would otherwise cost you a weekend of free work.

Payment terms that get money moving

For AI builds under $15K, the payment terms that work almost everywhere are 50% on signing and 50% on delivery. The deposit is not optional - it is the line that separates a real project from a client who is still shopping. A client who will not put down a deposit will not respect the scope either. The deposit filters for commitment before you spend a single hour building.

Define what "delivery" means in the same line, because that word triggers your final payment. Delivery is the deployed, working thing doing what the outcome paragraph promised - not "the client is fully satisfied," which is an open-ended standard that never triggers. Tie the final payment to an objective event: the system is live and passes the acceptance checks listed in the SOW. For larger builds, add a milestone payment in the middle so you are never carrying more than a third of the project unpaid.

Send it so it closes instead of stalls

A one-page SOW is a closing tool, so send it like one. Do not attach it to an email with "let me know your thoughts" - that invites edits and delay. Send it as the natural next step after the client has already said yes: "Great - here is the one-page scope so we are both looking at the same thing. Sign at the bottom and I will get started this week." The SOW confirms a decision that has already been made; it does not reopen it.

Keep it to one page on purpose. A twenty-page contract makes a small client nervous and invites their lawyer into a $3,000 deal. One page, plain language, five parts, signed same-day. If a client needs a heavier legal agreement, that is a separate document layered on top - the SOW is what gets the work started this week. Pair it with the [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) guide when a project is large enough to need both.

NOTE: Inside Claude Code Club, members swap the exact SOW templates, exclusion lists, and payment-term language that close AI projects without scope creep. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with [how to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project) to nail the scope before you write the SOW.

FAQ

What is a statement of work for an AI project?

A statement of work (SOW) for an AI project is a one-page document that names the outcome in a paragraph, lists exactly what is included, lists what is explicitly excluded, sets a timeline, and states payment terms. It is sent and signed before any work starts, and its job is to make sure you and the client share the same picture of what is being delivered before either of you commits time or money.

What should a statement of work include for an AI build?

Five parts: one paragraph naming the outcome and the result it produces, a bulleted list of exactly what is included, a bulleted list of what is explicitly excluded, a single-line timeline with start and delivery dates, and a payment-terms line (50% on signing, 50% on delivery is the default for builds under $15K). Leave out your methodology and hours - the client is buying an outcome, not your process.

Why is the excluded list the most important part of a SOW?

Because most scope creep is an honest mismatch, not a client trying to get free work. The client thought a feature was included; you thought it was not. The excluded list resolves that before it becomes an argument over unpaid work. Name the most expensive thing a client could reasonably assume is included, and put a fixed price on it so a future dispute becomes a future upsell.

What payment terms should I use in an AI project SOW?

For builds under $15K, 50% on signing and 50% on delivery works almost everywhere. The deposit filters for a client who is committed rather than still shopping. Define delivery as the deployed, working system passing the acceptance checks in the SOW - not "the client is satisfied," which never triggers. For larger builds, add a milestone payment in the middle so you never carry more than a third unpaid.

How is a statement of work different from a contract?

A SOW defines the specific deliverable, scope, timeline, and payment for one project, on one page, in plain language. A contract is the broader legal agreement covering liability, ownership, and terms across the relationship. For most AI projects under $15K a one-page SOW is enough to start work. When a project is large enough to need heavier legal protection, layer a contract on top - do not replace the SOW with it.

• /clear wipes the conversation to a blank slate - the agent forgets everything you just discussed and starts fresh. Use it when you switch to an unrelated task.
• /compact summarizes the conversation into a short recap and keeps going - the agent remembers the gist of what you were doing. Use it when you want to continue the same task but the window is filling up.
• The rule I use: new task = /clear, same task but running low on room = /compact. Your CLAUDE.md and open files reload either way, so a reset is cheaper than beginners fear.

What is the difference between /clear and /compact in Claude Code?

Both commands free up room in the context window, but they do opposite things with your conversation. /clear throws the whole conversation away and gives you a blank slate - the agent no longer remembers a single thing you said in that session. /compact keeps the conversation alive by replacing it with a short summary of what happened, so the agent still knows what you were working on but takes up far less room doing it.

Put simply: /clear is a reset, /compact is a save-and-shrink. You reach for /clear when you are done with one thing and moving to something unrelated. You reach for /compact when you are in the middle of a task, the window is filling up, and you want to keep the thread without losing your place.

What /clear actually does

/clear empties the conversation history for the current session. After you run it, the agent behaves as if you just opened the project - it has no memory of the questions you asked, the files it read, or the decisions you made a moment ago. What it does NOT wipe is your project setup: your CLAUDE.md file, your settings, and any files you point it at are all still there to be reloaded when the next task needs them.

This is why a reset costs less than most beginners assume. You are not deleting your project or your instructions. You are clearing the short-term chatter of one task so the next task starts clean, with a full window and no leftover context nudging the agent in the wrong direction.

TIP: A stale conversation is a real source of bad output. If the agent keeps referencing a file or a decision from twenty minutes ago that no longer applies, that leftover context is the problem - /clear removes it in one keystroke.

What /compact actually does

/compact asks the agent to write a concise summary of the conversation so far, then replaces the full back-and-forth with that summary. The result is a much smaller footprint that still carries the important thread: what you are building, what has been tried, and where you left off. You keep working in the same session, on the same task, with room to spare.

The tradeoff is fidelity. A summary is not the full transcript, so fine detail can get flattened - an exact variable name, a subtle edge case you discussed once, a specific line the agent quoted earlier. For most work the summary keeps enough to continue smoothly. For work where a precise detail matters, restate that detail in your next prompt right after compacting so it survives the shrink.

The rule I use to decide, every session

I do not overthink it. The decision comes down to one question: am I still on the same task, or have I moved to a new one?

1. New, unrelated task = /clear. I finished the login page and now I am writing a cold email. Nothing from the login work helps the email, and leftover context only risks confusing the agent. Blank slate.
2. Same task, window filling up = /compact. I am halfway through a feature, the agent has read a dozen files, and the window is getting tight. I want to keep going without losing the thread, so I summarize and continue.
3. Same task, plenty of room left = do nothing. Compacting early throws away detail you did not need to lose. Only compact when you are actually running low.

I call this the CCC context reset habit: clear between tasks by default, compact only mid-task under pressure. It keeps every session starting sharp and stops the slow drift that happens when one long conversation tries to hold three unrelated jobs at once.

Why a bloated conversation hurts output

As a conversation grows, two things get worse. First, you run out of room - a full window forces the agent to drop older context on its own, often the exact context you wanted kept. Second, and more subtle, a long thread full of half-finished tangents makes the agent slower and less focused, because it is weighing every past message when it decides what to do next. Managing context deliberately is a core part of keeping long sessions on track - see [Claude Code context management: how to keep long sessions on track](/blog/claude-code-context-management).

Make context resets a habit before your next build

Start every new task with a clean window and you will notice the agent stays sharper for longer. Clear between unrelated jobs, compact when a single task outgrows its window, and restate any critical detail right after you compact. It is a thirty-second habit that removes a whole category of confusing, off-target output.

NOTE: Inside Claude Code Club we share the exact session habits members use to keep long builds on track without babysitting the window. Start with the [curriculum](/curriculum) or join us at https://www.skool.com/claudecodeclub/about and bring the project you keep losing context on.

FAQ

What is the difference between /clear and /compact in Claude Code?

/clear wipes the conversation to a blank slate - the agent forgets everything you discussed in that session. /compact summarizes the conversation and keeps going, so the agent remembers the gist while using far less of the context window. Use /clear between unrelated tasks and /compact mid-task when the window is filling up.

Does /clear delete my project or my CLAUDE.md file?

No. /clear only empties the current conversation history. Your project files, settings, and CLAUDE.md are untouched and reload when your next task needs them. That is why a reset is cheaper than it feels - you are clearing one task's chatter, not your setup.

When should I use /compact instead of /clear?

Use /compact when you are still on the same task and want to keep the thread but the context window is running low. It summarizes what has happened so far and lets you continue with room to spare. If you were switching to an unrelated task instead, /clear is the better choice.

Does /compact lose information?

Some. A summary is not the full transcript, so fine detail can get flattened - an exact variable name or a subtle edge case discussed once. For most work the summary keeps enough to continue. If a precise detail matters, restate it in your next prompt right after compacting so it survives.

• Resuming a session brings back the whole conversation - what you were building, the files the agent read, the decisions you made - so you continue instead of re-explaining everything.
• Two ways to do it: continue your most recent session in one step, or open the list of past sessions and pick the exact one you want.
• The mistake that loses your context is starting a brand new session by habit. If you closed the app mid-task, resume the old one on purpose rather than opening a fresh window.

How do I resume a Claude Code session?

You resume a session by telling Claude Code to reopen a past conversation instead of starting a new one. When you do, the agent brings back the full thread: what you were building, the files it had read, and the decisions you made together. You pick up mid-task rather than re-explaining the whole project from scratch. There are two ways to get there - continue your most recent session in a single step, or open the list of your past sessions and choose the exact one you want.

This works the same way whether you build in the desktop app or the terminal. The desktop app is the easiest place to start - your recent sessions are listed for you to reopen with a click. The terminal offers the same thing through a continue option for your latest session and a resume option that shows the full list.

Continue your most recent session (the fast path)

Most of the time you want the session you were just in - you closed the laptop, made coffee, and now you want to keep going on the same feature. This is the one-step path: continue the latest session. The agent reopens the conversation you had going most recently, with all of its context intact, and you carry on from your next prompt as if you never stepped away.

TIP: If you only ever work on one thing at a time, continue-the-latest is all you need. It is the fastest way back into flow after a break.

Pick an older session from the list

When you have several projects going, the most recent session is not always the one you want. Opening the list of past sessions lets you scan your previous conversations and choose the exact one to reopen - the client dashboard from Tuesday, not the personal script you touched an hour ago. Each entry represents a distinct conversation thread you can bring back in full.

This is the difference between resuming and merely reopening a project folder. Reopening the folder gives you the files. Resuming the session gives you the files AND the conversation - the reasoning, the half-finished plan, the thing the agent already figured out - so you are not paying twice to rebuild context you already had.

The mistake that loses your context

The most common way people lose a session is simple: they open a brand new one out of habit. You come back to the desk, launch Claude Code, and start typing - and now you are in a fresh conversation that knows nothing about yesterday's work. The old session still exists, but you talked past it. The fix is to pause for one second when you sit down and ask whether you are continuing something or starting something new.

1. Continuing yesterday's work? Resume the session first, then type. Do not start prompting in a fresh window and expect the agent to remember.
2. Starting something genuinely new and unrelated? A new session is correct - a clean slate is what you want, the same logic behind clearing context between tasks.
3. Not sure which session was the right one? Open the list and read the recent conversations rather than guessing; picking the wrong one wastes the reload.

NOTE: Resuming restores the conversation, but it is not a substitute for durable project memory. For context that should survive across every session, put it in your CLAUDE.md file so the agent reloads it automatically - see [The Claude Code memory bank: how to keep context across every session](/blog/claude-code-memory-bank).

When to resume, when to start fresh

Resuming is the right move whenever the old context still helps. Starting fresh is right when it would only get in the way. The two decisions are mirror images of managing context inside a single session.

Build the resume habit into how you work

Make resuming the default when you return to unfinished work, and starting new the deliberate exception. That one habit removes the daily tax of re-explaining a project the agent already understood an hour ago. Pair it with a solid CLAUDE.md for the context that should never be lost, and you rarely start cold again.

NOTE: Inside Claude Code Club we walk members through the session and memory habits that keep long client builds moving without re-explaining the project every morning. Start with the [curriculum](/curriculum) or join us at https://www.skool.com/claudecodeclub/about and bring the project you keep losing your place on.

FAQ

How do I resume a Claude Code session?

Tell Claude Code to reopen a past conversation instead of starting a new one. You can continue your most recent session in one step, or open the list of past sessions and pick the exact one you want. Either way the agent brings back the full thread - what you were building, the files it read, and the decisions you made.

What is the difference between resuming a session and reopening a project?

Reopening a project folder gives you the files. Resuming a session gives you the files AND the conversation - the reasoning, the half-finished plan, and the context the agent already worked out. Resuming means you do not pay twice to rebuild context you already had.

Why did Claude Code forget my previous conversation?

Almost always because a brand new session was started by habit. Launching Claude Code and typing straight away opens a fresh conversation that knows nothing about earlier work. The old session still exists - resume it on purpose before you start prompting instead of opening a new window.

Should I use resume or my CLAUDE.md file for keeping context?

Both, for different jobs. Resume restores one specific conversation so you can continue a task. CLAUDE.md holds durable context you want reloaded automatically in every session. Use resume for short-term continuity and CLAUDE.md for the facts and rules that should never be lost.

• A portfolio built with Claude Code is three to four live, publicly accessible projects that each solve one real problem. Screenshots of local builds do not count. Hosted URLs do.
• Build in this order: a landing page for a fake business, a utility tool you actually use, a small app for a real person (a friend, a family business, anyone), then one build that matches your target client type.
• The goal is not to impress developers. It is to show a non-technical client that you can take an idea, build it, deploy it, and hand it over. Every portfolio piece should have a live URL and one sentence explaining what problem it solves.

Build a Portfolio With Claude Code

To build a portfolio with Claude Code, you need three to four live, publicly accessible projects that each prove one thing: you can take a brief, build something real, deploy it, and hand it over. That is the entire bar for a first portfolio. You do not need polished design, ten projects, or impressive code - you need hosted URLs that a prospective client can click and use. Claude Code handles the implementation. Your job is to pick the right projects and ship them.

The desktop app is where you start. Open it, point it at a new project folder, and describe what you are building. Claude Code reads your description and builds the files. You review, steer, and deploy. No terminal configuration required - the app handles the shell access Claude needs to write and run code on your machine. If you have not set up the desktop app yet, the [Claude Code desktop app guide](/blog/claude-code-desktop-app) walks through the first-time setup.

NOTE: This post is about building a portfolio to attract clients. If you are earlier in the process and still learning the basics, [Claude Code tips for beginners](/blog/claude-code-tips-for-beginners) covers the habits that make every build faster. If you already have a few projects and want to turn them into clients, [how to find clients for your AI agency](/blog/how-to-find-clients-for-your-ai-agency) picks up where this post leaves off.

The CCC Portfolio Stack: What to Build and in What Order

The CCC Portfolio Stack is a four-project sequence designed to get you from zero to a credible portfolio in under two weeks. Each project builds on the previous one and covers a different skill area that clients care about. The sequence matters - do not start with the hardest project.

1. A landing page for a fake business. Pick an industry you understand - a local gym, a freelance photographer, a small accounting firm. Build a one-page site that shows the services, includes a contact form, and is deployed live on a real URL. This proves you can build and deploy a client-facing web page. Time: one afternoon.
2. A utility tool you actually use. A script, a small app, or an automation that solves a problem you have today. A CSV cleaner, a link shortener, a time tracker, a daily standup generator. Real use = real proof the tool works. Deploy it publicly and use it for a week before adding it to the portfolio. Time: one to two days.
3. A build for a real person. A landing page for a friend's side hustle, a booking widget for a family business, an invoice generator for a freelance contact. This project teaches you the client communication loop: briefing, delivering, revising, handing over. That loop is the actual skill you are selling. Time: two to three days.
4. One project that matches your target client type. If you want to work with restaurants, build a reservation page. If you want to work with coaches, build a course waitlist and payment page. If you want to work with agencies, build a client reporting tool. This project is your strongest conversation starter because it demonstrates you understand their world specifically. Time: two to three days.

TIP: Every project in the CCC Portfolio Stack must have a live URL and a one-sentence description of what problem it solves and for whom. Those two things are what a client reads when they review your work. The URL says you can ship; the sentence says you understood the brief.

How to Deploy Each Project So It Has a Real URL

A portfolio piece without a live URL is a screenshot, not a project. The fastest zero-cost deployment path for Claude Code builds is Vercel for web apps and sites. Claude Code can generate the deployment configuration alongside the project, and Vercel's free tier gives you a public URL under vercel.app with no credit card required.

In practice: once your build is working locally, tell Claude Code you want to deploy it to Vercel. Claude will write or update the configuration files, point you to the Vercel CLI command or the drag-and-drop deploy option, and the result is a live URL in under five minutes. The [how to deploy an app with Claude Code](/blog/how-to-deploy-an-app-with-claude-code) guide covers every deployment path in detail, including Netlify and Railway for projects that need a backend or database.

What Your Portfolio Page Should Say

Your portfolio does not need to live on an expensive custom site. A single page - even a well-formatted Notion page or a simple HTML page you built with Claude Code - that lists your four projects with their URLs and one-sentence descriptions is enough to start. Add a short paragraph at the top that says who you help and what kind of builds you take on. Keep it plain. Clients do not read long bios.

For each project, write: the name of the project, a one-sentence description of what it does and who it is for, and the live URL. If the project was built for a real person, include their name and one sentence they said about working with you. If it was a self-initiated build, say so and describe what problem you were solving. That level of honesty works well - it shows you are not inflating experience you do not have.

NOTE: Two or three projects with live URLs and clear problem descriptions out-earn a portfolio of twenty vague descriptions of work. Clients do not count projects - they look for proof that you understood a brief and delivered something that works. Specificity is the proof.

The Portfolio Mistake That Costs Clients

The single most common portfolio mistake among new Claude Code builders is waiting until the work is polished. Most people spend three weeks refining project two while project one sits on localhost, never deployed. No client ever saw that project. The portfolio with three live but imperfect projects beats the one with one perfect project that took a month to finish.

A live URL that does what you said it would do is already a finished portfolio piece. Ship it, add it to your portfolio page, and start the next one. You can update any project later - and the practice of updating a deployed project is itself a skill worth demonstrating. The four-project sequence in the CCC Portfolio Stack is designed to be completable in under two weeks. The clock starts when you open the desktop app and begin project one.

• Never put a project in your portfolio that is not live. A GitHub link with no deployed URL is invisible to most clients.
• Never describe a project without naming the problem it solves. Technology names mean nothing to non-technical clients.
• Never wait for permission to build a self-initiated project. You do not need a client to build something portfolio-worthy.
• Never skip the handover step on the real-person project. The practice of explaining and handing over a build is the hardest skill and the most valuable one to demonstrate.

When Your Portfolio Is Enough to Start Taking On Clients

Your portfolio is ready to support a client conversation the moment you have two live URLs and a clear sentence about what you build. You do not need four projects to start outreach. You need enough to answer the question a prospective client will always ask: 'can you show me something you've built?'

Two deployed projects that are relevant to the type of client you are targeting are enough to have that conversation. Add the third and fourth while you are in early conversations. Every additional project you ship strengthens the next outreach. Inside Claude Code Club, members share their first portfolio projects, get feedback from the community, and find early clients without cold pitching. That combination - real projects, honest feedback, and warm introductions - shortens the gap from portfolio to first paid build significantly. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

FAQ

What should I build for my Claude Code portfolio?

Follow the CCC Portfolio Stack: a landing page for a fake business, a utility tool you actually use, a build for a real person, and one project that matches your target client type. Every project must have a live, publicly accessible URL. Screenshots of local builds do not count as portfolio pieces - clients need to click and see it working.

How many projects do I need before I can get clients?

Two live projects that are relevant to your target client type is enough to start having conversations. You do not need a complete portfolio to begin outreach. Add the third and fourth project while you are in early conversations. Two deployed, relevant projects answer the first question every client asks: can you show me something you have built?

How do I deploy a Claude Code project for free?

Vercel is the fastest zero-cost path for web apps and sites. Once your build is working locally, tell Claude Code you want to deploy to Vercel - it will write or update the configuration files. Vercel's free tier gives you a live URL under vercel.app with no credit card required and deployment in under five minutes. For projects that need a database, Railway or Supabase paired with Vercel covers the full stack.

Can I build portfolio projects without real clients?

Yes - and you should. Invent a fake business, pick an industry you understand, and build the exact deliverable you want to sell. A landing page for a fake gym is as useful as a portfolio piece as one for a real gym. The goal is a live URL that demonstrates you can go from brief to deployed product. Self-initiated builds are entirely valid.

What should my portfolio page say?

For each project: the project name, a one-sentence description of what it does and who it is for, and the live URL. Add a short paragraph at the top naming who you help and what kind of builds you take on. If a project was built for a real person, include their name and a one-sentence comment. Keep it plain. Clients read for proof, not biography.

• You can get AI clients without a portfolio if you stop positioning yourself as an AI developer and start positioning yourself as someone who solves a specific problem for a specific type of business.
• The fastest first-client path is a narrow, low-risk offer: one specific deliverable, one specific client type, a price they can say yes to without a meeting, and a fast proof you can produce in 48 hours.
• The objection you will face is not 'I need to see your portfolio' - it is 'I do not know if this is worth it.' Answer that before they ask by making the first step risk-free.

Why the Portfolio Problem Is Actually a Positioning Problem

Most people trying to get AI clients without a portfolio are not actually blocked by the lack of work to show. They are blocked by a positioning problem: they are asking clients to evaluate them as a generalist AI developer, and generalist developers need portfolios because there is no other way to know what they can do. Narrow your positioning to one specific outcome for one specific type of business and the portfolio question mostly disappears.

A client who hires a 'freelance AI developer' needs proof because the scope is undefined. A client who hires 'someone who builds booking systems for service businesses' has a much clearer picture of what they are buying. The more specific your positioning, the less proof you need - because the specificity itself carries credibility. You are not asking them to guess what you do.

NOTE: If you are still working out what type of client to focus on, [how to pick a niche for your AI agency](/blog/how-to-pick-a-niche-for-your-ai-agency) covers the niche decision in detail. The first-client tactics in this post assume you have at least a working hypothesis for a niche - a specific type of business or a specific kind of problem you want to solve.

The CCC First-Client Offer: How to Structure a No-Portfolio Sale

The CCC First-Client Offer is a format designed specifically for closing a first client when you have nothing to show. It has three parts: a narrow specific deliverable, a fast proof you can produce in 48 hours, and a risk-reversal that makes the first step easy to say yes to.

The fast proof is the most important part. When you have no portfolio, you replace social proof with live demonstration. You find the client, understand their basic need, build a rough version of the deliverable using their actual content - their business name, their service, their words - and send it to them. That build takes a few hours with Claude Code. The client receives something real, not a promise. That is a stronger close than a portfolio of work you did for other businesses.

How to Find the First Client Without Inbound

The fastest first-client path when you have no track record is warm outreach to your existing network, not cold outreach to strangers. You do not need a large network. You need three to five people who know you, run or work at a small business, and have a problem you can solve with Claude Code.

Start by listing everyone you know who owns or manages a small business. This list is longer than you think. Former colleagues who went independent. Family members who run a service business. Friends who sell something. People you follow on LinkedIn who have posted about a business problem. For each person, ask one question: is there one annoying thing in their business that a simple tool or page could fix? That is your opening. Not 'I do AI stuff' - 'I noticed you mentioned you spend two hours a week on X, I built something that handles that in five minutes, want to see it?'

• Start with your warm network - people who already know you are competent at something.
• Look for a specific operational pain, not a vague interest in AI.
• Build the fast proof before you ask for money. The build is the pitch.
• Price the first project to be easily affordable - the goal is a completed delivery and a testimonial, not maximum margin.
• Ask for a specific referral or testimonial when you hand over the work. That is the asset you are really building.

How to Handle the Portfolio Objection When It Does Come Up

When a prospective client does ask to see your portfolio, the worst answer is 'I do not have one yet.' The better answer names what you have built and why it is relevant to them specifically, even if it was a self-initiated project. 'I built a booking system for a fitness studio - it is not a client project but it is live and does exactly what you're describing. Want me to send the URL and build you a rough version based on your setup?'

That answer does three things: it names a specific thing you built, it proves you are already thinking about their specific context, and it offers a fast proof that advances the conversation instead of stalling it. The client is not really asking for a portfolio - they are asking for confidence that you can deliver. The fast proof gives them that directly. A live URL you built in an afternoon is more convincing than a PDF of past work.

TIP: Build at least one self-initiated project in your target niche before you start outreach. It takes a day with Claude Code. The [build a portfolio with Claude Code](/blog/build-a-portfolio-with-claude-code) post covers exactly what to build and how to deploy it. With one live URL relevant to your niche, you are no longer answering the portfolio question from zero.

What to Charge for the First Client

Price the first project to be easy to say yes to, not to maximize your rate. A first project priced between $300 and $800 removes the budget objection and lets you focus on the delivery. The goal of the first client is not margin - it is a completed delivery, a testimonial, and a referral. Those three assets are worth more than the difference between $300 and $1,500 for client number one.

Once you have a delivery, a testimonial, and ideally a referral, your second client is dramatically easier. You have proof. You have a name who can vouch for you. You can raise your price to reflect the value you demonstrated. The first-client discount is a one-time investment in social proof, not a permanent rate. Most experienced freelancers inside Claude Code Club closed their first client in this range and were at $1,500 to $3,000 per project by client number three.

If you want the fastest path to sustainable client work - and the pricing frameworks, proposal templates, and warm outreach scripts to run it - join Claude Code Club for $9 a month at https://www.skool.com/claudecodeclub/about. You will find members at every stage, from first outreach to established retainer books, and the community feedback loop shortens every part of this timeline.

FAQ

Can I get AI clients without a portfolio?

Yes - if you replace the portfolio with two things: a narrow, specific positioning that makes your offer clear without proof, and a fast proof you build and send before asking for money. A rough version of the deliverable built on the prospect's actual content - their business name, their service, their copy - is more convincing than a portfolio of work done for other businesses. It takes a few hours with Claude Code and costs nothing.

What should my first AI client offer look like?

The CCC First-Client Offer has three parts: a narrow deliverable (one specific outcome for one specific type of business), a fast proof (something small you can build and send in 48 hours), and a risk-reversal (an entry price or satisfaction guarantee that makes the first yes easy). All three parts together remove the three objections a no-portfolio freelancer faces: 'I do not know what I am buying,' 'I do not know if you can do it,' and 'I do not know if it is worth the risk.'

How do I find my first AI client with no track record?

Start with warm outreach to your existing network. List everyone you know who owns or manages a small business. For each person, identify one specific operational pain that a simple tool or page could fix. Build a rough version of that fix using their actual content before you ask for money. The build is the pitch. Warm network outreach converts faster than cold outreach because the trust is already there.

What should I charge for my first AI project?

Price the first project between $300 and $800 to remove the budget objection. The goal of the first client is a completed delivery, a testimonial, and a referral - not maximum margin. Those three assets are worth more than the difference between your first-client rate and your target rate. Once you have proof, raise the price for client number two and beyond.

How do I handle the portfolio objection?

Name a specific project you built (even a self-initiated one) that is relevant to their situation, and immediately offer to build them a fast proof. 'I built a booking system for a service business - here is the URL - want me to put together a rough version for your setup?' That answer gives them a live example and advances the conversation. The client is asking for confidence you can deliver, not a formatted PDF of past work.

• Claude Code project templates are folder scaffolds that include a CLAUDE.md, a project structure, and any starter config your stack needs. They eliminate the slow first-session setup and give the agent context before the first prompt fires.
• The CCC Starter Framework is a three-file minimum: CLAUDE.md for project context, a SPEC.md for what you are building, and a .gitignore tuned for the stack. That is enough for Claude Code to work without guessing.
• Install a template once from the desktop app's project settings, and every new project starts from the same clean baseline. You iterate on the template over time as you learn what context Claude Code actually needs.

What Claude Code Project Templates Actually Are

A Claude Code project template is a pre-configured folder you drop into a new repo before your first session starts. It includes at minimum a CLAUDE.md that tells the agent what this project is, what stack it uses, and what rules apply. It can also include a spec scaffold, a .gitignore, a folder structure, and any config files your stack expects. The point is that the agent starts with context instead of guessing.

Without a template, the first session of every project is the same slow friction: Claude Code asks clarifying questions or makes wrong assumptions, you correct them, the context fills up correcting errors instead of building. A template eliminates that friction by front-loading the information the agent needs. It is the single highest-leverage setup habit for anyone doing more than one build.

NOTE: If you have not yet written your first CLAUDE.md, the [CLAUDE.md guide](/blog/claude-code-claude-md-file) covers the format in detail. Templates build on top of that - they are a CLAUDE.md plus the surrounding structure your stack needs.

The CCC Starter Framework: Three Files That Cover Every Build

The CCC Starter Framework is the minimum-viable template that works across every stack. It is three files: CLAUDE.md, SPEC.md, and a stack-appropriate .gitignore. Everything else is optional and stack-specific. Here is what goes in each one.

The CLAUDE.md in a project template is a stub - it has the headings filled in but the project-specific content left blank. You fill it once when you create the project and it stays put. The SPEC.md is a scaffolded list of sections: what you are building, the user you are building it for, the data model, the routes, and the done criteria per feature. Fill in the sections before you prompt Claude Code and you get a first session that produces working code instead of architecture debates.

How to Install a Template in the Claude Code Desktop App

In the Claude Code desktop app, open the project settings panel for any new project. There is a project directory field - point it at a new folder. Before your first prompt, copy the template files into that folder from your template library. The desktop app picks up CLAUDE.md automatically and uses it as persistent project context for every session in that project.

The workflow is: create a new project folder, copy the template into it, fill in the CLAUDE.md blanks for this specific project, open the project in the desktop app, and start your first session. That is it. No terminal commands required to wire up the context - the desktop app reads CLAUDE.md from the project root by default.

• Keep your templates in a dedicated folder on your machine - something like ~/templates/ccc-starter - so copying is one command.
• Fill in the CLAUDE.md project name, stack, and rules fields before you open Claude Code. Leaving them blank defeats the template.
• Add a SPEC.md stub even if you fill it later - it signals to the agent that a spec exists and it should look there first.
• Update the template folder whenever you discover a rule or convention that would have saved you time on a project.

Stack-Specific Template Additions Worth Having

The three-file baseline works for any project. Stack-specific additions pay off when you build in the same stack repeatedly. A Next.js template should include a tsconfig.json stub, a tailwind.config.ts, and a src/app folder structure that matches how you organize pages. A Python agent template should include a pyproject.toml stub, a .env.example, and an agents/ folder with a README that tells Claude Code where tools live.

The rule is: add a file to a template only after you have manually created it on two or more projects. If it shows up twice, it belongs in the template. If it is a one-off, it does not. That keeps templates lean enough to actually use rather than a graveyard of half-configured files.

Keeping Your Templates Up to Date

A template is a living document, not a one-time setup. Every time you finish a project and notice a rule you had to correct, a folder you had to create, or a convention Claude Code kept getting wrong, those are template updates. Spend five minutes at the end of each project updating the relevant template. Over ten projects, the template becomes a machine that handles 80 percent of the first-session setup without any prompting.

The right signal that a template is mature is that your first session produces working, mergeable code rather than architectural scaffolding you have to clean up. Most CCC members reach that point after three to five iterations of the same template. The first version is always rough - the fifth version is quiet and reliable.

TIP: Inside Claude Code Club we share ready-to-copy templates for the most common stacks - Next.js, Express, Python agents, and CLI tools. You can drop them into any project today and adapt them as you go. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

FAQ

What is a Claude Code project template?

A pre-configured folder that includes at minimum a CLAUDE.md, a SPEC.md stub, and a stack-appropriate .gitignore. It gives the agent project context before your first prompt fires, eliminating the slow setup phase where Claude Code guesses at your conventions. You copy it into each new project and fill in the project-specific blanks.

What should go in a Claude Code project template?

The CCC Starter Framework minimum is three files: CLAUDE.md (project identity, stack, rules), SPEC.md (what you are building), and .gitignore (keeps secrets and build artifacts out of your repo). Add stack-specific files - tsconfig, tailwind config, folder structures - only after you have manually created them on two or more projects.

How do I install a template in the Claude Code desktop app?

Create a new project folder, copy the template files into it, fill in the CLAUDE.md project-specific blanks, then open that folder as a new project in the desktop app. Claude Code reads CLAUDE.md from the project root automatically and uses it as persistent context for every session. No terminal configuration needed.

How often should I update a project template?

After every project. Spend five minutes at the end noting any rule you had to correct, folder you had to create, or convention Claude Code kept getting wrong - those are template updates. A template matures across three to five uses of the same stack. The first version is rough; the fifth is reliable.

Do I need a different template for each stack?

Not necessarily. The three-file CCC Starter Framework baseline works for any stack. Add stack-specific files only when you notice yourself manually creating the same thing on multiple projects. You might end up with one base template and two or three stack-specific variants rather than a unique template per stack.

• Packaging an AI service means turning a repeatable build into a fixed deliverable at a fixed price. The client buys a defined outcome, not your time. You can sell the same package to ten different clients without re-scoping it each time.
• The CCC Offer Box framework has four parts: the named outcome, the fixed scope, the price, and the delivery timeline. Every part must be specific enough that the client does not need to ask a follow-up question to understand what they are buying.
• The moment to package a service is when you have delivered the same kind of build twice. After two deliveries you understand the real scope, the real edge cases, and the real delivery time. Before two deliveries you are guessing at the package.

Why Packaging an AI Service Changes How You Sell

When you sell an AI service as a packaged offer - a fixed deliverable at a fixed price - you remove the single biggest friction point in closing a deal: the client does not understand what they are buying. Most AI freelancers describe their service in terms of the technology they use (Claude Code, n8n, Supabase) or the process they follow (discovery call, build phase, handover). Clients do not buy processes or tools. They buy outcomes. A package names the outcome and puts a price on it.

The other benefit is on your side: you can sell the same package without re-scoping it from scratch. Hourly work requires a bespoke estimate every time. A package requires a two-minute qualification call to confirm the client fits the scope, then a link to the proposal. The time you save on pre-sales compounds across every new client.

The CCC Offer Box: Four Parts Every Package Needs

The CCC Offer Box is the packaging framework used by freelancers and agencies inside Claude Code Club. It has four parts. Every part must be specific enough that a prospective client can read it and understand what they are buying without a follow-up question.

Notice that none of these four components mention your tools, your process, or your method. The client does not need to know you built it with Claude Code. What they need to know is what they get, what is not included, what it costs, and when it arrives. A package that answers those four questions closes faster than a proposal that runs to six pages of process description.

When to Package vs When to Scope Custom

The right moment to turn a service into a package is after you have delivered the same kind of build twice. After two deliveries you know the real scope - the edge cases that always come up, the revision requests that are always the same, the integration that always adds two days. Before two deliveries you are guessing, and guessing turns a package into a scope-creep trap.

Custom scoping still makes sense for builds with high variance: large enterprise clients, projects that touch sensitive data, builds where the client's existing stack is genuinely unknown. The signal is whether you could deliver the same outcome ten times with the same template or whether every client would require a fundamentally different approach. High variance means custom scope. Low variance means package it.

NOTE: If you are earlier in the process - still figuring out what to build and who to build it for - the [how to pick a niche for your AI agency](/blog/how-to-pick-a-niche-for-your-ai-agency) post covers the niche decision that makes packaging much easier. You cannot package a service that serves everyone.

How to Write the Scope Without Leaving Room for Scope Creep

The scope section of a package is where most freelancers leave money on the table. A vague scope invites clients to interpret it generously - to assume that 'chatbot' means unlimited integrations, ongoing training, and priority support. A specific scope closes those gaps before the contract is signed.

Write the scope in two lists: what is included and what is not. The 'not included' list is as important as the included list. Name the specific things clients typically ask for that fall outside this package: mobile app version, ongoing support beyond two weeks, API integrations beyond the named list, content creation for the training data. Clients who read the not-included list and still hire you have self-qualified. Clients who object to the not-included list were going to cause scope creep anyway - you have saved yourself three weeks of difficult conversations.

• Name the deliverable specifically - not 'AI automation' but 'a Claude Code-powered Google Sheets macro that categorizes incoming leads by industry.'
• Cap the variable - not 'up to X pages' without a ceiling, but 'up to 20 pages, additional pages at $50 each.'
• Define revisions - one round means one consolidated list of feedback, not one question per day for two weeks.
• State what triggers a change request - anything not in the included list goes through the change request process at your stated rate.

Pricing a Packaged AI Service

Price a package by the value it delivers, not by the hours it takes. A chatbot that handles 200 customer queries a day saves the client a part-time hire. The value of that hire - measured at even a modest salary - dwarfs any hourly rate you could justify. The package price should reflect the outcome, not the time it took Claude Code to build it.

A simple starting point: estimate what the outcome is worth to a realistic client, find the floor that keeps your margin above 60 percent, and set the price between those two numbers, closer to the value side. Your Claude Code build time is not a fair input to the pricing calculation - it will only compress the number downward. The [how to price a Claude Code agency project guide](/blog/how-to-price-a-claude-code-agency-project) goes deeper on the value-based framework.

TIP: A packaged service also makes it easier to upsell. Once a client has bought a defined package, you can offer an add-on with the same fixed format: a named outcome, a fixed scope, a price, a timeline. The [upsell existing clients guide](/blog/upsell-existing-clients-without-a-pitch) covers how to introduce the second package without it feeling like a push. Inside Claude Code Club we share package templates, pricing frameworks, and proposal formats that members use on real clients - join for $9 a month at https://www.skool.com/claudecodeclub/about.

FAQ

What does it mean to package an AI service?

It means defining a fixed deliverable, fixed scope, fixed price, and fixed timeline so the client knows exactly what they are buying and you can sell it again without custom scoping. Instead of billing hourly for bespoke work, you sell a named outcome at a stated price. The CCC Offer Box framework structures this into four components: named outcome, fixed scope, price, and delivery timeline.

When should I package a service instead of scoping custom?

After you have delivered the same kind of build twice. Before two deliveries you are guessing at the real scope and edge cases. After two deliveries you know what always comes up and can price it accurately. Custom scoping still makes sense for high-variance projects - large enterprise clients, sensitive data builds, or projects where the client's stack is genuinely unknown each time.

How do I price a packaged AI service?

Price it by the value it delivers to the client, not by the hours it takes you to build it. Estimate what the outcome is worth to a realistic client, identify the floor that keeps your margin above 60 percent, and set the price between those two points, weighted toward the value side. Your Claude Code build time is not a fair pricing input - it compresses the number without reflecting the outcome.

What should the scope section of an AI service package include?

Two lists: what is included and what is not. The not-included list is as important as the included list. Name specific things clients typically request that fall outside the package - ongoing support beyond the stated window, additional integrations, content creation for training data, mobile versions. Clients who read the not-included list and still hire you have self-qualified and are unlikely to cause scope creep.

Can I package a service before I have any clients?

You can write the package, but treat it as a hypothesis until you have delivered it twice. Your first delivery will reveal scope assumptions that are wrong. Your second delivery will show you the real edge cases and revision patterns. Use the first delivery to stress-test the package, update the scope and price based on what actually happened, and then sell the second version as the real product.

• Building a SaaS with Claude Code works best when you treat each session as a delegation: describe the outcome you want, the constraints that matter, and the shape of the data - then let Claude handle the implementation while you review and steer.
• The build goes fastest when you do the thinking first. A one-page brief that names the user, the core loop, and the data model is worth more than any prompt trick. Claude can write code from vague instructions, but it cannot validate your idea or decide what the product should be.
• Most SaaS builds with Claude Code follow four phases: foundation (auth, database, routing), core feature, secondary features, and deployment. Each phase produces something runnable you can review before moving on.

Build a SaaS With Claude Code

To build a SaaS with Claude Code, open the desktop app, describe what you are building, and delegate the implementation one phase at a time. Claude Code can generate the full stack - routing, database schema, authentication, API endpoints, and the front end - across as many files as the project needs, in a single session or across many. What it cannot do is decide what to build. That part is yours, and doing it clearly before you start is what separates a weekend project from a month of drift.

The desktop app is the right starting point for this. Open it, create a project folder, and you are ready to give Claude Code your first instruction. No terminal setup, no environment to configure manually - the app handles the shell access Claude needs to read, write, and run code on your machine. If you have not set it up yet, [the Claude Code desktop app walkthrough](/blog/claude-code-desktop-app) is the place to start.

NOTE: This post is about the build process. If you are still deciding whether to build a SaaS or take client work instead, [micro-SaaS vs client work with Claude Code](/blog/micro-saas-vs-client-work-with-claude-code) walks through that decision first. If you want ideas for what to build, [10 things you can build with Claude Code](/blog/10-things-you-can-build-with-claude-code) is a quick starting list.

The Brief That Makes Everything Faster

Before you open Claude Code, write a one-page brief. Not a product spec, not a 40-page requirements document - a single page that answers four questions: who is this for, what is the one core action they take in the app, what data does the app store, and what does a successful session look like for the user. That brief is your first prompt, and it saves you from the most common SaaS mistake: starting with UI sketches before the data model is clear.

• Who uses this. One sentence. Not a broad category, a specific person - a solo consultant who tracks billable hours, a small team that needs a shared task list, a freelancer who invoices monthly.
• The core loop. What is the single most important action the user takes in the app, and what happens as a result. Everything else is secondary to this.
• The data model. What are the main things the app stores, and how do they relate. A simple list of three to five nouns is enough to start: clients, projects, time entries, invoices.
• The success state. What does a new user do in their first session to get value. If you can describe the first five minutes in the app, Claude Code can help you build it.

Hand this brief to Claude Code at the start of a new session. Ask it to confirm it understands the product before writing any code. That one pass - Claude echoing back what it will build - catches misreadings before they become wrong files, and it gives you a checkpoint to correct the direction without touching a single line of code.

The Four-Phase Build Process

Structure the build in four phases, each producing something runnable you can test before moving on. Phases give you checkpoints. Without them, a long build session drifts toward a pile of code that works in theory but has never been run end to end.

Do not skip the test at the end of each phase. It takes ten minutes and it prevents a common failure mode: finishing all four phases and discovering that a problem in phase one has been compounding silently through everything built on top of it.

TIP: Each phase gets its own Claude Code session. Starting a fresh session clears the accumulated context from the previous one, which keeps Claude's understanding of the codebase accurate rather than based on a mix of real files and an increasingly outdated mental model. Open the project, point Claude at what changed in the last phase, and start from there.

Phase One: Foundation - Auth and Database

Start with authentication and the database schema, because everything else in the build depends on them. A user who cannot sign in cannot use the app. A schema that needs to change after you have built three features on top of it is expensive to fix. Getting both right in phase one makes every subsequent session faster.

For auth, tell Claude Code which provider to use - Supabase Auth, Clerk, or NextAuth are common choices depending on your stack - and ask it to set up sign-up, log-in, and a protected route pattern. One protected route that redirects to login when there is no session is enough to prove the auth layer works before you build anything inside it.

For the schema, paste the data model from your brief and ask Claude Code to create the database tables, including foreign keys and any indexes you know you will need for the queries the core feature makes. If you are using Supabase, the [Claude Code to Supabase connection](/blog/connect-claude-code-to-supabase) gives Claude direct schema access so it writes migrations against your real project instead of guessing.

WARNING: Do not add billing in phase one. Every day I see builders wire Stripe before the core feature works. You cannot know what you are selling until the core loop is proven. Set up payments in phase three when you know the product is real.

Phase Two: The Core Feature

Phase two is the build that matters. Everything else in the app exists to support this one feature, so it deserves the most careful session setup. Open Claude Code, describe the core loop in plain language, and point Claude at the auth and schema from phase one. Ask it to build the feature end to end - the UI, the API route or server action, the database query, and the success and error states.

When Claude Code finishes a section, run it. Do not wait for the whole feature before testing. Each piece you run early is one fewer thing to debug when the full feature finally connects. When something is wrong, paste the error message directly into Claude Code and ask it to fix it in context - it will read the relevant files and correct the issue without you having to explain the whole project again.

NOTE: If the core feature is complex - multiple interacting parts, background jobs, or real-time state - break it into sub-tasks and delegate one at a time. Claude Code handles multi-file work well, but a single prompt that says 'build everything' often produces code that is plausible but untested in detail. Narrow the ask, review the result, then widen.

The Mistakes That Add a Week to a Weekend Project

Three mistakes account for most of the time lost on SaaS builds with Claude Code. None of them are about prompting technique. They are about when you do what.

• Building the landing page before the product works. A landing page is a sales artifact, not a product milestone. Build it last, when you know what you are selling and can describe it honestly. Building it first means rewriting it after the product changes, which it will.
• Letting the session run until something breaks. Long sessions accumulate context, and accumulated context goes stale. Claude Code at the end of a three-hour session is working from a mix of what it read at the start and what it inferred since. Fresh sessions are cheaper than debugging an outdated mental model.
• Accepting code you do not understand. You do not need to understand every line, but you need to understand every decision. If Claude Code makes a structural choice - a particular routing pattern, a caching strategy, a database design - ask it to explain why before you move on. The explanation takes a minute and it is the minute that saves you three hours when something breaks in production.

Deploying Your SaaS

Deploy early and often, not once at the end. The first deployment should happen after phase one, when all you have is auth and a blank dashboard. Deploying to production with almost nothing in it is the fastest way to catch environment-specific issues before they are buried under three phases of code.

For most stacks, Vercel handles the deployment and Claude Code can help configure it - ask it to set up the project, add the environment variables, and connect the domain. The [deploy an app with Claude Code](/blog/how-to-deploy-an-app-with-claude-code) post covers this in detail. For anything that runs background jobs or scheduled tasks, you need a separate worker host - Render and Railway are the common choices that Claude Code can configure.

NOTE: Inside Claude Code Club, members share the exact stack choices they made for their own SaaS builds, what broke in production and how they fixed it, and the prompts that got the most done per session. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) to build the foundation before you go deep on a product.

FAQ

Can you really build a SaaS with Claude Code?

Yes. Claude Code can generate the full stack - authentication, database schema, API routes, and front end - across as many files as the project needs. What it cannot do is decide what to build or validate that the idea is worth building. That part is yours. With a clear brief and a structured four-phase approach, a working first version is a realistic weekend project.

What stack should I use to build a SaaS with Claude Code?

Claude Code works with any stack, but it builds fastest with the ones it knows best. Next.js with Supabase is the most common choice in the community because both are well-documented and Claude Code handles them with high accuracy. Add Vercel for deployment and Stripe for payments and you have a complete production stack.

How long does it take to build a SaaS with Claude Code?

A simple SaaS - one core feature, auth, a database, and deployment - is a realistic weekend project with focused sessions. More complex products with multiple features, billing, and background jobs typically take one to three focused weeks of part-time building. The build itself is fast; the slowest parts are testing, fixing production issues, and validating that the core feature actually does what users need.

What should I build first?

Authentication and the database schema. Everything else in the app depends on both, and getting them right before you build anything on top saves far more time than it costs. The core feature comes second, the landing page comes last.

How do I handle billing in a SaaS built with Claude Code?

Set up billing in phase three, after the core feature works. Claude Code can integrate Stripe - ask it to add a checkout session, a webhook handler for subscription events, and a billing portal link. Do not wire payments before you know the core loop is real, because the product will change and you will rewrite the billing integration to match.

• Claude Code headless mode runs Claude as a non-interactive process - no approval prompts, no interface - triggered by a script or pipeline. You pass the task with --print and optionally --allowedTools to control what it can do, and it runs to completion and exits.
• Headless is not the same as auto-accept. Auto-accept skips confirmation inside an interactive session; headless runs Claude as a one-shot command with no session at all. The right model depends on whether a human is available to catch problems.
• Use headless mode for deterministic, low-stakes, repeatable tasks - automated code reviews, test generation, documentation updates, scheduled reports. Do not use it unsupervised on tasks that write to production systems or spend money.

What Claude Code Headless Mode Is

Claude Code headless mode runs Claude as a non-interactive process that you trigger with a command, receives a task through a flag rather than a prompt, does the work, and exits. There is no interface, no approval step waiting for a human, and no session to manage. It is Claude Code as a tool in a pipeline, not Claude Code as a conversation partner.

The flag that enables it is --print. Pass it alongside your task and Claude Code runs non-interactively and prints the result to stdout. You can pipe that output to a file, another command, or a notification. Combine it with --allowedTools to define the exact set of tools Claude can use, and with --output-format for structured output when you are parsing the result downstream.

NOTE: Headless mode is one of three ways to run Claude Code without constant manual oversight. The others are auto-accept mode inside an interactive session and full subagent orchestration. [Claude Code subagents](/blog/claude-code-subagents) and [schedule Claude Code agents while you sleep](/blog/schedule-claude-code-agents-while-you-sleep) cover the other two patterns in detail.

Headless vs Auto-Accept: What the Difference Actually Is

These two modes are not the same thing, and confusing them is the source of most safety mistakes when people first start running Claude Code unattended.

The safety difference is not subtle. Auto-accept inside an interactive session still has a human present who can interrupt. Headless mode has nobody. A mistake in headless runs to completion - there is no mid-run checkpoint. That is what makes the --allowedTools flag so important: it is the guardrail that replaces the human.

How to Set Up a Headless Run

A basic headless invocation looks like this: pass the task as a string with -p (short for --print), name the tools it is allowed to use with --allowedTools, and redirect the output wherever you need it. That is the entire setup for most automated tasks.

1. Define the task precisely in a string. Headless mode has no back-and-forth to clarify - what you pass is all it gets. Vague tasks in headless produce vague output with no way to course-correct mid-run.
2. Restrict tools with --allowedTools. If the task is read-only code review, give it only Read and Bash. If it writes test files, add Write. Never give it more tools than the task needs - each extra tool is a surface for something unexpected to happen.
3. Set the output format. Use --output-format json if something downstream parses the result, or leave it as the default text if you are piping to a file or a notification.
4. Test it interactively first. Run the same task in a regular interactive Claude Code session before you automate it. If it behaves correctly there, headless will too. If it behaves unexpectedly interactively, headless will silently do the unexpected thing at 2am.

WARNING: Never set up a headless run on a task you have not tested interactively at least twice. The failure mode for an untested headless task is not a crash with a clear error - it is code that looks plausible but is wrong, committed and deployed before anyone notices. Test first, then automate.

Where Headless Mode Earns Its Keep

Headless mode is most valuable for tasks that are deterministic, low-stakes if they go slightly wrong, and expensive to do by hand on every cycle. The combination of low risk and high repetition is what makes the automation worth the setup time.

• Automated code review on a pull request. Point Claude at a diff and ask for a review pass with a specific checklist. The result is a comment or a file, not a production change.
• Test generation after a code change. Ask Claude to read a changed file and generate tests for the new logic. Review the tests before running them - you are still in the loop, just not in the generation loop.
• Documentation updates after a code change. Point headless Claude at a changed module and ask it to update the inline docs or the readme section. Diff the result before committing.
• Scheduled reports. Run a headless pass nightly to summarize the day's error logs, a code health metric, or a project status. The output goes to a channel or a file, not to a deployment.
• CLAUDE.md maintenance. Headless Claude can read a project's actual current state and update the project context file to match, so the context file does not drift from reality as the build evolves.

Where It Is the Wrong Tool

Headless mode is not a way to make Claude Code faster or more autonomous in general. There are specific situations where removing the human from the loop makes a task harder, not easier, to trust.

• Tasks that touch production systems or real user data. A headless run that can write to a production database or call an API with real side effects needs all of the guardrails that a human approval step replaced - rate limiting, hard caps, a spend ceiling. Without those, the automation is an open faucet.
• Tasks that involve judgment calls. If the right answer depends on context that was not in the task string, headless Claude will make a choice. That choice will be confident and may be wrong. Keep judgment calls in interactive mode where you can redirect.
• Tasks on unfamiliar codebases. Headless mode works well when Claude Code already understands the project from a CLAUDE.md or a prior session. On a codebase it has never seen, an unguided headless pass often touches the wrong files or applies a correct fix in the wrong place.
• First runs of any new automation. Every new headless task should start as an interactive task. Only after it behaves correctly interactively, several times, should you move it to a cron job or a pipeline trigger.

Wiring It Into a Pipeline or Cron Job

The simplest wiring is a shell script in a cron job: set the environment, run the claude command with --print and --allowedTools, and send the output to a file or a notification channel. If the task lives in a GitHub Actions workflow, the same command runs as a step - authenticate with your Claude credentials in the workflow environment, and call the command the same way you would from a terminal.

Hooks extend headless mode without changing the core command. A PostToolUse hook can validate what Claude wrote before it is saved. A Stop hook can scan the final output before the process exits. Use hooks to add the guardrails that auto-accept inside an interactive session would otherwise handle with a human. The [Claude Code hooks that earn their keep](/blog/claude-code-hooks-that-earn-their-keep) post covers hook patterns that pair well with headless runs.

NOTE: Inside Claude Code Club, members share the exact headless workflows they run - what tasks they automated, how they scoped the tool permissions, and what broke before it worked reliably. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) to build a strong foundation before you start running Claude unattended.

FAQ

What is Claude Code headless mode?

Headless mode runs Claude Code as a non-interactive process with no interface and no approval prompts. You pass the task with the --print flag, optionally restrict tools with --allowedTools, and Claude runs to completion and exits. It is Claude Code as a command in a pipeline rather than a conversation.

How do I run Claude Code in headless mode?

Use the --print flag (or -p) with your task: claude --print "your task here" --allowedTools Read,Write,Bash. That runs non-interactively, prints the result to stdout, and exits. Add --output-format json if something downstream needs to parse the output.

What is the difference between headless mode and auto-accept?

Headless mode is a one-shot command with no session and no human present. Auto-accept (--dangerously-skip-permissions) is an interactive session where approval prompts are bypassed but a human can still watch and interrupt. Headless runs to completion with no intervention; auto-accept can still be stopped mid-run.

Is headless mode safe?

It is safe for low-stakes, deterministic tasks on systems that have their own guardrails. Always restrict tools with --allowedTools, test the task interactively before automating it, and never run headless Claude unsupervised on tasks that touch production systems, spend money, or require judgment calls. The --allowedTools flag is the guardrail that replaces the human approval step.

Can I use Claude Code headless mode in GitHub Actions?

Yes. Authenticate with your Claude credentials in the workflow environment, then run the claude --print command as a step the same way you would from a terminal. Restrict tools to Read and Bash for a review or summary task, and write the output to a file or a pull request comment. Test the same command locally before wiring it into the workflow.

• A technical spec for Claude Code is not a requirements doc for a human engineer - it is a context document written for an AI agent that has no memory between sessions and no ability to ask your client for clarification. Keep it short, concrete, and unambiguous.
• The spec has five parts: one-sentence goal, stack and constraints, feature list with explicit out-of-scope items, success criteria the agent can verify, and a starting file tree. Anything outside those five is padding that costs token budget without improving the build.
• Write the spec before you open Claude Code, not as you go. The agent's first question shapes every subsequent decision - send it in with a complete spec and it builds in the right direction from turn one.

What a Technical Spec for Claude Code Actually Is

A technical spec for Claude Code is a short plain document that defines what you are building, what the agent is allowed to touch, and what done looks like - before you type the first prompt. It is not a project plan, a PRD, or a design doc for a human engineer. It is context for an AI agent that starts fresh every session with no memory of yesterday's decisions, no relationship with your client, and no way to ask a clarifying question without burning your time.

Most builds that go sideways with Claude Code share the same root cause: the agent started with a vague prompt and made a reasonable but wrong assumption about scope, stack, or priority. By session three you are untangling decisions the agent made in session one that nobody explicitly authorized. A spec eliminates that. When Claude Code reads a complete spec at the start of a session, it knows exactly where to go and - just as importantly - where to stop.

TIP: The CCC spec format described here is the same one I load into the project CLAUDE.md so it persists across sessions. The [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) post has the base structure you can adapt.

The Five Parts of a Working Claude Code Spec

Strip a well-run build down and you will find the same five pieces of context the agent needed to make good decisions. Everything else is either a nice-to-have or noise. Here is the CCC spec skeleton I use on every project.

That is the whole spec. One A4 page at most. If you are typing more than that, you are probably documenting decisions the agent could derive from context, or describing the implementation rather than the outcome. The spec defines the target; Claude Code picks the path.

The One-Sentence Goal (and Why It Has to Be One Sentence)

Every spec starts with a single sentence that names the product, the user, and the core job the product does. Not two sentences. Not a paragraph. One sentence, because if you cannot state the build in a sentence, the scope is not defined yet - and you are not ready to write a spec.

A weak goal: 'Build a task management app with productivity features.' A strong goal: 'A web app where a solo founder can add daily priority tasks, mark them done, and see the list persist across sessions using Supabase.' The difference is specificity. The weak version gives Claude Code permission to guess. The strong version gives it nothing to guess about.

Write the goal sentence before anything else. If you are building for a client, derive the sentence from the kickoff call, not from the proposal. The proposal is usually too vague - it is written to be accepted, not to be implemented. The [client kickoff call guide](/blog/client-kickoff-call-ai-build) has the questions that extract the goal sentence before you ever write the spec.

Stack and Constraints: What Claude Code Is and Is Not Allowed to Use

The stack section is where most builders underspecify and then wonder why Claude Code introduced a library they did not want. The agent will pick reasonable defaults when you leave it room - but 'reasonable' to Claude Code might mean a full authentication library when you wanted a simple cookie check, or a full ORM when you wanted a raw Supabase query. The spec names the tools that are in and explicitly bans the substitutes.

Format it as two short lists: 'Use' and 'Do not use.' Example: Use Next.js App Router, Tailwind CSS, Supabase for database and auth, React Query for server state. Do not use Prisma, NextAuth, any UI component library, or any paid third-party API. Two lists, no prose. The agent reads lists faster and violates prose instructions more often.

TIP: Add a version constraint for anything the agent tends to guess wrong. If you need React 18 not 19, say so. If you need Node 20, say so. Version surprises at deploy time are almost always traceable to a spec that did not specify.

Constraints also include environment rules: what goes in .env.local versus what is hardcoded, whether the build is for Vercel or somewhere else, and what the agent is not allowed to do to the repository structure. If the client has a monorepo and the agent should only touch a specific folder, that is a constraint. Put it in the spec, not in a prompt three sessions in when the damage is already done.

The Feature List: In Scope and Explicitly Out of Scope

The feature list is two sections, not one. 'In scope' without 'out of scope' is an invitation to build adjacent features the agent thinks are related. The out-of-scope list is where most specifications skip a step and most builds drift.

For in-scope: list each feature as a user action, not a technical task. 'User can add a task with a title' is a feature. 'Create a POST endpoint at /api/tasks' is an implementation detail. Write features; let Claude Code design the implementation. One feature per line, no sub-bullets at the spec stage.

For out-of-scope: name the obvious adjacent features you are deliberately not building this sprint. If the build is a task manager and you know a client might ask for team sharing later, put 'Team sharing, comments, and notifications are out of scope for this build' in the spec now. When Claude Code sees something is explicitly excluded, it stops adding it speculatively. When that exclusion is absent, the agent sometimes adds a feature because it seemed helpful - and you are reverting it in session five.

TIP: The out-of-scope list is also scope protection with clients. I paste it into the contract. When a client asks for something three weeks in, I point to the spec they approved. The [how to handle scope creep guide](/blog/how-to-handle-scope-creep-on-client-projects) covers the conversation from there.

Success Criteria the Agent Can Actually Verify

A success criterion is a testable statement. Not 'the app works well' - that is a feeling, not a criterion. A testable criterion is: 'A user can create a task, see it appear in the list immediately, mark it complete, and reload the page to find the state persisted.' Claude Code can run that test. It can also generate a test file for it, which is how I get a basic smoke test suite out of the spec with no extra work.

Write one criterion per major user flow, not per endpoint. Four or five criteria are usually enough for a lean build. Keep each one to a single sentence in plain English. If you need a second sentence to explain the criterion, split it into two criteria.

At the end of every session I paste the success criteria back into the prompt and ask Claude Code to run through them. 'Here are our success criteria. Walk through each one and tell me which pass, which fail, and what is left to do.' It is the most efficient review loop I have found - faster than reading code and more reliable than trusting the agent's last message.

The Starting File Tree

The file tree section is short and often skipped - which is why you keep finding components in the root folder and API handlers inside the wrong directory. Give Claude Code a minimal starting tree and it builds into it rather than around it. Approximately ten to fifteen paths is enough: the main directories, the config files, and the one or two files that need to exist before the build starts.

You do not need to pre-create every file - just name where they go. Example: src/app/page.tsx, src/app/api/tasks/route.ts, src/components/TaskList.tsx, src/lib/supabase.ts, .env.local. Claude Code reads the tree, understands the intended structure, and places new files accordingly. Without the tree, it defaults to its own conventions, which may not match your project, your client's conventions, or the existing codebase you are extending.

If you are building on an existing codebase rather than starting fresh, the file tree section becomes a map of the relevant files - the ones Claude Code should read and the ones it should not touch. Pair it with the constraints section to mark the no-go zones. The [how to use Claude Code on a large existing codebase guide](/blog/claude-code-large-existing-codebase) goes deeper on keeping the agent oriented in a code base it did not build.

How I Load the Spec Into Claude Code

The spec lives in two places: the CLAUDE.md file and the first prompt of every new session. CLAUDE.md is where the durable context goes - stack, constraints, file tree, and the out-of-scope list. These do not change during the build, so they belong in the persistent file the agent reads first. Features and success criteria can go in CLAUDE.md too, but I usually paste them fresh in each session prompt so I can update them as the build evolves without editing the file.

The first message of each session follows a fixed shape: 'Here is the spec for this build. [paste spec]. Today's task is [single concrete next step]. Start by reading the files in [directory] and tell me what you see before writing any code.' That last sentence - read before you write - is the single most valuable habit I have built into my workflow. It stops the agent from diving into implementation based on assumptions and makes it tell me what it actually found in the codebase first.

TIP: Claude Code Club members share their spec templates and first-session prompts in the community. The exact language that keeps the agent on track for a client build is one of the most asked-about resources we have. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

The Mistakes That Break a Spec

A spec that is too long is almost as bad as no spec. When the context document runs to ten pages, the agent's attention dilutes - it starts weighing section four at less than section one, and the rules buried in the middle get violated first. Keep the spec under one page. If you have that much to say, you have too much scope in one build.

A spec written in the third person is harder for Claude Code to parse than one written as direct instructions. 'The application should allow users to' is weaker than 'Users can.' Direct language processes faster and is less likely to be misread as a description of an existing system rather than a target to build toward.

The worst spec mistake is writing the spec after the build starts. I have done it. You get three sessions in, the agent has taken a turn you did not want, and you try to retroactively document the right direction. It does not work. The agent has already made decisions you would have prevented. Write the spec first, treat it as the mandatory first deliverable on every project, and send it to the client for a quick sign-off before session one. A ten-minute spec review is worth two hours of rework.

FAQ

What is a technical spec for Claude Code?

It is a short plain document written before the build starts that gives Claude Code its one-sentence goal, the stack it is allowed to use, a feature list with explicit out-of-scope items, success criteria it can verify, and a starting file tree. It replaces the need to re-explain the project in every session prompt.

How long should a Claude Code spec be?

One page or less. If you are writing more, either your scope is too large for one build or you are documenting implementation details instead of outcomes. The spec defines the target; Claude Code picks the path.

Do I need to write a spec for every Claude Code build?

Yes, even for small ones. A five-feature build with a one-page spec takes twenty minutes to write and saves two or three sessions of cleanup. The smaller the build, the shorter the spec - but the spec still needs to exist before the first prompt.

What is the difference between a spec and a CLAUDE.md file?

The spec is the document you write before the build; the CLAUDE.md is where you store the durable parts of the spec so Claude Code loads them automatically at the start of every session. The stack, constraints, and file tree go in CLAUDE.md. Features and success criteria can go there too, or be pasted fresh each session as they evolve.

What should go in the out-of-scope section?

Name the adjacent features you are deliberately not building in this sprint - the things a client might assume are included or the things Claude Code might speculatively add because they seem related. An explicit out-of-scope list stops scope drift before it starts and doubles as the contract language when a client asks for something that was never agreed.

• White-labelling an AI build means delivering a finished product under the client's brand without exposing your tools, your Claude Code prompts, or the internal systems that power the work. The client gets a polished output; you keep the process that made it.
• The delivery package covers five things: the working application, a handover document that covers usage and maintenance, credentials for anything the client owns, a plain-English FAQ for their team, and one optional walkthrough call. Your skill templates, CLAUDE.md files, and internal prompt library are not in the package.
• Price a white-label build at a premium over standard work because you are absorbing the operational complexity, the unknowns, and the margin on future change requests. The client is paying for a finished, maintained system - not for access to how you made it.

What White-Labelling an AI Build Actually Means

White-labelling an AI build means the client receives a finished, working product under their brand, with no visible trace of the tools, models, or process you used to build it. The code does not reference your agency. The interface does not say 'powered by Claude.' The documentation does not walk them through your Claude Code workflow. From the client's perspective, they commissioned a build and received a product - how you made it is your business.

This is different from a standard handover in one important way: in a standard project, a curious client might look at the git history and piece together your method. In a white-label engagement, the client has usually agreed - explicitly, in the contract - that the methodology, tooling choices, and internal prompt systems are the agency's IP. They are buying the outcome, not the recipe.

White-labelling suits a specific kind of client: one who wants a finished system their team can use and maintain, does not want to learn Claude Code or manage an AI workflow, and is willing to pay a premium for something they can call their own. If the client wants to learn the tools themselves or wants your prompts so they can run the system internally, that is a different engagement type and a different price.

The White-Label Delivery Package

A white-label delivery is not just the code. It is a complete package that lets the client's team own, use, and maintain the product without you in the room. Here is exactly what I include and what I keep.

The handover document is the piece most agencies underinvest in. It is a plain document - not a code comment, not a README buried in the repo - that a non-technical person on the client's team can read and understand. It covers what the product does, what it cannot do, how to submit a change request, and who to contact if something breaks. Writing it forces you to document the known limits of the build, which protects you from support requests outside the scope you delivered.

What to Keep as Your IP

The client owns the product. You own the process. That distinction is the commercial foundation of a white-label business, and it is why a white-label build can be profitable even when the delivery looks finished and complete. The things you keep are the things that let you build the next client's product at half the cost.

Your CLAUDE.md templates are your most reusable asset - they hold the stack decisions, the file conventions, the no-go zones, and the session-opening prompts that make every new build start from a position of strength rather than from scratch. One good CLAUDE.md for a React and Supabase stack gets reused across ten client builds. It is never in the delivery package.

Your prompt library is the same category. The prompts that reliably produce a working authentication flow, a correct database schema, or a solid API endpoint are the accumulated result of trial and error across multiple builds. They represent real time spent figuring out what works - and they stay in your internal Claude Code Club skill files, not in the client's repository.

TIP: If you do not have a prompt library yet, the Claude Code Club community is where members share and pressure-test the prompts that are working on real client projects. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

How to Structure the White-Label Agreement

The contract is where the white-label arrangement gets made explicit. Without a contract that says so, a curious client can reasonably argue they should receive your process documents alongside the product. The key clauses to include are: IP ownership of methodology, tool and model confidentiality, a scope of support definition, and a change request pricing schedule.

IP ownership of methodology means one clause that states the client owns the built application and its data, while the agency retains ownership of the development methodology, tools selection, prompt engineering, and internal documentation used to build it. This does not need to be a page of legalese - three sentences in plain English is enough to establish the principle and prevent the argument later.

The support scope definition is equally important. White-label clients often assume ongoing support is included. It is not, unless you quoted it. Define it: what is covered in the handover period, what constitutes a bug versus a feature request, and what the change request rate is after delivery. The [what to put in an AI project contract guide](/blog/what-to-put-in-an-ai-project-contract) has the exact clauses I use.

TIP: Charge a white-label premium of 20 to 40 percent over your standard build rate. The premium covers the extra polish, the handover documentation, the credentials transfer, and the higher support exposure in the first two weeks. Do not price it as a standard build with a renamed deliverable.

Credentials and Accounts: Who Owns What

One of the most common white-label handover mistakes is delivering a product that runs on the agency's API keys. The client is live, the product is working, and then the agency offboards a client or shuts down a key - and the client's product breaks. Before you hand over any white-label build, every account and every API key that the product depends on must be transferred to a client-owned account.

Transfer list for a typical AI build: the hosting account (Vercel, Railway, Fly), the database account (Supabase, Neon), any third-party API keys the product calls, the domain DNS if it is a client domain, and access to any model APIs if the product calls a model directly. The client creates the account, you configure it, you verify it works, you remove your own access. That sequence is the clean handover.

The exception is your own agency tooling that the client never sees - Claude Code, your internal Claude account, any skill files or automations that ran during the build. Those never transfer. The client does not know what powered the work, and they do not need to.

Pricing a White-Label Build

White-label builds command a higher price than standard client projects for a concrete reason: you are absorbing more responsibility. The client cannot see your process, so they cannot co-manage it. Every risk decision - stack choice, third-party service selection, architecture call - is yours alone. The premium compensates for that asymmetry.

The other pricing factor is the handover cost. Writing a handover document, transferring credentials, running a walkthrough call, and handling two weeks of post-delivery questions takes real time that does not show up in the build itself. Factor that into the quote rather than discovering it eats your margin after delivery.

One structure that works well: quote the build at your standard rate, then add a named 'white-label package' line item that covers the handover document, credentials transfer, the walkthrough call, and two weeks of bug support. Making it a visible line item - rather than hiding it in the build price - makes the premium legible to the client and makes it easy to reference in the contract. The [how much deposit to charge guide](/blog/how-much-deposit-to-charge-before-an-ai-project) covers getting that first payment secured before you start.

The Handover Call and What to Cover

The optional walkthrough call is not a training session. It is a single 30 to 45 minute call that covers four things: a live demo of the product working as specified, a walkthrough of the handover document, confirmation that the client can access everything they own, and a clear statement of what is and is not included in the two-week support window. That is the full agenda. Do not use it to teach the client Claude Code or walk them through your build process.

Record the call with the client's permission. Send the recording alongside the delivery package. Clients who watch the recording after the call can answer most of their own early questions without creating a support ticket, which means your two-week window stays manageable.

After the two-week support window closes, anything new is a change request. State that explicitly on the last day of the support window - a short email that says 'Your two-week support period ends on [date]. From that point, changes are handled on the standard change request rate of [rate]. Here is how to submit one.' No ambiguity, no drift, no client who assumes they have ongoing support they did not pay for.

FAQ

What does it mean to white-label an AI build?

It means delivering a finished AI-powered product under the client's brand with no visible trace of your tools, process, or agency. The client owns the product and can call it their own. You retain ownership of the methodology, prompts, and internal systems you used to build it.

Should I give the client my Claude Code prompts as part of the handover?

No. Your Claude Code prompts, CLAUDE.md templates, and skill files are your reusable IP - they are not part of what the client commissioned. The client buys the finished product, not the recipe. Include a handover document that covers usage and maintenance instead.

How much more should I charge for a white-label build?

A premium of 20 to 40 percent over your standard build rate is a reasonable starting point. The premium covers the handover documentation, credentials transfer, walkthrough call, and the two-week support window. Name it as a separate line item in your quote so the client understands what they are paying for.

What accounts and credentials should I transfer to the client?

Every account the product depends on and that the client will be paying for: hosting, database, any third-party APIs the product calls, and the domain if it is a client domain. The client creates the accounts, you configure them, you verify everything works, then you remove your own access. Your Claude Code account and internal tooling never transfer.

What is the difference between a standard handover and a white-label handover?

A standard handover gives the client the code, a brief readme, and usually a short call. A white-label handover includes all of that plus a plain-English usage document the client's non-technical team can read, a confirmed credentials transfer to client-owned accounts, and an explicit contract clause that separates product ownership from methodology ownership.

• Claude Code costs whatever your paid Claude plan costs per month, because it is included in the plan, not billed as a separate product. The cheapest way to run it is a paid Pro plan; heavier daily use moves you to the Max plan, which comes in a 5x and a 20x usage level.
• There is a second route: paying per token through the Anthropic API. That has no monthly floor and can be cheaper for very light or very bursty use, but it gets expensive fast for sustained daily building, which is why most regular users are better off on a flat plan.
• Your real monthly cost is driven less by the sticker price and more by how you work. Tight prompts, small context, and the right model for the task can keep you on a cheaper plan for months longer than a sloppy setup would.

How Much Does Claude Code Cost Per Month?

Claude Code costs the price of your paid Claude plan per month, because it is bundled into the plan rather than sold as its own product. You do not pay a separate Claude Code fee on top. That means the monthly-cost question is really a plan question: the paid Pro plan is the entry point and the floor, and the Max plan sits above it in two usage levels for people who build every day. The one thing that is free - nothing. The Free Claude plan does not include Claude Code at all, so there is no zero-dollar way to run it.

So the honest answer to how much it costs per month is: one paid plan, at the tier that matches how hard you push it. Most people learning Claude Code or building small projects sit comfortably at the Pro floor. You only climb to a Max level when your own usage forces it, which we get into below. Check the live numbers on [Claude's own pricing page](https://claude.com/pricing) before you budget, since plans and prices change over time.

NOTE: This is the money side of a decision we walk through in full in [which Claude plan for Claude Code](/blog/which-claude-plan-for-claude-code). That post ranks the plans by usage; this one is about what actually lands on your card each month and how to keep it low.

The Two Ways You Pay: Flat Plan vs Per Token

There are two separate billing routes into Claude Code, and mixing them up is where most confusion about cost comes from. The first is a flat monthly plan, where Claude Code draws from the same usage pool as the Claude app. The second is the Anthropic API, where you pay per token for exactly what you send and receive, with no monthly minimum.

The flat plan wins for anyone who works with Claude Code regularly, because a fixed fee is easier to budget and you are not watching a meter on every prompt. The per-token API route wins in two cases: when you barely use it, so a whole monthly plan would be waste, and when you are running metered automated jobs where you genuinely want to see the cost of each run. For steady day-to-day building, the flat plan is almost always the cheaper and calmer choice.

TIP: If you are going the API route, treat the key like money, because it is. Never put it behind anything that could spend without a limit. The general safety discipline is in [keep your API keys safe in Claude Code](/free-resources/keep-api-keys-safe-claude-code).

What Actually Drives Your Monthly Cost

The sticker price is the smaller half of the story. What decides whether you outgrow Pro in a week or stay on it for months is how you use the tool. Every prompt has a cost in usage, and that cost scales with how much context you load and how large the task is. A lean session and a bloated session can differ by a lot even when they produce the same result.

• Context size. The more of your codebase you pull into a session, the more each turn costs. Pointing Claude at the two files that matter is far cheaper than letting it read the whole repo every time.
• Model choice. A heavier model costs more per turn than a lighter one. Reach for the strong model when the task genuinely needs it, and let a lighter one handle the routine edits and lookups.
• Prompt discipline. Vague prompts cause re-work, and re-work costs usage twice. A clear, specific request that lands on the first try is the cheapest prompt there is.
• Session hygiene. Long, meandering sessions carry a growing context with them. Starting a fresh session for a new task drops the accumulated weight and the cost that comes with it.

None of this is about being stingy. It is about not paying for capacity you are wasting. The habits that keep your monthly cost down are the same habits that make Claude Code faster and more accurate, which is why they are worth building early rather than after a bill surprises you.

NOTE: We keep a running set of these habits in [what to do about Claude Code usage limits](/blog/claude-code-usage-limits-what-to-do) and [why is Claude Code slow](/blog/why-is-claude-code-slow). The overlap is not a coincidence: the moves that cut cost and the moves that cut lag are mostly the same moves.

When to Stay on the Floor, and When to Move Up

Start on the Pro floor and stay there until your usage forces a change. The honest trigger to move up is simple: you are regularly blocked mid-task, during the workday, often enough that waiting for the limit to reset is costing you real time. Not once in a busy week - that is normal and cheap to wait out. Several times a day is the signal that a bigger plan will pay for itself in recovered hours.

The mistake runs both ways. Some people buy the top Max level on day one, feel responsible, and then use a fraction of it - that is money spent on headroom they never touch. Others cling to the floor while losing an hour a day to blocked sessions, which is a false economy. The self-check I use: for one week, note every time Claude Code stops me before I finished a task. Zero or one, stay put. Several a day, move up one level. Let your real usage make the call, not a guess about a busy future.

The Mistake That Made My First Month Cost More

My first month cost more than it needed to, and the reason was not the plan. It was that I let Claude read the entire project into context on almost every prompt, for a codebase that was already large. Each turn was carrying a pile of files it did not need for the change I was actually asking for, and I was burning through the usage window by lunchtime without noticing why.

The fix cost nothing. I started pointing Claude at the specific files a task touched, kept a short project context file so it did not have to rediscover the layout every session, and split unrelated work into fresh sessions instead of one endless one. My usage per real unit of work dropped hard, and the plan I already had suddenly felt roomy. The lesson I would save you: before you upgrade to spend your way out of hitting limits, check whether you are simply feeding the model far more than the job needs. Nine times out of ten, that is the cheaper fix.

A Simple Way to Estimate Your Own Monthly Cost

You do not need a spreadsheet. Run Claude Code the way you actually work for one week on the Pro floor and pay attention to one thing: how often you get blocked before you are done. That single count tells you almost everything about your real monthly cost.

1. Week one: run on the Pro floor and log every time Claude Code stops you mid-task before you finished.
2. If the count is zero or one for the week, your monthly cost is the Pro price and you are done. Do not upgrade to solve a problem you do not have.
3. If you are blocked several times a day, price out the next Max level up and weigh it against the time you are losing to resets. That comparison, not a guess, is the upgrade decision.
4. If your use is genuinely light and occasional, price the same week as per-token API usage instead, and pick whichever number is smaller.

NOTE: Inside Claude Code Club, members share what their months actually cost at each usage level and the small habits that kept them on a cheaper plan longer. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) to get productive first, then right-size the spend.

FAQ

How much does Claude Code cost per month?

Claude Code is included in a paid Claude plan, so it costs whatever that plan costs per month. The paid Pro plan is the entry point and the floor; the Max plan sits above it in a 5x and a 20x usage level for heavier daily building. Check Claude's own pricing page for the current numbers, since prices change.

Is Claude Code free?

No. Claude Code is not included on the Free Claude plan, so there is no zero-dollar way to run it. You need at least a paid Pro plan, or you can pay per token through the Anthropic API instead.

Is it cheaper to pay per token or buy a plan for Claude Code?

For steady daily building, a flat monthly plan is usually cheaper and far easier to budget than per-token API billing. The per-token route wins only for very light, occasional, or bursty use, or for metered automated jobs, because it has no monthly floor but climbs quickly with sustained use.

What makes Claude Code cost more some months?

Usage, not the sticker price. Loading large amounts of context, using a heavier model for routine tasks, vague prompts that cause re-work, and long sessions that carry a growing context all burn through your usage faster. Tightening those keeps you on a cheaper plan for longer.

How do I lower my Claude Code monthly cost?

Point Claude at the specific files a task needs instead of the whole repo, keep a short project context file so it does not rediscover your layout every session, use a lighter model for routine work, and start fresh sessions for unrelated tasks. These habits cut usage per unit of work, which is what actually lands on your bill.

• Price a maintenance retainer as a fixed monthly fee tied to a defined envelope of work, not open-ended support. Name the outcome the client is buying - a system that keeps working - and set the number against the value of that, not against your hours.
• A workable starting range for a small build is a monthly fee that covers a defined block of change requests, a response-time promise, and hosting oversight. The exact number comes from the size of the system and what a day of it being broken would cost the client, not a flat percentage rule.
• The load-bearing part is the exclusions list. Write down what the retainer does not cover - new features, redesigns, work outside the envelope - so every quick fix that would have been unpaid becomes a defined add-on the client expects to pay for.

How to Price a Maintenance Retainer

Price a maintenance retainer as a fixed monthly fee attached to a defined envelope of work, and anchor the number to the outcome the client is buying rather than to your hours. The outcome is simple to name: a system that keeps working, changes when the business needs it to, and never becomes the client's problem to figure out. When you price against that, the retainer is cheap. When you price against hours, it looks like a cost to trim the moment things are quiet.

The envelope is what makes the number defensible. A retainer is not open-ended support - that is a trap that turns every message from the client into unpaid work. It is a monthly fee that buys a specific, bounded set of things: a block of change requests, a response-time promise, oversight of hosting and dependencies, and a standing relationship so the client is never starting from a cold stranger when something breaks. Define that block, and the price stops being a guess.

NOTE: This is the recurring-revenue move behind [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer). That post is about making the offer; this one is about putting the right number on it and drawing the line around what it covers.

Start From the Outcome, Not Your Hours

The fastest way to underprice a retainer is to estimate how many hours of maintenance the system will need and multiply by your rate. It feels rigorous. It is exactly backwards, because with AI-assisted work your hours keep shrinking as you get better, which means hourly maintenance pricing sends your invoice in the wrong direction over time. The better the system runs, the less you earn - that is not a business, that is a slow fade.

Price the outcome instead. Ask what a day of this system being down would cost the client - in lost sales, in staff time, in a stalled process - and set the monthly fee as a small fraction of that. A retainer that costs a fraction of one bad day is an easy yes and stays an easy yes, because the client is not comparing it to your effort. They are comparing it to the risk of the thing they depend on quietly failing with no one on call.

TIP: The same outcome-first discipline decides your build price too. If you are still setting project fees off hours, fix that first in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project). The retainer inherits whatever framing you used on the build.

What Goes Inside the Retainer, and What Does Not

A retainer that will not bleed margin has a clear inside and a clear outside. The inside is the bounded envelope of ongoing care. The outside is everything that is really a new project wearing a small-ask costume. Write both down. The line between them is where your margin lives or dies.

The exclusions list is the load-bearing part, and most people write it too gently or skip it. Be specific. Most scope creep on a retainer happens because the client genuinely believed a new feature was covered and you genuinely did not, so nobody is being unreasonable - the document just failed to draw the line. Put a number on work beyond the envelope, so a bigger ask flips from an awkward favor into a defined add-on the client already expects to pay for.

WARNING: Never promise open-ended support to close a retainer. It feels generous and it quietly guts the deal, because every quick fix outside the envelope is unpaid work eating the margin on your next engagement. A bounded envelope you actually honour is worth more to the client than an unbounded promise you will come to resent.

A Simple Way to Size the Number

You do not need a formula, you need a floor and a ceiling that both come from real things. The floor is your genuine cost to be available and honour the envelope - the standing responsibility, not a guess at hours. The ceiling is a fraction of what the system being broken would cost the client. Your number sits between them, closer to the ceiling the more the business depends on the system.

1. Name the outcome in one sentence: what the client actually gets is a working system that keeps working and changes when they need it to.
2. Estimate the cost of a bad day: what does it cost this client, in money and time, when the system is down or wrong for a day. That sets your ceiling.
3. Define the envelope: how many small changes a month, what response time, what hosting and security oversight. That is what the fee buys.
4. Set the monthly fee as a small fraction of the bad-day cost, above your floor to be available. Then write the exclusions list so everything outside the envelope is a separate, numbered add-on.

Sanity check it against a simple test: if the client cancelled the retainer, would the risk they are now carrying feel bigger than the fee they just saved? If yes, the number is right and the retainer sells itself. If the fee feels large next to the risk, either the system does not need a retainer yet or you have priced the envelope too wide for what this client actually uses.

How to Present It So the Client Says Yes

Lead with the outcome, keep the mechanism in the background. The client is not buying change requests and dependency updates - those are how you deliver it. They are buying the fact that the thing their business now runs on will not silently break with no one responsible for it. Every line of the retainer offer should point back to that, or it belongs in an appendix.

Offer it at the moment of maximum trust, which is the handoff. A client who has just been given a working, documented system is the easiest person in the world to offer a retainer to, because they can already see exactly where they will want help next. Present one clear monthly number, the envelope it covers, the exclusions, and the response-time promise, on a single page. One page that a client can read the value of in ten seconds closes better than a long document that makes them feel they are signing something heavy.

NOTE: Claude Code Club members share the actual retainer numbers and envelopes they run, and how they present them at handoff without it feeling like an upsell. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) to get the delivery side sharp first, then layer the recurring offer on top.

FAQ

How do I price a maintenance retainer?

Set a fixed monthly fee tied to a defined envelope of work - a block of change requests, a response-time promise, and hosting oversight - and anchor the number to the outcome the client is buying rather than your hours. Size it as a small fraction of what a day of the system being broken would cost the client, above your floor to be available.

How much should a maintenance retainer cost?

There is no flat rule, because it depends on the size of the system and how much the business depends on it. Price it as a small fraction of what a bad day - the system down or wrong - would cost the client, above your genuine cost to be available. If the risk of cancelling feels bigger than the fee saved, the number is right.

Should a maintenance retainer be priced by the hour?

No. Hourly maintenance pricing sends your invoice down as you get faster, which is the wrong direction for a business. Price the outcome - a working system that keeps working - as a fixed monthly fee, so your improving speed stays in your column instead of shrinking what you earn.

What should a maintenance retainer include and exclude?

Include a defined block of small changes, bug fixes, keeping the system running, and hosting and security oversight, plus a response-time promise. Exclude new features, redesigns, rebuilds, and new integrations - those get a separate quote. The specific exclusions list is what stops quick fixes from becoming unpaid work.

When is the best time to offer a maintenance retainer?

At the handoff, right after you deliver a working, documented system. That is the moment of maximum trust, when the client can already see where they will want ongoing help, so a bounded monthly retainer reads as sensible protection rather than an upsell.

• Claude code token usage is the total text processed on every turn: everything Claude Code reads (your prompt, CLAUDE.md, the files it opens, tool results) plus everything it writes back. You are billed for input and output, and the running conversation history is re-sent on every turn - so a long session quietly costs more per message the longer it runs.
• The three biggest silent drains are: large files read in full when only a section was needed, conversation history that keeps growing across a marathon session, and re-reading the same files repeatedly because context was not kept tight. None of these are the model misbehaving - they are context you left in the window.
• The fix is context discipline: a short CLAUDE.md, pointing Claude at specific files instead of letting it search, starting a fresh session when a task is done, and using plan mode for big tasks so you approve the approach before it spends output tokens building the wrong thing.

What Counts as Token Usage in Claude Code

Token usage in Claude Code is the total amount of text the model processes on each turn, measured in tokens - small chunks of text roughly the size of a few characters or a short word. Every turn has two halves: input tokens (everything Claude Code reads before it responds) and output tokens (everything it writes back). Both count against your usage, and output tokens are the more expensive half.

The part most people miss is that Claude Code is stateless between turns. It does not remember your last message on its own - the full conversation so far is re-sent as input on every single turn so the model can see the whole thread. That means a session that has run for twenty messages is sending twenty messages of history as input on message twenty-one, before you have even added your new request. This is why long sessions feel like they get slower and burn usage faster: the input is growing every turn.

The Biggest Silent Drain: Reading Whole Files It Did Not Need

The single largest source of wasted token usage is Claude Code reading large files in full when it only needed a small part of them. When you ask a vague question in a big project, Claude Code opens files to figure out where the relevant code lives - and a single large file can be thousands of tokens of input, most of which was irrelevant to the change you wanted.

The fix is to point it at the exact target. Instead of "fix the login bug," say "in src/lib/auth.ts, the token refresh on line 40 is not clearing the old session - fix that." Now Claude Code reads one file, or one section, instead of hunting through five. In the Claude Code desktop app you can drag the specific file into the conversation so it never has to search. Every file it does not have to open is input you did not spend.

TIP: This is the same discipline that makes Claude Code more accurate, not just cheaper. Tight context means fewer wrong-file edits. The [Claude Code context engineering guide](/blog/claude-code-context-engineering) goes deeper on referencing files precisely.

Why Long Sessions Cost More Per Message

Because the whole conversation is re-sent as input on every turn, a marathon session gets more expensive the longer it runs - even if your individual messages stay short. The first message in a session might send a few hundred tokens of input. The fiftieth message sends the accumulated history of the first forty-nine turns before your new request is even read. You are paying to re-transmit the entire backstory over and over.

The fix is conversation hygiene: start a fresh session when a task is done. End a focused work block with a one-line summary - "we added the invoice PDF export and fixed the date bug; next is the email step" - then open a new session and paste that summary as the first message. You carry forward the decisions without dragging the entire transcript, which resets your input cost back to near zero.

NOTE: This is also the fix for quality drift, not just usage. A stuffed context window makes Claude Code start contradicting earlier instructions. The [when to start a fresh session guidance](/blog/claude-code-context-engineering) covers the signals to watch for.

Plan Mode Saves Output Tokens on Big Tasks

Output tokens are the expensive half of usage, and the most wasteful output is a large build that went in the wrong direction. When you ask Claude Code to implement a big feature in one shot, it may write hundreds of lines across several files before you get to see whether the approach was right. If it was wrong, you have paid for all that output and now have to pay again for the rewrite.

Plan mode fixes this. You ask Claude Code to produce a plan first - the files it will touch, the approach, the order of steps - and you approve or correct it before it writes a single line of implementation. The plan is cheap output; the wrong implementation is expensive output. Catching a bad approach at the plan stage is the highest-leverage way to cut output token usage on anything non-trivial.

• Use plan mode for anything that touches more than one or two files, so you approve the shape before the spend.
• Ask for a targeted edit, not a full-file rewrite, when the change is small - "change only the refresh function" produces far less output than "rewrite this file."
• Break large asks into a sequence of small, verified steps rather than one giant request that produces a wall of output you then have to unwind.

NOTE: The [Claude Code plan mode guide](/blog/claude-code-plan-mode) walks through using it on real client work so you ship without rework.

Keep Your CLAUDE.md Lean

Your CLAUDE.md file loads as input at the start of every session, so its length is a fixed tax on every conversation. A tight, 300-word CLAUDE.md that states your stack, your conventions, and your no-go zones is a good investment. A 5,000-word CLAUDE.md that tries to document everything is spending token budget on rules the model rarely needs, on every single turn, forever.

Aim for the shortest CLAUDE.md that reliably stops the mistakes you actually see. If Claude Code keeps using the wrong import, add a line about your stack. If it keeps touching a folder it should not, add a no-go line. Do not pre-load rules for problems you do not have. Lean context is cheaper and, again, more accurate - the model is not diluted by rules that do not apply to the task in front of it.

TIP: The [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) post has short starting templates you can trim to fit. Inside Claude Code Club, members share the lean CLAUDE.md files they run in real production projects - it is one of the most reused resources we keep on file. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

How to Tell What Is Using Your Usage

If you feel like you are hitting limits faster than the work justifies, the cause is almost always one of the drains above rather than the volume of real work. Run through this checklist before assuming you need a bigger plan. Most usage problems are a context problem in disguise.

If you have tightened all of that and still consistently run out, that is the signal that your workload genuinely needs more headroom - and that is a plan question, not a usage-discipline question. The [which Claude plan for Claude Code](/blog/which-claude-plan-for-claude-code) post breaks down Pro versus Max by real usage, and the [Claude Code usage limits guide](/blog/claude-code-usage-limits-what-to-do) covers what to do the moment you hit a cap mid-build.

FAQ

What uses the most token usage in Claude Code?

The largest single drain is Claude Code reading whole files it did not need because the request was vague. The second is conversation history: because the full thread is re-sent on every turn, a long session sends more and more input each message. Output tokens are the most expensive per token, so a large build that went the wrong way and had to be redone is also costly.

Does a long Claude Code session use more tokens?

Yes. Claude Code is stateless between turns, so the entire conversation so far is re-sent as input on every turn. On the fiftieth message it is sending the accumulated history of the first forty-nine turns before it even reads your new request. Starting a fresh session with a short summary resets that input cost back to near zero.

How do I reduce token usage in Claude Code?

Point Claude at specific files instead of letting it search, keep your CLAUDE.md short (a few hundred words, not thousands), start a fresh session when a task is done rather than running a marathon thread, and use plan mode on multi-file work so you approve the approach before it spends output tokens building it.

Do input and output both count toward Claude Code usage?

Yes. Input is everything Claude Code reads on a turn - your prompt, your CLAUDE.md, the files it opens, and the conversation history. Output is everything it writes back. Both count, and output is the more expensive half per token, which is why avoiding wrong-direction builds with plan mode matters so much.

Does a big CLAUDE.md file increase token usage?

Yes. Your CLAUDE.md loads as input at the start of every session, so its length is a fixed cost applied to every conversation. A lean CLAUDE.md that states your stack, conventions, and no-go zones in a few hundred words is efficient. A multi-thousand-word file spends token budget on rules the model rarely needs, every turn.

• An AI agency monthly report exists to protect the retainer, not to list your tasks. Clients do not renew because you were busy - they renew because they can see the outcome they are paying for. Lead the report with results tied to their goal, not a log of hours.
• Use a fixed five-part structure every month: the headline result, what changed since last month, what you shipped, what is next, and one clear ask or decision. Keeping it the same every month makes it fast to write and easy for the client to read at a glance.
• Send it before they ask, on the same day each month, and keep it to one page or one short screen. A report that arrives on schedule signals control - and control is what a retainer client is actually buying.

What a Monthly Client Report Is Actually For

An AI agency monthly report is a short document sent to a retainer client that shows them the outcome they are paying for, on a predictable schedule. Its real job is retention. A client renews when the report makes the value obvious and the relationship feel handled. A client drifts when the report reads like a timesheet, or worse, when no report arrives and they start wondering what they are paying for.

The most common mistake is treating the report as proof of effort - a long list of everything you touched this month. Clients do not buy effort. They buy an outcome: more leads, less manual work, a system that runs. If your report leads with tasks instead of results, you are training the client to evaluate you on activity, which is the one metric where AI-assisted work looks suspiciously cheap. Lead with the outcome and the effort becomes context, not the headline.

The Five-Part Report Structure I Use Every Month

Use the same five sections every month. A fixed structure is faster for you to write, easier for the client to skim, and it builds a rhythm - by month three they know exactly where to look for the number they care about. This is the CCC retainer report shape, and it fits on one page.

Notice what is not on the list: hours, a tool changelog, and internal process detail. None of that belongs in a client report. If the client wants a deeper breakdown they will ask, and you can send it - but the default document is the outcome, not the machinery behind it.

Lead With the Number the Client Cares About

The headline result is the whole report in one line, and it must be tied to the goal the client hired you for. If they hired you to cut the time their team spends on manual reporting, the headline is the hours saved this month - not the automation you built to save them. If they hired you for lead flow, the headline is leads, not the scraper you shipped. Translate every deliverable back into their language before it goes in the report.

Only use numbers you can actually stand behind. Never round up, never estimate a result you did not measure, and never present your own guess as a client outcome. If you cannot measure the headline metric yet because the tracking is not in place, say so plainly and make getting that tracking live the 'what is next.' A report built on a fabricated number is worse than a modest honest one - it costs you the trust the retainer runs on the moment the client checks.

NOTE: If you are still setting the price and scope of this kind of ongoing work, the [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) post covers the pitch, and [how to get repeat clients for your AI agency](/blog/how-to-get-repeat-clients-for-your-ai-agency) covers the wider retention picture the report feeds into.

How to Write It Fast Without It Feeling Generic

The report should take fifteen minutes, not an afternoon, or you will start skipping it - and a skipped report is a retainer at risk. The way to make it fast is to keep a running note during the month. Each time you ship something, drop a one-line outcome into a note for that client. At month end you are editing a list, not reconstructing four weeks from memory.

You can have Claude Code help draft it from that running note. Point it at your notes file and your last report, and ask it to produce this month's report in the same five-part structure, outcome-first, in the client's language. You are not outsourcing the judgment - you decide the headline and check every number - but the assembly and the wording are exactly the kind of repeatable task the desktop app handles well. The result is a consistent, on-brand report in minutes.

• Keep a one-line-per-win running note per client so month-end is editing, not remembering.
• Reuse last month's report as the template so the structure and tone stay identical every time.
• Write every deliverable as an outcome in the client's words before it goes in - translate 'built a Zapier flow' into 'cut your invoice admin to zero.'
• Draft with Claude Code from your notes, then edit the headline and verify every number by hand before sending.

When and How to Send It

Send the report on the same day every month, before the client asks for it. A report that arrives on schedule, unprompted, signals that the engagement is under control - and control is the thing a retainer client is really paying for. A report you only send when chased signals the opposite, no matter how good the work inside it is.

Send it as a short email with the report in the body or as a one-page PDF - not a link to a dashboard the client has to log into and interpret. The client should be able to read the headline on their phone in ten seconds and feel good about the money. If there is a decision you need from them, put it at the very end as a single clear ask so it does not get lost, and follow up once if they do not respond within a few days.

TIP: The monthly report is also the natural moment to surface more work. If 'what is next' keeps pointing at something bigger than the current scope, that is an upsell the client is already primed for. The [how to upsell existing clients without a pitch](/blog/upsell-existing-clients-without-a-pitch) post covers doing this without it feeling like a sales push. Inside Claude Code Club we share the exact report templates and client-facing systems that keep retainers renewing - join for $9 a month at https://www.skool.com/claudecodeclub/about.

FAQ

What should an AI agency monthly report include?

Five sections: a headline result tied to the client's goal, what changed since last month, what you shipped (outcome-first bullets), what is next, and one clear ask or decision. Leave out hours, tool changelogs, and internal process detail - the client is buying an outcome, so lead with the outcome.

How long should a client report be?

One page, or one short screen. The client should be able to read the headline in ten seconds. A long report is less likely to be read and trains the client to evaluate you on volume of activity rather than the result they are paying for. Keep depth available on request, but default to short.

How do I write a monthly client report quickly?

Keep a running note during the month with one line per win, reuse last month's report as a template, and draft this month's from those notes - you can have Claude Code assemble the draft in your fixed five-part structure. You still decide the headline and verify every number by hand. Done this way it takes about fifteen minutes.

When should I send the monthly report?

On the same day every month, before the client asks. An on-schedule, unprompted report signals the engagement is under control, which is what a retainer client is actually paying for. Send it as a short email or a one-page PDF, not a dashboard link they have to log in and interpret.

Should a monthly report include hours worked?

No. Listing hours trains the client to evaluate you on effort, which is the one metric where AI-assisted work can look cheap and invite fee pressure. Report the outcome the client is paying for instead. If they specifically ask for a time breakdown you can provide it, but it should never be the default headline.

• Context engineering means deliberately shaping what Claude Code reads before it acts - your CLAUDE.md, the files you pin, how you open a session, and when you clear conversation history. The model can only work with what is in its context window, so the quality of your context determines the quality of what it builds.
• The three levers are: your CLAUDE.md file (persistent project instructions that load every session), explicit file references (pointing Claude at the exact code it needs instead of making it search), and conversation hygiene (knowing when to start a fresh session so you are not dragging stale context through a long build).
• The most common mistake is treating Claude Code like a search engine - typing a vague request and hoping it finds the right file. Context engineering flips that: you give it the right file, the right constraint, and the right scope before you ask.

What Context Engineering Actually Means in Claude Code

Context engineering for Claude Code is the practice of deliberately deciding what the model reads before it starts any piece of work. Claude Code does not have persistent memory between sessions. It has a context window - a fixed amount of information it can hold at once - and every response it gives is based entirely on what is currently inside that window. Context engineering is the skill of making sure the right things are in that window at the right time.

That sounds simple, but in practice most people using Claude Code are doing the opposite. They open a session, type a request, and hope the model figures out where the relevant code lives. Sometimes it does. Often it makes an educated guess, touches the wrong file, and produces output that technically answers the question but breaks something else. Context engineering is the fix.

NOTE: New to Claude Code? The [Claude Code desktop app guide](/blog/claude-code-desktop-app) is the right starting point. This post assumes you have a project open and want to get more consistent results from it. The [CLAUDE.md file guide](/blog/claude-code-claude-md-file) goes deeper on the specific file referenced throughout this post.

The Three Levers of Context in Claude Code

There are three things you actually control when it comes to Claude Code's context: what is in your CLAUDE.md file, which files you explicitly reference in your message, and how long you let a conversation run before starting fresh. Each one has a different time horizon - CLAUDE.md is permanent, file references are per-message, and conversation hygiene is per-session.

These three levers cover almost every consistency problem people blame on the model. Claude Code is not being random when it touches the wrong file or forgets a constraint you mentioned six messages ago. It is working with the context it has. Engineering that context is your job.

Your CLAUDE.md File Is Your Most Important Context Investment

The CLAUDE.md file in your project root is the single most impactful thing you can add to any Claude Code project. It loads automatically at the start of every session and tells Claude Code the things that are always true about this project: the tech stack, the naming conventions, the folders it should never touch, the style rules you care about, and the constraints that must hold across every file it generates.

Without it, you are re-explaining your project from scratch every session. With it, Claude Code starts each session already knowing that your project uses TypeScript strict mode, that all components live in src/components, that you never want inline styles, and that the database schema lives in a specific migration folder. You stop correcting the same mistakes repeatedly.

• List the tech stack and major dependencies so Claude Code never suggests an import from a library you are not using.
• Name the folders that are off-limits or that have special rules - e.g. never edit migrations directly, always run them through the migration tool.
• State the code style rules that matter to you: casing, file naming, how you handle errors, what the testing pattern is.
• Include a short project description (one or two sentences) so Claude Code knows what the product is supposed to do when it makes architectural decisions.
• Add a section for things Claude should always confirm before doing - dropping a table, making a schema change, touching a production config.

TIP: Keep CLAUDE.md short enough to read in two minutes. A 5,000-word file adds so much context that the model is spending token budget on your rules instead of your code. Aim for under 500 words for a typical project. The [CLAUDE.md templates post](/blog/claude-md-templates-by-project-type) has working templates by project type if you want a starting point.

How to Reference Files Without Making Claude Hunt

When you type "update the auth handler" and Claude Code has 400 files to search through, it is doing pattern matching on filenames and directory names to find a candidate. Sometimes that is fine. But in a mature codebase with multiple files that touch authentication - middleware, a helper module, a routes file, a types file - it may pick the wrong one, make a change there, and not touch the one you needed.

The fix is to be specific about what you are pointing at. In the Claude Code desktop app, you can drag a file into the conversation or reference it by path. In a terminal session, you can paste the relevant code block. Either way, you are making the target unambiguous. Claude Code works best when the context contains the actual thing to be changed, not a description of where it might be found.

• Reference the file path explicitly in your message when asking about a specific file - for example: "in src/lib/auth.ts, update the token refresh logic to..."
• For a change that spans multiple files, name all of them in your message so Claude Code knows the full scope before it starts.
• Paste the relevant function or block inline for small, targeted changes. This is faster than file search and keeps the context tight.
• If you want Claude to understand the existing pattern before changing it, paste both the thing you are changing and a working example of the pattern to follow.

When to Start a Fresh Session

Every message you send and every response Claude Code gives adds to the conversation history in the context window. Early in a session that history is useful - Claude can refer back to decisions you made two messages ago. Late in a long session, that same history starts to crowd out the code it actually needs to work with, and the model starts reflecting earlier context more than recent instructions.

The signal that it is time to start a new session is when Claude Code starts contradicting a constraint you set, generating code in a style you moved away from three tasks ago, or asking you to clarify something it got right earlier. That is not the model regressing. That is a full context window redistributing attention. The fix is a fresh session with your CLAUDE.md already loaded, a clean slate, and your current focus in the first message.

TIP: A useful habit: end each focused work session with a summary message - something like "we added X, changed Y, and the next step is Z." Then start a new session and paste that summary as the first message. You carry the decisions forward without carrying all the noise of how you got there.

Context Engineering for Agents and Subagents

If you are running Claude Code in agent mode or dispatching subagents with the /agents command, context engineering becomes even more important because each subagent starts with its own context window and cannot share memory with the others mid-run. The information a subagent needs to do its job has to be passed to it explicitly in its task description.

This means your CLAUDE.md becomes the shared foundation - every subagent reads it at startup. Beyond that, each subagent task should include the specific files it will touch, the constraints that apply to its scope, and a clear deliverable. A subagent told "improve the checkout flow" will do something. A subagent told "in src/pages/checkout.tsx, update the payment form to show a loading state during submission, matching the pattern in src/components/Button.tsx" will do the right thing.

NOTE: The [Claude Code subagents guide](/blog/claude-code-subagents) covers how to structure multi-agent runs. The [agent loops post](/blog/claude-code-agent-loops) explains how the agentic loop works and where context decisions matter most inside it. Inside the club, members share the CLAUDE.md files they actually run in production projects - it is one of the more practically useful things we keep on file. Join for $9 a month at https://www.skool.com/claudecodeclub/about.

The Most Common Context Mistakes and How to Fix Them

Most inconsistency problems in Claude Code trace back to one of a small number of context mistakes. They are not hard to fix once you know what you are looking for.

FAQ

What is context engineering in Claude Code?

Context engineering is the practice of deliberately shaping what Claude Code reads before it acts - primarily through your CLAUDE.md file, explicit file references in each message, and conversation hygiene (knowing when to start a fresh session). The model can only work with what is in its context window, so controlling that input controls the quality of the output.

What should I put in my CLAUDE.md file for context engineering?

A short project description, the tech stack and major dependencies, the folder structure and any folders Claude should never touch, your code style rules, and a list of things Claude must confirm before doing. Keep it under 500 words - a long CLAUDE.md eats context budget that could go toward the actual code.

How do I reference specific files in Claude Code?

In the Claude Code desktop app you can drag a file into the conversation. In any session you can reference the file by its path in your message - for example, "in src/lib/auth.ts, update the refresh logic to..." For small changes, pasting the relevant code block directly into the message is faster and keeps the context tight.

When should I start a new Claude Code session?

Start a new session when a major task is complete, when Claude Code starts contradicting constraints you set earlier, or when its output style starts drifting. A full context window will redistribute attention across everything it holds - starting fresh with a summary of decisions made is more reliable than trying to correct drift mid-session.

Does context engineering matter for Claude Code subagents?

Yes, and it matters more than in a single session because each subagent starts with its own context window and cannot share memory with other subagents mid-run. Each task you give a subagent should include the specific files it will touch, the constraints on its scope, and a clear deliverable - not just a vague goal.

• Claude Code lets you ship a working side project in a weekend because it handles the parts that usually kill momentum - the boilerplate, the config, the parts where you get stuck and close the laptop. You still make every product decision; Claude Code handles the execution.
• The weekend sequence that works: Friday evening for scoping and setup, Saturday for building the core loop, Sunday for polish and deploy. Each phase has a specific Claude Code mode and a clear stopping rule so you do not keep adding features instead of shipping.
• The number one mistake is scoping too wide. A side project that ships at 60 percent of what you imagined is infinitely more useful than one that stays at 90 percent forever. Use Claude Code's plan mode on Friday to force yourself to decide what the MVP actually is, then hold the line on Saturday.

Why Side Projects Die Before They Ship

Ship a side project with Claude Code and the usual blockers change. Not disappear - change. The idea is not the hard part. The hard part is the Friday evening where you open your editor, realize you need to wire up authentication before you can build the thing you actually want to build, spend two hours on that, and close the laptop frustrated. Or the Saturday where you get stuck on a CSS layout problem that has nothing to do with your idea and costs you the whole day.

Claude Code removes those specific blockers. It sets up auth. It handles the layout. It writes the boilerplate that has nothing to do with what makes your project interesting. That is not magic - it is just removing friction at the exact points where momentum dies. You still have to know what you are building, make every product decision, and test whether it actually works. But the parts that kill side projects become fast.

NOTE: This guide is for people who have Claude Code installed and want a practical shipping sequence. If you are not set up yet, start with the [install guide for Mac](/guides/install-claude-code-on-mac) and your [first Claude Code project walkthrough](/guides/your-first-claude-code-project). The [Claude Code desktop app post](/blog/claude-code-desktop-app) explains why the desktop app is the right starting point over the terminal.

Friday Evening: Scope and Setup (Two Hours Maximum)

The Friday session has one job: make the scope small enough to ship by Sunday. Most side projects fail because they try to ship the full vision instead of the version that proves the idea. Use Claude Code's plan mode on Friday to force a scoping decision.

Open Claude Code, switch to plan mode, and describe your idea plainly - what it does, who it is for, and what a person does with it. Then ask: "what is the smallest version of this that is actually useful to someone?" Claude Code will give you a feature list. Your job is to cut it by half and ask again. The thing you end up with after two rounds of cutting is your weekend scope. Write it down somewhere you will see it on Saturday.

1. Describe the idea to Claude Code in plan mode - one paragraph, plain English, no technical detail yet.
2. Ask it for a minimal feature list and a suggested tech stack. Do not argue with the tech stack recommendation unless you have a specific reason - use what it suggests so you are not debugging setup instead of building.
3. Cut the feature list to the three things that make the project worth using at all. Everything else is a future version.
4. Ask Claude Code to scaffold the project with that stack. Let it run. When it stops, open the scaffolded project and make sure it boots.
5. Write a CLAUDE.md file now. Ask Claude Code to generate one based on the scaffold it just created. Review it, add anything specific to your project, and save it. This will save you time on Saturday.

TIP: The stopping rule for Friday: the project boots, there is a CLAUDE.md in the root, and you have a written list of exactly three features to build. If you are past two hours and not there, you have scoped too wide. Cut more.

Saturday: Build the Core Loop

Saturday has one job: build the thing the project actually does. Not the landing page, not the settings screen, not the pricing. The core loop - the sequence of actions a user takes to get the main value out of the product. For a tool that analyzes text, that is: paste text, get analysis, see results. For a tracker, that is: add an item, mark it done, see your list. Build that first and build nothing else.

Work in focused sessions of 90 minutes with breaks between them. A typical Saturday might be: morning session for the data model and backend logic, afternoon session for the UI that drives that logic, evening session to connect them and make the core loop actually work end to end. Claude Code should be open for the whole day. Give it one clear task at a time - not "build the app" but "build the form that takes user input and saves it to the database."

• Start each session by telling Claude Code exactly what you are building in this session and referencing the specific files it will need to touch.
• When Claude Code finishes a task, test it manually before moving to the next one. Do not stack unverified changes.
• If you hit a bug, describe it to Claude Code with the exact error message and the file it appeared in. Do not debug by yourself when Claude Code can see the same error you do.
• Resist the urge to add features. When an idea comes up for something outside your three-feature scope, write it down and keep going. The list will be there on Monday.

WARNING: The most common Saturday failure mode is feature creep disguised as polish. "I just need to make this one thing nicer before I continue" turns into three hours on something that was not in scope. The core loop does not have to be beautiful on Saturday. It has to work.

Sunday: Polish and Deploy

Sunday has two phases: a short polish pass and a deploy. The polish pass is not about making the project look finished - it is about making it usable by someone who is not you. That means: clear labels, an obvious way to get started, no blank states that leave someone confused about what to do next, and no obvious visual breakage on a phone.

Ask Claude Code to review the project for usability gaps - things that would confuse a first-time visitor. It will suggest changes. Pick the ones that take under ten minutes each and skip the rest. Then deploy. Vercel is the fastest path for most projects built on modern frameworks - the [deploy with Claude Code guide](/guides/deploying-to-vercel-with-claude-code) walks through the exact steps. If Claude Code scaffolded the project, it will also know how to deploy it.

1. Morning: do the polish pass. Give yourself a two-hour maximum. When the time is up, stop polishing.
2. Set up a domain or use the Vercel preview URL for now - having a real URL is the goal, not having a perfect domain.
3. Ask Claude Code to check for environment variable issues, hardcoded localhost references, and any build errors before you push.
4. Push, watch the deploy, click through the live URL as a user would. Note what is broken, not what is missing. Fix what is broken. Accept what is missing as future work.
5. Share the URL with one real person and get their reaction before you decide what to build next.

What Claude Code Is Good at in This Sequence (and What It Is Not)

Claude Code is good at all the execution that does not require knowing what your project is supposed to feel like. Scaffolding, auth, forms, API routes, basic styling, database schema, deployment config - these are fast and reliable. It is not a substitute for the product thinking. The scoping decision on Friday, the judgment call about which three features matter, the test of whether the core loop is actually satisfying to use - those are yours.

The most important skill in the weekend sequence is not knowing how to prompt Claude Code. It is knowing when to stop adding things. Claude Code makes adding things fast, which makes scope creep faster. The weekend framework is specifically designed to create forcing functions against that - two-hour Friday sessions, 90-minute Saturday blocks, a two-hour Sunday polish cap. The time boxes are the discipline.

NOTE: Inside Claude Code Club, members share the projects they actually ship - what the scope was, what got cut, what Claude Code handled and what it could not. It is a useful reality check on what is possible in a weekend. The community is $9 a month at https://www.skool.com/claudecodeclub/about. The [curriculum](/curriculum) also has a structured path through building your first project if you want a guided sequence rather than a free-form weekend sprint.

What to Do With It After You Ship

The weekend ends with a live URL. That is the win. What you do next depends on what you learn from the one person you shared it with on Sunday. If they found it confusing, the next session is usability. If they wanted a feature you cut, that tells you something about whether the cut was right. If they used it and did not come back, that is information too.

The common mistake after shipping a side project is immediately expanding it based on what you wish it had. The more useful move is to watch how the first person actually used it and build based on that. Claude Code makes iteration fast enough that a week of small sessions can take the project further than a second weekend sprint on a wishlist.

TIP: Keep your CLAUDE.md updated after each session. Every constraint you add there is time you save re-explaining the project next time. The [context engineering guide](/blog/claude-code-context-engineering) covers how to use CLAUDE.md and session management to keep Claude Code consistent as the project grows.

FAQ

Can you really ship a side project with Claude Code in a weekend?

Yes, if the scope is tight enough. The key constraint is your three-feature rule on Friday evening - the weekend sequence only works if you make a real cut to what you are building, not just a nominal one. Claude Code handles execution fast, but it cannot compress a two-month project into a weekend. A focused, well-scoped idea with a clear core loop is genuinely shippable in two days.

What tech stack should I use for a weekend side project with Claude Code?

Use what Claude Code recommends when you describe your project in plan mode on Friday. The goal of the weekend is to ship, not to use a specific stack. If you have a preference and it is a stack Claude Code knows well (Next.js, React, Python, Node), that is fine - just do not spend Friday debating it. The setup time matters more than the choice.

What if I get stuck on Saturday?

Describe the block to Claude Code with the exact error message and the file where it appeared. If Claude Code cannot resolve it in two or three attempts, it is probably a scope or architecture issue rather than an implementation issue - ask it to propose a simpler approach to the same goal. Do not spend more than 30 minutes stuck on any single problem without checking whether the approach itself is the issue.

How do I deploy a Claude Code project after the weekend?

Vercel is the fastest path for most web projects. The [deploying to Vercel guide](/guides/deploying-to-vercel-with-claude-code) walks through it. If Claude Code scaffolded your project, tell it you want to deploy to Vercel and it will handle the config. Check for hardcoded localhost references and missing environment variables before you push - those are the two most common issues on a first deploy.

What is the most common reason a side project does not ship over a weekend?

Scope creep, almost always. The project started with three features and by Saturday afternoon has twelve. Claude Code makes adding things fast, which makes the temptation to add one more thing harder to resist. The time boxes in the Friday/Saturday/Sunday framework exist specifically to create a forcing function against this. Hold the line on your three Friday features until the project is live.

• Connect Claude Code to Supabase with Supabase's own hosted MCP server at https://mcp.supabase.com/mcp. Run claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp", then run claude /mcp and authenticate in the browser. No personal access token is needed for the hosted route.
• Before you point it at anything that matters, add three guardrails to the URL: project_ref to scope it to one project, read_only=true so it runs SQL as a read-only user, and a features list so it only exposes the tool groups you actually need.
• Once it is connected, Claude Code can list your tables, write and apply migrations, run SQL, pull logs to debug, and generate TypeScript types from your schema, all inside the same build conversation instead of a separate copy-paste step.

What the Supabase MCP Server Actually Gives Claude Code

Connect Claude Code to Supabase by adding Supabase's own hosted MCP server, at https://mcp.supabase.com/mcp, and authenticating once through your browser. Once it is connected, Claude Code can list your tables, write and apply database migrations, run SQL queries, read project logs to debug an issue, and generate TypeScript types straight from your schema, all inside the same session where you are already building.

This is a server Supabase built and runs themselves, not a community package stitched together against their API. That is why it keeps working when Supabase ships a change instead of quietly going stale. The tools are grouped into feature sets - database, debugging, development, functions, branching, docs, account, and storage - and you choose which groups to turn on when you register the server.

NOTE: New to this whole idea? Start with [what are MCP servers, and why do they matter for Claude Code](/blog/what-are-mcp-servers-and-why-they-matter), then the club's [guide to setting up MCP servers](/guides/setting-up-mcp-servers). If you just need any database and are not committed to Supabase yet, [connect Claude Code to a database](/blog/connect-claude-code-to-a-database) covers the general case first.

How to Connect It: the Hosted Route

The hosted route is the one Supabase documents as the default, and it is the one I would use. It authenticates through your browser, so there is no token to generate, paste, or accidentally commit.

1. In your project folder, run claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp" to register the server. Using --scope project writes it to a .mcp.json in the repo so the connection travels with the project.
2. In a regular terminal (not an IDE extension), run claude /mcp, select the supabase server, and choose Authenticate. A browser window opens where you sign in to Supabase and grant access.
3. Pick the organization that contains the project you want to work with when you sign in. After that, ask Claude Code something like: what tables are in the database, use the MCP tools. If it answers with your real schema, the connection is live.

If you would rather not put the URL in a shared repo file, drop the --scope project flag and it registers only for you on that machine. Either way, the authentication is per-account through the browser, not a secret baked into the config.

TIP: There is an older setup floating around that spawns @supabase/mcp-server-supabase locally through npx with an --access-token flag. It still exists, but the hosted remote server is the current default and skips the token entirely. Reach for the local package only in a CI environment where a browser login is not possible, in which case you pass a personal access token as an Authorization header instead.

The Three Settings That Keep It Safe

Do not point a wide-open MCP connection at a production database. The server acts with your developer permissions, so an LLM that gets confused - or gets fed a malicious instruction hidden inside your own data - can run real queries. Three URL parameters shrink that risk to almost nothing, and you set them by editing the server URL you registered.

You combine them with & in the URL, like https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true. For a database you cannot afford to break, scope it, set it read-only, and restrict the features to the smallest set that answers your question. Widen access only when a specific task genuinely needs to write.

WARNING: The attack worth knowing about is prompt injection: text living inside your own data (a support ticket, a user-submitted field) that tells the model to run a query it should not. Keep manual approval of tool calls on for interactive work and read each proposed query before you approve it. Read-only mode plus project scoping is what turns a bad approval from a disaster into a harmless no-op.

What Actually Broke the First Time I Wired It Up

The first time I set this up I used the old npx-spawned local server, and Claude Code reported it as connected. It was not really connected. The server showed as present, but none of its tools were discoverable, so the model just quietly failed to use them with no error to explain why. I spent longer than I would like re-checking my token before realizing the setup itself was the problem, not the credential.

Switching to the hosted remote server and authenticating through the browser fixed it in one pass. The lesson I would save you: if Claude Code says a Supabase MCP server is connected but never actually uses any Supabase tools, do not assume your token is wrong. Confirm the tools are discoverable first by running /mcp and checking the tool list, and prefer the hosted route so there is no token in the loop to doubt at all.

What This Is Actually Good For

The everyday win is that Claude Code stops guessing at your schema. Instead of you pasting a table definition into a prompt, it reads the real one and writes SQL or a migration against what is actually there.

• Ask for a migration in plain English and have Claude Code write it, then apply it against a development branch rather than typing DDL by hand.
• Debug a slow or failing feature by having it pull the project logs and run a read-only query to see the actual rows, not a mock of them.
• Generate up-to-date TypeScript types from the live schema so your app code and your database stop drifting apart.
• Run a report - the real numbers behind a client dashboard - with a read-only SQL query instead of exporting a CSV and eyeballing it.

Branching deserves its own note. Supabase's branching feature lets Claude Code create a throwaway development database, make changes there, and merge back when they are proven, so you are never testing a risky migration against live data. It is on a paid plan and worth it the moment real user data is involved.

When Not to Bother With It

Skip it for a one-off script with no database behind it, or a throwaway prototype where you do not care about the schema surviving. The setup earns its keep once there is a living project - real tables, real migrations, a schema you would otherwise be re-describing to the model every session.

NOTE: Inside Claude Code Club, members share the actual MCP configs they run for tools like this - which feature groups they leave on, which projects they keep read-only, and the ones that were not worth the setup. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the structured path through MCP setup first.

FAQ

How do I connect Claude Code to Supabase?

Register Supabase's hosted MCP server with claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp", then run claude /mcp, select the supabase server, and choose Authenticate. A browser window opens where you sign in to Supabase and grant access. No personal access token is required for the hosted route.

Do I need a Supabase access token to connect Claude Code?

Not for the hosted server. It authenticates through your browser using dynamic client registration, so there is no token to create or store. You only need a personal access token for a CI environment where a browser login is not possible, where you pass it as an Authorization header instead.

How do I stop Claude Code from writing to my production Supabase database?

Add read_only=true to the server URL so every query runs as a read-only Postgres user, and add project_ref=<id> to scope the server to one project and disable account-level tools. Combine them like https://mcp.supabase.com/mcp?project_ref=abc123&read_only=true, and keep manual approval of tool calls on so you can review each query first.

What can Claude Code do once it is connected to Supabase?

It can list tables and extensions, write and apply migrations, run SQL queries, pull project logs to debug, generate TypeScript types from your schema, and manage development branches on a paid plan. The exact abilities depend on which feature groups you enabled in the server URL.

Why does the Supabase MCP server show as connected but no tools work?

This is the classic symptom of the older local npx setup, where the server registers but its tools are not discovered, with no error shown. Switch to the hosted remote server at https://mcp.supabase.com/mcp and authenticate through the browser, then run /mcp to confirm the tools are actually listed.

• The right Claude plan for Claude Code depends on how heavily you use it. The paid Pro plan is the entry point and includes Claude Code; the Max plan comes in two levels that give you 5x or 20x more usage than Pro per 5-hour session. The Free plan does not include Claude Code at all.
• Start on Pro. Move to Max only once you keep hitting the usage limit mid-work, not once or twice a week. That single signal - being blocked while you still have work to do - is the honest trigger to upgrade, not a feature you are missing.
• Usage is metered in rolling 5-hour sessions with a weekly cap on top. When you hit a limit you wait for the window to reset; the highest Max level also lets you opt into paying per token at standard API rates to keep going past the cap.

Which Claude Plan Do You Need for Claude Code?

You need a paid Claude plan to use Claude Code, and the entry point is Pro. Pro includes Claude Code and is enough for most people learning it or working on small projects. The Max plan exists for one reason: more usage. It comes in two levels that give you 5x or 20x the usage of Pro in each rolling 5-hour session. The Free plan does not include Claude Code, so it is not an option here.

The decision is not about unlocking features. Claude Code itself is the same tool on Pro and Max. What changes is how long you can keep working before you hit a limit. So the plan question is really a usage question, and the honest way to answer it is to start low and move up only when your own usage forces it. Check current prices on [Claude's own pricing page](https://claude.com/pricing) before you decide, since plans and prices change.

NOTE: This is the pricing side of the same story we tell newcomers in [Claude Code for non-coders](/blog/claude-code-for-non-coders) and the [Claude Code desktop app](/blog/claude-code-desktop-app) walkthrough. You install the desktop app, sign in with your plan, and Claude Code is there - the plan is what governs how much you can run.

Pro vs Max, Ranked by How You Use Claude Code

Here is the ranked answer, cheapest first. Pick the lowest one that does not leave you blocked mid-task.

1. Pro - the default. If you are learning Claude Code, building small projects, or using it in bursts rather than all day, start here. It includes Claude Code and gives you real working room without paying for capacity you will not touch.
2. Max, 5x level - the working-daily plan. If you use Claude Code most days on real projects and keep bumping the Pro limit, this is the natural step up. Five times the per-session usage of Pro is enough for sustained daily building.
3. Max, 20x level - the heavy plan. If you run Claude Code for hours at a stretch, on larger codebases or with agents working in the background, this gives twenty times Pro's per-session usage. It is also the level that lets you keep going past the cap by paying per token.

There are also team and enterprise plans for organizations that need shared administration, seat management, and governance controls. For an individual builder or a solo agency operator, the real choice sits between Pro and the two Max levels.

What the Usage Limits Actually Mean

Claude Code usage is metered in rolling 5-hour sessions, with a weekly cap layered on top. The 5-hour window is short-term throttling; the weekly cap is the ceiling for the whole week. Both Pro and Max share the same usage pool across Claude and Claude Code, so a heavy chat session and a heavy build session draw from the same budget.

When you reach a 5-hour limit, you wait for that window to reset and then keep working. When you reach the weekly cap, you are done until the next week - unless you are on the 20x Max level, which lets you opt into extra usage billed per token at standard API rates so you are not fully stopped. The exact number of prompts you get per window is not a fixed figure Anthropic publishes as a single number; it varies with how large and complex each request is, so treat any specific prompt count you see quoted elsewhere as a rough estimate, not a guarantee.

TIP: If you are hitting limits sooner than you expect, the fix is often technique before it is a bigger plan. Tighter prompts and smaller context cost less per turn. We cover the practical moves in [what to do about Claude Code usage limits](/blog/claude-code-usage-limits-what-to-do), and the recent limit changes in [Claude Code weekly limits](/blog/claude-code-weekly-limits-september-2026).

The One Signal That Says Upgrade

Upgrade when you are regularly blocked while you still have work to do. Not when you hit a limit once in a busy week - that is normal and cheap to wait out. The trigger is hitting the wall during the workday, often enough that waiting for the reset is costing you real momentum. That is the moment a bigger plan pays for itself in recovered time.

The mistake goes both ways. Some people over-buy on day one, pay for the 20x level, and use a fraction of it. Others cling to Pro while losing an hour a day to blocked sessions. The self-check we teach members is simple: for one week, note every time Claude Code stops you mid-task. Zero or one? Stay put. Several times a day? Move up a level. Let your actual usage make the call, not a guess about your future usage.

How This Fits an Agency or Client Workflow

If you build for clients, treat the plan as a cost of goods, not a personal subscription. A single Max level that keeps you unblocked through a delivery week is cheap against the value of shipping on time. The usage a client project pulls - especially anything running in the background - used to hide inside a personal plan; now it is metered, so it belongs in how you price the work.

NOTE: Claude Code Club members compare notes on which plan level actually covers real client delivery, and how to fold that cost into a quote instead of eating it. It is $9 a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) to get productive on Claude Code first, then right-size the plan.

FAQ

Which Claude plan do I need for Claude Code?

You need a paid plan. Pro is the entry point and includes Claude Code, which is enough for learning it and for small projects. The Max plan gives you 5x or 20x more usage than Pro per 5-hour session for heavier use. The Free plan does not include Claude Code.

Can I use Claude Code on the free Claude plan?

No. Claude Code is not included on the Free plan. You need at least the paid Pro plan to use it, and can move up to Max for more usage.

What is the difference between Pro and Max for Claude Code?

The tool is the same; the difference is usage. Pro is the baseline paid plan. Max comes in two levels that give 5x or 20x the usage of Pro per 5-hour session, aimed at people who use Claude Code daily or run it for long stretches on larger codebases.

What happens when I hit my Claude Code usage limit?

Usage is metered in rolling 5-hour sessions with a weekly cap on top. When you hit a limit you wait for the window to reset and then continue. The 20x Max level also lets you opt into extra usage billed per token at standard API rates so you can keep working past the cap.

When should I upgrade from Pro to Max?

Upgrade when you are regularly blocked mid-task, not just once or twice in a busy week. For one week, note every time Claude Code stops you before you finished; if it happens several times a day, move up a level, and if it barely happens, stay on Pro.

• Claude Code for non-coders works because you describe what you want in plain English and Claude writes, runs, and fixes the code for you. You install the desktop app, open a folder, type what you want built, and review the result. The terminal is optional, not required.
• The single habit that keeps a non-coder unstuck is to ask before you build. Tell Claude to plan the steps in plain language first, read them back, and only then say go. That one move turns a black box into something you can actually steer.
• Start with something small and real that you would use this week: a one-page site, a simple tracker, a script that renames your files. Shipping one working thing teaches more than any tutorial, and it is the fastest way to see whether this is for you.

Can a Non-Coder Actually Use Claude Code?

Yes. Claude Code is built so that you describe what you want in plain English and it writes, runs, and fixes the code for you. You do not read the code line by line, you do not memorize syntax, and you do not need a computer science background. Your job is to say clearly what you want, look at what came back, and tell Claude what to change. That is a skill any careful person already has.

The reason this now works for non-coders is the desktop app. You open it the way you open any program, point it at a folder on your computer, and type a request into a chat box. Claude does the technical work in the background and shows you the result. The terminal, the black window with the blinking cursor that scares most beginners off, is optional. Most people who join the club never touch it.

TIP: If you have ever written a clear brief for someone, described a problem to a helpful support agent, or given step-by-step directions to a friend, you already have the core skill. Building with Claude Code is mostly clear communication, not typing.

What You Need to Get Started (It Is Less Than You Think)

You need three things: the Claude Code desktop app, a Claude account, and a small idea for something to build. That is the whole list. You do not need to install a pile of developer tools first, and you do not need to understand what any of them do before you begin.

1. Install the Claude Code desktop app and sign in. This is the same as installing any other app: download, open, log in.
2. Pick a folder on your computer to work in. A new empty folder is perfect for your first build. Claude works inside the folder you point it at and does not roam the rest of your machine.
3. Type what you want in plain English. Not code, not commands. Something like: build me a simple page that lists my three services with a photo and a contact button.

From there Claude does the building. When it finishes, it tells you what it made and how to look at it. If something is off, you say so in plain words and it fixes it. For the full first-day walkthrough, the club keeps a step-by-step [day-one setup guide](/blog/claude-code-day-one-setup) that assumes zero coding background.

The Ask-First Habit: The One Move That Keeps You Unstuck

The single most useful habit for a non-coder is what we call the Ask-First Habit inside Claude Code Club: before you let Claude build anything real, ask it to plan the steps in plain English first. Tell it not to write any code yet, just to explain what it is about to do and why. Read that plan back. If it makes sense, say go. If it does not, correct it before a single line is written.

This matters because the moment a non-coder feels lost is when the tool runs ahead and produces something they cannot follow. Asking for the plan first turns a black box into a conversation you can steer. You do not need to understand the code Claude will write. You only need to understand the plan, and a good plan is always in plain language.

NOTE: A simple version of the Ask-First Habit: type "Before you build anything, list the steps you'll take in plain English and wait for me to approve them." This one sentence, added to the front of a request, is the difference between feeling in control and feeling lost.

What Should a Non-Coder Build First?

Build something small and real that you would genuinely use this week. The goal of your first build is not to impress anyone. It is to see one thing you asked for actually work on your own screen. That single experience teaches more than a month of watching tutorials, and it tells you honestly whether this is for you.

Pick one, describe it clearly, use the Ask-First Habit, and ship it. When it works, you will want to build the next thing, and that pull is the whole point. If you want a curated list of starter ideas with the exact wording to paste in, the club keeps a running set inside the [beginner tips guide](/blog/claude-code-tips-for-beginners).

What to Do When You Get Stuck

When something breaks or does not look right, describe what you see in plain English and ask Claude to fix it. You do not diagnose the problem yourself. Say what you expected, say what actually happened, and let Claude do the debugging. This is the part non-coders worry about most and it is genuinely the easiest part, because explaining a problem is something you already know how to do.

• Describe the gap: "I expected a blue button but I see a grey one. Can you fix it and tell me what was wrong?"
• Ask for a plain-English explanation, not just a fix, so you slowly learn what tends to go wrong.
• If a change made things worse, say "undo that last change" and Claude walks it back. You are never one wrong move away from ruining your work.

The thing that keeps non-coders moving is realizing that being stuck is just the next message in the conversation, not a wall. You are allowed to not know why something broke. That is what Claude is for.

Where a Non-Coder Goes From Here

Once you have shipped one small thing, the path forward is simply to build the next slightly bigger thing, and the next. You do not need to become a programmer. Plenty of people build real, useful tools this way and never learn to read code in depth. The skill that compounds is describing what you want clearly and reviewing what comes back, and that skill grows every time you build.

NOTE: Claude Code Club is where non-coders learn to build alongside people doing the same thing, with a step-by-step curriculum and real builds to copy. It is 9 dollars a month at https://www.skool.com/claudecodeclub/about, and the [curriculum](/curriculum) starts from zero coding background, no terminal required.

FAQ

Can you use Claude Code without knowing how to code?

Yes. You describe what you want in plain English and Claude Code writes, runs, and fixes the code for you. Your job is to explain the goal clearly and review the result, not to write or read code yourself.

Do I need to use the terminal to use Claude Code?

No. The Claude Code desktop app lets you work entirely through a chat box. You open a folder, type what you want, and review what Claude builds. The terminal is optional and most beginners never use it.

What is the best first thing for a non-coder to build?

Something small and real you would use this week, like a one-page personal site, a simple tracker, or a script that tidies a messy folder. Shipping one working thing teaches you more than any tutorial.

What do I do when Claude Code makes something that does not work?

Describe in plain English what you expected and what actually happened, then ask Claude to fix it and explain what went wrong. You do not diagnose the problem yourself. If a change made things worse, you can ask it to undo the last change.

Do I need to install lots of developer tools before I start?

No. You need the Claude Code desktop app, a Claude account, and a small idea. Claude handles the technical setup as part of building, so you do not have to configure a developer environment first.

Will I have to learn to read code eventually?

Not necessarily. Many people build real, useful tools with Claude Code and never learn to read code in depth. The skill that compounds is describing what you want clearly and reviewing what comes back.

• What to charge for an AI audit comes down to the value of what you find, not the hours you spend. Price it as a flat fee, not hourly. A focused audit for a small business typically lands between a few hundred and a couple of thousand dollars depending on scope and the size of the business.
• Never sell the audit hourly. Hourly caps your price at your speed and punishes you for being fast. A flat fee lets you charge for the outcome, and the outcome of a good audit is a clear plan the client could not have written themselves.
• Price the audit to be an easy yes, then make the real money on what comes after. The audit is the door, not the room. Its job is to earn trust and surface the work, so the retainer or build project that follows is the natural next step.

What Should You Charge for an AI Audit?

Charge a flat fee based on the value of what you deliver, not the hours you spend. An AI audit is a focused review of where a business is losing time or money to manual work, and a clear plan for what to automate first. For a small business, a focused audit commonly sits somewhere between a few hundred and a couple of thousand dollars, scaling with the size of the business and the depth of the review. The exact number is set by the outcome, not a timesheet.

The mistake almost everyone makes is anchoring the price to how long the audit takes them. That is the wrong anchor. A client is not paying for your afternoon. They are paying for a plan they could not have produced on their own, aimed at a problem that is costing them real money every month. Price against that, and the number stops feeling awkward.

TIP: A clean rule of thumb: your audit fee should feel small next to the monthly cost of the problem you are auditing. If a business is losing many hours a week to manual work, a four-figure audit that maps the fix is an easy yes, not an expense to argue over.

Why a Flat Fee Beats an Hourly Rate

Sell the audit as one flat fee, never by the hour. Hourly pricing quietly caps your income at your own speed and punishes you for getting faster, which is exactly backwards. The better you get at spotting what to automate, the less time an audit takes, and under an hourly model that means you earn less for being more skilled. A flat fee fixes this: you charge for the result, and the result gets better as you improve.

There is also a trust cost to hourly billing on an audit. A client watching a meter feels like every question they ask makes the bill go up, so they ask fewer questions and trust you less. A flat fee removes the meter and lets the conversation be about the work. This is the same reasoning behind moving builds off hourly entirely, which the club covers in [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds).

The Door-and-Room Framework for Pricing the Audit

Price the audit as a door, not a room. Inside Claude Code Club we call this the Door-and-Room Framework: the audit is the door that earns trust and reveals the work, and the room is the retainer or build project where the real money is. When you understand that the audit is the entry point and not the whole relationship, you price it to be an easy yes rather than trying to make your entire margin on the first sale.

1. The door (the audit): priced to be an easy yes, delivering a clear written plan the client keeps whether or not they hire you for more. It stands alone as a real deliverable.
2. The threshold (the recommendation): every audit ends with a specific next step, scoped and priced, so the client sees exactly what the room costs and what they get.
3. The room (the retainer or build): the ongoing work the audit uncovered. This is where the relationship becomes profitable, and the audit is what made it possible to sell.

This framework also protects you from the trap of a client taking the plan and running. That is fine. A client who pays for the audit and implements it themselves still paid you fairly for the plan, referred you when it worked, and cost you almost nothing to serve. The audit was profitable on its own. The room is the upside, not the requirement.

How to Turn the Audit Into a Retainer

End every audit with one specific, scoped recommendation, not a menu of ten options. The client hired you precisely because they could not decide what to do first, so handing them a long list of possibilities recreates the exact problem they paid you to solve. Point at the single highest-value thing to automate, price it, and make the next step obvious.

WARNING: Do not deliver an audit as a raw list of problems. A list of problems is a bill of anxiety. A ranked plan with one clear first move is a path forward. Same findings, completely different feeling, and only one of them leads to a retainer.

When the audit points cleanly at ongoing work, the retainer sells itself because you are not pitching, you are continuing. For the mechanics of packaging that next step, the club keeps a walkthrough on [turning a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer).

Common Mistakes That Kill Audit Pricing

• Pricing by the hour, which caps your income at your speed and puts a meter on the client's trust.
• Making the audit free to win the deal, which trains the client to value your thinking at zero before the relationship even starts.
• Overbuilding the audit into a fifty-page report nobody reads, when a tight plan with one clear first move sells the next step better.
• Ending with a list of problems instead of one ranked recommendation, which leaves the client exactly as stuck as before.
• Forgetting to scope and price the next step inside the deliverable, so the natural momentum into the retainer is lost.

Avoid these five and the audit does its real job: it makes you the obvious person to hire for the work it uncovered.

Where to Learn the Full Offer

The audit is one of the cleanest first offers to sell because it is low-risk for the client, fast to deliver, and it opens the door to everything that follows. Priced as a flat fee, ended with one clear recommendation, and understood as a door rather than a room, it becomes the front end of a real agency rather than a one-off favor.

NOTE: Claude Code Club is where people building AI agencies share the exact offers, prices, and scripts that are closing right now, including the audit-to-retainer path in this post. It is 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the client-work track.

FAQ

How much should I charge for an AI audit?

Price it as a flat fee based on the value of the plan you deliver, not the hours you spend. For a small business, a focused audit commonly lands between a few hundred and a couple of thousand dollars, scaling with the size of the business and the depth of the review.

Should I charge hourly or a flat fee for an AI audit?

Charge a flat fee. Hourly caps your income at your speed, punishes you for getting faster, and puts a meter on the client's trust. A flat fee lets you charge for the outcome, which is what the client actually values.

Should an AI audit be free?

No. A free audit trains the client to value your thinking at zero before the relationship starts. Price it to be an easy yes, deliver a real plan they keep, and make the money that follows on the retainer or build it uncovers.

What should an AI audit actually deliver?

A clear written plan of where the business is losing time or money to manual work, ranked by value, ending with one specific, scoped, and priced next step. A ranked plan with a clear first move sells the next step far better than a long list of problems.

How do I turn an AI audit into a retainer?

End the audit with one specific, scoped, and priced recommendation rather than a menu of options. When the audit points cleanly at ongoing work, the retainer sells itself because you are continuing the plan, not pitching a new one.

What if the client takes the audit and does it themselves?

That is fine. They paid you fairly for the plan, they will refer you when it works, and the audit was profitable on its own. The follow-on retainer is the upside, not the requirement, which is exactly why you price the audit to stand alone.

• Connect Claude Code to Trello with Trello's own hosted MCP server at mcp.trello.com/v1. Run claude mcp add trello --transport http https://mcp.trello.com/v1, approve the browser authorization, and Claude Code can read and update your boards in the same conversation you're already building in.
• The authorization screen asks for Read, Write, and Search permissions separately. Grant Read and Search by default and only add Write once you actually want Claude Code creating or moving cards, not just reporting on what's there.
• The server ships with no delete tool at all, so even a write-enabled connection can't permanently remove a board, list, or card. The worst a bad prompt can do is make a mess you can undo, not one you can't.

How Do You Connect Claude Code to Trello?

Connect Claude Code to Trello by registering Trello's own hosted MCP server, at https://mcp.trello.com/v1, then approving the authorization in your browser the first time it runs. There's no API key to copy or token to generate by hand. Once it's connected, Claude Code can search your boards, read a card's full description and checklist, and create or update cards as part of the same conversation you're already having about a build, instead of you tabbing over to trello.com to check what's actually on the board.

NOTE: MCP servers in general are covered in [what are MCP servers, and why do they matter for Claude Code](/blog/what-are-mcp-servers-and-why-they-matter), and the club's [guide to setting up MCP servers](/guides/setting-up-mcp-servers) if this is your first one.

Step One: Register the Server

The setup is a single registration step, the same whether you build inside the Claude Code desktop app or the terminal.

1. Run claude mcp add trello --transport http https://mcp.trello.com/v1 to register the server.
2. Restart Claude Code. On first use it opens your browser to a Trello authorization screen instead of asking you for a token.
3. Approve the connection and pick which permissions to grant, then run claude mcp list to confirm trello shows up as connected.

TIP: If Claude Code can't see a board that should be there, the fix is almost always the authorization scope, not the command. Re-run the connection and check that Read (or Write, if you need it) was actually granted, not just requested.

Read, Write, Search: Pick Scopes on Purpose

Trello's authorization screen breaks permissions into three separate grants instead of one all-or-nothing toggle, and that separation is the whole safety model. Treat it the same way you'd treat a database credential: hand over exactly what the task needs, not the full set out of convenience.

Start with Read and Search only. Add Write later, deliberately, once you've watched the connection behave for a week and trust what it does with a card it's allowed to touch.

What This Is Actually Good For

The obvious use is pulling a real spec instead of retyping one. Point Claude Code at a card and it reads the description and checklist directly, the same pattern as [connecting Claude Code to Notion](/blog/connect-claude-code-to-notion) or Linear, just for boards instead of docs or tickets.

• Pull a card's full description and checklist as the spec for a build, instead of summarizing it into a prompt yourself and losing the detail buried in a comment.
• Have Claude Code move a card to Done and leave a comment with what shipped once a change is finished, so the board reflects reality without you switching tabs to update it.
• Turn a running board into a plain-language status update a client can read, useful when they check Trello and you'd otherwise be writing that summary by hand every Friday.

None of this replaces actually looking at the board yourself before a client call. It removes the manual copy-paste tax between where the task list already lives and the session where you're doing the work.

The One Thing It Still Won't Do

NOTE: Trello's MCP server doesn't include a delete tool at all, by design. A write-enabled connection can archive, move, and rewrite cards, but it cannot permanently remove a board, list, or card, no matter how the request is phrased.

That's a meaningfully different safety model than the read-only database bridge covered in [how to connect Claude Code to a database](/blog/connect-claude-code-to-a-database), where the protection lives in the credential you create. Here the protection is built into the server itself. It's a reasonable default for a task board, where the worst outcome of a bad prompt is clutter you can clean up, not data you can't get back.

Skip the Older Community Servers Now

WARNING: If you find setup instructions asking you to generate a Trello API key and token and run a community npm package, that's the older route from before Trello shipped its own server. It still works, but it means managing a long-lived token yourself instead of a scoped, revocable browser authorization. Use the official mcp.trello.com/v1 route above unless you have a specific reason not to.

When Not to Bother With It

Skip the setup if your task list already lives inside Claude Code itself, or if it's a solo project with no board to speak of. It earns its place the moment a real board is the source of truth for a project, and you'd otherwise be tabbing over to trello.com every few minutes to check what's actually assigned and what's actually done.

NOTE: Members inside Claude Code Club share the actual MCP configs and permission choices they run day to day, including which connections earned a permanent spot and which got scoped back after week one. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the structured path through MCP setup first.

FAQ

How do I connect Claude Code to Trello?

Run claude mcp add trello --transport http https://mcp.trello.com/v1, restart Claude Code, and approve the browser authorization screen the first time it runs. No API key or token generation is required with the official route.

Do I need a Trello API key and token to connect it?

No, not with the official hosted server. Trello's own MCP server at mcp.trello.com/v1 uses a browser authorization flow instead. A Trello API key and token are only needed for older, community-built Trello MCP servers.

Can Claude Code delete cards or boards once it's connected?

No. Trello's MCP server has no delete tool at all, regardless of which permissions you grant. A write-enabled connection can create, move, and update cards, but it cannot permanently remove a board, list, or card.

Which permissions should I grant when connecting Claude Code to Trello?

Grant Read and Search by default, since those cover pulling context out of boards. Only add Write once you specifically want Claude Code creating or updating cards, not just reading what's already there.

I already set up a community Trello MCP server. Should I switch?

It's worth switching to the official mcp.trello.com/v1 server when you get a chance. It's maintained directly against Trello's own product, and the browser authorization is easier to scope and revoke than a long-lived API token sitting in a config file.

• SendFeedback is a tool Claude Code can call on its own, not a command you type. When a tool keeps failing, when Claude can't finish a request after real effort, or when you tell it the last thing it did was wrong, it drafts a feedback report and opens a review form instead of just continuing.
• Nothing gets sent until you choose to send it. You can send the draft as written, edit it, attach or exclude the current transcript, or cancel outright. Transcript sharing starts turned off by default, and Claude Code remembers your last choice for next time.
• If you do attach and send the transcript, it's retained for 5 years on the same path as manual /feedback and /bug reports. On a session that touched client code or credentials, that line is worth reading before you approve the draft, not after.

What Is Claude Code's SendFeedback Tool?

SendFeedback is a tool Claude Code can invoke itself, mid-session, to draft a feedback report about what just went wrong and put it in front of you for review. It requires Claude Code v2.1.238 or later. It fires when a command or tool fails repeatedly, when Claude can't complete a request after sustained attempts, when you tell it directly that it made a mistake, or when you explicitly ask it to file a report. In every case, invoking the tool only builds a draft. It doesn't send anything on its own.

This is a genuinely different mechanism from typing /feedback or /bug yourself. Those two commands still exist and still open the standard feedback window directly, bypassing the auto-draft entirely. SendFeedback is the new piece: Claude noticing something went wrong and writing the first draft of the report for you, instead of you reconstructing what happened from memory after the session's already moved on.

What Actually Gets Sent (and What Doesn't)

When SendFeedback fires, the session pauses and an interactive review form appears. You get four real choices: send the draft as written, edit the report before sending, toggle whether the current transcript is attached, or cancel and send nothing at all. The draft itself is built from context already available in the session, not from a fresh scan of your whole machine.

Why Transcript Sharing Starts Off

Transcript sharing defaults to off on every SendFeedback draft. You have to actively turn it on for that submission, and Claude Code remembers your last choice going forward, though the setting can still be changed per submission. That default exists because a session transcript is everything that happened in the conversation, including file contents Claude read or wrote along the way.

WARNING: Once you attach a transcript and send it, whether through SendFeedback, /feedback, or /bug, it's retained for 5 years on the same path. That's not a criticism of the feature, a real transcript is genuinely useful for fixing a real bug. It's just the fact worth knowing before you toggle it on, not after.

The Off-by-Default Check We Use on Client Work

Inside the club we call this the Off-by-Default Check, and it's three questions, not a policy document. Run it in the ten seconds you already have while the review form is sitting on screen.

1. Glance at what's actually in view before you toggle the transcript on: client API keys, real customer data, or anything under an NDA you signed changes the answer.
2. Default to sending the written draft alone. It's usually enough for a real product issue to get acted on, and it carries none of the session's raw content.
3. If the bug genuinely needs the full transcript to reproduce, say so, attach it deliberately, and treat that choice the same way you'd treat pasting a client's code into any third-party tool.

This isn't about distrust of the feature. It's the same instinct as reviewing a diff before you ship it, covered in [how I review Claude Code's output before I ship it](/blog/review-claude-code-output-before-you-ship): a review step only works if you actually use it instead of clicking through on autopilot.

When It's Actually Worth Sending

Send it when something genuinely broke and kept breaking, not every time Claude Code gets a little slow or a prompt needs rewording. A tool that fails the same way three times in a row, or a request that dies after real effort, is exactly the kind of thing a feedback report is meant to catch, and reporting it is how a rough edge actually gets fixed instead of just worked around by everyone who hits it.

Where This Works (and Where It Doesn't)

SendFeedback works in the interactive Claude Code app, the terminal, and Claude Code on the web, anywhere a human is actually present to see the review form and make a choice. It is not available through the Claude Agent SDK, which makes sense: a programmatic session running unattended has no one there to click send, so there's no draft-and-review step to offer.

NOTE: Members inside Claude Code Club compare notes on which new Claude Code features are actually worth turning on for client work versus which ones need a second look first, the same way we did with this one. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the workflow track first.

FAQ

What is SendFeedback in Claude Code?

SendFeedback is a tool Claude Code can call on its own when a command keeps failing, a request can't be completed, or you say it made a mistake. It drafts a feedback report and opens a review form. It requires Claude Code v2.1.238 or later.

Does Claude Code send my code automatically when something fails?

No. SendFeedback only builds a draft and opens a review form. Nothing is sent until you choose to send it, and you can edit the draft or cancel it entirely before that happens.

Is transcript sharing turned on by default with SendFeedback?

No, it starts off by default on every draft. You have to actively enable it for that submission. Claude Code remembers your last choice for future reports, but you can change it each time.

How long does Anthropic keep a submitted transcript?

Transcripts shared through SendFeedback, /feedback, or /bug are retained for 5 years, since all three report through the same submission path.

What's the difference between SendFeedback and typing /feedback myself?

/feedback with text, and /bug, open the standard feedback window directly with no draft step. SendFeedback is Claude noticing a problem mid-session and writing the first draft of that report for you to review, rather than you typing one from a cold start after the fact.

Does SendFeedback work with the Claude Agent SDK?

No. It's available in the interactive Claude Code app, the terminal, and Claude Code on the web, but not through the Agent SDK, since an unattended programmatic session has no one present to review the draft before it's sent.

• Run `claude mcp add atlassian --transport http https://mcp.atlassian.com/v1/mcp/authv2`, approve the OAuth prompt in your browser, and Claude Code can read and update Jira tickets directly from the desktop app or the CLI.
• The same server also covers Confluence, Bitbucket, Jira Service Management, and Compass, so it's one connection for the whole Atlassian side of a project.
• OAuth is the default and works for most people. If you're on a shared or headless machine, or you keep getting logged out, an API token is the steadier fallback - covered below.

How Do You Connect Claude Code to Jira?

Atlassian built and runs an official remote MCP server for Jira, Confluence, Bitbucket, and the rest of its suite, so you're not relying on a third-party integration to keep it working. It follows the same pattern as every other official server Claude Code supports - see [what MCP servers are and why they matter](/blog/what-are-mcp-servers-and-why-they-matter) if you haven't connected one before, or [the general setup guide](/guides/setting-up-mcp-servers) for the mechanics that apply across all of them.

Once it's connected, Claude Code can pull a ticket's full description and comment history before it starts work, search a project by component or label, and update status or leave a comment when a task is done - all without you switching tabs to copy context back and forth.

Step One: Register the Server

1. Open a terminal (or the desktop app's built-in terminal panel) and run: claude mcp add atlassian --transport http https://mcp.atlassian.com/v1/mcp/authv2
2. Claude Code opens your default browser to Atlassian's login. Sign in and approve the connection - you'll pick which site (and, on some plans, which projects) it can access.
3. Back in Claude Code, run claude mcp list to confirm "atlassian" shows as connected, or claude mcp get atlassian for the full connection detail.

TIP: If the add command errors out immediately, update the Claude Code CLI first (claude update) - remote MCP support landed in a specific release, and an older build won't recognize the --transport http flag.

Browser OAuth vs an API Token

OAuth is the default path and it's the one most people should use - you approve access once in the browser and Claude Code handles the session from there. It's scoped to whatever you approve, so a personal machine only exposes what you personally have access to.

An API token is the alternative, and it needs to be turned on by an Atlassian admin under Administration settings before it'll work. It's worth the extra setup step on a shared or headless machine where a browser popup isn't practical, or as the fallback described below.

What This Is Actually Good For

• Reading the full ticket - description, comments, linked issues - before you touch a line of code, so Claude Code starts with the same context you'd have if you'd read it yourself.
• Searching a project by component or label before scoping a sprint, instead of scrolling a board by hand.
• Transitioning a ticket's status and leaving a comment when work is done, so the tracker stays current without a separate manual step.

That last one is worth treating carefully - see [reviewing Claude Code's output before you ship](/blog/review-claude-code-output-before-you-ship) for why an agent marking its own ticket done isn't the same as it actually being done.

The One Reliability Quirk to Know About

WARNING: Users in Atlassian's own community forums have reported the OAuth connection to this MCP server needing frequent re-authentication - sometimes as often as every session. Atlassian has acknowledged the reports. If you hit this, the API token path above is the more stable fallback until it's resolved.

This isn't a dealbreaker, it's a known rough edge. If you're setting this up for daily use rather than an occasional check-in, it's worth testing the token path from day one instead of discovering the OAuth quirk mid-project.

It's Not Just Jira

The same server also covers Confluence, Bitbucket, Jira Service Management, and Compass. One connection, one OAuth approval, and Claude Code can pull a Confluence page for context while it works a linked Jira ticket - that's the actual point of running it as a single server instead of four separate integrations.

When Not to Bother With It

If you're working solo on a project with no tracker, or Jira is just where tickets go to be forgotten, skip this. It earns its keep once a project has real ticket history worth reading and a status that other people actually check.

NOTE: Inside Claude Code Club we walk through the full MCP setup live, including which servers are worth connecting first for your specific stack. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum).

FAQ

How do I connect Claude Code to Jira?

Run claude mcp add atlassian --transport http https://mcp.atlassian.com/v1/mcp/authv2, approve the OAuth prompt in your browser, then confirm with claude mcp list. It's Atlassian's own official server, covering Jira along with Confluence, Bitbucket, and the rest of the suite.

Should I use OAuth or an API token to connect?

OAuth is the default and works for most people - approve it once in the browser. An API token, enabled by an Atlassian admin, is the better choice for a shared or headless machine, or if you hit the OAuth re-authentication quirk covered above.

Can Claude Code see my whole Jira site once it's connected?

Only what you approve during the OAuth flow - the site and projects you grant access to, not every project in your organization. An admin can further restrict access by permission group on their end.

Why does Claude Code keep asking me to log into Jira again?

This is a known reliability quirk with the OAuth connection that Atlassian has acknowledged in its own community forums. If it's happening often, switch to the API token path, which an Atlassian admin can enable under Administration settings.

Does this also work with Confluence and Bitbucket?

Yes. It's a single Atlassian MCP server that covers Jira, Confluence, Bitbucket, Jira Service Management, and Compass - one connection instead of four separate ones.

• On September 14, 2026, Anthropic replaces the temporary +50% weekly capacity boost on Claude Code with a smaller, permanent +25% increase over the original pre-boost baseline - a roughly 17% drop from what you're using today.
• Both numbers are true because they measure from different starting points. Only the weekly limit changes - the 5-hour rolling limit, API customers, and consumption-based Enterprise plans aren't touched.
• If you've scoped or priced work assuming today's boosted capacity, September 14 is the date that assumption stops holding.

What's Actually Changing on September 14

Since May 2026, Anthropic has run a temporary +50% capacity boost on Claude Code's weekly usage limits for Pro, Max, Team, and seat-based Enterprise plans. On September 14, 2026, that temporary boost goes away and is replaced by a permanent increase of +25% over the original pre-boost baseline - not over today's boosted level. Anthropic hasn't published the underlying token numbers, only this indexed change, so treat the percentages as relative, not absolute.

This applies to the weekly window specifically. The separate 5-hour rolling rate limit is untouched, free plans aren't part of this change, and API customers and consumption-based Enterprise plans were never on the boosted number in the first place.

Why Both Numbers Are True

150 down to 125 is a real cut from where things stand right now, and 125 up from 100 is a real permanent gain over where things stood before May. Both framings get repeated online because both are correct - they're just measuring from different starting lines. The one that matters for your planning is the first one: 125 is less than what you have today.

What This Actually Means If You Bill Around Claude Code Capacity

• A build that comfortably fits inside one weekly cycle at the boosted level might spill into a second week once the standard level takes effect - same scope, less room to run it in.
• A retainer sized around "however much I need this week" gets quietly more expensive to deliver once the ceiling drops, even though nothing about the client relationship changed.
• The desktop app and the CLI on the same account draw from one shared weekly allowance, not separate budgets per tool - so a client-facing agent running in the background counts against the same number as your own hands-on work.

The Capacity Buffer: What I'm Doing to Every Proposal This Month

Inside the club we call this the Capacity Buffer: price and schedule against roughly 80% of your weekly allowance, never the full ceiling. It's the same logic as never quoting a client your absolute fastest possible timeline - you leave room for the number to move against you before it actually does.

1. Re-check any proposal priced in the last month against the boosted assumption - if the math only worked at 150, it needs a second look before September 14.
2. Front-load the heaviest, most token-hungry work into the first week of a project cycle, while there's still more room to absorb a heavy day.
3. Tell the client plainly when a deadline depends on shrinking capacity rather than quietly absorbing the risk yourself and hoping it doesn't show up in the timeline.

WARNING: Don't find out you've hit the new ceiling mid-sprint on a client deadline. Test your actual weekly usage pattern against the 125-index level before September 14, not after.

When This Doesn't Change Anything for You

If you're a light or moderate user who's never come close to hitting the weekly limit, this change is background noise, not action. See [Claude Code usage limits and what to do about them](/blog/claude-code-usage-limits-what-to-do) for the general playbook, and [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project) or [how to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project) for the pricing and scoping fundamentals this builds on.

NOTE: Inside Claude Code Club we track changes like this the day they're announced and adjust the pricing playbook together. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the pricing and contracts track first.

FAQ

What is the Claude Code weekly limit change on September 14, 2026?

Anthropic's temporary +50% capacity boost on weekly usage limits, running since May 2026, is replaced by a smaller permanent +25% increase over the original pre-boost baseline - about a 17% reduction from today's boosted level.

Why do I see both +25% and -17% describing the same change?

They measure from different starting points. +25% is measured against the original pre-boost baseline from before May 2026. -17% is measured against the temporary boosted level most active users are on right now. Both are accurate.

Does this affect the 5-hour Claude Code rate limit?

No. This change is specific to the weekly usage window. The separate 5-hour rolling rate limit is not affected.

Does this affect API customers or Enterprise consumption plans?

No. It applies to Pro, Max, Team, and seat-based Enterprise plans. API customers and consumption-based Enterprise plans were never on the temporary boosted number and aren't part of this change.

How should I price client work around this change?

Use what we call the Capacity Buffer - price and schedule against roughly 80% of your weekly allowance rather than the full ceiling, front-load token-heavy work early in a cycle, and tell clients directly when a deadline depends on shrinking capacity.

• Connect Claude Code to GitHub with GitHub's own official remote MCP server at api.githubcopilot.com/mcp. Generate a GitHub personal access token scoped to the repos you need, then run claude mcp add-json github with that token in the header to register it.
• Unlike Slack, Notion, and Linear, GitHub's remote server doesn't yet support one-click browser OAuth inside Claude Code, so a scoped token is the standard route for both the desktop app and the CLI, not a fallback for one over the other.
• Once it's connected, Claude Code can read a repo, browse issues and pull requests, check CI run status, and open or update issues and PRs directly from a session, instead of you tabbing over to github.com to paste context back and forth.

How Do You Connect Claude Code to GitHub?

Connect Claude Code to GitHub by registering GitHub's own official remote MCP server, hosted at api.githubcopilot.com/mcp, using a GitHub personal access token for authentication. Generate a fine-grained token scoped to the specific repos you're working in, then run one command to register it: claude mcp add-json github with the token passed as a Bearer header. That's the whole setup, and it works the same way whether you're building inside the Claude Code desktop app or the CLI.

Once it's connected, Claude Code can read a repository's files and structure, search and browse open issues and pull requests, check the status of CI runs, and open or update issues and PRs as part of the same conversation you're already having about a build. It's a server GitHub built and runs themselves against their own API, the same pattern as [connecting Claude Code to Linear](/blog/connect-claude-code-to-linear) or Notion, not a community package reverse-engineered against endpoints that can change without notice.

NOTE: MCP servers in general are covered in [what are MCP servers, and why do they matter for Claude Code](/blog/what-are-mcp-servers-and-why-they-matter), and the club's [guide to setting up MCP servers](/guides/setting-up-mcp-servers) if this is your first one.

Step One: Generate a Scoped Token, Not an All-Repo One

GitHub's remote server authenticates with a personal access token rather than a full browser OAuth login, so this step happens before you touch Claude Code at all. Go to github.com/settings/personal-access-tokens/new and create a fine-grained token, not a classic one. Fine-grained tokens let you pick exactly which repositories the token can see and exactly which permissions it has inside them, instead of handing over blanket access to everything in your account.

1. Under Repository access, select Only select repositories and pick the ones you're actually building against, not every repo in the account.
2. Under Permissions, grant Contents (read or read/write, depending on whether you want Claude Code opening PRs), Issues, and Pull requests. Skip anything you don't have a concrete reason to hand over.
3. Set an expiration. A token that never expires is a liability sitting in your config months after the project that needed it wrapped up.

This is the same instinct as the Linear API key's read-only option, applied one step earlier: the access decision happens when you generate the token, not as a separate setting inside Claude Code. A token scoped to two repos with read and issue access can't reach a third repo or push a commit, no matter what you ask it to do.

Step Two: Register the Server

With the token copied, register the server from a terminal window, the same one-time step whether you build inside the desktop app or the CLI day to day.

1. Run claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' with your real token in place of YOUR_GITHUB_PAT.
2. Restart Claude Code so it picks up the new server.
3. Run claude mcp list to confirm github shows up, or claude mcp get github for the full detail.

TIP: On an older Claude Code version, add-json can return an Invalid input error, and on Windows it sometimes fails outright. If that happens, use the older syntax instead: claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT". Both register the exact same server.

Don't hardcode the token into a file you might commit. Store it in a .env file, add that file to .gitignore, and reference it as an environment variable when you run the command, the same habit covered in [Claude Code environment variables: how to keep your API keys safe](/blog/claude-code-environment-variables).

What This Is Actually Good For

The obvious use is starting work from the real issue instead of retyping it, the same pattern as the Linear connection, but with the added value of GitHub also being where the code and the CI results already live. Claude Code can read an issue, look at the actual file it references, check whether the last CI run on a branch is green, and open a pull request when the change is ready, all without you narrating any of that context by hand.

• Pull an issue's full description and comments as context before you start a change, instead of summarizing it into a prompt yourself and losing detail.
• Ask Claude Code to check whether a specific pull request's CI checks passed before you tell a client it's ready, rather than clicking through to the Actions tab yourself.
• Have Claude Code open a pull request with a real description once a change is done, instead of you writing the PR summary from a cold start after the session ends.

It doesn't replace reviewing the diff yourself before you merge anything, that habit is covered in [how I review Claude Code's output before I ship it](/blog/review-claude-code-output-before-you-ship). What it removes is the manual copy-paste tax between where the issue, the code, and the CI status already live and the session where you're actually building.

Desktop App Users: The One Thing to Know

Slack, Notion, and Linear's hosted MCP servers all support a one-click browser OAuth login the first time you connect, no token to generate. GitHub's remote server doesn't offer that yet inside Claude Code, in the desktop app or the CLI, which is why a personal access token is the standard route here rather than a fallback for people who'd rather skip the browser flow.

If you'd rather log in with your GitHub account instead of managing a token, GitHub also ships a local version of the server that runs through Docker and supports a real OAuth browser login on first use. It's a heavier setup, since it needs Docker installed and running, so I'd only reach for it if avoiding a token specifically matters to you, most builders are fine with the scoped token above.

Skip the Old Community Package

WARNING: If you find setup instructions referencing an npm package called @modelcontextprotocol/server-github, skip them. That community package has been deprecated since April 2025 in favor of GitHub's own official server. Use the api.githubcopilot.com/mcp route above instead.

When Not to Bother With It

Skip the setup for a throwaway script or a repo you're not going back to. It earns its place the moment there's a real, actively-updated repo on the other end, open issues, a review process, CI checks that actually gate a merge, the kind of project where you'd otherwise be tabbing over to github.com every few minutes anyway.

NOTE: Members inside Claude Code Club share the actual token scopes and MCP configs they run day to day, including which ones earned a permanent spot and which didn't survive the first week. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the structured path through MCP setup first.

FAQ

How do I connect Claude Code to GitHub?

Generate a fine-grained GitHub personal access token scoped to the repos you need, then register GitHub's official remote MCP server with claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'. Restart Claude Code and run claude mcp list to confirm it's connected.

Do I need a GitHub personal access token, or can I just log in with OAuth?

You need a token for the remote server. Unlike Slack, Notion, and Linear, GitHub's remote MCP connection doesn't yet support a one-click browser OAuth login inside Claude Code. A local Docker-based version of the server does support OAuth login instead, but it's a heavier setup most builders don't need.

Can Claude Code see every repo in my GitHub account once it's connected?

Only if you scope the token that way, which you shouldn't. A fine-grained personal access token lets you pick exactly which repositories it can see and exactly which permissions it has in each one, so the real access decision happens when you generate the token, not as a separate setting afterward.

Can Claude Code open pull requests, or is it read-only?

It can do both, depending on the permissions you granted the token. With Contents and Pull requests write access, Claude Code can open and update PRs directly. Grant read-only permissions instead if you want it limited to reading issues, code, and CI status.

What if claude mcp add-json fails or returns an error?

On older Claude Code versions or on Windows, add-json can fail with an Invalid input error. Use the legacy syntax instead: claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Authorization: Bearer YOUR_GITHUB_PAT". It registers the identical server.

• Two structured rounds of revisions, built into the price and defined narrowly as fixing what doesn't match agreed scope. Anything past that, or anything that's a new request rather than a fix, gets priced separately.
• Unlimited revisions isn't generosity, it removes the client's reason to give you clear, bundled feedback the first time, and it quietly turns an afternoon build into a month of small edits with no natural end point.
• Put the number in the proposal before the project starts, not as a rule you invoke mid-project when someone's on their sixth round. Stated upfront it reads as normal. Invoked mid-project it reads as a fight.

The Number I Actually Use

Two rounds of revisions, included in the price, defined as fixing anything that doesn't match what was scoped. Round one happens after the first delivery. Round two happens after I've made those changes. After that, anything further is a new, priced request, not a continuation of the same invoice.

That's not a rule I invented to protect my time in the abstract, it's the fix for a specific failure mode Claude Code makes worse, not better. A build that used to take a week now takes an afternoon, which means the temptation to treat every follow-up message as a free, instant re-generation is stronger than it ever was with slower tools. Two structured rounds keeps that speed from quietly becoming an open-ended queue.

Why Unlimited Revisions Is a Trap, Not a Selling Point

Unlimited revisions sounds like a strong offer on a proposal, and it costs you almost nothing to type. What it actually does is remove the client's only incentive to give you clear, complete feedback in one pass. If round three is free and round four is free too, there's no reason not to send a one-line note today and another one tomorrow, each one restarting your context and stretching a project that should have closed weeks ago.

WARNING: The projects that ran longest for me weren't the ones with the most revisions, they were the ones with unlimited revisions and no structure. A capped number with a real deadline attached forces feedback to arrive as one considered pass instead of a drip.

What Counts as a Revision vs a New Request

This is the line that actually matters, more than the number itself. A revision fixes something that doesn't match what you agreed to build. A new request is a change of mind, a new feature, or a different direction than what was scoped. Confusing the two is where free revisions quietly turn into free scope expansion.

Say this distinction out loud the first time a request lands in the second column, don't just quietly absorb it. Most clients aren't trying to sneak in free work, they genuinely don't know where the line is until you draw it. Naming it once, calmly, usually settles the question for the rest of the project.

Bundle Feedback Into One Pass Per Round

A round isn't a round if it arrives as five separate messages over three days. When I deliver a build, I ask for every piece of feedback in one message before I touch anything again, that's what makes a round countable and closeable. Feedback that trickles in one line at a time doesn't just cost more of your time, it makes it genuinely harder to tell when a round has actually ended.

Set a short window for that one bundled pass, three to five business days is typical, and say plainly that revisions submitted after the window starts the next round instead. That keeps a client's slow reply from stretching your own timeline indefinitely, and it gives both sides a clear moment where the project is either done or explicitly moving to another round.

Put It in Writing, Not Just in the Kickoff Call

This is what we call the Change Line inside the club: the exact sentence in your contract that states the revision count and turns any new request into a priced change instead of an argument. See [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) for where it sits alongside the rest of the six-clause baseline, and [how to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects) for what to do once a request clearly crosses the line.

A verbal mention on the kickoff call doesn't hold up three weeks later when a client genuinely doesn't remember agreeing to a cap. Put the number in the proposal and in the contract, in the same plain language you'd use talking to them directly, not buried in legal boilerplate they skimmed past.

How to Say It Without Sounding Petty

State it once, plainly, as a normal part of how every project runs, not as a condition you're specially imposing on this client. I write some version of: this includes two rounds of revisions on the agreed scope, submitted as one bundled pass within five business days of delivery. Anything beyond that, or anything outside the original scope, is billed at my standard rate. No apology, no hedge.

NOTE: Inside Claude Code Club we share the actual Change Line wording members use in proposals and contracts, including how it's held up when a client pushed on it. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the pricing and contracts track first.

FAQ

How many revisions should I include in a client project?

Two structured rounds, built into the price and defined as fixing anything that doesn't match agreed scope. Anything past that, or anything that's a new request rather than a fix to existing scope, gets priced as a separate change.

What's the difference between a revision and a new request?

A revision fixes something that doesn't match what was already scoped, a color that's off-brand, a feature that doesn't behave as described. A new request is a change of mind, a new feature, or a different direction than what was agreed, and it should be priced separately rather than absorbed into a revision round.

Should I offer unlimited revisions to win a client?

No. Unlimited revisions removes the client's incentive to give clear, bundled feedback up front, since there's no cost to sending another small note tomorrow. A capped number with a real deadline attached almost always finishes faster and cleaner than an unlimited offer does.

How do I charge for revisions beyond what's included?

Price them the same way you'd price any new scope, at your standard rate, stated in the same contract clause that sets the included revision count. Naming the number and the rate upfront, before the project starts, is what keeps this from turning into a negotiation mid-project.

• Connect Claude Code to Linear with Linear's own hosted MCP server. Run claude mcp add --transport http linear https://mcp.linear.app/mcp once, approve the browser OAuth flow, and Claude Code can then read issues, projects, and comments, and create or update them, as part of a normal build conversation.
• No API key is required for the hosted route. If you want a narrower, read-only connection instead, generate a Linear API key with only the Read permission enabled and use a local server against that key instead of the OAuth flow.
• The MCP connection inherits your own Linear permissions exactly. It can't see a team or workspace you can't see yourself, so the real scope decision is which teams your Linear account already has access to, not a separate setting inside Claude Code.

What the Linear MCP Server Actually Gives Claude Code

Connect Claude Code to Linear by adding Linear's own hosted MCP server, at https://mcp.linear.app/mcp, and authenticating once through your browser. Once it's connected, Claude Code can search your Linear workspace, pull an issue's full description and comment history as context, and create or update issues, change status, assign people, and leave comments, all from inside the same session where you're already building.

This is a server Linear built and runs themselves, not a community package reverse-engineered against their API. That matters the same way it did for [connecting Claude Code to Notion](/blog/connect-claude-code-to-notion): it's maintained against Linear's actual product, so it keeps working when Linear ships changes instead of quietly breaking. Community alternatives exist too, but the hosted route is the one I'd default to unless you have a specific reason not to.

NOTE: MCP servers in general are covered in [what are MCP servers, and why do they matter for Claude Code](/blog/what-are-mcp-servers-and-why-they-matter), and the club's [guide to setting up MCP servers](/guides/setting-up-mcp-servers) if this is your first one.

How to Connect It

The hosted route is the fastest, and it's the one Linear documents as the default.

1. In Claude Code, run claude mcp add --transport http linear https://mcp.linear.app/mcp to register the server.
2. On first use, Claude Code opens your browser for a Linear OAuth login. Approve it, and the connection is live for that machine going forward, no API key to generate or store.
3. Run /mcp inside a Claude Code session to confirm the connection completed and see which Linear tools are now available.

If you'd rather run a narrower, read-only connection, Linear lets you generate an API key with only the Read permission enabled, then point a local MCP server at that key instead of using the hosted OAuth route. That trade gives up write access, so Claude Code can pull issue context but can't create or update anything on your behalf, which is the right call for a shared machine or a client-facing workspace you'd rather not risk.

What This Is Actually Good For: the Ticket-to-Diff Loop

The obvious use is starting a build from the ticket instead of retyping it. Point Claude Code at a Linear issue and it reads the real description and every comment, including the back-and-forth a client or teammate already had about scope, instead of you summarizing that thread into a prompt by hand and losing detail on the way.

I run this as a loop, and inside the club we just call it the Ticket-to-Diff loop: pull the issue, build against exactly what it says, then push the result back into the same issue instead of leaving it stranded in your terminal history. It sounds small, but it's the difference between Linear being a to-do list you check before you code and Linear being the actual system of record for what happened.

• Pull an issue's description and comments as context before scoping a change, so you're building against what the team actually agreed to, not your memory of a standup.
• Move an issue to In Progress when a build session starts and back to a review status when it's ready, so status in Linear matches reality without a separate update.
• Leave a comment with what changed and why, in the same voice you'd use if you'd typed it yourself, so a teammate or client reading the ticket later gets the real story.

TIP: Ask Claude Code to summarize an issue's comment thread before you commit to a scope, especially on an older ticket with a long back-and-forth. It's a faster way to catch a decision that got buried on comment forty than scrolling the thread yourself.

Scope It to What Your Own Account Can Already See

Linear's MCP connection doesn't have its own permission model separate from you. It authenticates as your Linear account and inherits exactly what you can already see and edit, team by team. If you can't access a team in Linear's own interface, Claude Code can't reach it through the connection either, and if you can, it can, so the real access-control decision already happened when your workspace admin set up your account.

That makes the scope conversation different from Notion's page-by-page sharing model: there's no separate list of what's shared with the integration to review. Workspace admins can still restrict MCP access at the org level with allowlists if that's a concern, but for most solo builders and small agency teams, the thing to actually check is whether your own Linear seat has access to more teams than the client work in front of you needs.

When Not to Bother With It

Skip it for a one-off build with no Linear presence, or a client who tracks work in a spreadsheet or a shared doc instead. It earns its place once there's a real, actively-updated issue tracker on the other end, where skipping the connection means you'd be retyping ticket context into a prompt every session anyway.

NOTE: Members inside Claude Code Club share the actual MCP configs they run, including the ones that earned a permanent spot in their setup and the ones that didn't survive the first week, at https://www.skool.com/claudecodeclub/about. It's $9 a month, or start with the [curriculum](/curriculum) for the structured path through MCP setup first.

FAQ

How do I connect Claude Code to Linear?

Add Linear's official hosted MCP server with claude mcp add --transport http linear https://mcp.linear.app/mcp, then approve the browser OAuth flow that opens on first use. Run /mcp inside a session to confirm the connection and see the available tools.

Do I need a Linear API key to connect Claude Code?

Not for the hosted route, it authenticates through browser OAuth instead. You'd only generate an API key if you want a narrower, read-only connection, in which case Linear lets you create a key with only the Read permission enabled.

Can Claude Code see my entire Linear workspace once connected?

It can see whatever your own Linear account can already see, team by team, no more and no less. The connection inherits your existing permissions rather than getting a separate grant, so a team you can't access in Linear's own interface stays inaccessible through Claude Code too.

Can Claude Code create and update Linear issues, or is it read-only?

The hosted OAuth connection can do both by default, it can read issues and comments and also create issues, update status, assign people, and comment. If you want read-only instead, use a Linear API key with only the Read permission enabled rather than the full OAuth route.

• For a new client, charge 50% upfront before you open Claude Code. That's the standard range freelancers across every service industry converge on, and there's nothing about AI work that makes you the exception.
• For a larger project, split it into thirds instead of one deposit: a third at signing, a third at a build milestone, a third at delivery, so no single payment is carrying the whole risk of the project stalling out.
• The deposit isn't really about cash flow. It's a filter. A client who balks at putting money behind their own project before you've spent a single hour on it was never going to be an easy client to collect the rest from either.

The Range I Actually Charge

For a new client and a project under a few thousand dollars, I charge 50% before I open Claude Code. That's not an aggressive number, it's the standard range that freelancers across every service industry, not just AI builds, land on when you ask them directly: 25% to 50% upfront, with 50% being the common default for smaller projects and new relationships where you have no payment history to lean on yet.

The AI part of the project doesn't change this math. If anything it argues for the higher end of the range, not the lower one: a Claude Code build moves fast once scope is locked, which means your exposure to unpaid work happens in the first few days, not spread out over a slow six-week timeline where you'd notice a payment problem before you'd sunk much time in.

The Deposit Ladder: When to Split It Into Thirds

A flat 50% deposit works until a project gets big enough that the other 50% due on delivery becomes its own risk, the client stops responding after your build is 90% done and you're chasing a large final invoice with no leverage left. Past a certain size, I stop using one deposit and switch to what I call the deposit ladder: a third at signing, a third at a build milestone we agree on up front, and a third at delivery.

The middle milestone in the ladder isn't arbitrary, tie it to something real: a working prototype, the core feature built, a staging link they can click. That gives the client a checkpoint to confirm the project is actually moving, and it gives you a natural moment to collect before you're carrying the full cost of a build that's most of the way done.

What the Deposit Is Actually Protecting

Cash flow is the reason people usually give for a deposit, and it's real, but it's not the main reason I hold the line on it. A deposit is a filter you run before you've spent a single hour on the project. A client who's genuinely ready to work with you pays it without much friction, because they already believe the project is worth doing. A client who pushes back hard on a standard deposit, especially on a small project where 50% isn't a large number, is telling you something about how the rest of the relationship is going to go.

NOTE: I've had exactly one project where a client's deposit pushback turned out to be nothing, a real cash timing issue on their end that they explained clearly and we worked around. Every other time I've heard serious resistance to a standard deposit, it predicted exactly the kind of payment chase I was trying to avoid by charging one in the first place.

How to Ask for It Without It Feeling Awkward

State it once, plainly, as a normal part of how you work, not as a special condition you're imposing on this particular client. I say some version of: I require 50% to start and 50% at delivery, invoice goes out with the proposal, and I begin the build once the first half clears. No apology, no hedge, no over-explaining why. The clients who are going to be fine with it hear a normal business term. The ones who aren't will surface that now, at the cheapest possible point in the relationship, instead of later.

Put the number in writing before you start, not as a verbal agreement you're trusting them to remember. See [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) for where the deposit terms sit alongside the rest of what belongs in there, and [paid discovery: how to charge for scoping an AI build](/blog/paid-discovery-phase-ai-projects) if the project needs a scoping phase before you're even ready to quote a deposit at all.

One Exception: Don't Deposit-Gate a Repeat Client

The deposit is answering a question, will this client actually pay me, and a repeat client already answered it the last time they paid your invoice on time. Requiring the same 50% upfront from someone who's paid you cleanly on three prior projects reads as either forgetting who you're talking to or not trusting them, neither of which is the message you want to send to your best clients. Drop to a smaller deposit, net-15 terms, or nothing upfront at all once the relationship has actual payment history behind it, and save the full deposit for where it's still doing real work: new clients and one-off projects.

NOTE: Inside Claude Code Club we share the actual proposal language and invoice terms members use for the deposit conversation, including what changed once a client became a repeat one. Join for 9 dollars a month at https://www.skool.com/claudecodeclub/about, or start with the [curriculum](/curriculum) for the pricing track first.

FAQ

How much deposit should I charge for an AI project?

50% upfront for a new client on a smaller project is the standard I'd default to, in line with the 25-50% range freelancers across service industries generally charge. For larger, multi-week builds, split it into thirds instead: a third at signing, a third at a build milestone, a third at delivery.

Should I charge a deposit for a repeat client?

Not the full amount, and often not at all. A deposit exists to answer whether a client will actually pay you, and a client with a clean payment history from prior projects has already answered that. Drop to a smaller deposit or net terms once you have real history with them.

What if a client refuses to pay a deposit?

Treat it as information, not just an obstacle to negotiate past. A client who pushes back hard on a standard deposit before you've done any work is often signaling how the rest of the payment relationship will go. It's worth asking why directly, a real cash-timing reason is different from general resistance to paying anything upfront.

Should I charge more deposit for a rush project?

Yes. A rush turnaround means you're compressing or turning away other work to fit the client in, so price that risk into the deposit, 50-100% at signing is standard for rush work regardless of the project's overall size.

• As of August 14, 2026, Claude Code runs in auto mode by default for Pro, Max, and Team plans that haven't pinned a different mode. Instead of a permission prompt before every edit or command, tool calls route through a safety classifier that blocks anything irreversible, destructive, or aimed outside your project.
• Anthropic's own testing is the reason for the switch: in a controlled study with 1,053 paid testers, humans caught only 13.6% of dangerous commands slipped into a session, while the auto mode classifier caught 89% of the same commands.
• You can still switch modes any time. Press Shift+Tab in the CLI or use the mode dropdown in the desktop app for one session, or pin a personal default, use the disableAutoMode setting, or set an org-wide defaultMode in managed settings if you never want it on.

What Auto Mode Default Actually Means

As of August 14, 2026, Claude Code runs in auto mode by default for every Pro, Max, and Team plan that hasn't pinned a different mode. Instead of stopping to ask permission before each file edit or terminal command, every tool call now routes through a safety classifier that blocks anything irreversible, destructive, or aimed outside your project environment. If you had already set your own default mode before the change, nothing shifts for you. If you're on Claude Enterprise or accessing Claude Code through the API, auto mode stays opt-in for now, with the same default flip planned for the following month.

Auto mode itself isn't new, we covered how it works when it launched as an opt-in feature in [how Claude Code auto mode runs tasks on its own](/blog/claude-code-auto-mode-runs-on-its-own). What changed on August 14 is who gets it without asking, and the data Anthropic is showing to justify making it the default instead of a setting most people never touch.

NOTE: One practical detail worth knowing: Anthropic stopped charging Pro, Max, and Team users for the classifier's extra token overhead effective the same day it went default. The safety check doesn't quietly eat into your usage limits.

Why Anthropic Flipped the Default: the Safety Data

The case for the switch isn't that auto mode is flawless. It's that manual permission review, in practice, is worse than most people assume. Anthropic hired 1,053 paid testers through a research vendor for a coding study, then swapped a single permission prompt mid-session for a clearly dangerous command to see who caught it. The testers caught it 13.6% of the time (143 of 1,053). Auto mode blocked 89% of the same command (937 of 1,053). Head to head, auto mode blocked 800 commands a human tester had approved, and humans blocked only 6 that auto mode allowed.

That last row explains the reflex problem. People approve 97% of individual permission prompts, but reject 39% of plan-mode proposals, the same people who scrutinize a plan will click through a permission dialog without reading it, because dozens of prompts a day is fatigue, not judgment. In a review of flagged real-world sessions from May to June 2026, manually approved sessions contained serious unintended harm at production severity more than twice as often as auto mode sessions. The full data set, including the third-party red-teaming and prompt-injection testing, is in [Anthropic's own writeup](https://claude.com/blog/auto-mode-default-in-claude-code) if you want the source numbers directly.

What the Classifier Still Refuses to Do

Auto mode isn't unlimited autonomy. It has hard denies it won't cross regardless of what you or Claude ask for, and a fallback that hands control straight back to you when it gets stuck.

• Data exfiltration is a hard deny. Sending your code or secrets to an external destination can't be approved from inside auto mode at all, you'd have to switch modes or run that command yourself.
• Destructive git commands get a git-status check first. Before something like git reset --hard, the classifier looks at your actual repository state so it knows what would be lost.
• Three blocked actions in a row, or twenty across one session, and Claude Code drops back to manual approval automatically. It doesn't keep retrying against a wall.
• Content pulled from outside your project, web pages, tool output, file contents, gets screened for hidden instructions before it reaches your context, an extra layer against prompt injection.

How to Turn It Off or Set a Different Default

Two switches exist, one for right now and one that sticks. Press Shift+Tab in the CLI to cycle modes mid-session, or use the mode dropdown in the desktop app if you're not touching a terminal. Either one changes the current session instantly.

• For a personal permanent default: pin your own mode. Once you've set one yourself, the August 14 change doesn't touch you going forward.
• To turn auto mode off entirely: use the disableAutoMode setting.
• For a team or org-wide default: admins pin defaultMode in managed settings, which overrides the account-level default for everyone under it.

None of this touches your existing permission rules in settings files. They still fire before the classifier runs, with one exception: allow-rules broad enough to grant arbitrary code execution, like a wide-open Bash(python:*) rule, get set aside while auto mode is active, since a rule that broad would let a command skip the classifier entirely. The rule itself isn't deleted, it just doesn't apply until you switch modes. See [Claude Code permissions explained](/blog/claude-code-permissions-explained) for how the rest of the permission system fits together with this.

Should You Actually Turn It Off?

For most day-to-day build work, no. Leave it on. The data above isn't marketing, it's the same pattern I'd expect from watching people click through prompts: the tenth permission dialog in an hour gets less scrutiny than the first one, and that's exactly where a classifier that doesn't get tired helps.

Where I still keep my hand on the wheel is anything touching production infrastructure directly, a live database, a paid API key with real spend behind it, a deploy to something clients depend on. Auto mode reduces risk, Anthropic says so plainly in their own writeup, it doesn't eliminate it, because it's still a classifier making judgment calls, not a guarantee. Pair it with the habit from [Claude Code checkpoints and /rewind](/blog/claude-code-checkpoints-and-rewind): work in a branch, commit often, and you get the speed of auto mode with a real undo button underneath it.

NOTE: We walk members through setting a sane default mode per project type, and where to keep manual review on for client work, inside Claude Code Club (https://www.skool.com/claudecodeclub/about). It's $9 a month, or start with the [curriculum](/curriculum) if you want the structured path first.

FAQ

Is Claude Code auto mode on by default now?

Yes, as of August 14, 2026, for Pro, Max, and Team plans that hadn't already pinned a different default mode. Enterprise and API access remain opt-in for now, with the same default change planned for the following month.

How do I turn off Claude Code auto mode?

Press Shift+Tab in the CLI or use the mode dropdown in the desktop app to switch modes for the current session. To turn it off permanently, use the disableAutoMode setting, or pin your own default mode so future sessions don't start in auto mode at all.

Is auto mode actually safer than approving permission prompts myself?

In Anthropic's own 1,053-tester study, auto mode caught 89% of dangerous commands slipped into a session versus 13.6% caught by human testers clicking through prompts. That's Anthropic's data on their own product change, treat it as directional evidence for the decision, not an independent audit.

Can auto mode still do something destructive?

It's designed not to, with hard denies on things like sending code or secrets externally, and a check of your git status before destructive git commands. It's still a classifier, not a guarantee, so keep manual review on for anything touching production infrastructure or real spend.

Does auto mode cost more in usage or tokens?

The classifier uses a small number of extra tokens per tool call, but Anthropic stopped charging Pro, Max, and Team users for that overhead the same day auto mode went default.

• Connect Claude Code to Notion with Notion's official hosted MCP server at mcp.notion.com. Register it once with claude mcp add, authenticate in the browser, and Claude Code can then search, read, and write your Notion pages and databases as part of a normal build conversation.
• Prefer a local server and your own integration token instead of the hosted route? Notion also publishes an open-source npm package, @notionhq/notion-mcp-server, that runs with a NOTION_TOKEN you generate at notion.so/my-integrations.
• Notion's sharing model is page-level: the integration only sees pages you've explicitly shared with it, not your whole workspace. Share narrow, and widen only when a real task needs it.

What the Notion MCP Server Actually Gives Claude Code

Connect Claude Code to Notion by adding Notion's own hosted MCP server, at https://mcp.notion.com/mcp, as an MCP server inside Claude Code, then authenticating once in your browser. Once it's connected, Claude Code can search your Notion workspace, read a page or database's real content, and create or update pages, all as part of the same conversation you're already having about a build, not a separate copy-paste step.

This is a server Notion built and runs themselves, not a community workaround stitched together against their public API. That matters for reliability: it's maintained against Notion's actual product, not reverse-engineered from it. If you'd rather run a local server against your own integration token instead of using Notion's hosted one, they also publish an open-source package, @notionhq/notion-mcp-server, for that route. Both are documented in [Notion's own MCP guide](https://developers.notion.com/guides/mcp/get-started-with-mcp).

NOTE: MCP servers in general are covered in [what are MCP servers, and why do they matter for Claude Code](/blog/what-are-mcp-servers-and-why-they-matter), and the club's [guide to setting up MCP servers](/guides/setting-up-mcp-servers) if this is your first one.

How to Connect It: Hosted vs Self-Hosted

Most people should use the hosted route, it's fewer steps and Notion manages the server for you.

1. In Claude Code, run claude mcp add notion --transport http https://mcp.notion.com/mcp to register the server.
2. On first use, Claude Code opens your browser for a Notion OAuth login. Approve it, and the connection is live for that machine going forward.
3. In Notion, open the pages or databases you want Claude Code to reach and share them with the connection, the same way you'd share a page with a teammate.

If you'd rather self-host, run the npm package locally instead: npx -y @notionhq/notion-mcp-server, with a NOTION_TOKEN environment variable set to an integration secret you generate at notion.so/my-integrations. The self-hosted route is the same underlying API, it just puts you in charge of the token and the server process instead of Notion.

TIP: If Claude Code can't see a page that should be shared, the fix is almost always in Notion, not Claude Code. Open the page, check Share, and confirm the connection or integration is actually listed there. A page not explicitly shared is invisible to the server, by design.

What This Is Actually Good For

The obvious use is pulling a project brief straight from Notion instead of retyping it into a prompt, see [how to write a project brief for Claude Code](/blog/how-to-write-a-project-brief-for-claude-code) for how that brief should be structured in the first place. Point Claude Code at the linked page and it reads the brief directly rather than you summarizing it by hand.

• Turn a build session into a written changelog or spec pushed back into a client's shared Notion workspace, instead of a summary that only lives in your terminal history.
• Pull a client's existing SOPs or intake docs from Notion as context before scoping a project, so Claude Code isn't guessing at conventions you already wrote down somewhere.
• Keep a running build log in Notion that updates as you work, useful for client visibility if they're used to checking a Notion page rather than a git log.

None of this replaces a real conversation with a client about scope. It removes the manual copy-paste tax between the tool your notes already live in and the tool doing the building.

What to Share and What Not To

Notion's sharing model is page-level, not workspace-level. The MCP connection, hosted or self-hosted, only sees pages and databases you've explicitly shared with it, the same permission model as sharing a page with a person. It does not get your whole workspace by default.

Share narrow to start: the one project's pages, not your entire team wiki. Widen access only when a specific task actually needs it, and treat an integration token the same way you'd treat any other credential, it's a secret, not a config value to paste into a shared file.

When Not to Bother With It

Skip the setup for a one-off build with no ongoing Notion presence, or a client who doesn't use Notion at all. It earns its place once there's a real, living set of docs on the other end, a brief, an SOP library, a changelog, something you'd otherwise be retyping every session.

NOTE: Members inside Claude Code Club share their actual MCP configs for tools like this, including which ones were worth the setup time and which weren't, at https://www.skool.com/claudecodeclub/about. It's $9 a month, or start with the [curriculum](/curriculum) for the structured path through MCP setup first.

FAQ

How do I connect Claude Code to Notion?

Add Notion's official hosted MCP server with claude mcp add notion --transport http https://mcp.notion.com/mcp, then authenticate through the browser OAuth flow that opens on first use. Share the specific Notion pages or databases you want reachable with the connection.

Do I need to generate a Notion API token to connect Claude Code?

Not for the hosted route, it authenticates through your browser instead. You only need to generate an integration token from notion.so/my-integrations if you choose the self-hosted @notionhq/notion-mcp-server package instead of Notion's hosted server.

Can Claude Code see my entire Notion workspace once connected?

No. Notion's sharing model is page-level. The MCP connection only sees pages and databases you've explicitly shared with it, the same way sharing works with a teammate, not your full workspace by default.

What's the difference between the hosted and self-hosted Notion MCP server?

The hosted server at mcp.notion.com is run by Notion and authenticates via browser OAuth, no token to manage. The self-hosted @notionhq/notion-mcp-server package runs locally and needs a NOTION_TOKEN integration secret you generate and manage yourself. Both talk to the same underlying Notion API.

Why can't Claude Code see a specific Notion page after I connected it?

The page almost always hasn't been shared with the connection yet. Open the page in Notion, check its Share settings, and confirm the integration or connection is listed there, since an unshared page is invisible to the MCP server by design.

• /design is a research preview command that brings an artboard-style design workflow into the Claude Code CLI and the Claude Code desktop app. You type /design with a brief, and Claude publishes a canvas of editable UI options called artboards instead of guessing at one layout and showing you code.
• It runs on Pro, Max, Team, and Enterprise plans and needs Claude Code v2.1.233 or later. You review the artboards, pick the one you want, tell Claude which option to implement, and it writes the actual code from there.
• The failure mode is treating the output as finished. Run it through the CCC Artboard Loop: name the constraint in the brief, compare every option before you commit, then review the implementation as a normal diff, the same as any other change Claude makes.

What Is Claude Code's /design Skill?

/design is a research preview skill that brings an artboard-based design workflow into Claude Code, in both the CLI and the desktop app. You describe what you want built or redesigned, and instead of writing one version of the UI and hoping it matches what you meant, Claude publishes a canvas of several editable artboards for you to look at and choose between. It runs on Claude Code v2.1.233 or later, on Pro, Max, Team, and Enterprise plans, and it is built on the same artifacts system that already powers shareable Claude Code output.

The shift is small to describe and large in practice. Before this, asking Claude Code to redesign a screen meant it picked one direction and built it, and if that direction was wrong you were editing code to correct a design decision. /design separates those two steps: you compare layouts first, on a canvas, before a single line of implementation code gets written.

How the /design Workflow Actually Works

1. Open the desktop app's Code tab (or the CLI) in a session attached to your project, and type /design followed by a real brief, not just a screen name.
2. Claude prints a link to a published canvas. Open it and you see a set of artboards, editable draft layouts for the thing you described.
3. Look at each artboard the way you would look at design comps. Nothing is implemented yet, this is still the compare stage.
4. Pick the one you want, tweak it on the canvas if you need to, then tell Claude which option to implement.
5. Claude writes the actual code for the artboard you chose, and it lands in your project as a normal set of file changes, reviewed the same way you review any Claude Code diff.

NOTE: The docs' own example prompt is a good template for the brief: describe the redesign in terms of how the screen actually gets used, not just what it should look like. 'Redesign the composer based on what people actually use it for' names a real constraint. 'Make it nicer' does not.

The CCC Artboard Loop

We teach members a short discipline for this instead of running /design and shipping whatever comes back. Call it the Artboard Loop, and it is three steps, none of them optional.

1. Name the constraint in the brief. A vague brief produces artboards that all miss the same thing. State the actual use pattern, the device it has to work on, or the one element that cannot move, before you hit enter.
2. Compare before you commit. Open every artboard on the canvas, not just the first one that loads. The point of this workflow is comparison, and skipping straight to the top result throws away the reason to use it.
3. Review the implementation like any other diff. Picking an artboard tells Claude what to build, it does not exempt the resulting code from review. Read the diff, run the app, and check it the way you would check a change Claude made without /design.

TIP: The artboard you pick is a draft, not a spec. Treat the first implementation as a starting point you refine in the same session, the same way you would iterate on any other Claude Code build.

What It's Actually Good For (and Where It Still Needs You)

This is a research preview, so the honest scope matters more than the pitch. It is genuinely useful for the moment where you know a screen needs to change but cannot describe the fix in one sentence, or where you have a vague sense of better and no mockup to hand Claude. Publishing three real, comparable options turns a fuzzy request into a decision, which is a faster loop than describing, building, disliking it, and re-describing.

• Good for: exploring layout directions fast, getting a non-technical stakeholder to point at an option instead of trying to describe one in words, and unsticking a redesign that has stalled because nobody can agree on the brief.
• Still needs you for: a real design system with locked components, an accessibility pass, and pixel-level brand execution. A research preview is a draft generator, not a design review.

How This Changes Client Work

For anyone building client work in Claude Code, the practical win is the canvas itself. Clients rarely have the vocabulary to describe a layout they want, but almost everyone can point at one of three real options and say that one, move that button up. Sending a canvas link instead of a screenshot of one attempt turns a design round into a five-minute decision instead of a back-and-forth email thread. The implementation step after that is exactly like any other Claude Code change: you still own the review, the diff, and the decision to ship it.

NOTE: Inside Claude Code Club we test new research previews like this against real client screens as soon as they ship, and post what actually held up. Start with the [curriculum](/curriculum) or join us at https://www.skool.com/claudecodeclub/about and bring the screen you would redesign first.

FAQ

What is Claude Code's /design skill?

It's a research preview command that turns a written brief into a canvas of editable UI options called artboards, built on Claude Code's artifacts system. You compare the artboards, pick one, and tell Claude to implement it, which separates choosing a layout from writing the code for it.

Does /design work in the terminal or only in the desktop app?

Both. It works in the Claude Code CLI and in the Claude Code desktop app's Code tab. The desktop app makes the canvas easier to open and compare since you are already working in a windowed view.

Do I need a paid plan to use /design?

Yes. It's available on Pro, Max, Team, and Enterprise plans, and it requires Claude Code v2.1.233 or later. Update Claude Code first if the command doesn't show up.

What happens after I pick an artboard?

You tell Claude which artboard to implement, and it writes the real code for that option into your project as a normal set of file changes. From there it's the same review loop as any other Claude Code diff, read it, run it, and check it before you ship.

Is /design production ready?

It's a research preview, so treat the output as a strong draft rather than a finished design. It's good at generating real, comparable layout options fast. It doesn't replace an accessibility pass, a locked design system, or a final brand-level review.

• The upsell that works isn't a new pitch, it's a specific problem you already found while doing the first job, named out loud instead of quietly fixed for free or left for the client to discover later.
• We call this the Second Ask: one sentence, sent once, naming the exact next problem and what fixing it would take. No package, no call, no sales language.
• Timing decides whether it lands. Ask while the first project is still visibly working, not in the same message as the final invoice and not months later when the relationship has gone cold.

Why Most Agency Upsells Feel Like a Pitch (and Get Ignored)

Most upsells fail because they show up as a pitch instead of a finding. You finish the project, then send a message about a retainer, a package, or ongoing support, and the client reads it as sales, because it is sales, dressed as a favor. They already said yes once. Asking them to sit through a second version of the same conversation, with a new price attached, is the thing that makes people go quiet.

The client isn't rejecting more work. They're rejecting being sold to twice by someone they already paid. The fix isn't a better pitch, it's not pitching at all.

The Second Ask

The Second Ask is the one thing that reliably gets a real upsell to land: name a specific problem you found while doing the first job, in one sentence, with no package attached. Not a menu of services. Not availability for a call. One real thing you noticed, and what it would take to fix it.

• It has to be specific. 'I could also help with your marketing' is a pitch. 'Your checkout drops about a third of people at the shipping step, I can see why, want me to fix it' is a finding.
• It has to come from the work you just did. You earned the right to say this because you were in the code, not because you're trying to fill your calendar.
• It has to be optional in tone. State it and stop. Don't chase it with a follow-up asking if they saw your message, that turns a finding back into a pitch.

TIP: If you can't name a specific next problem, you don't have a Second Ask yet, and sending a generic one anyway is what breaks trust. Wait until you actually see one, even if that means waiting past this project.

When to Make the Second Ask

Timing does most of the work here. Ask while the thing you built is still visibly working and the client can feel the value of it, not buried in the same email as the final invoice, and not three months later once the relationship has gone quiet.

• Best window: a few days to two weeks after launch, once they've actually used the thing and the win is fresh, but before the invoice email that closes the project.
• Worst window: the same message as the final invoice. That message is doing accounting, not selling, and mixing the two makes the ask read as padding the bill.
• Second worst window: months later, out of nowhere. At that point it reads as a cold pitch from someone who happens to have your email address, not a finding from someone who was just in your system.

What to Offer Instead of 'More Hours'

The Second Ask names a problem, not a service tier. Once they say yes, scope it the same way you scoped the first project, as a defined outcome, not open hours. 'More hours available if you need them' asks the client to manage you. A named fix with a price attached asks them to make one decision.

If the same specific problem keeps showing up across different clients after the first job, that's worth turning into its own offer. See [how to turn a one-off client into a monthly retainer](/blog/how-to-turn-a-one-off-client-into-a-monthly-retainer) for what that looks like once it's a pattern instead of a one-off.

The Exact Message I Send

This is close to word for word what goes out. Short, specific, and it stops instead of building a case.

• Subject or opener names the thing plainly: 'One thing I noticed while I was in the checkout flow.'
• One sentence describing the problem in the client's terms, not yours: what it costs them, not what it is technically.
• One sentence on what fixing it looks like and roughly what it takes.
• A single, low-friction next step: 'Want me to send a quote for that' or 'happy to just do it if you'd rather skip the back and forth.' Then stop typing.

NOTE: Notice what's missing: no package name, no bullet list of everything you could also do, no urgency. The moment it starts to read like marketing copy, cut it back down to the one sentence that started it.

Pitch vs the Second Ask

What Kills an Upsell Before It Starts

• Asking before you've actually delivered the first thing well. An upsell rides on trust you have to earn first, not on being first in line.
• Naming a problem so vague it could apply to any client. That's a tell that you're pitching, not reporting a real finding.
• Chasing the message with a follow-up. One clean ask beats three reminders, and reminders are what turn a finding back into a pitch.
• Discounting to make it land. If the finding is real, it doesn't need a discount to be worth saying yes to. A discount signals you weren't sure it was worth full price either.

If a client's response to a well-timed, specific Second Ask is still a hard no or radio silence, that's useful information on its own, worth reading against the broader signs in [client red flags to watch for](/blog/client-red-flags-to-watch-for) before you invest more in the relationship.

Try This on Your Next Project

On your current build, write down the first specific problem you notice that's outside the current scope, the moment you notice it. Don't fix it for free and don't pitch it yet. Hold it until launch, then send the one-sentence version within two weeks.

NOTE: Inside Claude Code Club we track which Second Asks actually turned into paid follow-on work and which ones went quiet, so members can see real numbers instead of guessing at what lands. Join at https://www.skool.com/claudecodeclub/about for $9 a month, or start with the [curriculum](/curriculum) if you want the pricing and proposal track first.

FAQ

How do I upsell an existing client without sounding pushy?

Name one specific problem you actually found while doing the work, in a single sentence, with no package or sales language attached. Send it once, close to launch while the value of the first project is still visible, and let them respond instead of following up repeatedly.

When is the best time to upsell a client?

A few days to two weeks after launch, once the client has used the thing you built and the win is still fresh. Avoid bundling it with the final invoice, since that reads as padding the bill, and avoid waiting months, since by then it reads as a cold pitch.

What should I offer instead of 'more hours available'?

A named fix for a specific problem, scoped and priced the same way you scoped the original project. Open-ended hours ask the client to manage you. A defined outcome asks them to make one decision.

What if I can't think of a next problem to mention?

Don't send a generic upsell anyway. Wait until you actually notice something specific, even if that means waiting past this project. A vague ask reads as a pitch and costs you more trust than staying quiet.

Should I discount an upsell to make it more likely to land?

No. If the problem you named is real, it doesn't need a discount to be worth saying yes to. Discounting a well-timed, specific ask signals you weren't confident it was worth full price, which undercuts the exact trust that made the ask land in the first place.

• Connect Claude Code to Figma by turning on the Dev Mode MCP Server inside the Figma desktop app, then adding it as an MCP server in Claude Code (the official Figma plugin does this in one step). Claude Code then reads a selected frame's real structure - components, variables, spacing, layout - instead of guessing from a picture.
• It only sees what you've selected or linked, not your whole file, and design tokens come through as named variables when the file uses Figma variables, not just approximate colors and pixel values.
• Generated code still needs a manual check before it goes to a client. I run what we call the CCC Design Parity Check inside the club, three quick passes that catch the gaps the MCP connection doesn't close on its own.

What the Figma Dev Mode MCP Server Actually Does

The Dev Mode MCP Server is a feature built by Figma, not a community workaround. It runs locally from the Figma desktop app and exposes the structure of a selected frame or file, its components, layout, spacing values, and any design tokens set up as Figma variables, in a format Claude Code can read directly. Point Claude Code at it and it stops guessing at a design from a flattened image and starts working from the actual layer tree.

That's the real difference from the older way of doing this, which was pasting a screenshot into your prompt and asking Claude Code to eyeball the spacing. A screenshot is pixels. The Dev Mode MCP Server hands over structure: this frame is built from a Button component with these variant properties, this color is the token brand/primary-600, this gap is 24 pixels because that's the auto-layout spacing value. Claude Code still has to write the code, but it's no longer reverse-engineering a picture to do it.

NOTE: The server only exposes what you've selected in Figma or linked via a Dev Mode link, not your entire file. It requires the Figma desktop app to be open and running locally, it isn't a cloud service you connect to from anywhere.

How to Set It Up in Claude Code

1. Open the Figma desktop app, go to your preferences, and turn on the Dev Mode MCP Server. Figma starts it locally on your machine (by default at http://127.0.0.1:3845/sse) as long as the app stays open.
2. In Claude Code, install the official Figma plugin, which registers the MCP server connection for you. If you'd rather add it by hand, add an MCP server pointing at that local address in your Claude Code MCP settings instead.
3. In Figma, select the frame or layer you want Claude Code to build from, or copy its Dev Mode link from the toolbar.
4. In Claude Code, describe what you want built and reference the selection or paste the Dev Mode link. Claude Code pulls the live structure from Figma as part of that turn.

One setup step is worth doing before your first real build: run the design-system-rules generation command once per project. It writes a persistent rules file so every future Claude Code session in that codebase already knows your token names and conventions, instead of you re-explaining them every session. Treat it the same way we treat a CLAUDE.md file, see our [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) for how that file should be structured alongside it.

TIP: If Claude Code can't see the server at all, it's almost always because the Figma desktop app got closed or the MCP toggle got flipped off after a Figma update. Check that first before you touch your Claude Code config, see [Claude Code MCP server not working](/blog/claude-code-mcp-server-not-working) for the rest of the usual suspects.

What Actually Transfers Cleanly vs What You Still Have to Check

The MCP connection closes most of the gap between a design file and working code, but not all of it. Knowing which half you're still responsible for is what keeps a Figma-sourced build from surprising a client later.

That last row catches people the most. A Figma file usually shows one frame at one width. The MCP server hands over exactly that frame's structure, it doesn't invent a mobile layout that was never designed. If the client needs a responsive build, say so in your prompt and expect to review Claude Code's judgment calls on the breakpoints the design never specified.

The CCC Design Parity Check

Before anything built from a Figma reference goes to a client, I run three passes. It takes ten minutes and it's caught more mismatches than any other single habit in this workflow.

1. Side by side, zoomed in. Open the Figma frame and the running build at the same zoom level and check spacing and alignment directly against each other, not from memory.
2. Token check, not color check. Open the generated code and confirm it's referencing your actual variable names (brand/primary-600) rather than a hardcoded hex value that happens to look close. A hardcoded fallback breaks the first time the client updates their brand color in Figma.
3. Test at a second width even if the design only showed one. Claude Code made layout decisions somewhere between the designed frame and a phone screen. Find out what they were before the client does.

WARNING: Skipping the token check is the mistake I see most. The build looks identical to the design in a screenshot, but it's using a one-off hex value instead of the design system's actual variable, so it quietly drifts the next time the client changes their palette.

Where This Fits in a Client Handoff

This connection earns its place the moment a client hands you an actual Figma file instead of a PDF or a set of screenshots. It's the fastest way I know to go from that file to a first working pass, and it removes almost all of the manual pixel-measuring that used to eat the first hour of a build. It doesn't replace a real project brief, it feeds one, see [how to write a project brief for Claude Code](/blog/how-to-write-a-project-brief-for-claude-code) for how I combine a linked Figma frame with the rest of the scope before I start building.

When Not to Bother With It

Skip the setup on a simple one-off, or when the client only has a screenshot or a PDF and no live Figma file at all. Pasting an image straight into your prompt still works fine for a landing page or a small component, see [how to build a landing page with Claude Code](/blog/build-a-landing-page-with-claude-code) for that path. Reach for the MCP server when there's a real design system behind the file, tokens, reusable components, multiple frames, the kind of build where structure actually matters more than a single picture.

NOTE: We walk members through the full Figma-to-Claude-Code setup live inside Claude Code Club, including the design-system-rules step most people skip. Join for 9 dollars a month at claudecodeclub.ai and bring your next client file.

FAQ

How do I connect Claude Code to Figma?

Turn on the Dev Mode MCP Server in the Figma desktop app's preferences, then add it as an MCP server in Claude Code, either by installing the official Figma plugin or by pointing your MCP settings at the local address Figma exposes. Select a frame in Figma, then reference that selection or its Dev Mode link in your Claude Code prompt.

Does Claude Code see my whole Figma file once it's connected?

No. The Dev Mode MCP Server only exposes what you've selected in Figma or linked directly, not your entire file or workspace. It also requires the Figma desktop app to stay open, since the server runs locally on your machine rather than in the cloud.

Will the code Claude Code generates from Figma match the design exactly?

Close, but not automatically perfect. Component structure, spacing, and any values set up as Figma variables transfer cleanly. Custom fonts not installed locally, interaction states the design never drew, and breakpoints beyond the one frame you linked still need a manual pass, which is what the CCC Design Parity Check in this post is for.

Do I need a paid Figma plan to use the Dev Mode MCP Server?

The server is a feature of the Figma desktop app itself rather than a separate paid add-on, but access to Dev Mode has historically depended on your Figma plan and role. Check your current plan's Dev Mode access in Figma directly before you build a workflow around it, since Figma changes plan features over time.

What if Claude Code can't see the Figma MCP server?

Confirm the Figma desktop app is open and the Dev Mode MCP Server toggle is still on, that's the most common cause after a Figma update resets it. If it's still not connecting, work through the rest of the usual causes in our guide to a Claude Code MCP server not working.

• Client work gets you paid the same month for a problem someone else already confirmed is worth solving. A micro-SaaS only pays you once you've found people willing to pay for it yourself, which can take a lot longer than the build.
• Claude Code has made the build itself fast either way, so build speed stopped being the real decision. The actual dividing line is distribution: client work borrows the client's audience, a micro-SaaS makes you find your own.
• I run new ideas through a short checklist before committing a week of Claude Code sessions to either path, what we call the CCC Build-or-Bill Test inside the club.

The Actual Difference Isn't Build Speed Anymore

Claude Code closes most of the build-time gap between a client project and a micro-SaaS. A working first version of either one is realistically a few focused sessions away, not a few months. That changes which question actually matters when you're deciding what to spend a week on. It's no longer can I build this fast enough, it's who is going to pay for it, and how hard is it going to be to find them.

Client work answers that question before you start: someone already has the problem, already has budget, and already agreed to pay you to solve it. A micro-SaaS answers it after you ship: you're betting that a wider group of strangers has the same problem and will pay a recurring price for your specific answer to it. Same builder, same tool, very different bet.

What Client Work Gets You

• Cash the same month, usually against a deposit or a milestone, not a hope that strangers convert.
• Scope someone else already defined. You're solving a problem a real person described to you, not guessing what a market wants.
• Distribution you didn't have to build. The client already has the audience, the internal team, or the customer base your work reaches.
• A ceiling tied to your hours or your team size, since revenue only grows when you take on more work or raise your rate.

If you haven't already moved off pricing by the hour, that ceiling is the first thing to fix regardless of which path you're weighing, see [why I stopped charging hourly for AI builds](/blog/stopped-charging-hourly-for-ai-builds) for how that shift changes the math on client work specifically.

What a Micro-SaaS Gets You

A micro-SaaS can pay you while you sleep, once it works, because revenue stops being tied one-to-one to your hours. That's the appeal, and it's real. What it costs you is everything client work handed you for free: you have to find the buyers yourself, you own support and uptime with no one else covering it, and there's a real chance you build the whole thing and nobody pays for it.

WARNING: Claude Code lowering the cost of the build doesn't lower the cost of finding your first paying users. That part hasn't gotten any faster, and it's usually the part that actually determines whether a micro-SaaS works. Don't let a fast build convince you distribution is solved too.

The CCC Build-or-Bill Test

Before I let a new idea eat a week of Claude Code sessions, I run it through four questions. It's not a formula, it's a way to catch myself before I build something nobody asked for, or turn down client cash to chase a hunch.

1. Has a version of this come up more than once? One client asking for something is a client request. Three different clients asking for a version of the same thing is a pattern, and a pattern is the strongest signal I've found for a real micro-SaaS candidate.
2. Do I already have a way to reach buyers without paying for every one of them? An audience, a community, a referral network. If the honest answer is no, budget real time for distribution, not just the build.
3. Am I willing to still be maintaining this in a year, with no client relationship forcing me to? A SaaS doesn't end when you ship it, someone has to keep answering support tickets and keeping it running.
4. Would I still take this project if it paid nothing for the first 90 days? If the answer is a hard no, that's a client-work problem, not a bet you're actually willing to make.

TIP: Question one does most of the work. If an idea only ever came from a single client, it's client work, price it and move on. The moment the same request shows up a third time across unrelated clients, that's worth a real look as its own product.

The Hybrid Most Builders in the Club Actually Run

Very few people I know pick one lane and stay there. The common pattern is client work funding the runway while a short list of repeated requests gets tracked on the side, and only the ones that clear the Build-or-Bill Test above turn into an actual product attempt. That keeps income steady while you find out, cheaply, whether any given idea has real pull beyond the one client who first asked for it.

If you're still building a client roster to fund that runway, see [how to pick a niche for your AI agency](/blog/how-to-pick-a-niche-for-your-ai-agency). A tight niche also happens to be where repeated requests show up fastest, since you're solving close variations of the same problem for everyone in it.

What Changes About Pricing and Billing

That last row is real engineering work, not an afterthought. If a Build-or-Bill Test candidate clears the bar, see [how to add Stripe payments to your Claude Code build](/blog/add-stripe-payments-to-claude-code) for what actually needs to exist before you can charge anyone on a recurring basis.

Run the Test on Your Next Idea

Next time a client asks for something and it feels familiar, write it down instead of just building it and moving on. After the third time you write down a version of the same request, run it through the four questions above before you decide what it is.

NOTE: Inside Claude Code Club we track which member-built ideas started as a single client request and turned into something bigger, and which ones stayed exactly the client work they started as. Join for 9 dollars a month at claudecodeclub.ai and bring the idea you keep getting asked for.

FAQ

Is a micro-SaaS a better use of Claude Code than client work?

Neither is inherently better, they're different bets. Client work pays you the same month for a problem someone else already validated. A micro-SaaS only pays once you've found people willing to pay for it yourself, which can take far longer than building it, since Claude Code has made the build itself fast for either path.

How do I know if a client request should become a micro-SaaS?

Watch for the same request showing up across multiple, unrelated clients rather than just one. A single client asking for something is a client-work problem. The same underlying request appearing a third time across different clients is the strongest signal that it might work as its own product, which is question one of the CCC Build-or-Bill Test in this post.

Does Claude Code make it easier to run both client work and a micro-SaaS at once?

It makes the build side of both faster, which is why a hybrid approach is common among builders in the club: client work funds the runway while repeated requests get tracked on the side and only the ones that clear a real checklist turn into a product attempt.

What's the biggest risk of switching from client work to a micro-SaaS?

Underestimating distribution. A fast build with Claude Code can create the illusion that finding paying customers will be just as fast. It usually isn't, since the client-work path hands you an audience for free and a micro-SaaS doesn't.

What does a micro-SaaS need that a client project usually doesn't?

Real subscription billing (plan tiers, recurring charges, failed-payment handling), ongoing support with no client relationship forcing it, and a way to reach buyers you don't already have a relationship with. All three are extra work beyond what a typical client project requires.

• Claude Code on the web runs at claude.ai/code as a cloud session on Anthropic-managed infrastructure. It keeps running after you close the browser tab, and you can check on it, comment on the diff, or send a follow-up from the Claude mobile app.
• It's currently a research preview for Pro, Max, and Team users, and for Enterprise users with premium seats or Chat + Claude Code seats - not yet the default way most people should build, but worth knowing when it earns its place.
• The desktop app stays the default in the club because it gives you the full diff view, browser pane, and local control in one window. Reach for a cloud session when the task doesn't need you watching, not as a replacement for how you build day to day.

What Claude Code on the Web Actually Is

Claude Code on the web is the browser version of Claude Code. It lives at claude.ai/code, and instead of running on your laptop, the task runs in a cloud session on Anthropic-managed infrastructure, or on your organization's own infrastructure if that's been set up. The practical difference from typing claude in a terminal or opening the desktop app's Code tab is where the work happens: not on the machine in front of you, but on a virtual machine you can close the lid on.

The detail that actually changes how you work is persistence. A cloud session keeps running after you close the browser tab or shut your laptop. You can open the Claude mobile app later, see what it did, leave a comment on the diff, or send it a follow-up message, all without your laptop being open or even in the room.

NOTE: As of this writing it's a research preview, open to Pro, Max, and Team users, plus Enterprise users on premium or Chat + Claude Code seats. Preview features move fast, and details here can shift, so check code.claude.com/docs for the current state before you build a workflow around it.

How It's Different From the Desktop App's Code Tab

The two aren't competing products, they're the same underlying session reached from different places. Here's what actually changes depending on where you start it.

If you already use the desktop app, this isn't a separate tool to learn from scratch. The Code tab's Cloud environment option starts the same kind of cloud session, see our [desktop app guide](/blog/claude-code-desktop-app) for how that fits into the three-tab workflow we teach. The web version at claude.ai/code is the same underlying session, reached from a browser instead of the app.

How to Start One, From the Browser or Your Terminal

Getting a repository connected is the only real setup step, and there are two ways to do it. During web onboarding at claude.ai/code, you can authorize the Claude GitHub App, which is also what unlocks auto-fix on pull requests (more on that below). Or, if you already work from a terminal, run /web-setup inside Claude Code to sync your existing gh CLI login instead, no separate app to install.

• From claude.ai/code: sign in, connect GitHub, pick a repository, and describe the task.
• From your terminal: run claude --cloud "describe the task" to send it to the cloud while you keep working locally. Use /tasks to check progress without leaving the terminal.
• Bring it back: run claude --teleport (or /teleport inside a session) to pull a cloud session into your terminal and keep going locally, once its branch is pushed and your working directory is clean.

TIP: A cloud session clones your GitHub remote at your current branch, not your local uncommitted changes. Push first, or the cloud session won't see the work you were just doing. This tripped me up the first time I tried it.

The Off-Desk Test: When I Actually Send a Task to the Cloud

I still build most of my day in the desktop app, with the diff view and browser pane open where I can watch each change land. Before I reach for a cloud session instead, I run what we call the Off-Desk Test inside the club, three short questions, and if I answer yes to at least two, it goes to the cloud.

1. Am I about to be away from this machine? A commute, a client call, an overnight run. If yes, the cloud session keeps working while the desktop app would just sit idle.
2. Is the work already fully pushed to a branch? Cloud sessions clone from your GitHub remote, not your uncommitted local state, so anything still sitting in your working directory needs to be committed and pushed first.
3. Can I review the result from wherever I end up? The diff view and mobile app cover reading and commenting, but if the task needs a full local dev environment to actually verify, running it locally is the shorter path.

The Off-Desk Test isn't about which tool is better. It's about matching where a task runs to whether you're actually going to be sitting in front of it. Most client work still belongs in the desktop app, in Manual or Accept Edits mode, with you watching. The cloud is for the parts of the day you're not at your desk anyway.

What You Get in a Cloud Session

• A diff indicator on the session, something like +42 -18, that opens into a full diff view, the same review habit as any local session.
• Auto-fix on pull requests, if you've installed the Claude GitHub App: Claude watches CI checks and review comments on a PR and pushes a fix when it's confident, or asks you when a comment is ambiguous.
• Sharing controls. Team and Enterprise accounts can set a session to Private or Team-visible; Pro and Max accounts can set Private or Public, and Public means any signed-in claude.ai user can open it. Check a session for credentials or client-sensitive code before you flip that toggle.
• Sessions expire after a period of inactivity and the VM gets reclaimed, but reopening it from claude.ai/code spins up a fresh VM with your conversation history restored, so nothing you did is actually lost.

WARNING: That sharing default is worth pausing on for client work. A Public session on a Pro or Max account is visible to any logged-in claude.ai user, and it can contain code and credentials from a private repository. If you're building for a client, set sharing to Private and only widen it on purpose.

The Self-Hosted Option, If Your Org Needs It

One more layer worth knowing exists, even if you'll rarely touch it as a solo builder: organizations on Team or Enterprise plans can route these same cloud sessions onto their own infrastructure instead of Anthropic's, through a public beta called self-hosted environments. It's off by default, and turning it on is a real infrastructure commitment, not a settings toggle. If a client or a bigger agency you work with asks about it, that's a pricing and scoping conversation of its own, we walk through exactly how to price that request in [how to price a Claude Code build when the client wants it self-hosted](/blog/pricing-self-hosted-claude-code-for-clients).

Try It on One Task This Week

Pick one task you'd normally start right before leaving your desk, something you'd otherwise just let sit until you're back. Push your branch, run claude --cloud with the task described in one clear sentence, and check it from your phone before you sit back down.

NOTE: Inside Claude Code Club we test every new Claude Code surface as it ships and share what's actually worth building a habit around versus what's still rough. Join for 9 dollars a month at claudecodeclub.ai.

FAQ

What is Claude Code on the web?

It's the browser version of Claude Code at claude.ai/code. Instead of running on your own machine, the task runs as a cloud session on Anthropic-managed infrastructure (or your organization's own infrastructure, if self-hosted environments are set up). The session keeps running after you close the browser, and you can check on it, review the diff, or send a follow-up from the Claude mobile app.

Do I need the desktop app to use Claude Code on the web?

No. You can sign in at claude.ai/code in any browser and connect a GitHub repository without installing anything. If you already use the desktop app or terminal, the same cloud sessions are also reachable from there, including the claude --cloud command.

Does closing my laptop stop a cloud session?

No, that's the actual difference from a local session. A cloud session keeps running after you close the browser tab or shut your laptop. You can check its progress later from claude.ai/code, your terminal, or the Claude mobile app.

Is Claude Code on the web the same as the self-hosted option?

No, they're different layers. Claude Code on the web is the browser entry point at claude.ai/code, and by default those sessions run on Anthropic's own infrastructure. Self-hosted environments is a separate, opt-in beta for Team and Enterprise organizations that routes those same cloud sessions onto infrastructure the organization runs itself.

Should I use the cloud version instead of the desktop app for client work?

Not by default. The desktop app still gives you the full diff view, browser pane, and local review in one window, which is where most client work should happen. Reach for a cloud session when you genuinely won't be at your machine to watch it, not as a replacement for the review habits you'd use locally.

• Self-hosted Claude Code environments run on the client's own infrastructure instead of Anthropic's, and setting one up means building and operating a runner fleet, not flipping a setting. That's real, ongoing work your build rate wasn't priced to cover.
• It's currently a public beta available only on Team and Enterprise plans, off by default, and Anthropic's own guidance is that most teams don't need it. Only quote it when a client has an actual network or compliance reason, not because it sounds more secure.
• I price it as a separate infrastructure line, either a fixed setup fee plus a maintenance retainer or an hourly DevOps rate, kept apart from the build itself so a client can see exactly what the extra requirement costs.

What a Client Is Actually Asking For

When a client says they want Claude Code self-hosted, they're asking you to run the software that executes Claude Code's cloud sessions on infrastructure they control instead of on Anthropic's. That's a real, separate system: a runner process that lives on hosts inside their network, registered against an environment their organization sets up in admin settings. It is not a checkbox on your side, and it's not something you can quote at your normal build rate.

The distinction matters because the phrase self-hosted gets used loosely. Some clients mean this specific feature. Others mean I don't want you sending our code to a chatbot, which is a much smaller ask you can usually answer without touching infrastructure at all, see [is Claude Code safe for client work](/blog/is-claude-code-safe-for-client-work) for how I handle that version of the question. Find out which one you're actually being asked before you price anything.

What Actually Changes vs. a Normal Build

That last row is the one clients miss, and it's the one you need to say out loud before you quote anything. Self-hosting doesn't remove Anthropic from the picture. The model still runs on Anthropic's API, so the actual conversation, meaning the prompts and responses, still leaves their network for inference. What self-hosting buys them is that the code itself, the checkouts and build artifacts and secrets, never leaves infrastructure they control. If a client is picturing something fully air-gapped, correct that before you scope the work, not after you deliver it.

Why a Client Would Actually Need This

There are legitimate reasons to ask for it, and knowing them is how you tell a real requirement from a client who just heard the phrase somewhere and liked the sound of it.

• Their sessions need to reach internal services, databases, or private registries without exposing them to the public internet.
• They want compilers, internal CLIs, or proprietary SDKs pre-installed so every session starts ready to build against their own stack.
• A compliance or security policy specifically requires that repository checkouts and build artifacts stay on infrastructure they control.

If none of those apply, don't sell it. Even Anthropic's own guidance is blunt about this: most teams are better served by the hosted default, which needs no infrastructure to run or maintain. Talking a client into paying for infrastructure they don't need is the kind of sale that comes back to bite you in month three, when nobody on their side wants to own the runner fleet you built.

The Infra Line: How I Split the Quote

This is the rule I use inside the club, and it's simple: the build is one line item, and where it runs is a separate one. I call it the Infra Line, the point in a proposal where what I'm building stops and what it takes to run this on your infrastructure starts. Everything on the build side of that line is priced the way I'd price any other project. Everything on the infrastructure side gets its own number, because it's a different kind of work with a different kind of risk.

Concretely, standing up a self-hosted environment means someone builds and maintains a runner image, decides how the fleet scales, configures network egress and git credentials, and keeps it running as Claude Code's own requirements change. That's DevOps work. If you're the one doing it, price it as DevOps work, not as a few extra hours tacked onto a build estimate.

1. Quote the build normally, on whatever pricing model you already use for the actual application work.
2. Quote the infrastructure separately, either as a fixed setup fee for standing up the runner and environment, or an hourly DevOps rate if the client's network is complicated enough that you can't scope it tightly up front.
3. Add an ongoing line if you're the one keeping it running. A self-hosted environment isn't set up once and forget it, runner images need updates, capacity needs adjusting as usage grows, and someone has to be the person who gets paged when a runner stops picking up sessions.

TIP: Say the Infra Line out loud on the call, not just in the line items. The build is X. Running it on your own infrastructure instead of the default is a separate Y, because that's a different piece of work with its own maintenance. Said that plainly, most clients nod and move on. Said vaguely, it reads like padding.

What I Actually Say When a Client Asks For This

I don't lead with a price. I lead with the question that tells me whether they need it at all: what's the specific reason you need this self-hosted, versus the standard setup? If they have a real answer, network access, internal tooling, or a compliance requirement, I scope the infrastructure work properly and quote it as its own line. If the answer is vague, general unease about AI tools, or something they read once, I walk them through what self-hosting actually changes and let them decide with the full picture instead of the buzzword.

NOTE: The clients who genuinely need this almost always have a compliance or security team who can answer the specific-reason question in one sentence. If nobody on their side can answer it, that's your signal the standard, Anthropic-hosted setup is the right call, and you've just saved both of you a scoping headache.

Put This in the Contract, Not Just the Quote

Whatever you agree, write it down as its own scope item, separate from the build. Name who owns ongoing maintenance of the runner fleet once the project ships, because that's the question that causes friction later if it's left implicit. See [what to put in an AI project contract](/blog/what-to-put-in-an-ai-project-contract) for the rest of what belongs in there alongside it.

NOTE: Inside Claude Code Club we share the actual line-item language members use when a client's ask goes beyond a standard build, including the self-hosted conversation above. Join for 9 dollars a month at claudecodeclub.ai and bring the scope-creep question you're sitting on.

FAQ

What does self-hosted Claude Code actually mean?

It means the client's organization runs the runner process that executes Claude Code's cloud sessions on their own infrastructure, instead of those sessions running on Anthropic's infrastructure by default. It's a public beta available on Team and Enterprise plans, off by default, and setting it up means building and maintaining a runner fleet, not flipping a toggle.

Does self-hosting stop code from ever leaving the client's network?

No, and this is the correction to make before you quote anything. Repository checkouts, build artifacts, and secrets stay on the client's infrastructure, but the conversation itself, the prompts and responses, still goes to Anthropic's API because that's where the model runs. If a client is picturing something fully air-gapped, self-hosting doesn't get them there on its own.

How should I price a self-hosted setup for a client?

Separate it from the build entirely, what I call the Infra Line. Quote the application build the way you normally would, then price the infrastructure work, the runner image, network configuration, and ongoing maintenance, as its own line, either a fixed setup fee or a DevOps hourly rate. Don't fold it into your standard build estimate.

Should every security-conscious client get a self-hosted setup?

No. Anthropic's own guidance is that most teams are better served by the standard hosted setup, which needs no infrastructure to run. Ask what the specific reason is before you scope anything, real network access needs, internal tooling requirements, or a compliance policy are legitimate reasons. General unease about AI tools usually isn't, and it's a smaller conversation you can answer without touching infrastructure at all.

• To refactor code with Claude Code safely, build the fence first: a passing test you trust, a clean git state with everything committed, and one written sentence defining what behaviour must not change. Then refactor one seam at a time and run the test after each.
• The failure mode is not bad code. It is a refactor that silently becomes a rewrite. Claude Code will happily improve things you did not ask it to touch, and those improvements are where behaviour changes hide.
• Use the Fence-First Refactor and keep every diff small enough that you can read it in one sitting. A refactor you cannot review is a refactor you cannot trust, no matter how good it looks.

How Do You Refactor Code With Claude Code?

Build the fence before you move anything. Commit your current work so the tree is clean, get one test passing that exercises the code you are about to change, and write a single sentence saying what behaviour must be identical afterwards. Then open the Claude Code desktop app, describe the one structural change you want, and refuse everything else. Run the test after each step. Commit after each step. That loop is the whole method, and it is boring on purpose.

Refactoring is the task where agent speed hurts you most. Writing new code has an obvious pass or fail at the end: the feature works or it does not. A refactor has no such signal. The app still runs, the code reads better, the diff looks professional, and the one edge case that used to be handled by a strange-looking conditional is now gone. You find out three weeks later. Everything below exists to make that outcome visible while it is still cheap.

The Fence-First Refactor

The Fence-First Refactor is the pattern we teach for this, and the name is the instruction. You do not move furniture before you know where the walls are. The fence is three things, all built before you write the first prompt, and each one takes under five minutes.

1. A clean git state. Everything committed, nothing staged, a named branch for the refactor. This is what makes an unlimited number of retries free, and it is the single highest-value habit in agent-assisted work.
2. A green test that touches the code. It does not have to be elegant. It has to fail if the behaviour changes. One test that calls the function with a realistic input and asserts the exact output beats a suite that only checks the file imports.
3. A one-sentence contract. Write it in the prompt: the public function signatures stay identical and the API response for an existing order stays byte for byte the same. If you cannot write that sentence, you do not yet know what you are protecting.

The contract sentence is the piece people skip and the piece that does the most work. It converts a vague instruction into a checkable one, and it gives you something concrete to hold the finished diff against. It also gives Claude Code a boundary it can reason about instead of guessing at your intent from the shape of the code.

TIP: If the code has no test at all, write the test with Claude Code first, in a separate commit, before any refactoring starts. That commit is not overhead. It is the only thing standing between you and a silent behaviour change, and the [test-driven approach](/blog/claude-code-test-driven-development) is worth reading before you start.

Refactoring Is Not Rewriting, and Claude Code Will Blur the Line

A refactor changes structure and leaves behaviour untouched. A rewrite changes both. Claude Code is extremely good at rewriting and it does not always announce the switch, because from inside the task both look like improving the file. You ask it to extract a function and it also renames three variables, converts a loop to a map, adds a null check that was not there, and removes a branch it judged unreachable. Four of those five are fine. The unreachable branch was reachable on Sundays.

• Named scope in the prompt. Say what may change and add the words: change nothing else, even if you see something worth improving.
• Ask for the list first. Have it read the file and list the changes it would make, ranked, before it edits anything. You pick one. This is what [plan mode](/blog/claude-code-plan-mode) is for and it costs you one extra exchange.
• Separate commits for separate intents. Structural moves in one commit, behaviour fixes in another, formatting in a third. A mixed commit is unreviewable and it hides the one line that mattered.
• Treat every removal as suspicious. Additions are easy to evaluate. Deletions are where the behaviour lives, and a deleted guard clause looks exactly like a deleted redundancy in a diff.

There is a version of this that is not the agent's fault. If your prompt says clean up this file, you have asked for a rewrite and you will get one. The word refactor carries a precise meaning in your head and a fuzzy one in a sentence, so replace it with the actual operation: extract, inline, rename, move, split, or deduplicate. One verb, one target, one commit.

Split the Refactor Into Seams

A seam is a place where the code can be cut without touching anything on the other side. Refactoring seam by seam is what turns an unreviewable 900-line diff into six diffs you can actually read. Find the seams before you start and the whole job becomes a sequence of small, verifiable moves rather than one long act of faith.

• Extract the pure logic first. Anything that takes inputs and returns outputs with no side effects moves cleanly and is trivial to test once it is out.
• Move the input and output edges next. Parsing, validation, and serialisation are usually tangled into the middle and they are the second easiest thing to pull free.
• Leave the stateful core for last. Anything that writes to a database, mutates shared state, or fires an external call is where the real risk is, and by the time you reach it the surrounding code is simple enough to read.
• Stop at the first surprise. If a move requires a change you did not predict, that is information about the system, not an obstacle. Commit what works, then investigate.

One seam per session is a good default for anything unfamiliar. Long sessions accumulate context that stops being relevant, and a refactor conversation that started with the parser is a poor place to discuss the database layer. Clear the session between seams and let the commit history carry the memory instead, which is the habit behind [Claude Code context management](/blog/claude-code-context-management).

The Prompt That Keeps a Refactor Honest

A good refactor prompt names the operation, the target, the contract, and the verification. Four parts, one message, no ambiguity about what counts as done. Here is the shape, and it works whether the target is a 40-line function or a service class nobody has opened in a year.

1. The operation. Extract the date parsing out of processOrder into its own function. One verb, not clean up.
2. The target file and boundary. In src/orders/process.ts only. Do not touch any other file.
3. The contract. processOrder keeps its exact signature and return shape. No behaviour changes of any kind, including error messages.
4. The verification. Run npm test after the change and show me the result. If anything fails, stop and tell me rather than fixing it.

That last line matters more than it looks. Without it, a failing test becomes a second, unrequested change made to satisfy the first one, and now you are reviewing a fix to a problem you never saw. Telling it to stop on red turns the test from a hurdle into a tripwire.

NOTE: Put the standing rules in your project's CLAUDE.md so you stop retyping them: never mix formatting with logic changes, never delete a branch without explaining why it is dead, always run the test suite before reporting success. Rules that live in the file get applied when you are tired, which is exactly when you need them.

How to Refactor When There Are No Tests

You write the test first, and you write it to describe what the code currently does rather than what it should do. That distinction is the whole trick. You are not documenting correct behaviour, you are pinning down existing behaviour, including the bits that look wrong. If the function returns null on an empty array, your test asserts null. Fix it later, in a commit with its own name.

1. Ask Claude Code to read the target file and describe every input it handles and every output it produces, including error paths. Read that list yourself and correct it.
2. Have it write tests that assert the current output for each of those cases. Do not let it improve anything while writing them.
3. Run the tests. Any that fail are telling you the description was wrong, which is worth knowing before you refactor and not after.
4. Commit the tests on their own. Now the fence exists and the refactor can start.

This is also the fastest way to understand code you did not write, because a test that captures real behaviour teaches you more than a summary does. If the file is one of many and the whole codebase is unfamiliar, the wider approach in [Claude Code on a large existing codebase](/blog/claude-code-large-existing-codebase) is the place to start before you pick a file to improve.

Reviewing a Refactor Diff

Read the diff for what disappeared, not for what appeared. New code announces itself and is easy to judge. Removed lines are quiet, and a refactor is mostly removal. Every deleted conditional, early return, try block and default value is a question you have to answer before you merge.

• Scan deletions first. In a review, read every removed line before you read a single added one.
• Check the error paths. Structure changes routinely flatten specific error handling into a generic catch, and nothing fails until production.
• Confirm the signatures. If the contract said the public interface stays identical, verify that literally rather than trusting the summary.
• Watch for silent defaults. A value that used to be required and is now optional with a fallback is a behaviour change wearing a tidiness costume.
• Run the app, not just the tests. Tests confirm what you thought to check. Two minutes of clicking finds what you did not.

If the diff is too big to review properly, that is not a reason to skim it. It is a signal that the seam was too wide. Reset to the last commit and cut the job smaller. This is the general discipline in [review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship), and refactors are the case where it pays the most, because there is no feature to demo that would have caught the mistake.

A Refactor Routine You Can Run Every Time

Here is the whole Fence-First Refactor as a routine. It looks slower than just asking for a cleanup and it is faster in practice, because the time refactoring costs is almost never the editing. It is the week you spend finding out why an old customer's invoices stopped generating.

1. Commit everything and create a branch named for the refactor.
2. Get one test green that fails if the behaviour changes. Write it first if it does not exist, in its own commit.
3. Write the contract sentence: what must be identical afterwards.
4. Pick one seam. Name the operation, the file, the contract and the verification in a single prompt.
5. Let it run, then read the deletions in the diff before anything else.
6. Run the tests and open the app. If it is red, stop rather than layering a fix on top.
7. Commit that seam alone with a message naming the operation.
8. Clear the session and repeat for the next seam.

The branch and the per-seam commits are doing quiet work throughout: they make abandoning a bad attempt completely painless, which is what lets you be aggressive about resetting instead of trying to argue a confused session back on track. The [git workflow for Claude Code](/blog/claude-code-git-workflow) covers that safety net in full, and it is the prerequisite for everything here.

TIP: Inside [Claude Code Club](https://www.skool.com/claudecodeclub) members post the actual refactor diffs and the prompts that produced them, which is a much faster way to calibrate what a safe seam looks like than reading about it. The [curriculum](/curriculum) covers the workflow alongside testing and review. It is $9 a month to join.

FAQ

Can Claude Code refactor code safely?

Yes, if you constrain it. The risk is not that it writes bad code, it is that a refactor quietly becomes a rewrite and changes behaviour you did not ask it to touch. Commit everything first, get one test green that fails when behaviour changes, name the exact operation rather than saying clean this up, and review the deleted lines in the diff before the added ones.

How do I stop Claude Code from changing things I did not ask for?

Name the boundary explicitly and add the phrase: change nothing else, even if you see something worth improving. Restrict it to one named file. Ask it to list the changes it would make and let you pick one before it edits anything. Standing rules like never mix formatting with logic belong in your project's CLAUDE.md so they apply in every session without retyping.

How big should a refactor be in one go?

Small enough that you can read the whole diff in one sitting without losing attention. In practice that is one seam: one extraction, one rename, one move. If the diff has grown past what you will genuinely review, the answer is to reset to the last commit and cut the job smaller, not to skim it and merge.

What if the code has no tests to refactor against?

Write the tests first, and write them to describe what the code currently does rather than what it should do. If a function returns null on an empty array, assert null even if that looks wrong. Commit those tests on their own, then start refactoring. Fixing the behaviour you disagree with is a separate task with its own commit.

What is the difference between refactoring and rewriting?

A refactor changes structure and leaves behaviour identical. A rewrite changes both. The distinction matters because they need different levels of verification, and the word refactor is fuzzy enough in a prompt that you will often get the second when you asked for the first. Use the precise verb instead: extract, inline, rename, move, split or deduplicate.

Should I refactor with Claude Code before or after adding a feature?

Before, in a separate commit, whenever the existing structure is what makes the feature awkward. Mixing a refactor into a feature commit produces a diff nobody can review, because there is no way to tell which changes were required and which were tidying. Refactor to make the change easy, commit, then make the easy change.

• To write a case study for your AI agency, lead with the client's situation before the build, name three numbers - the starting state, the ending state, and how long it took - and close with one direct quote from the client in their own words.
• Structure beats length. Situation, stakes, approach, result, quote, next step. Under a thousand words is fine and often better, because the reader is scanning for whether you have solved their problem before.
• Use the Three-Number Case Study as the test: if you cannot state a before, an after, and a duration, you do not have a case study yet. You have a description of some work, and buyers cannot price that.

How Do You Write a Case Study for an AI Agency?

Start with the client's situation before you arrived, in their language and with enough specificity that a similar buyer recognises themselves in the first two sentences. Then give three numbers: what the metric was before, what it is now, and how long the work took. Explain the approach in plain terms without turning it into a technical tour. Close with one direct quote from the client and one clear next step. That is the whole document, and it usually fits on a single page.

The reason most agency case studies fail is not writing quality. It is that they are written from the builder's point of view, which makes them a description of what was made rather than an account of what changed. A buyer reading your case study is not evaluating your craft. They are checking whether you have already solved a problem shaped like theirs, and whether the outcome was worth what it cost.

The Three-Number Case Study

Every case study we consider finished carries three numbers, and the framework is named after them because they are the part people leave out. The before number, the after number, and the elapsed time. Without all three, a reader has no way to judge whether the result was impressive, and no way to imagine the same thing happening to them.

1. The before number. The state of the thing when you arrived: how many hours the process took, how many enquiries went unanswered, how long onboarding ran. This is the number clients never think to record, so ask for it during scoping, not at the end.
2. The after number. The same measurement taken after the build, from the same source. Same source matters. A before figure from a client's memory and an after figure from a dashboard is not a comparison.
3. The elapsed time. How long from kickoff to live. This is the number that does the most persuading in an AI build, because a short timeline is genuinely surprising and it is the part a buyer can verify against their own experience of software projects.

If you cannot produce all three, the honest move is to write the case study qualitatively and drop the numbers entirely rather than inventing a plausible one. A vague claim reads as modest. A specific claim that turns out to be decorative reads as a lie, and the client whose logo is on the page will notice first.

WARNING: Never estimate a client's number to make the case study work. If the before figure was never measured, say so plainly: the team had not tracked this, so we recorded a baseline in week one. That sentence is credible. A rounded percentage you reverse-engineered is not, and it only has to be questioned once.

Capture the Numbers Before the Project Starts

The reason agencies have no case studies is almost never that the work went badly. It is that nobody wrote down what things looked like beforehand, and by the time the project is delivered the old state has been forgotten by everyone. The fix is administrative and takes ten minutes: make the baseline part of scoping.

• Ask the measurement question in discovery. How would you know this worked? Whatever they answer is your before number, and it is also your definition of done.
• Screenshot the current state. The old spreadsheet, the manual process, the inbox. These are the images that make a case study concrete and they stop existing the day you go live.
• Put the case study in the agreement. One line saying you may write up an anonymised summary of the work, with the client having approval over anything named. Asking at the start is routine. Asking afterwards is a favour.
• Diarise the follow-up. The real result is often visible thirty or sixty days after launch, not on delivery day. Book that check-in while you still have their attention.

This is one of the practical arguments for a properly structured scoping phase, since the same conversation that gives you an accurate quote gives you a baseline to measure against. If you are already running [a paid discovery phase](/blog/paid-discovery-phase-ai-projects), the measurement question belongs in the document you deliver.

The Six-Part Structure That Works

Use the same six parts every time and write them in this order. The consistency is the point: a reader comparing three of your case studies should be able to find the result in the same place in each, and you should be able to produce a new one in an hour rather than starting from a blank page.

1. Situation. Who the client is, in a sentence, and what their world looked like before. Industry and size, not a paragraph of praise.
2. Stakes. Why it mattered that this got fixed. What it was costing them in time, money, or missed work. This is the paragraph that makes the reader keep going.
3. Approach. What you built and the two or three decisions that made the difference. Plain language, no architecture diagrams, no listing every technology.
4. Result. The three numbers, stated flatly, plus anything that changed which cannot be counted.
5. Quote. One direct sentence from the client. Their words, not yours, and specific rather than complimentary.
6. Next step. One line inviting the reader to a conversation, with a link. A case study without a next step is a brochure.

Keep the approach section shorter than you want to. The build is the part you find most interesting and the part the buyer cares least about, and every extra technical paragraph makes the work sound more complicated than the price you are about to quote. Two decisions explained well beats a full account of the stack.

Getting a Quote Worth Printing

Ask specific questions and you get printable answers. Ask for a testimonial and you get one generic sentence about how great it was to work together, which persuades nobody because every agency page has the same one. The difference is entirely in how you ask, and the ask should happen on a call rather than by email.

• What was the most annoying part of the old process? The answer names the pain in the client's own words, which is exactly the language a similar buyer will recognise.
• What did you expect to go wrong that did not? This produces the objection-handling quote, and it is the single most useful sentence you can print.
• What would you tell someone considering this? A recommendation phrased as advice sounds like advice. Phrased as a testimonial, it sounds like marketing.
• What surprised you about the timeline? On an AI build the answer is usually about speed, and it lands better from them than from you.

Record the call with permission, pull the sentences verbatim, and send them the tidied version for approval. Never write the quote yourself and ask them to sign it off, even though they will usually agree. The specific, slightly awkward phrasing of a real client is what makes it read as real, and smoothing it out removes the only evidence that a person said it. The full process for collecting proof is in [how to get testimonials for your AI agency](/blog/how-to-get-testimonials-for-your-ai-agency).

What to Do When the Client Will Not Be Named

Write it anonymised and keep every specific except the identity. A named logo is nice. Specific numbers and a recognisable situation are what actually persuade, and you can keep all of those while replacing the client with a description. Confidentiality is a formatting problem, not a reason to have no case studies.

• Replace the name with a category. A twelve-person recruitment firm in Manchester tells the reader more than a logo they do not know.
• Keep the numbers, blur the scale if you must. A range is fine. Round numbers are fine. Removing them is not.
• Offer a reference call instead of a public quote. Many clients who refuse a written endorsement will happily speak to a prospect privately, and that converts better anyway.
• Get written permission for the anonymised version too. One email, kept on file, and it prevents the conversation you do not want to have later.

There is a second version of this problem worth naming. Some clients do not want it known that AI was involved in the work at all, which is a live consideration on this kind of build and one to settle before you write anything. The reasoning is covered in [should you tell clients you used AI](/blog/should-you-tell-clients-you-used-ai), and the safe default is that whatever you agreed privately governs what you publish.

Where the Case Study Actually Goes

A case study that only lives on a website page is doing a fraction of its job. The document is a sales asset first and a marketing page second, and its highest-value use is being sent to one specific person who has just raised the exact objection it answers.

1. Attach it to proposals. One relevant case study attached to a quote does more than three paragraphs arguing you are qualified.
2. Send it after an objection. When a prospect worries the timeline is unrealistic, the case study showing that exact timeline is the whole reply.
3. Put it on the site with the result in the heading. Not our work with Acme. The heading is the outcome, because that is what makes someone click.
4. Break it into posts. The situation is one post, the surprising decision is another, the result is a third. One case study is a month of material.
5. Use it in cold outreach. A short specific result sent to someone with the same problem outperforms any pitch, because it is evidence rather than a claim.

Two or three strong case studies will out-earn a portfolio of twenty descriptions of work, so treat them as assets to be maintained rather than pages to be filled. This is also the strongest material your website can carry, which is the argument in [what to put on your AI agency website](/blog/what-to-put-on-your-ai-agency-website), and it is what turns a first project into a second one.

TIP: Members of [Claude Code Club](https://www.skool.com/claudecodeclub) post real case studies and the outreach they were used in, so you can see which framings led to replies rather than guessing. The business track in the [curriculum](/curriculum) covers proof assets alongside pricing and proposals. It is $9 a month to join.

FAQ

How long should an agency case study be?

Under a thousand words in most cases, and one page is a good target. Buyers scan case studies looking for whether you have solved a problem like theirs and what the outcome was, so length works against you. If the detail is genuinely valuable, put the short version on the page and offer the longer write-up to anyone who asks.

What should a case study include?

Six parts in this order: the client's situation before the work, why it mattered, what you built and the key decisions, the result stated as three numbers, one direct client quote, and a clear next step with a link. The three numbers are the before state, the after state, and how long the project took from kickoff to live.

Can I write a case study without the client's permission?

Not with them named. You can write an anonymised version describing them by category and keeping the specifics, and you should still get written permission for that. The cleanest approach is to include a single line in your agreement at the start of the project giving you the right to publish an anonymised summary, with the client approving anything identifiable.

What if I do not have any results to show yet?

Write up your own builds instead. A project you built for yourself, with a real before and after, is a legitimate case study as long as you say clearly that it is your own. It demonstrates the same thing a client project does: that you can define a problem, ship something, and measure whether it worked.

How do I get a good quote from a client?

Ask specific questions on a call rather than requesting a testimonial by email. What was most annoying about the old process, what did you expect to go wrong that did not, and what would you tell someone considering this. Record with permission, pull the sentences verbatim, and send the tidied version for approval rather than writing it for them.

Should the case study mention that AI was used?

That depends on what you agreed with the client, and it is a conversation to have before you write anything rather than after. Some clients are happy for it to be a feature of the story, particularly where the timeline is the impressive part. Others prefer it left out entirely. Whatever was agreed privately governs what you publish.

• Claude Code reads screenshots. Drag an image file into the Claude Code desktop app, paste one from your clipboard, or just give it a file path in your message, and it looks at the picture instead of guessing from your description.
• Capture with Cmd+Ctrl+Shift+4 on macOS or Windows key + Shift + S on Windows, which both put a region of the screen on the clipboard. If you are in a terminal session on a Mac, paste with Ctrl+V rather than Cmd+V.
• Treat a screenshot as a specification, not a hint. The Three-Shot Rule - the broken state, the intended state, and the console - is what turns a four-round guessing game into a single fix.

How Do You Send a Screenshot to Claude Code?

Three ways, and all of them work. In the Claude Code desktop app you drag the image file onto the message box or paste it straight from the clipboard, then type what you want done. In a terminal session you paste from the clipboard with Ctrl+V. And in either place you can skip the clipboard entirely by writing the file path into your message, as in: look at /Users/me/Desktop/bug.png and tell me why the sidebar overlaps the content. Claude Code opens the file and reads it like any other file in the project.

1. Drag and drop into the desktop app. The simplest route, and the reason the desktop app is the default recommendation for this kind of work. No path to type, no shortcut to remember.
2. Paste from the clipboard. Take a region screenshot, put your cursor in the message box, paste. In the desktop app the usual paste works. In a terminal on macOS use Ctrl+V.
3. Give it a file path. Always available, never fiddly, and the only method that works identically everywhere. It is also the one to use when the image is already saved, such as a design export or a screenshot a client emailed you.
4. Point it at a folder. If you have five exported design frames, say: read every png in /Users/me/designs and describe the layout system before you write anything. It will read them in turn.

The file path method deserves more credit than it gets. It survives every quirk of every terminal, it can be repeated exactly in a later session, and it lets you keep a small folder of reference images inside the project so the next person to open it sees what you were building against. That is a real advantage over pasting, which leaves no trace.

The Three-Shot Rule

One screenshot usually starts a conversation. Three usually end one. The Three-Shot Rule is our name for the pattern that consistently gets a correct fix on the first attempt: send the broken state, the intended state, and the console together, in one message, with one sentence tying them to each other.

1. Shot one, the broken state. What the screen actually looks like right now, captured wide enough to include the surrounding layout rather than cropped tight to the fault.
2. Shot two, the intended state. The design, the mockup, a competitor page, or the same screen on a viewport where it still works. This is the shot people skip, and it is the one that removes the guessing.
3. Shot three, the console. The browser devtools console or the terminal output at the moment the problem happens. Errors that never reached your eyes are frequently the actual cause.

The sentence matters as much as the images. Something like: the first image is what I get, the second is what the design says, the third is the console at that moment. Without it, three images arrive with no stated relationship and the first thing Claude Code does is infer one, which is exactly the step you were trying to remove.

TIP: If you only have time for two of the three, send the broken state and the intended state. A difference is far more useful than a fault. It converts a diagnosis problem, which is open-ended, into a comparison problem, which is bounded.

Why Cmd+V Does Not Paste Your Screenshot

In a terminal session on macOS, use Ctrl+V rather than Cmd+V. Cmd+V is the terminal application's own paste, and it deals in text, so image data on the clipboard has nowhere to go and nothing appears. Ctrl+V is handled by Claude Code itself, which knows what to do with an image. This single keystroke is the most common reason people conclude that Claude Code does not accept screenshots at all.

• Nothing at all appeared: you almost certainly used Cmd+V in a terminal. Try Ctrl+V with the same clipboard contents.
• A file path appeared instead of an image: you copied the file in Finder rather than copying the image data. That is fine - the path works, so just send the message as it is.
• A wall of unreadable characters appeared: your terminal tried to paste raw image bytes as text. Clear the line and use the file path method instead.
• It worked yesterday and not today: check whether you are in the desktop app or a terminal. The two have different paste behaviour and they look more alike than they should.

None of this applies in the desktop app, where an image behaves like an image and drag and drop always works. That is the honest case for using the app for anything visual. The terminal is a fine place to run a build, but it is a lossy place to hand somebody a picture.

How to Capture the Right Screenshot

Capture a region to the clipboard, not a full screen to a file. Region capture forces you to decide what is relevant and it keeps the image tight enough that the important detail is legible. Both operating systems have this built in and neither needs extra software.

• Include the surrounding context. A button that is 20 pixels too low is invisible when cropped to the button. Capture the container it sits in.
• Capture at the size the problem occurs. If the bug only appears on a narrow window, resize the window first and screenshot that, rather than describing the width in words.
• Do not annotate with arrows and circles unless the target is genuinely ambiguous. A clear sentence does that job better and does not obscure pixels.
• Redact anything confidential before sending. Client names, real customer records and live keys have no business being in a screenshot, and blurring is faster than regretting it.

Turning a Design Screenshot Into Working Code

Claude Code will build a close approximation of a layout from a screenshot, and it will get the structure right far more often than the specifics. Expect the arrangement of sections, the rough hierarchy and the general spacing rhythm to come out sensible. Do not expect exact hex values, exact font names, or the spacing scale your design system already uses. Those come from you, not from the picture.

The productive framing is that a screenshot answers what goes where and your prompt answers what it is made of. Send the image, then in the same message name the stack, the component library and the file the new code belongs in. That combination is what separates a usable first draft from a generic one, and it is the same principle covered in [how to prompt Claude Code](/blog/how-to-prompt-claude-code).

NOTE: For anything with real design intent, a screenshot plus the design tokens beats a screenshot alone every time. If your project has a theme file, say so in the message: match this layout using the colours and spacing already defined in src/styles/theme.ts. You will get code that fits the codebase rather than code that merely resembles the image.

Bugs a Screenshot Explains Better Than You Can

Some faults are cheap to show and expensive to describe. Anything positional, anything about overlap, and anything where the rendered result differs from what the code appears to say falls into this group. In those cases, writing three careful paragraphs is slower and less accurate than one image, and the paragraphs introduce your own interpretation of the problem, which may be wrong.

• Layout and overlap. Elements sitting on top of each other, a footer floating halfway up the page, a modal escaping its container.
• Spacing that is off by a small amount. Nobody can describe a 6 pixel discrepancy usefully, and everyone can see it.
• Rendering that contradicts the code. The class is applied, devtools shows the rule, and the browser still does something else.
• Errors inside a third-party interface. A failed webhook page, a payment dashboard warning, a hosting build log that you cannot easily copy as text.
• Anything on a phone. Screenshot the device, send it across, and skip the entire exercise of describing a mobile viewport in words.
• Charts and visual output. Whether the axis labels collide or the legend truncates is a visual question, and it deserves a visual answer.

There is one thing to keep doing in text: error messages you can select. Copy those as text rather than screenshotting them. Text is searchable, it survives being quoted back exactly, and it costs almost nothing. Screenshot the things that only exist as pixels, and paste the things that already exist as characters. That split is covered further in [how to debug with Claude Code](/blog/how-to-debug-with-claude-code).

What Claude Code Cannot See in a Screenshot

A screenshot is one moment on one viewport with no interaction and no state. Everything outside that frame is invisible, and assuming otherwise produces confident fixes for problems you do not have. Knowing the boundary is what stops you from blaming the tool for a gap you introduced.

• Anything below the fold or off screen. If the page scrolls, only the captured part exists.
• Hover, focus, active and disabled states. A still image has no interaction in it.
• Animation and timing. A layout that flickers during load looks perfectly fine once it settles.
• Which viewport width this was. Send a second screenshot at another width, or say the width in the message.
• The network tab and the console, unless you captured them. A visual symptom with a silent underlying request failure is a routine trap.
• Your intent. The image shows what is. Only your sentence shows what should be.

WARNING: Watch for confident fixes to invisible causes. If a suggested change does not match what you know about the code, say so rather than applying it. A screenshot narrows the problem, it does not prove the diagnosis, and the review habit in [review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship) applies here exactly as it does anywhere else.

Let Claude Code Take Its Own Screenshots

You can remove yourself from the loop entirely by connecting a browser automation MCP server, which lets Claude Code open a page, capture it, and look at the result of its own change. That turns a back-and-forth into a loop it can run alone: make the change, load the page, screenshot it, compare against the target, adjust. You go from being the eyes to being the reviewer.

• It sees the actual rendered result rather than reasoning about what the CSS should produce.
• It can check several viewport widths in a row without you resizing anything by hand.
• It closes its own feedback loop, which is what makes unattended visual work possible at all.
• It removes the slowest part of visual debugging, which was never the thinking - it was you screenshotting, pasting, and describing.

This is worth setting up once and then forgetting about, and it is one of the few MCP servers that changes the shape of the work rather than just adding a capability. We cover the setup and which servers are worth the trouble in [the best Claude Code MCP servers](/blog/best-claude-code-mcp-servers). Start manual, get comfortable with the Three-Shot Rule, then automate the shots you are tired of taking.

Screenshots Cost Context, So Spend Them Deliberately

Images consume context, and more of it than an equivalent sentence does. Two or three well-chosen screenshots are a good trade. Twelve dumped in at once are not, because you crowd out the code and the project instructions that the answer actually depends on, and quality drops for reasons that look mysterious from the outside.

• Send the smallest set that makes the difference visible. Usually two images, occasionally three.
• Crop to the relevant region. A full 5K display screenshot spends context on your dock and your open tabs.
• Do not resend an image that is already in the session. Refer back to it: in the first screenshot I sent, the header was 8 pixels too tall.
• Start a fresh session for a new visual problem rather than accumulating images across an afternoon.

The general discipline behind this - deciding what earns a place in the window and what does not - is the single habit that most improves results over a long session, and it is the subject of [Claude Code context management](/blog/claude-code-context-management). Screenshots are just one more thing competing for the same finite space.

A Screenshot Workflow That Holds Up

Here is the whole thing as a routine you can run without thinking about it. It takes under a minute and it replaces the most tedious loop in front-end work, which is describing a visual problem to somebody who cannot see it.

1. Reproduce the problem on screen and leave it there. Do not fix the window size afterwards.
2. Capture the broken state as a region to the clipboard, wide enough to show the surrounding layout.
3. Capture the intended state - the design, the mockup, or the working version - as a second image.
4. Open devtools, capture the console at that moment as a third image if there is anything in it.
5. Paste all three into one message. In the desktop app just drag them in.
6. Write one sentence naming what each image is and what you want changed. Name the file if you know it.
7. Read the proposed change before applying it, and say so if the diagnosis contradicts what you know about the code.

That is the Three-Shot Rule in practice. It is not clever, and that is the point: it removes the two failure modes that cause almost all wasted rounds, which are an undescribed difference and an unread console. Once it is a habit you stop noticing you are doing it, and visual bugs stop being the part of the job you put off until the afternoon.

TIP: Inside [Claude Code Club](https://www.skool.com/claudecodeclub) members post the actual screenshots and the actual prompt that fixed them, which is a much faster way to learn this than reading about it. If you want the structured path first, the [curriculum](/curriculum) covers the visual workflow alongside the rest. It is $9 a month to join.

FAQ

Can Claude Code read screenshots and images?

Yes. You can drag an image file into the Claude Code desktop app, paste one from your clipboard, or write the file path into your message and let it open the file itself. It reads the picture directly, which is why sending a screenshot of a broken layout works better than writing a paragraph describing it. The file path method is the most reliable because it behaves identically in the desktop app and in a terminal.

How do I paste a screenshot into Claude Code on a Mac?

Capture a region to the clipboard with Cmd + Ctrl + Shift + 4, then paste. In the desktop app the normal paste works. In a terminal session use Ctrl+V rather than Cmd+V, because Cmd+V is the terminal application's own text paste and image data on the clipboard has nowhere to go. If nothing appears at all, that keystroke is almost always the reason.

Can Claude Code build a page from a design screenshot?

It will produce a close first draft of the layout, and it reliably gets structure and hierarchy right. It will not infer your exact hex values, font family or spacing scale from a picture, so supply those in the same message by naming your theme file or your design tokens. Send the image for what goes where, and write the prompt for what it is made of.

How many screenshots should I send at once?

Two or three, chosen deliberately. The pattern we use is the Three-Shot Rule: the broken state, the intended state, and the console. Images consume context, so a dozen at once crowds out the code and project instructions the answer depends on, and quality quietly drops. Crop each one to the relevant region rather than sending a full display capture.

Should I screenshot an error message or copy the text?

Copy the text whenever the error is selectable. Text is searchable, it can be quoted back exactly, and it costs far less context than an image. Screenshot the things that only exist as pixels - layout faults, overlap, spacing, third-party dashboards you cannot copy from, and anything on a phone. The split is simple: paste characters, screenshot pixels.

Can Claude Code take screenshots itself?

Yes, with a browser automation MCP server connected. It can open a page, capture it, compare the result against the target and adjust without you taking the screenshot each round. That closes the visual feedback loop, which is the slowest part of front-end work. Set it up after you are comfortable with the manual pattern, not before.

• Charge for discovery on anything you cannot quote confidently after one conversation. Keep the first call free to qualify, then sell a fixed-fee discovery phase that produces a written scope, and credit that fee against the build if they proceed.
• Price it as a percentage of the build you expect to quote, roughly a tenth, with a floor that makes it worth doing. Delivered in days, not weeks, and paid before you start.
• The Handoff Test is how you know it is sellable: if the client could hand your discovery document to a different builder and get a usable quote from it, you have made something worth paying for. If they could not, you wrote a sales proposal and called it discovery.

Should You Charge for a Discovery Phase?

Yes, for any project you cannot price confidently after a single conversation. Keep the first call free, because that call is qualification and it is your job to establish whether there is a project at all. Everything after it - the requirements, the data model, the integration list, the risks, the written scope - is work, and work that a competent client can see the value of. Charge a fixed fee, deliver in days, and credit the fee against the build if they go ahead.

The reason to do this is not that discovery is hard, though it is. It is that free scoping puts you in an impossible position: you have to do enough thinking to quote accurately, while being paid nothing for it, while competing against people who will guess a number quickly and adjust later. Charging removes all three problems at once. You get paid for the thinking, you take the time to do it properly, and you stop competing on speed of guessing.

The Handoff Test

Here is the standard we hold discovery to. Could the client take what you delivered, hand it to a completely different builder, and get an accurate quote from it without talking to you? If yes, you produced something with independent value and the fee was obviously fair. If no, you produced a sales document with a price tag on it, and the client will feel that even if they cannot name it.

That test is uncomfortable on purpose. It rules out the version of paid discovery that is really just a proposal with extra pages, and it forces the deliverable to contain the specific things another builder would need: what is being built, what it connects to, what the data looks like, what is explicitly out of scope, and where the risk sits. Write it so it survives you leaving, and you never have to defend the invoice.

TIP: There is a commercial upside to passing the Handoff Test that is easy to miss. A client who genuinely could take the document elsewhere and does not is a client who chose you on merit rather than on lock-in. That is a much better position to start a build from, and those projects run more calmly.

What a Paid Discovery Actually Delivers

A document and a number. The document says what is being built and what is not. The number is a fixed-price quote for the build, or a tight range with the conditions that would move it named explicitly. Anything less and you are selling a meeting. These are the sections that earn the fee.

• The outcome in one paragraph, in the client's own language, agreed with them before anything else is written.
• A feature list split into in-scope, out-of-scope, and later. The out-of-scope list is the most valuable part of the entire document and the part clients read twice.
• The integration list: every external system involved, who owns access to it, and whether that access has actually been confirmed rather than assumed.
• The data model at a level a non-technical person can follow. What records exist, what they contain, and who is allowed to see them.
• The risk list: what could make this take twice as long, with a plain statement of what happens to the price if it does.
• A build quote and a delivery window, with the assumptions the numbers rest on written next to them.

The out-of-scope list is where most of the future arguments get prevented. Scope creep does not usually arrive as a big new demand, it arrives as a small thing that everyone assumed was included. Writing down what is not included, during a phase the client is paying for, is the cheapest insurance available, and it works alongside the practices in [how to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects).

How to Price a Discovery Phase

Price it as a proportion of the build you expect to quote - around a tenth is a workable rule - with a floor low enough that a client will say yes without a committee and high enough that you will take it seriously. Fixed fee, never hourly. Paid before you start, not on delivery. And credited against the build if they proceed, which is what makes it an easy yes rather than a second decision.

Crediting the fee against the build is doing more work than it looks. It reframes the decision from should I pay for scoping into should I put down a deposit, which is a decision clients already know how to make. It also means that the only person who is out of pocket is the one who does not proceed, which is exactly the person you wanted to charge in the first place.

If you are also still working out the build number itself, price the two together rather than in sequence. The discovery fee should follow from the build quote, not float free of it, and the reasoning behind the build quote is covered in [how to price a Claude Code agency project](/blog/how-to-price-a-claude-code-agency-project).

Free Call or Paid Discovery: Where the Line Sits

The line is between finding out whether there is a project and working out what the project is. The first is sales and it is on you. The second is consulting and it is on them. Most builders draw this line far too late, then wonder why they spend two unpaid weeks on deals that never close.

The free call still needs to be a good one, because it is where you decide whether to offer discovery at all. The questions that make it useful are the same ones in [client discovery questions before you quote](/blog/client-discovery-questions-before-you-quote) - you are just asking them to qualify rather than to scope, and stopping the moment the answers start requiring real work to obtain.

How to Sell It Without Losing the Deal

Present it as the first phase of the project rather than as a gate before the project. The wording that works is close to this: the honest answer is that I cannot give you a firm price yet without understanding the integrations properly. What I would suggest is a scoping phase, fixed fee, delivered in a week, and you end up with a written scope and a fixed quote. If we go ahead with the build, that fee comes off the total.

• Lead with the reason, not the fee. The reason is that a firm price requires real work, and clients accept that immediately when it is said plainly.
• Say the deliverable out loud. A written scope and a fixed quote is a thing. A discovery phase is not, until you describe it as one.
• Name the credit in the same breath as the price. Left to a second sentence, it sounds like a concession you were forced into.
• Give it a short, specific duration. A week sounds like a project. A few weeks sounds like a delay.
• Do not apologise anywhere in the paragraph. The moment you sound uncertain about charging, they become uncertain about paying.

If the discovery offer sits inside a written document, keep it to a single page with the deliverable, the fee, the timeline and the credit visible without scrolling. The structure that does this well is the same one in [the one page AI proposal that closes](/blog/one-page-ai-proposal-that-closes), just aimed at a smaller decision.

Why Free Scoping Costs You the Project

Free scoping does not just cost you the hours. It costs you the deal, in a way that is almost invisible while it is happening. Because the work is unpaid, you rush it. Because you rushed it, the quote carries padding you cannot justify. Because the number looks padded, the client negotiates. And because you have already sunk a week into it, you accept less than you should to avoid wasting the week.

1. You do the thinking anyway, but compressed into the gaps between paid work, which is where mistakes come from.
2. You quote defensively. Unknowns become contingency, contingency becomes a bigger number, and the bigger number invites the price conversation.
3. You have no leverage in that conversation, because the sunk cost is entirely yours and both of you know it.
4. Nothing is on paper, so the scope stays negotiable throughout the build and every assumption resurfaces later as a request.
5. Serious buyers and tyre-kickers get identical effort from you, which means the tyre-kickers are subsidised by your real clients.

That last one is the argument that usually lands. Somebody is paying for all that free scoping, and it is the clients who did say yes. Charging for discovery moves the cost onto the person creating it, which is the ordinary way every other professional service works.

WARNING: The tell that you have been scoping for free is a quote you cannot defend line by line. If a client asks why the number is what it is and your honest internal answer is that it felt about right, you did not scope the project - you estimated your own anxiety about it.

When Not to Charge for Discovery

This is not a universal rule and treating it as one will cost you work. Skip the paid phase when the project is small enough to quote from a conversation, when the client is already yours, or when you genuinely want the relationship for reasons beyond this one project. Judgment beats policy here.

• Small fixed-scope jobs. If you can quote it accurately in one call, charging to scope it looks like friction for its own sake.
• Existing clients. You already know their systems and their people, which is most of what discovery buys. Fold the scoping into the work.
• Work you want for the case study. If the reference is worth more to you than the fee, decide that deliberately and say nothing about it.
• Very early conversations. Discovery is offered after the free call establishes that there is a real budget and a real problem, never before.
• Anything you would decline at full price. A paid discovery is not a way to make a bad project tolerable.

There is also a version of this that scales down neatly. Not every project needs a week of scoping, and a short paid audit with a two-page write-up is often the right size for a smaller build. The principle survives the shrinking: the client pays for the thinking, and the thinking arrives as a document.

What Happens If They Do Not Buy the Build

You got paid, they got something useful, and you found out cheaply that they were not going to proceed. That is a good outcome, not a failed sale, and the sooner you believe that the easier the whole model becomes to run. The alternative outcome - two unpaid weeks and the same answer - is strictly worse in every direction.

• Deliver the document properly regardless. Half-delivering because you sense they are drifting is the one move that turns a neutral outcome into a bad reputation.
• Ask for the reason and record it. A pattern in why clients stop after discovery tells you something real about your positioning or your pricing.
• Follow up on a calendar, not on a feeling. Budgets return, and a discovery document ages well because the problem is usually still there.
• Treat it as a paid case study. You now have a full picture of a real project and a client who paid you, which is a stronger reference than most free work produces.

Some of these come back months later with the same document and a signed budget. That only happens if the follow-up is systematic rather than sentimental, which is the argument in [how to follow up with a client without being annoying](/blog/how-to-follow-up-with-a-client-without-being-annoying). A discovery client is the easiest person on your list to follow up with, because there is a specific artefact to reference.

Running the Discovery Phase Itself

Keep it tight and finish it. The failure mode is not underpricing, it is letting a week become a month while you wait for access to a system nobody can find the credentials for. Set the shape before you start and hold it.

1. Take payment and send a short agreement naming the deliverable, the duration and what you need from them.
2. Ask for access on day one. Systems, credentials, the existing codebase, the person who actually knows how the current process works.
3. Run one structured session with the people who use the thing, not only the person who is buying it.
4. Write the out-of-scope list before the in-scope list. It is faster, and it exposes disagreements while they are still cheap.
5. Send a draft mid-way and ask for corrections. Nothing in the final document should be a surprise on delivery day.
6. Deliver the document and the quote together, walk them through it live, and ask for the decision on that call.

Delivering it live matters more than it sounds. A document sent by email gets skimmed, filed, and discussed without you in the room. Walked through on a call, it becomes a conversation about the build, and the build quote is right there in front of both of you at the moment the client is most convinced that you understand their problem. That is the same reason kickoff works better live, as covered in [the client kickoff call for an AI build](/blog/client-kickoff-call-ai-build).

TIP: Members of [Claude Code Club](https://www.skool.com/claudecodeclub) share the actual discovery documents and the wording that got them signed, which beats writing your first one from a blank page the night before a call. The business track in the [curriculum](/curriculum) covers where paid discovery sits alongside pricing and proposals. It is $9 a month to join.

FAQ

What is a paid discovery phase?

A short fixed-fee engagement, usually days rather than weeks, in which you work out exactly what is being built and produce a written scope with a firm price attached. It sits between the free qualifying call and the build itself. The client pays for the thinking, owns the resulting document, and normally has the fee credited against the build if they proceed.

How much should I charge for discovery?

A workable rule is around a tenth of the build price you expect to quote, with a floor low enough to be an easy yes and high enough that the work is worth doing properly. Always a fixed fee rather than hourly, because hourly reintroduces the argument about time that paid discovery exists to end. Take payment before you start.

Should the discovery fee be credited against the build?

Yes, in full, and say so at the moment you name the price. Crediting it turns the decision from should I pay for scoping into should I put down a deposit, which clients already know how to make. It also means the only person out of pocket is the one who does not proceed, which is precisely who you wanted to charge.

What if the client refuses to pay for discovery?

Take it as information rather than as an objection to overcome. A client who will not fund a small fixed-fee phase is unlikely to fund a build, and you learned that for the cost of one conversation instead of two unpaid weeks. If the project is small enough to quote from a single call, quote it and skip discovery entirely.

How long should a discovery phase take?

Days, not weeks. Around a week is the shape most builds want, and smaller projects can be scoped in two or three days with a shorter write-up. The risk is not underpricing it, it is letting the phase drift while you wait for system access, so ask for credentials and contacts on day one and hold the end date you promised.

Is paid discovery the same as a proposal?

No, and the difference is the Handoff Test. A proposal is a sales document that argues for hiring you. A discovery deliverable is a specification that another builder could quote from without ever speaking to you. If what you are producing fails that test, you are charging for a proposal, and clients can feel the difference even when they cannot articulate it.

• Claude Code on Windows runs natively on Windows 10 build 1809 or later, or Windows Server 2019 or later, on x64 or ARM64 hardware with 4 GB of RAM or more, and it works in Bash, Zsh, PowerShell or CMD.
• The desktop app from claude.com/download is the default recommendation because it gives you Claude Code with no terminal at all; the native installer, WinGet and npm are still there if you want the command line as well.
• Sandboxing is supported on WSL 2 but not on native Windows or WSL 1, and Git for Windows is optional - without it Claude Code runs shell commands through the PowerShell tool rather than Git Bash.

Does Claude Code Work on Windows?

Yes. Claude Code on Windows works natively, with no WSL, no virtual machine and no dual boot. You need Windows 10 build 1809 or later, or Windows Server 2019 or later, running on x64 or ARM64 hardware with 4 GB of RAM or more. Supported shells are Bash, Zsh, PowerShell and CMD. The fastest way in is the desktop app from claude.com/download, which runs Claude Code without a terminal. You also need a Pro, Max, Team, Enterprise or Console account.

• Operating system: Windows 10 build 1809 or later, or Windows Server 2019 or later.
• Hardware: 4 GB of RAM or more, on x64 or ARM64. Both architectures are supported, so a Windows on ARM laptop is fine.
• Shell: Bash, Zsh, PowerShell or CMD. Any of the four works, and which one you have open matters mainly during install.
• Account: Pro, Max, Team, Enterprise or Console. The free Claude.ai plan does not include Claude Code access.

That last line catches more people than any technical requirement does. The install itself will complete perfectly on a free account, because installing software and having access to it are separate things. If everything looks correct and you still cannot get a session going, check the plan before you touch anything else.

For a lot of Windows users the honest recommendation is to stop reading after the desktop app. It installs like any other Windows application, it does not ask you to think about shells or PATH variables, and it is the version most people should be using day to day. The terminal install is optional and you can add it later without undoing anything you have already done.

Native Windows or WSL: Which One to Choose

Choose native Windows unless you specifically need sandboxing or you already work inside WSL. Native Windows needs nothing extra installed, and Git for Windows is optional rather than required. WSL 2 needs WSL 2 enabled on the machine before you start. The one genuine functional difference is sandboxing: it is supported on WSL 2, and it is not supported on native Windows or on WSL 1.

WARNING: WSL 1 is the trap. Sandboxing is supported on WSL 2 and is not supported on WSL 1, so an older WSL install costs you all of the extra setup and gives you none of the one feature that justified it. If you are going to use WSL for this, make sure it is WSL 2.

On native Windows, where sandboxing is not available, the control you actually rely on is the permission system - what Claude Code is allowed to run without asking you first. That is worth setting up deliberately rather than by clicking through prompts, and we walk through it in [claude code permissions explained](/blog/claude-code-permissions-explained). It matters more on Windows precisely because you do not have the sandbox as a second layer.

How to Install Claude Code on Windows

There are two routes and the desktop app is the default one. Download it from claude.com/download and it installs like any other Windows application, with no terminal, no package manager and no PATH to reason about. If you also want the command line version, there are three installers to pick from: the native script, WinGet, or npm.

Start with the app. It is the version that gets used, because it is the version that opens without a decision attached to it. We covered what it does and does not give you in [the Claude Code desktop app](/blog/claude-code-desktop-app), and the short version is that it lets you use Claude Code without the terminal entirely.

1. PowerShell, native install: irm https://claude.ai/install.ps1 | iex . This is the one to use if you are not sure. You do not need to run PowerShell as Administrator.
2. CMD, native install: curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd . Same outcome, written for CMD syntax, and it cleans up the downloaded file after itself.
3. WinGet: winget install Anthropic.ClaudeCode . Use winget upgrade Anthropic.ClaudeCode later when you want a newer version.
4. npm: npm install -g @anthropic-ai/claude-code . As of v2.1.198 the npm package requires Node.js 22 or later. Never install it with sudo.

NOTE: Native installs update themselves in the background. WinGet installs do not - you stay on whatever version you installed until you run winget upgrade Anthropic.ClaudeCode yourself. Neither is wrong, but if you pick WinGet, write that upgrade command down somewhere you will actually see it again.

Once it is installed, the setup that matters is not the installer at all, it is what you do in the first hour of your first project. [Claude Code day one setup](/blog/claude-code-day-one-setup) covers that part, and it is identical on Windows and macOS.

Do You Need Git for Windows?

No. Git for Windows is optional on native Windows and Claude Code works fine without it. What changes is how shell commands run. With Git for Windows installed, Claude Code uses Git Bash for the Bash tool. Without it, Claude Code runs shell commands through the PowerShell tool instead. Both are supported. Installing Git is worth it mainly if you want the Bash behaviour to match tutorials written on macOS or Linux.

If Git for Windows is installed and Claude Code cannot find Git Bash, point it at the executable directly. Set CLAUDE_CODE_GIT_BASH_PATH in your settings.json to the full path, for example C:\\Program Files\\Git\\bin\\bash.exe. Notice the doubled backslashes. settings.json is JSON, and a single backslash is an escape character in JSON, so a path copied the way Windows displays it will not parse and the setting will look like it was ignored.

This is the single most Windows-specific thing in the whole setup, and it is worth understanding rather than copying. Any Windows path you put into any JSON settings file has the same rule. If a setting that takes a path appears to do nothing, count the backslashes before you assume the setting is broken.

Why Your Install Command Errored

Almost always because a command written for one shell was pasted into the other. PowerShell and CMD are different shells with different syntax, and Windows opens both of them in similar looking windows. Two specific error messages tell you exactly which shell you are in. The fix is not to change the command, it is to change the window you are typing into.

You can check which shell you have before you paste anything. The PowerShell prompt begins with PS, as in PS C:\. The CMD prompt is the same path without it, so just C:\. That two-letter difference is the entire diagnosis, and it saves the loop of running the same failing command again slightly differently.

One more thing worth ruling out: neither native install command needs Administrator rights. If you hit a permissions error, opening an elevated prompt and trying again is not the intended fix and usually is not the problem either. Read the first line of the error rather than the whole block, and match it against the table above.

How to Verify the Install Worked

Run claude --version. If Claude Code is installed and reachable it prints a version string, something along the lines of 2.1.211 (Claude Code). If you want more detail, run claude doctor, which prints read-only diagnostics about your install and your settings without starting a session. Read-only is the useful part: you can run it as often as you like while troubleshooting and it will not change anything underneath you.

• claude --version confirms the binary exists and is on your PATH. If this errors, the problem is the install or the PATH, not your settings.
• claude doctor reports on install and settings together and does not start a session, so it is the right first command when something is behaving oddly.
• If you installed the desktop app, opening it and starting a session is its own verification. If it opens and connects, you are finished.
• If the binary is clearly installed and sessions still will not start, check the account tier. Claude Code needs Pro, Max, Team, Enterprise or Console.

Removing it again is equally plain, and knowing how is also how you learn where things went. Uninstalling from PowerShell on Windows removes $env:USERPROFILE\.local\bin\claude.exe and $env:USERPROFILE\.local\share\claude. Those two paths are the binary and its data, and checking whether they exist is a quick way to confirm a native install actually landed.

What Is Different on Windows Compared to Mac

Less than people expect, and the differences all sit at the edges rather than in the work. The install commands differ. Sandboxing is available on WSL 2 and not on native Windows or WSL 1. Shell commands run through Git Bash or the PowerShell tool depending on whether Git for Windows is installed. The sessions themselves - how you talk to Claude Code, what it reads, what it asks permission for - are the same product.

• Install: irm https://claude.ai/install.ps1 | iex or winget install Anthropic.ClaudeCode on Windows, different commands elsewhere. Identical software afterwards.
• Sandboxing: supported on WSL 2, not supported on native Windows or WSL 1. On native Windows your permission rules are the layer doing that job.
• Shell tooling: Git Bash for the Bash tool when Git for Windows is installed, the PowerShell tool when it is not.
• Paths in settings.json: Windows paths need doubled backslashes, because the file is JSON and a lone backslash escapes the next character.
• Everything else: your project instructions file, your slash commands and your permission rules behave exactly as they do on any other machine.

The practical upshot is that Windows is a first-class place to run this, and most of the friction people report is one of three things: the wrong shell during install, a path written without escaped backslashes, or an account tier that does not include Claude Code. None of those are Windows being difficult. They are just the three places Windows differs enough to catch you once.

TIP: Claude Code Club has Windows users in it, which sounds like a small thing until you have spent an evening searching a problem and found nothing but macOS terminal output. Members swap the Windows-specific answers - PowerShell versus CMD, WSL 2 setup, Git Bash paths that will not resolve - alongside everything else. It is $9 a month to join.

FAQ

Does Claude Code run on Windows without WSL?

Yes. Native Windows is fully supported and needs nothing extra installed - no WSL, no virtual machine, no dual boot. Git for Windows is optional rather than required. The only capability you give up by staying native is sandboxing, which is supported on WSL 2 but not on native Windows or WSL 1. For most people the tradeoff favours staying native and using permission rules instead.

What are the system requirements for Claude Code on Windows?

Windows 10 build 1809 or later, or Windows Server 2019 or later, on x64 or ARM64 hardware with 4 GB of RAM or more. Supported shells are Bash, Zsh, PowerShell and CMD. Separately from the hardware, you need a Pro, Max, Team, Enterprise or Console account, because the free Claude.ai plan does not include Claude Code access even though the software will install without complaint.

Should I install Claude Code with WinGet or the native installer?

Both work, and the difference is updates. Native installs update themselves in the background. WinGet installs do not, so you stay on the version you installed until you run winget upgrade Anthropic.ClaudeCode yourself. If you want it to look after itself, use the native installer with irm https://claude.ai/install.ps1 | iex in PowerShell. If you already manage your software through WinGet, staying consistent is a reasonable trade.

Why does my Claude Code install command fail in PowerShell?

Because you are running the CMD version of the command. If the error mentions that the token && is not a valid statement separator, you are in PowerShell and should run irm https://claude.ai/install.ps1 | iex instead. The reverse error, that irm is not recognized, means you are in CMD and want the curl install.cmd command. Check the prompt: PowerShell begins with PS, CMD does not.

Do I need Git for Windows to use Claude Code?

No. It is optional. With Git for Windows installed, Claude Code uses Git Bash for the Bash tool. Without it, shell commands run through the PowerShell tool instead, which is fully supported. If Git is installed but cannot be found, set CLAUDE_CODE_GIT_BASH_PATH in settings.json to the full path of bash.exe, remembering to double every backslash because JSON treats a single one as an escape character.

• Tell them, and tell them early. Disclosure in the proposal or the discovery call reads as a description of your method, while the same fact discovered after delivery reads as something you were caught hiding.
• Clients asking about AI are rarely asking a philosophical question. They are asking whether it will break, who fixes it when it does, and whether they are paying developer rates for something that took you an afternoon.
• One sentence is enough: I build with AI tooling, I review and test everything myself, and I stand behind the result. Put it in the proposal and it never has to become a conversation later.

Should You Tell Clients You Used AI?

Yes, tell them - and put it in the proposal or the discovery conversation rather than in an email after delivery. You are not confessing to something. You are describing how you work, the same way you would name a hosting provider or a framework. The disclosure itself is almost never what damages a relationship. The timing is. A client who hears it up front hears a method. A client who works it out afterwards hears a secret.

I have watched both versions of this happen to builders I know. The ones who put a line in the proposal get a shrug, occasionally a question, and then the project proceeds. The ones who said nothing and got asked about it in month two spent the rest of the engagement defending work that was already finished and already fine. Nothing about the code changed between those two outcomes. Only the order of the sentences did.

Hiding It Is the Actual Risk

The exposure runs in the opposite direction to how most builders feel it. Disclosing costs you an occasional awkward question in a discovery call. Not disclosing costs you the relationship on the day it surfaces, and it does surface, because software has a long tail and you are not the last person who will ever look at that codebase.

• Their own developer reads the repository when the project is handed over, and forms a view without you in the room.
• You mention a tool by name on a call, casually, six weeks in, and the client connects it to a question you dodged earlier.
• A bug appears and needs explaining, and the explanation would be simple if you had not created a reason to be careful about how you word it.
• They hire someone else later to extend the work, and that person tells them a story about how it was built.
• Your own website talks about building with AI while your proposals do not mention it. Clients read both.

Here is the part that actually hurts. Once it is discovered rather than disclosed, the AI stops being the subject of the conversation. Your judgment becomes the subject. The client is no longer asking whether AI-assisted code is acceptable, they are asking what else they were not told, and that is a much harder question to answer well.

WARNING: If you would feel uncomfortable if the client learned how the work was built, that discomfort is information. It is not telling you to hide it better. It is telling you that you have not yet worked out how to describe your own process in a way you can stand behind, and that is worth fixing before the next proposal goes out.

How to Say It in One Sentence

One sentence, stated plainly, positioned as method rather than caveat. Something close to: I build with AI tooling as part of my process, I review and test everything that ships, and I stand behind the result the same way I would if I had typed every line. That is the whole disclosure. It names the tool, names the accountability, and does not invite a debate.

• In a proposal: one line in the how I work section, sitting alongside your stack and your process. Not a disclaimer at the bottom in smaller type.
• On a discovery call: said in passing while you describe your process, in the same tone as everything else you say about it.
• In the contract scope: a plain statement that AI tooling forms part of the delivery method, so it is on the record before anyone signs.
• When asked directly mid-project: answer in one sentence and then carry on. Length reads as guilt, and a short confident answer usually ends the topic.

What makes that sentence work is the second half of it. Any builder can say they use AI. The part the client needs is that a named human reviewed it, tested it, and remains responsible for it. If you only say the first half, you have handed them the worry without the reassurance. Your [one page AI proposal](/blog/one-page-ai-proposal-that-closes) is the natural home for it, because a proposal is already a document about method.

What Clients Are Really Asking When They Ask

When a client asks about AI, they are almost never opening a debate about creativity or authorship. They are asking three practical questions in a single awkward sentence, and if you answer the literal question rather than the real ones, you leave them exactly as worried as they were before.

1. Is this going to break? They have heard that AI-generated code can be fragile. Answer it by describing what you test and how you verify, not by defending the tool.
2. Who fixes it when it does break? This is the one that actually keeps them up. Name the support arrangement, and say plainly that they call you, not a chatbot.
3. Am I paying developer rates for something you generated in an afternoon? This is the question nobody says out loud. Answer it before they have to ask it.
4. Where does my material go? For clients with confidential documents, customer data or unreleased product information, this is a legitimate operational question and deserves a specific answer rather than reassurance.

Answer the question underneath the question and the surface question dissolves. That fourth one in particular rewards being able to speak specifically about what stays local, what is sent where, and what your permission setup allows - which is the ground covered in [is Claude Code safe for client work](/blog/is-claude-code-safe-for-client-work). A concrete answer here does more for a client's confidence than any amount of general reassurance.

Up Front Versus Discovered Later

The same facts land completely differently depending on when the client learned the context. This is not a psychological trick, it is just how trust works: information volunteered is read as transparency, and identical information uncovered is read as something that was being managed.

Nothing in the left column is different from the right column except sequence. That is the entire argument for early disclosure, and it is why the right place for it is the proposal or the first real conversation, when nothing has been delivered yet and there is nothing for the information to retroactively reframe.

When Disclosure Is Not Optional

Sometimes this is not a judgment call at all. The client's contract, their vendor policy, or the terms of their own client's agreement can make disclosure a hard requirement, and in those cases the decision was made before you were asked. Read the paperwork before you assume it is silent on the subject.

• The agreement you sign. Look for clauses on third-party tools, subprocessors, confidentiality, and who owns what is delivered.
• Their internal AI policy. Larger organisations increasingly have one, and it usually applies to contractors as well as staff.
• Their procurement or security questionnaire. If they send one, the disclosure question is often already in it, and answering it inaccurately is a different category of problem entirely.
• The contract above yours, if you are subcontracting through an agency. Their obligations to their client flow down to you whether or not anyone mentioned it.

Then there is the client who says plainly that they do not want AI used. Before you decline or agree, find out what they mean, because the phrase covers several different concerns. Some mean no AI-generated content published under our name. Some mean our confidential material must not be sent to an outside service. Some are reacting to something they read and have not thought past it. Those are three different requirements and only one of them is genuinely incompatible with how you work.

WARNING: The one move that is never available is agreeing to no AI and then using it quietly. That converts a disagreement about tooling into a breach of what you agreed, and it is the version of this that ends in a refund conversation or worse. If the requirement is real and you cannot meet it, say so and decline the work.

How to Answer: Why Does It Cost That If AI Wrote It?

Because they are buying a working outcome and someone accountable for it, not a quantity of typing. The honest answer is short: the price reflects what the thing is worth to their business and the fact that it is my name on it, not how many hours it took to produce. Said calmly, in one breath, that usually settles it. Said defensively, it never does.

It helps to be specific about what the money is actually paying for, because the client has genuinely lost sight of it in that moment. They are paying for the scoping conversation that decided what to build. For the judgment about what not to build, which is where most of the savings actually live. For the review and the testing. For the evening you spend fixing something urgent. And for the fact that a person, not a tool, carries the consequence if it goes wrong.

If this question keeps arriving, look at how you price rather than how you explain. Hourly billing makes the question unanswerable by design, because you have told the client that hours are the product and then handed them a reason to believe the hours went down. That is the argument for [pricing the outcome instead of the hour](/blog/stopped-charging-hourly-for-ai-builds), and it removes the objection at the source rather than talking past it every time.

None of this is about having a clever line ready. It is about having decided, before anyone asks, that how you build is a normal part of what you sell. Builders who have decided that answer the AI question in a sentence and get on with the work. Builders who have not, negotiate against themselves in every discovery call they take.

TIP: Inside Claude Code Club, members share the exact wording they use for this - the proposal lines that get signed, and the answers that land when a client pushes back on price. Reading three versions that already worked beats writing your own from scratch the night before a call. It is $9 a month to join.

FAQ

Do I have to tell clients I used AI?

It depends on what you agreed to. Check the contract, their vendor or AI policy, and any security questionnaire they sent, because disclosure obligations are often already written down. Where the paperwork is silent it becomes a judgment call, and disclosing early is the safer side of that call. If your agreement does say something specific, follow it rather than a general rule of thumb.

What if a client says they do not want AI used at all?

Ask what they mean before you respond. The phrase usually covers one of three concerns: no AI-generated content published under their name, no confidential material sent to outside services, or a general unease they have not examined. The first two can often be worked with. If the requirement is genuinely incompatible with how you build, decline the project rather than agreeing and doing it quietly anyway.

How do I disclose AI use without sounding like I am apologising?

Keep it to one sentence and say it in the same tone as the rest of your process. Name the tooling, then name your accountability: you review and test everything and you stand behind the result. Put it in the how I work section of the proposal, not in a disclaimer at the bottom. Length signals discomfort, so a short confident line usually ends the topic immediately.

Will telling clients I used AI make them want to pay less?

Only if your pricing is built on hours. If you sell time, disclosing that the work went faster hands the client an argument, and they will use it. If you price the outcome, the tooling is simply how the outcome gets produced and the conversation does not arise. The disclosure is not the problem in that scenario - the pricing model is what created the opening.

When in a project should I bring up AI?

In the proposal or the discovery conversation, before anything is delivered. At that point there is no finished work for the information to reframe, and the client evaluates it as part of your method alongside everything else. The worst possible moment is after delivery or during a bug, when the same fact arrives with a reason attached and gets read as an explanation rather than a description.

• You can build a working WordPress plugin with Claude Code in an afternoon, because WordPress already supplies the admin, the database, the users and the theme. Your plugin is only the missing behaviour, which is a much smaller build than it sounds.
• The whole outcome is decided by four answers you give before you prompt: what the plugin does, where in WordPress it appears, what it stores, and who is allowed to use it. Skip those and the agent invents them for you, usually wrongly.
• The traps are WordPress-specific rather than AI-specific: unprefixed function names, missing capability checks, unsanitised input, and code that assumes a plugin is the only thing running on the site. Review for those four every time.

Why a WordPress Plugin Is a Good Build to Do With Claude Code

A WordPress plugin is a small amount of code that plugs into a large amount of existing application. The login system, the database layer, the admin interface, the user roles, the media handling and the front-end theme are already there and already work. Your plugin adds one behaviour on top. That is a genuinely small surface, which is exactly the shape of build an agent handles well.

It is also a build with a real audience attached. An enormous share of the small-business web runs on WordPress, which means a plugin that solves one specific annoyance has customers who already have the platform installed. Compared with a standalone app where you have to persuade someone to sign up for anything at all, the distance between a working plugin and someone actually using it is short.

NOTE: The framing that makes this easy: you are not building an application. You are writing the paragraph that WordPress is missing. Every time the agent starts building something WordPress already provides - its own user table, its own settings screen, its own file uploader - stop and point it at the existing one.

Answer These Four Questions Before You Prompt

The quality of the plugin is decided before you type anything into Claude Code. Four answers, written down, in plain language. If you cannot answer one of them, that is the part of the idea that is not finished yet, and the agent will paper over it with a guess.

1. What does it do, in one sentence, with no and in it. Adds a delivery-date field to the checkout is a plugin. Adds a delivery-date field and emails the driver and shows a dashboard is three plugins in a coat.
2. Where does it appear? WordPress has distinct surfaces and they are built completely differently. An admin settings page, a block in the editor, a shortcode in a post, a widget, a change to the front-end output, or something with no interface at all that just runs on a schedule. Name the one you want.
3. What does it store, and where? Nothing at all, a handful of settings in the options table, extra fields attached to posts, or its own database table. These are four different builds, and the agent will default to the most complicated one if you leave it open.
4. Who can use it? Every admin, only the site owner, logged-in users, or the public. WordPress has a capability system for exactly this, and an agent that was not told will frequently write an endpoint anyone on the internet can call.

Write those four answers into a short brief and hand it over as the opening message rather than describing the plugin conversationally. This is the same discipline as any other build, and we go deeper on it in [how to write a project brief for Claude Code](/blog/how-to-write-a-project-brief-for-claude-code). On WordPress it matters more than usual because the platform has so many valid places to put the same feature.

The Build Order That Works

Build in the order that gets something visible on the screen fastest, then add behaviour to a thing that already exists. Trying to get the whole plugin right in one prompt produces a large amount of code you cannot check.

1. Get an empty plugin to activate. A single main file with the plugin header comment, nothing else. Drop it in, activate it, confirm WordPress shows it in the plugin list with no errors. This takes two minutes and it proves your local setup works before any real code exists.
2. Add the surface with nothing behind it. The settings page that renders one heading, or the shortcode that outputs the word working. See it appear in the right place in the admin or on the page. Now you know your hooks are registered correctly.
3. Add the storage. Save one setting, reload the page, confirm the value came back. Persistence is where most plugin bugs live and it is far easier to prove with one field than with twelve.
4. Add the actual behaviour. Now that the plumbing is verified, the interesting part is a small change to a thing that already works, which is the cheapest possible place to be wrong.
5. Add the guards. Capability checks, input sanitising, output escaping, and a check that the plugin degrades sensibly if something it depends on is missing.

TIP: Run a local WordPress install rather than testing on a live site. The agent will occasionally produce a fatal PHP error, and on a live site that is a white screen for your visitors while you work out which line did it. Locally it is a two-second annoyance.

Tell Claude Code your WordPress version and whether the site uses a block theme or a classic theme in the first message. The correct way to add a feature has changed significantly between those two worlds, and an agent guessing will sometimes hand you the approach that was right several years ago.

The Four WordPress Traps to Review For Every Time

These are not AI mistakes. They are WordPress mistakes that agents make because a plugin is written as though it is the only code on the site, when in reality it is sharing one PHP process with a theme and thirty other plugins.

Run that review as a separate task in a fresh session rather than as the last line of the build prompt. An agent that has spent an hour building something is a poor judge of it; a clean session reading the code cold behaves like a different reviewer. Ask it to list every place user input enters and every action that changes data, with line numbers, and state which check guards each one. A list with line numbers is checkable, a paragraph saying the security looks fine is not.

WARNING: If your plugin adds an endpoint that anything can call, treat it with the same seriousness as any other public surface. This is the single most common way a small helpful plugin turns into a real problem on somebody's site, and it is invisible in the browser because the admin screens all look correct.

Turning the Plugin Into Something People Install

A plugin that works on your machine is about seventy percent of the job. The last stretch is the part that decides whether anyone else ever runs it.

• A readme that says what it does in the first sentence and what it does not do in the second. The second sentence prevents most bad reviews.
• Sensible defaults, so it does something useful the moment it is activated without a settings tour.
• Clean uninstall. Remove your options and tables when the plugin is deleted, unless the user has asked you to keep the data.
• A version number and a changelog, because the first support question you get will be which version are you on.
• One screenshot of the thing actually working. It converts better than any description of it.

This is also where a plugin becomes a paid product rather than a favour. A narrow plugin that removes a specific recurring annoyance for a specific kind of site is one of the more straightforward things to sell, because the buyer can evaluate it in about a minute. If you are building for a client rather than for a marketplace, the handover matters as much as the code, which we cover in [how to hand off a Claude Code project](/blog/how-to-hand-off-a-claude-code-project).

TIP: Claude Code Club members ship small builds like this constantly and post them for review before they go out, which is the cheapest way to find the capability check you forgot. If you are about to put a plugin on somebody else's site, that is the room you want reading it first. It is $9 a month to join.

What Not to Build First

Three categories are much harder than they look and make poor first plugins, regardless of how capable the agent is.

1. Anything that touches payments or checkout on a live store. The cost of a subtle bug is somebody's real money and the testing burden is enormous. Build your second plugin here, not your first.
2. Anything that has to work across every theme. Front-end output that must look right on any theme anyone might install is a support commitment, not a feature. Admin-side plugins avoid this entirely.
3. Anything that duplicates a core WordPress capability. If the platform already has a way to do it, your version has to be better than a thing thousands of people have maintained for years, and it usually is not.

The best first plugin is boring, admin-side, and scratches an itch you personally have on a site you personally run. You get a real user with real feedback on day one, and that user is you, which makes the feedback loop about as short as it can get.

FAQ

Can Claude Code build a WordPress plugin from scratch?

Yes, and it is a good fit because WordPress supplies most of the application already and the plugin is a small piece of code on top. What the agent will not do reliably on its own is add the capability checks, prefixing and input sanitising that WordPress specifically requires, because those are conventions of the platform rather than obvious parts of the request. Build with the agent, then review for those four things.

Do I need to know PHP to build a WordPress plugin with Claude Code?

Not to get a working plugin, but you do need to be able to read what came back well enough to spot when a function is missing a permission check or a value is going into the database unfiltered. You do not have to be able to write it from memory. Reading is a much lower bar than writing and it is the bar that actually matters here.

Should I test a new plugin on my live site?

No. Use a local WordPress install or a staging copy, because an agent will occasionally produce a fatal PHP error and on a live site that is a blank page for your visitors until you find the line. Locally the same mistake costs you a few seconds and nobody else sees it.

How long does it take to build a simple WordPress plugin?

A narrow admin-side plugin with one settings screen and one behaviour is realistically an afternoon, most of which is the reviewing and testing rather than the writing. Anything that touches the front end across multiple themes, or that handles payments, is a much larger commitment and should not be your first one.

Can I sell a plugin I built with Claude Code?

Yes, and a narrow plugin that removes one specific recurring annoyance is one of the easier things to sell because a buyer can evaluate it in about a minute. What decides whether it sells is not how it was written but whether the problem is real and specific enough that someone was already looking for a solution to it.

• Estimate the phases, not the build. Building is the part AI compressed; discovery, review, client feedback and deployment are unchanged, and they are where the calendar actually goes.
• Estimate in working sessions rather than calendar days, then convert. A build that is four sessions of work still takes three weeks if the client answers questions once a week, and the client only ever hears the second number.
• Quote a date range tied to named client dependencies rather than a single day. Two weeks from the day I have your logins and content is a promise you control; two weeks from today is a promise they control.

Why Claude Code Project Timelines Get Estimated Wrong

Estimates go wrong because the thing that got dramatically faster is not the thing that consumed the calendar. AI compressed the writing of code. It did not compress waiting for the client to send their brand assets, or the two days of review after the first demo, or the afternoon lost to a domain registered to somebody who left the company three years ago.

So the builder does the honest thing and estimates from experience: this used to be four weeks of code, the agent makes me several times faster, call it one week. Then the project takes five, and the extra four weeks contained almost no code at all. Nothing about the reasoning was lazy. It measured the wrong quantity.

NOTE: The reframe that fixes this: you are not estimating how long the work takes. You are estimating how long it takes for the work, the client and the outside world to all be ready at the same time. The second number is always larger, and it is the one on the invoice.

Split the Project Into Four Phases and Estimate Each Separately

Estimate four phases on their own, because they scale completely differently and only one of them is affected by how fast your agent is.

Write a number against each phase in your notes before you write a number in the email. The first time you do this the split is usually a shock. On small client builds it is common for the build phase to be a minority of total elapsed time, which means quoting the build and adding a bit for safety is structurally guaranteed to underquote.

Discovery is the phase most builders leave out of an estimate entirely, and it is the one that most reliably decides whether everything after it goes smoothly. If you are not running one properly, fix that before you fix your estimating - we covered it in [the discovery call for AI projects](/blog/discovery-call-for-ai-projects).

Estimate in Sessions, Then Convert to Calendar Time

Estimate the build in working sessions, meaning uninterrupted blocks where you and the agent are genuinely on the problem. Sessions are a unit you can judge from experience. Calendar days are not, because they also contain other clients, weekends, and everybody else's response times.

1. Break the build into features you can name in one sentence each. Anything you cannot name in one sentence is two features hiding.
2. Put a session count against each one. Most well-scoped features on a Claude Code build land at one to three. If something reads as more than five, it is not a feature and you have not finished scoping it.
3. Add the phases around it: discovery sessions, your own review passes, deployment and handover. These are real work and they belong in the total.
4. Convert to calendar time using how many of these sessions you honestly get in a week on this project, not how many exist in theory. For most people carrying more than one client that number is three or four, not ten.
5. Add the client's response latency. If they take two days to answer and the build needs three decisions from them, that is six days of calendar no amount of speed removes.

TIP: Keep the session estimates in a note and write the actuals beside them when the project ships. Three projects in, you will know your personal multiplier between what you estimate and what happens, and that one number makes you better at this than almost anyone quoting on instinct.

The conversion step is where the honesty lives. Four sessions of work is not four days. It is four sessions plus the gaps, and the gaps belong to the client's calendar as much as yours. Skipping the conversion is how a genuinely accurate build estimate becomes a missed deadline.

The Unknowns That Actually Blow Up Timelines

Some categories of work carry far more variance than their size suggests. Price the variance instead of pretending it is not there, and name it on the call so the client hears it from you before it happens rather than after.

• Anything that integrates with a system you have not seen. An API you have not read is not an estimate, it is a guess. Ask for access during discovery and look at it before you quote.
• Anything that depends on the client's existing accounts. Payment processors, domain registrars, analytics, email providers - the work is minutes and the access is sometimes weeks.
• Anything involving their real data. Real data is always messier than the sample, and the cleanup is invisible until you have it in front of you.
• Anything with a compliance, legal or brand approval step. That is not your timeline. Ask who signs off and how long they usually take.
• Anything described as simple by somebody who is not building it. That word rarely survives contact with the actual requirement.

The move that removes most of this risk is charging for a short paid discovery before you quote the build. You look at the systems, read the API, see the data, and then give a number you can defend. Clients who will not pay for a couple of hours of scoping are usually the same clients who will not pay for the overrun either.

How to Present the Estimate So It Holds

Quote a range, tie the start to a named dependency, and list what you need from them in the same message. A range with conditions is a professional estimate. A single confident date with no conditions is a hostage you handed over for free.

1. Give a range, not a point. Two to three weeks, not seventeen days. False precision buys you nothing and costs you the margin the moment it slips.
2. Start the clock on their action. Two to three weeks from the day I have access to your site and the product copy. Now the date moves when they move, which is both fair and true.
3. List the dependencies explicitly. Three or four bullets naming exactly what you need and when. This is the highest-value paragraph in the whole document.
4. Name the review rounds. Two rounds of feedback included, each returned within three working days. Unbounded feedback is an unbounded timeline, and one line prevents it.
5. Say what happens when scope changes. Not as a threat, just a mechanism: new requests get quoted as an addition rather than absorbed. The related trap is covered in [how to handle scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects).

WARNING: Never quote a timeline out loud on a call under pressure. Give a range you already worked out, or say you will send the estimate that evening. Every disastrous timeline I have watched a builder commit to was said in a meeting because a silence needed filling.

What to Do When You Are Going to Miss It

Tell them early, say specifically what changed, and give a new date with the same conditions attached. The damage from a slipped deadline is almost entirely about when they found out, not how late it was.

A client told in week one that the integration is worse than it looked and delivery moves by five days will usually say fine. The same client told on the delivery date will not, because they have already told somebody else, and you have made them look bad rather than merely late. Silence is the expensive part, not the delay.

Then write the real number in your notes next to the estimate. An overrun is only wasted if it does not calibrate the next quote. Two or three of those and your estimates stop being optimistic, which is worth more to your margin than any further speed improvement in the build itself.

TIP: Members of Claude Code Club compare real numbers on this - what they quoted, what it took, and where the extra weeks went. Seeing three other builders' actuals is the fastest way to calibrate your own before a client pays for the lesson. It is $9 a month to join.

FAQ

How long does a typical Claude Code client project take?

It depends far more on the client than on the build, which is why a single number is not useful. The honest framing is that the coding phase is often a minority of elapsed time, and discovery, review rounds and access to the client's existing accounts consume the rest. Estimate the four phases separately and you will land closer than any rule of thumb.

Should I quote a fixed deadline or a range?

A range, tied to a named dependency such as the day you receive access and content. A single date implies a precision the work does not have and hands the client a stick if anything moves by a day. A range with conditions reads as more professional, not less, because it shows you have thought about what could change.

How do I stop client feedback from wrecking the timeline?

Put a number on it in the estimate: how many rounds of feedback are included and how many working days each one has. Unbounded review is the most common source of overrun on small builds precisely because nobody ever agreed it was bounded. One line fixes it, and clients rarely object because it also tells them when to expect the finished thing.

Does using Claude Code let me quote shorter timelines than other builders?

On the build phase, genuinely yes. On the total, much less than you would expect, because discovery, review, approvals and access are unaffected. Quoting the compressed build as though it were the whole project is the specific mistake that makes fast builders look unreliable, and it is entirely avoidable.

What should I do if the project is going to run over?

Tell the client as soon as you know, say specifically what changed, and give a revised date with the same conditions attached. Clients forgive delays they hear about early far more readily than delays they discover on the due date, because the early version lets them adjust their own commitments instead of being caught out by yours.

• Claude Code is slow for three reasons and almost never anything else: you are sending too much context on every turn, the tools it runs (tests, builds, searches, MCP servers) are eating the clock, or you are using a heavier model than the job needs.
• The fix order matters. Trim context first because it is free and it compounds, then time your tools, then change model. Swapping model first hides the real problem and you pay for it again next week.
• Run the Slow Loop Audit: read your context bill, time one tool call, then check the model. It takes about five minutes and it tells you exactly which of the three is costing you the wait.

Why Claude Code Is Slow - The Short Answer

Claude Code is slow because of what you are asking it to carry, not because the product is broken. Every turn, it re-sends the conversation plus whatever files, memory, and tool definitions are loaded, and the model has to read all of that before it writes a single character. On top of that, some of the wait you feel is not the model at all - it is your test suite, your build, or a slow search running inside the loop while the agent waits like you do.

So there are exactly three meters to read. The context meter: how many tokens go up on every turn. The tool meter: how long the commands it runs actually take. The model meter: whether the model you selected is heavier than this task needs. Almost every slowness complaint resolves to one of those three, and you can find out which in about five minutes.

NOTE: The single most common cause is the least dramatic one: a project that quietly accumulated a huge CLAUDE.md, half a dozen MCP servers, and a habit of reading whole files. None of those feel slow on the day you add them. Together they tax every turn forever.

The Slow Loop Audit - Three Checks in Order

The Slow Loop Audit is our name for the fixed order you check these in. Order matters because context is free to fix and it compounds across every future turn, while changing model is a one-time trade you can make any time. Do them in this order and you never pay twice.

1. Read the context bill. Look at what is auto-loaded before you type anything: your CLAUDE.md, any memory or rules files, connected MCP servers and their tool definitions, and any files already read into the conversation. This is the fixed tax on every single turn.
2. Time one tool call. Ask Claude Code to run the thing it runs most often - your test command, your build, a search across the repo - and watch the clock yourself. If that command takes ninety seconds by hand, the agent is not slow, your command is.
3. Check the model. Only after the first two are clean should you ask whether the task actually needs the heaviest model available. Routine edits, renames, and file plumbing do not.

TIP: Do the audit on a boring, repeatable task, not on the hard thing you are stuck on. You want to measure the loop, not the difficulty of the problem.

Cause One - Your Context Is Too Big

Context is the number one cause and the easiest to fix. Everything the model has to read before responding is paid for in latency on every turn, not once. A CLAUDE.md that grew to a few thousand words, a rules directory nobody has pruned, and three files that were read in full an hour ago are all still riding along on the request you just sent.

• Trim CLAUDE.md to instructions that change behavior. If a line is describing something the agent can discover by reading the code, delete it. Project structure, file paths, and conventions belong in the code, not in a file that is re-sent every turn.
• Prefer search over reading. Grep and Glob return the matching lines, a full Read returns the whole file. On a large file that difference is the whole slowdown.
• Disconnect MCP servers you are not using today. Each connected server injects its tool definitions into the context whether you call it or not, so six idle servers are six standing taxes.
• Start a fresh session when you change task. A long conversation carries everything that came before it. If you finished the bug and are now on a feature, the bug's context is pure overhead.
• Watch for large generated files. A lockfile, a build artifact, or a giant JSON fixture read into context once will slow every turn after it.

The tell for a context problem is that the first turn of a session feels fine and the twentieth feels sluggish, on the same kind of task. Latency that grows as the conversation grows is context, every time.

Cause Two - The Tools Are the Bottleneck, Not the Model

A large share of perceived slowness is the agent sitting there waiting for your machine. When Claude Code runs your test suite, it waits for the exact same amount of time you would. If your suite takes four minutes, an agent loop that runs it three times spends twelve minutes doing nothing but waiting, and it will look for all the world like the model is thinking.

• Give it a narrow test command. Point it at the one test file relevant to the change rather than the whole suite, and only run the full suite at the end.
• Keep searches out of dependency folders. A repo-wide search that walks node_modules or a build output directory is slow for the agent for the same reason it is slow for you.
• Run long builds outside the loop. If a production build takes minutes, do not make it a step the agent waits on mid-task.
• Check hooks. A hook that fires on every tool call adds its own runtime to every tool call. A formatter that takes two seconds is fine; a full type check is not.

WARNING: This is the cause people misdiagnose most often. They switch to a faster model, see no improvement, and conclude Claude Code is just slow. Time one tool call by hand before you touch anything else and you will know within a minute whether the wait is yours or the model's.

Cause Three - You Are Using a Heavier Model Than the Task Needs

Model choice is a real lever, but it is the third one, not the first. Heavier models reason more and therefore take longer to produce the first token and the last one. That is a fair trade on architecture decisions, tricky debugging, and anything where being wrong is expensive. It is a bad trade on renaming a variable across twelve files.

Extended thinking is the same trade in a smaller package. When you ask for more deliberation, you are explicitly buying latency with the expectation of a better answer. Turn it on for the hard step and off for the plumbing, rather than leaving it on all session and wondering where the time went.

TIP: A practical split that works: heavier model to plan and to review, lighter model to execute the plan. The expensive thinking happens twice, at the start and the end, instead of on every mechanical edit in between.

When It Is Not You - Limits, Retries, and Network

Some slowness is genuinely outside your project. If you are near a usage limit, requests can be throttled or retried, and a retry looks exactly like a long think from where you are sitting. Heavy demand periods can add latency the same way. Neither of those is fixed by trimming CLAUDE.md, so it is worth ruling them in or out before you go rearranging your setup.

The way to tell the difference is consistency. A context or tool problem is reproducible - the same task is slow every time you run it. A limits or network problem is erratic, and the same prompt that crawled at four in the afternoon returns quickly an hour later. If your slowness moves around on its own, stop optimizing and go do something else for twenty minutes.

If you are running into usage limits regularly, that is a separate problem with its own fixes, and we walked through those in [what to do about Claude Code usage limits](/blog/claude-code-usage-limits-what-to-do).

The Setup That Stays Fast

Speed is not a one-time cleanup, it is a habit of not accumulating weight. The projects that stay fast are the ones where somebody prunes on a schedule instead of only when it gets painful.

1. Cap your CLAUDE.md. Pick a length you are willing to re-read on every turn and hold it there. When you add a line, ask what comes out.
2. Keep MCP servers to the ones this project actually uses, and disconnect the rest.
3. Have a fast test command and a slow one, and tell the agent which is which in your project instructions.
4. Start fresh sessions at task boundaries rather than running one enormous conversation all day.
5. Re-run the Slow Loop Audit when a project starts to feel heavy, rather than guessing at it.

If you want the wider version of this, keeping a session lean is the same discipline as [Claude Code context management](/blog/claude-code-context-management), and the file itself is covered in [the CLAUDE.md file guide](/blog/claude-code-claude-md-file).

TIP: Inside Claude Code Club we compare setups directly - what is in people's CLAUDE.md, which MCP servers are actually earning their place, and which test commands they hand the agent. It is the fastest way to find out that the thing slowing you down has already been solved by somebody three desks over. Membership is $9 a month.

FAQ

Why is Claude Code slow all of a sudden?

Sudden slowness on a project that used to be quick is almost always something that got added recently: a new MCP server, a much longer CLAUDE.md, a hook that now runs on every tool call, or a test command that grew. Check what changed in your setup in the last week before you assume it is the model. If nothing in your project changed and the slowness comes and goes on its own, it is more likely limits or network conditions than anything you can fix locally.

Does a bigger CLAUDE.md really make Claude Code slower?

Yes, because it is re-sent on every turn rather than read once. A long instructions file is a fixed cost added to every request for the life of the project, so the cost is the length multiplied by the number of turns you will ever take. That is why trimming it is the highest-leverage speed fix available and why it is the first step of the Slow Loop Audit.

Will switching to a lighter model fix slowness?

It will help if the model was genuinely the bottleneck, and it will do nothing at all if your context is bloated or your test suite is the thing eating the clock. That is why model is the third check, not the first. Time one tool call by hand and look at what is auto-loaded before you type; if both are clean, then a lighter model for mechanical work is a good trade.

Do MCP servers slow Claude Code down?

Connected servers add their tool definitions to the context whether or not you call them, so a stack of servers you are not using today is a standing cost on every turn. It is not that any one server is heavy, it is that they accumulate. Keep the ones this project uses connected and disconnect the rest, and reconnect them when you actually need them.

Is extended thinking worth the extra wait?

On genuinely hard problems, yes, because the cost of a wrong answer you then have to unpick is much higher than the extra seconds. On routine edits it is pure overhead. Treat it as something you switch on for a specific step rather than a setting you leave on all session, and the wait stops feeling like a tax.

• To add authentication with Claude Code, pick a managed auth provider first, have the agent wire it in, and then run a separate review pass whose only job is to check that the server refuses unauthenticated requests.
• The failure mode is not a broken login screen. It is a working login screen in front of an API that never verifies anything, because the agent built what you described and you described the visible half.
• Run the Auth Gate Checklist: identity, session, authorization. Three gates, checked on the server, tested by trying to walk past each one. If you cannot break in by hand, you are done.

How to Add Authentication With Claude Code - The Short Version

Adding authentication with Claude Code is a three-part job: choose a managed auth provider, have the agent wire the sign-up and sign-in flow into your app, and then run a dedicated review pass that checks the server actually enforces the rules. The first two parts take an afternoon. The third part is the one people skip, and it is the one that decides whether you shipped a login or a decoration.

Be specific about the provider before you start. Tell the agent which auth service you are using, which framework you are on, and whether you want email and password, social sign-in, or magic links. A vague request produces a plausible custom implementation, and a custom auth implementation is the last thing you want on a project you are going to hand to a client.

WARNING: Do not have Claude Code write your own password hashing, session store, and token logic from scratch because it is capable of it. It is capable of it. That is not the same as it being a good idea. Use a managed provider so the parts that must never be wrong are somebody's full-time job.

The Real Risk - The Login Works and the Server Does Not Care

The classic AI-built auth bug is that everything you can see works perfectly. You sign up, you sign in, you get redirected to the dashboard, the wrong password gets rejected. And behind that, the API route that returns the data will happily return it to anyone who calls it directly, because nothing on the server ever checks who is asking.

This happens for an understandable reason. You asked for a login. The agent built a login. The login is the visible part, and the visible part is what got described, demonstrated, and approved. The invisible part - every server route independently refusing requests that do not carry a valid session - was never in the request, so it was never in the build.

WARNING: We have watched an endpoint go live with no authentication in front of it and a funded API key behind it, and get found and drained overnight. Nobody had to be clever. The endpoint was public, the key had money on it, and that was the whole story. Treat any route that can spend money or read private data as something that must prove the caller is allowed, every single call.

The Auth Gate Checklist - Three Gates You Have to Close

The Auth Gate Checklist is how we structure the review pass. There are exactly three gates between a stranger and your data, they are checked in order, and every one of them has to live on the server. If any gate is enforced only in the browser, it is not a gate, it is a suggestion.

1. Identity - who is this? Sign-up, sign-in, sign-out, password reset, and email verification. Handled by your auth provider, not by you.
2. Session - are they still who they said they were? The token or cookie that proves identity on every subsequent request, stored somewhere a script on another site cannot read, and verified on the server before anything else happens.
3. Authorization - are they allowed to do this specific thing to this specific record? This is the gate that gets forgotten. A valid session proves you are a user. It does not prove you are allowed to read invoice number 412.

Give the agent the checklist explicitly. Ask it to walk each server route and tell you which of the three gates that route enforces and where in the code the check happens. Routes that cannot answer are your bug list, and you will usually get one.

Gate One - Identity, and Why You Use a Provider

Use a managed authentication provider. The reason is not that authentication is hard to write, it is that authentication is hard to keep correct over years while you are busy doing other things. Password hashing standards move, token handling has sharp edges, and account recovery is a whole security surface on its own. A provider absorbs all of that and keeps absorbing it after you have stopped thinking about the project.

When you brief Claude Code, name the provider and the framework in the same sentence, and say which flows you want. Something like: wire up this specific auth provider in this specific framework, with email sign-in and Google sign-in, protected routes, and a sign-out that clears the session. Specificity here is the difference between the agent following a documented integration path and the agent inventing one.

TIP: Ask the agent which version of the provider's SDK it is writing against and have it check the current integration docs before it writes code. Auth SDKs change their recommended patterns more often than most libraries, and a confidently written integration against last year's API is a frustrating afternoon.

Gate Two - Session Handling, Where the Sharp Edges Are

The session gate is where a good-looking build most often goes wrong, because the mistakes are invisible in the browser. The app works. It just also works for people it should not.

• Verify on the server, on every request. Not once at login, not in a layout component, not in the router. Every server route that touches private data checks the session itself.
• Do not keep tokens where another script can read them. Prefer the httpOnly cookie your provider offers over anything the page's own JavaScript can reach.
• Make sign-out actually end the session server-side. Clearing local state and redirecting to the home page looks identical to the user and is not the same thing.
• Check expiry and refresh properly. A session that never expires is a permanent key handed to whoever eventually gets a copy.
• Keep secrets out of the client bundle. Anything shipped to the browser is public, no matter what it is named.

The test is blunt and it takes two minutes. Sign out, then call a protected API route directly with no session at all. You should get a refusal. If you get data, the gate is not there, whatever the login screen suggested.

Gate Three - Authorization, the One Everyone Forgets

Authorization answers a narrower question than authentication: not are you a real user, but are you allowed to touch this record. Being signed in is not permission. On most small builds this is the gate that is simply missing, because the app was built and tested by one person who only ever had their own data in front of them.

The failure looks like this. A route fetches an item by the identifier in the URL, checks that a valid session exists, and returns the item. Any signed-in user can change the number in the URL and read somebody else's record. The session check passed, so it feels secure. Nothing checked ownership.

1. Every fetch of a single record filters by the current user's identifier as well as the record identifier, in the query itself.
2. Every write checks ownership before it writes, not after.
3. Role checks live on the server. A hidden admin button is not an access control, it is a hidden button.
4. If your database supports row-level security, turn it on and treat it as the backstop, not as the only check.

TIP: Create a second test account. Almost every authorization bug becomes obvious the moment there are two users in the system and you try to reach one account's data while signed in as the other. One-user testing is how these ship.

The Review Pass - Make the Agent Attack Its Own Build

Run the security review as a separate task in a fresh session, not as the last line of the build request. In the build session the agent has spent an hour establishing that the work is going well, and asking it to critique that same work in the same breath gets you a summary rather than an audit. A clean session reading the code cold is a genuinely different reviewer.

Give it a specific brief. Ask it to list every server route, state which of the three gates each one enforces and on which line, and flag every route that returns data without verifying both session and ownership. A list with line numbers is checkable. A paragraph saying the authentication looks solid is not.

1. Call a protected route with no session. Expect a refusal.
2. Call it with a second user's session and someone else's record identifier. Expect a refusal.
3. Sign out, press back, and try to use the page you were on. Expect a refusal.
4. Search the client bundle for anything that looks like a secret. Expect nothing.
5. Only after all four behave, call it done.

This is the same discipline as any other agent output, which we go into in [how to review Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship). Auth is just the place where skipping it costs the most.

Where This Fits in a Client Build

If you are building for someone else, authentication is a line item with a review attached, not a checkbox on the feature list. Scope it that way out loud. The build is an afternoon and the review pass is its own block of time, and saying so up front is much easier than explaining afterwards why the audit was not included.

It also pairs with the other thing clients quietly assume is handled: payments. If your build has both a login and a checkout, they are the two places where being approximately right is not good enough. We covered the other half in [adding Stripe payments with Claude Code](/blog/add-stripe-payments-to-claude-code).

TIP: Claude Code Club members share the exact briefs they hand the agent for auth work, and the review prompts that actually surface holes rather than reassurances. If you are about to put a login in front of someone's real users, that is the room you want to check your plan in first. It is $9 a month to join.

FAQ

Can Claude Code build a complete authentication system?

It can produce a working sign-up, sign-in and protected-route setup quickly, especially when you point it at a managed auth provider and name your framework. What it will not reliably do on its own is enforce ownership checks on every record and refuse unauthenticated requests at every server route, because those parts are invisible in the browser and therefore rarely part of the request you made. Build with the agent, then review against the three gates.

Should I let Claude Code write custom auth instead of using a provider?

No, for the same reason you would not hand-roll it yourself. Authentication is not hard to write once, it is hard to keep correct for years as standards shift and edge cases surface, and account recovery alone is a security surface most small projects get wrong. A managed provider makes those problems someone else's ongoing job, which is exactly what you want on a build you will not be staring at every week.

How do I test that my authentication actually works?

Sign out and call a protected API route directly with no session, then create a second account and try to read the first account's records while signed in as the second. Those two tests catch the overwhelming majority of real holes in small builds. If both are refused by the server and no secrets appear in your client bundle, you are in decent shape.

What is the difference between authentication and authorization?

Authentication establishes who someone is, authorization decides what that person is allowed to do. A valid session proves a user is signed in; it says nothing about whether they may read a particular invoice or delete a particular project. Most small-build security bugs are authorization bugs sitting behind working authentication, which is why the checklist treats them as two separate gates.

Is it safe to store an auth token in local storage?

Prefer the httpOnly cookie your provider offers, because anything the page's own JavaScript can read can also be read by a script that gets injected into your page. It is not that local storage is guaranteed to be exploited, it is that the cookie option costs you nothing and removes a category of risk. Take the free win.

• To generate documentation with Claude Code, point it at the real source files first, have it write the doc from what it read, then make it cite the file and function behind every claim. Skipping the citation step is what produces confident, wrong docs.
• The failure mode is not bad writing, it is invented behaviour. An agent asked to write a README from a project description will describe the project you meant to build, not the one on disk.
• I run the Read-Write-Prove loop: scope the read, generate the draft, then verify each statement against a real line of code. Anything that cannot be traced gets cut, not softened.

How to Generate Documentation With Claude Code

To generate documentation with Claude Code, do it in three ordered moves. First, tell it exactly which files to read and nothing else, so its picture of the project comes from the code rather than from your description of it. Second, ask for the specific document you want, in a named format, written only from what it just read. Third, make it go back and attach a file path and a function or route name to every factual claim it made. The third move is not optional polish. It is the step that converts a plausible document into an accurate one.

The reason this order matters is that documentation is the one output where being wrong is worse than being absent. A missing README costs a new person twenty minutes of reading code. A README that describes an endpoint which no longer exists costs them an afternoon and a certain amount of trust in every other document in the repository. Generated docs fail in that specific direction, so the process has to push back in that specific direction.

NOTE: Documentation is the highest-leverage thing an agent can write for you and the easiest thing for it to fake, because prose has no test suite. Nothing fails loudly when a paragraph is wrong. You have to build the failure signal yourself.

Why Generated Docs Go Wrong

Generated documentation goes wrong because the agent fills gaps instead of reporting them. If it has read six of your twenty files and you ask for a complete architecture overview, it will produce a complete-looking architecture overview. The missing fourteen files get replaced by the most conventional version of what those files usually contain in a project like yours. The output reads well precisely because it is generic.

This shows up in a few recognisable ways once you know to look. Setup instructions list environment variables that were renamed. A feature list includes something that was cut and never removed from an old comment. An API reference documents the parameters a function should logically take rather than the ones in its signature. In every case the sentence is reasonable and the code disagrees.

• Stale features: described because an old file, comment, or branch still mentions them.
• Conventional invention: filled in from how projects like yours usually work, not from your code.
• Silent scope gaps: whole modules the agent never opened, summarised anyway.
• Drift on names: a variable, flag, or route renamed in code but not in the doc it was generated from.

None of that is a reason to write docs by hand. It is a reason to treat the first draft as a draft. The agent is genuinely excellent at reading a large amount of code quickly and turning it into clear prose. It is unreliable at knowing the edge of its own knowledge, so you supply that edge.

The Read-Write-Prove Loop

Read-Write-Prove is the loop I use for every generated document, from a one-page README to a full internal handbook. It is three prompts, not one, and the separation is the whole point. Asking for all three at once collapses them back into a single confident guess.

1. READ - name the files. Read these specific paths, nothing else, summarise what each one does, and list anything you could not determine from these files alone. That last clause is what produces an honest gap list.
2. WRITE - name the document. Using only what you just read, write the API reference as a table of endpoint, method, required parameters, and what it returns. Naming the format stops it padding with narrative it cannot support.
3. PROVE - demand a citation per claim. For each row, give the file and the exact function or handler name it came from. If a row has no source, delete the row and say what is undocumented. Deletion, not hedging.

The PROVE step is where the value lives, and it is the step people skip because the draft already looks finished. When I started running it properly on my own projects, the consistent result was not a small correction. It was a handful of rows deleted per document and a short list of things that genuinely had no source, which is exactly the list I actually needed. The undocumented list is more useful than the documentation, because it tells you where the code is unclear enough that a careful reader could not work it out.

TIP: Insist on deletion rather than a caveat. An agent given permission to write that something may vary depending on configuration will use it on every uncertain claim, and you end up with a document that is technically never wrong and practically useless.

Which Documents Are Worth Generating

Not every document benefits equally. The ones worth generating are the ones whose content is fully determined by the code, because those are the ones where PROVE has something to check against. The ones worth writing yourself are the ones that encode a decision, because no amount of reading source files reveals why you chose one approach over another.

The split is easy to remember: generate description, write judgement. If a careful reader with your whole repository open could reconstruct the document, generate it. If they could not, it has to come from you, and that is also the part worth your time.

Keeping Docs From Drifting Again

Generated docs decay the same way handwritten ones do, only faster, because they were cheap to produce and nobody feels ownership of them. The fix is to attach regeneration to a moment that already happens rather than to a resolution to be diligent. Two moments work well: the point where you finish a feature, and the point where you review a change.

The practical version is a single instruction in your project convention file saying that any change to a route, a command, a flag, or an environment variable requires the matching document to be regenerated in the same session. Because the instruction lives in the file the agent reads every time, it applies without you remembering it. The guide to the [Claude Code CLAUDE.md file](/blog/claude-code-claude-md-file) covers what belongs in it, and [CLAUDE.md templates by project type](/blog/claude-md-templates-by-project-type) has starting points you can adapt.

For anything that can be executed, add one more check: run the doc. Setup instructions that were generated and never followed are a guess. Following them on a clean clone takes ten minutes and is the only way to find the step that was true six weeks ago. This is the same instinct behind [reviewing Claude Code output before you ship](/blog/review-claude-code-output-before-you-ship).

WARNING: Never let generated docs be the only place a fact lives. If the document says the service needs a specific variable and nothing in the code enforces it, the document will eventually be the only thing that is wrong, and nothing will tell you.

A Working Prompt Sequence

Here is the sequence in the form I actually use, for a README on a small service. Run it in the desktop app with the project open. The terminal works identically if you prefer it, but nothing here requires it.

1. Read package.json, the entry file, the config file, and every file the entry file imports directly. List each one and what it does in a single line. Then list every question about this service you cannot answer from those files.
2. Write a README with these sections and nothing else: what this service does, how to run it locally, required environment variables, available commands. Use only what you read. Where you have a gap from your list, write TODO and the specific question.
3. Now audit your own README. For every environment variable and command, give the file and line where it is defined. Delete anything you cannot locate and list what you deleted.
4. Follow your own local setup section on a fresh clone and tell me the first step that fails.

Four prompts, and the last two are the ones that make the difference. If you only have appetite for one extra step beyond the draft, make it the audit. Consistently, the audit is what removes the sentence that would have cost somebody an afternoon. Getting sharper at writing these read-scopes is mostly a prompting skill, and [how to prompt Claude Code](/blog/how-to-prompt-claude-code) covers the general shape.

TIP: Inside Claude Code Club, members bring the README the agent just wrote and we run the audit prompt on it together, which usually turns up two or three claims nothing in the repository supports. If you have a doc you are about to commit, post it at claudecodeclub.ai for $9 a month and we will read it with you.

FAQ

Can Claude Code write a README from scratch on a project it has never seen?

Yes, and it will be readable immediately. The risk is that readable and accurate come apart. Give it an explicit list of files to read rather than letting it decide what is relevant, then make it cite a source for every factual statement. A README generated from a named read-scope and audited afterwards is genuinely reliable. One generated from a sentence about what your project does is a well-written guess.

How do I stop generated documentation from describing features that no longer exist?

Make citation mandatory and deletion the penalty. Ask for the file and function behind each claim, and instruct it to remove any claim it cannot locate rather than hedge it. Stale features almost always come from an old comment, a dead file, or a stale branch that the agent read in good faith, so the citation step is what surfaces them.

Should documentation live in the repository or somewhere else?

In the repository, next to the code it describes. Documentation in a separate wiki drifts because updating it is a different task in a different tool, whereas a file in the repo can be regenerated in the same session as the change that invalidated it. The exception is anything a non-technical audience needs, which belongs wherever they already look.

Is it worth generating docs for a solo project?

Yes, and the reason is not future teammates. Generated module overviews are the fastest way to give an agent accurate context in later sessions, so the doc pays for itself the next time you come back to a part of the project you have forgotten. On a solo project, the reader you are writing for is mostly yourself in three months, plus the agent working alongside you.

How often should I regenerate documentation?

Tie it to the change rather than the calendar. Any edit to a route, command, flag, or environment variable should regenerate the matching document in the same session, which you can enforce with a line in your project convention file. Scheduled quarterly reviews sound disciplined and get skipped; the change-triggered version happens because the trigger is already in front of you.

• A client kickoff call for an AI build has one job: lock the four things that cause almost every overrun. Those are the definition of done, the single decision-maker, the access you need, and the reporting rhythm. Rapport is a side effect, not the agenda.
• The kickoff is not the discovery call. Discovery decides whether to work together and what to charge. Kickoff happens after the money is agreed and exists to make delivery boring.
• Run the Four Locks agenda in forty-five minutes, send a written recap the same day, and treat anything the client will not confirm in writing as an unresolved risk rather than a detail to sort out later.

What a Client Kickoff Call Is Actually For

A client kickoff call is the first meeting after the project is agreed, and its only job is to remove the ambiguity that would otherwise surface halfway through the build. You are locking four things: what finished looks like in terms a non-technical person can check, who has the authority to approve it, what access you need and when it arrives, and how often you will report. Everything else on the call is conversation.

This is a different meeting from the discovery call, and running them as one costs you both. Discovery happens before the money is agreed and exists to decide whether there is a problem worth paying to solve, which the post on [discovery calls for AI projects](/blog/discovery-call-for-ai-projects) covers. Kickoff assumes the sale is closed and the client's mood has changed from evaluating you to expecting results, which is exactly the moment they will answer the hard questions honestly.

NOTE: The kickoff is the cheapest moment in the whole engagement to be difficult. A question that feels awkward on day one costs you thirty seconds. The same question in week four costs you a renegotiation, and by then the client has told their boss a date.

The Four Locks Agenda

The Four Locks is the agenda I run every time, in this order, because each lock depends on the one before it. Forty-five minutes is enough. If you cannot close all four in that time, the thing blocking you is the finding, and it belongs in the recap as a risk rather than getting glossed over so the call can end on time.

1. Lock the definition of done. Not a feature list, a sentence the client would use to tell a colleague it worked. Our team stops copying orders into the spreadsheet by hand is checkable. An automated order pipeline is not.
2. Lock the decision-maker. One named person who can approve and reject. If there are two, you have two projects. If the person on the call has to check with someone who is not there, that someone is the decision-maker and the next call includes them.
3. Lock access. Every system, credential, export, and sample file you need, with a named owner and a date. Access is the single most common reason a build stalls, and it is always somebody else's queue.
4. Lock the rhythm. When you will report, in what format, and what the client does with it. A fixed weekly note beats an open promise to keep them posted, because the note is a commitment you can keep without being asked.

The order is deliberate. Done comes first because it changes what access you need. Access comes before rhythm because the first report is usually about whether access arrived. If you jump to the schedule before agreeing what finished means, you have scheduled a journey to an unspecified destination.

How to Lock Done So It Cannot Move

Done is locked when the client has described the outcome in their own words and you have written it down in those words. Not paraphrased into your language, and not translated into a feature list. The reason is that a feature list can be satisfied completely while the client remains unhappy, and when that happens you are technically right and unpaid.

The question I use is blunt: three months from now, what has changed in your week that tells you this was worth the money? It gets an answer about behaviour rather than software. Then I ask the counterpart: what would make you say this did not work? That second answer is more valuable, because it names the failure mode they are quietly worried about and have not mentioned.

• Write the client's exact sentence at the top of the recap, in quotes, as the acceptance test.
• List what is explicitly not in scope. Two or three lines is enough, and it prevents the most predictable requests later.
• Name the one thing that would count as failure, and say how you will avoid it.
• Agree who checks the acceptance test and on what date.

TIP: If the client cannot describe done without describing features, the project is not scoped yet and the kickoff has just earned its keep. Stop, book a short scoping session, and do not start building against a feature list nobody can check.

Access Is the Real Schedule Risk

On AI builds specifically, access is the risk that eats timelines, and it is almost never the client's fault in a way you can complain about. They need somebody in IT to create an account, somebody in operations to export a sample, somebody in legal to confirm the data can leave a system. Each of those is a queue you do not control, and each one looks trivial until it takes nine days.

So the access lock is a list with owners and dates, made on the call while the decision-maker is present and motivated. Read it back. Ask who chases it if a date slips. Then put the list in the recap, because the recap is what the decision-maker forwards internally, and a forwarded list with names on it moves faster than a request you made once in a meeting.

There is a second reason to be precise here, and it is about your own exposure. Being handed credentials and client data on day one is a responsibility, and the client is entitled to know how you will handle it. Saying so plainly at kickoff builds more confidence than any reassurance later, and the piece on whether [Claude Code is safe for client work](/blog/is-claude-code-safe-for-client-work) sets out the position worth taking.

WARNING: Never start the clock on a fixed timeline before access exists. If the agreement says four weeks, the recap should say four weeks from the day the last item on the access list arrives. That single sentence has saved more projects than any amount of buffer.

The Recap Is the Deliverable

The call is not finished when the call ends. It is finished when the recap is sent and confirmed, the same day, while everyone still remembers what was said. The recap is short and it exists to be forwarded. Anything the client will not confirm in writing was not actually agreed, and finding that out on day one is a gift.

Ask for one word back: confirmed. Not a signature, not a countersigned document, just a reply that says yes this is right. That reply is what you point at, calmly and without drama, the first time someone remembers the project differently. And when a request does arrive that sits outside the exclusions, you are having a pricing conversation rather than an argument, which is the whole subject of [handling scope creep on client projects](/blog/how-to-handle-scope-creep-on-client-projects).

TIP: Inside Claude Code Club, members post their kickoff recap before they send it and we look for the lock that is missing, which is almost always the start condition or the single decision-maker. Bring yours to claudecodeclub.ai for $9 a month and we will read it with you before the client does.

What to Do When a Lock Will Not Close

Sometimes a lock will not close on the call. The client genuinely does not know who signs off, or cannot say what done looks like, or has no idea whether the data can be exported. This is not a failed kickoff. It is a successful one, because you now know the actual risk on day one instead of week three.

The move is to name it, write it in the recap as an open item with an owner and a date, and decide honestly whether work can start without it. Some open items are harmless and some are structural. Not knowing the export format is harmless. Not knowing who approves is structural, and starting a build with an unnamed approver means building for a person whose opinion you have not heard.

• Harmless open item: log it, start work, resolve it in the first report.
• Structural open item: log it, delay the start, and say plainly why. Clients respect this far more than a quiet start followed by a surprise.
• Either way, it goes in the recap. An open item that only exists in your head is a risk you have accepted on the client's behalf.

The habit underneath all of this is treating the first week as the cheapest place to be uncomfortable. A kickoff that surfaces two problems has done its job. A kickoff where everyone was pleasant and nothing was written down has moved those same two problems to the point where they cost real money. If the scope itself still feels loose, fix that before kickoff using [how to scope a Claude Code client project](/blog/how-to-scope-a-claude-code-client-project).

FAQ

How long should a client kickoff call be?

Forty-five minutes is the right target for a typical build, and an hour is the ceiling. The four locks fit comfortably in that time if you send the agenda in advance and do not use the call to re-explain the proposal. If you genuinely need longer, that is usually a sign the scope was not settled before the project was agreed, which is a scoping problem rather than a meeting-length problem.

Is the kickoff call the same as the discovery call?

No, and combining them costs you both. Discovery happens before the money is agreed and exists to decide whether the project is worth doing and what it should cost. Kickoff happens after and exists to remove delivery ambiguity. The client answers differently in each one, because in discovery they are selling you the opportunity and in kickoff they want the thing to work.

Who should be on the kickoff call from the client side?

The person who can approve and reject the work, plus anyone who controls access you need. If the approver cannot make it, reschedule rather than proceeding with a proxy, because a kickoff without the decision-maker locks nothing. Keep the list short otherwise, because a large kickoff turns into a status meeting where nobody commits to anything.

What if the client has never bought an AI build before?

Then part of your job on the call is calibrating expectations, and the most useful thing you can do is be specific about what will be manual, what will be reviewed by a person, and what could be wrong. A first-time buyer who has been told plainly that a human checks the output is a far easier client in week four than one who was allowed to assume it runs itself.

Should I charge for the kickoff call?

It belongs inside the project fee rather than being billed separately, because it happens after the agreement and its purpose is to protect the delivery you are already being paid for. What you should not do is run a full kickoff before anything is signed. That is a free scoping session in disguise, and it is where a lot of unpaid work quietly happens.

• To use Claude Code in a monorepo, open the session at the package level rather than the repo root, and give that package its own CLAUDE.md describing how it is built, tested, and run.
• The failure mode is not that the agent is confused by size. It is that a vague request at the root gives it permission to touch anything, so a small change quietly spreads across packages.
• Run the package-scoped session: name the package, name the boundary, and require an explicit plan before any cross-package edit.

The Short Answer

To use Claude Code in a monorepo, scope each session to one package instead of the repo root. Start the session in the package directory, keep a short CLAUDE.md in that package describing its build, test, and run commands, and state the boundary in the request itself: this package only, and tell me before you touch anything outside it. A root-level session with a vague request is what produces edits scattered across packages you did not mean to open.

NOTE: The size of a monorepo is not the problem. Claude Code does not need to read every package to work in one of them. The problem is that a root session makes every package equally reachable, so a small change has nowhere to stop.

Why a Monorepo Breaks an Agent's Sense of Scope

A monorepo is many projects sharing one root. Human developers hold the boundaries in their head: this change belongs to the web app, that helper lives in the shared package, the mobile client is not part of this task. None of that is written down anywhere the agent can read, so when you open a session at the root and ask for a fix, the agent sees one enormous project with no internal walls.

What follows is not a hallucination. It is a reasonable reading of an unreasonable request. You ask it to rename a field. It finds that field in the shared types package, updates it there, then updates the three apps that import it, then updates a test fixture in a fourth package you forgot existed. Every individual edit is correct. The change as a whole is now far larger than the one you agreed to review.

• The blast radius grows silently. In a single-package repo you can read the whole diff. In a monorepo the diff spans packages owned by different people, and you stop reading carefully around file twelve.
• The build feedback is slower. A cross-package change often will not fail until a downstream package builds, so the agent gets its signal late or not at all.
• The conventions are not uniform. One package uses one test runner, another uses a different one, and a root-level instruction that is true for one is wrong for the other.
• The context fills with the wrong things. Time spent reading unrelated packages is context not spent on the code you actually asked about.

The Package-Scoped Session - The Rule That Fixes Most of It

The package-scoped session is the working rule I use for every monorepo task: one session, one package, one stated boundary. Open the session inside the package directory rather than the repo root. Say which package you are in. Say explicitly that the agent should stop and tell you before editing anything outside it. That third sentence is the one people skip, and it is the one that does the work.

1. Open in the package, not the root. Point the session at the directory that owns the change. The agent still has the machine, so it can read a sibling package when it genuinely needs to, but the default gravity is local.
2. Name the package out loud in the request. 'In packages/billing, fix the proration rounding' beats 'fix the proration rounding' because the first sentence rules out the other twenty directories before the agent starts looking.
3. State the boundary and the escape hatch. 'Do not edit files outside this package. If the fix requires a change in the shared package, stop and show me the plan first.' This turns a silent spread into a decision you get to make.
4. Require the plan before the cross-package edit. When the agent comes back and says the change needs a shared type updated, you now have the useful conversation: is this actually a shared concern, or did we just leak a package detail into common code?

TIP: The escape-hatch sentence is worth more than any tooling. An agent that pauses at the package wall gives you a design review at exactly the moment a design decision is being made, instead of a surprise in the diff an hour later.

Give Every Package Its Own CLAUDE.md

A single CLAUDE.md at the repo root cannot describe a monorepo accurately, because the thing it most needs to describe - how you build, test, and run this code - is different per package. Keep the root file for what is genuinely global (the package manager, the commit conventions, the rule that the agent may not edit another package without asking) and put the specifics in a short CLAUDE.md inside each package.

The most valuable line in a package CLAUDE.md is usually the import rule. Writing 'this package may import from the shared package but nothing else, and nothing may import from it' gives the agent the architectural constraint that lives in your head and nowhere in the code. It also makes bad suggestions self-evident, because a proposed import that violates the rule now reads as obviously wrong rather than as a judgment call.

Handling a Change That Genuinely Spans Packages

Some changes really do cross the wall, and the boundary rule is not there to stop them. It is there to make them deliberate. When the agent comes back with 'this needs a field added in the shared types package', treat it as three separate pieces of work rather than one, and run them in that order: change the shared package, verify it builds, then update each consumer.

1. Do the shared change first, on its own, and get it building and tested before anything downstream touches it. A shared package that is half-changed makes every downstream error ambiguous.
2. Update consumers one package at a time, in separate passes. The temptation is to let the agent sweep all of them in one go. That produces a diff nobody reviews properly.
3. Verify at each stop. Run that package's own build and tests before you move to the next one, so a failure points at the package you just touched rather than at the whole tree.
4. Keep the commits split by package where your workflow allows it. It makes the change reviewable by the people who own each piece, and it makes a revert surgical instead of catastrophic.

WARNING: The specific thing to watch for is the agent solving a local problem by widening a shared interface. Adding an optional field to a shared type makes one package compile and quietly costs every other package clarity. If the reason for a shared change is 'it was the fastest way to make this build', that is a signal to look for the local fix instead.

When to Run Separate Sessions Instead of One

If you have two unrelated tasks in two packages, run two sessions. It sounds obvious and almost nobody does it, because one session already has momentum. The cost of reusing it is that the context now carries the first task's files, decisions, and half-remembered constraints into the second task, and the second task inherits assumptions that were never true for it.

Separate sessions also give you a cleaner recovery. When something goes wrong in a monorepo, the first question is always which change caused it. Two sessions with two scopes and two sets of commits answers that in seconds. One long session that wandered through five packages turns it into an investigation.

NOTE: This is easiest to run in the Claude Code desktop app, where a second session is a second window rather than a context switch you have to think about. Seeing two scoped sessions side by side is what makes the habit stick.

Start With One Package This Week

Pick the package in your monorepo you change most often. Write it a CLAUDE.md with four things: install, build, test, and what it is allowed to import. Then run your next task as a package-scoped session with the boundary sentence included, and notice how differently the agent behaves when it has to ask permission to leave. Most people find the first thing it asks about is a shared change they would have merged without noticing.

NOTE: Inside the Claude Code Club we trade the actual CLAUDE.md files we use in real monorepos and pull apart the ones that are not working. Bring the package that keeps going wrong and we will scope it with you.

FAQ

Can Claude Code handle a monorepo?

Yes, and it handles one well when the session is scoped to a package rather than the repo root. The difficulty in a monorepo is not size, it is that a root-level session treats every package as equally in scope, so a small request can spread. Open the session inside the package that owns the change, name that package in the request, and tell the agent to stop and ask before editing anything outside it.

Should CLAUDE.md live at the monorepo root or in each package?

Both, with a clear split. The root file holds what is true everywhere: the package manager, the workspace layout, commit conventions, and the rule that the agent may not cross a package boundary without asking. Each package gets a short file with its own install, build, test, and run commands plus what it is allowed to import. Build and test commands differ per package, so a root-only file will be wrong for most of them.

How do I stop Claude Code from editing other packages?

Say it in the request and repeat it in the root CLAUDE.md, and include an escape hatch rather than a flat ban. The wording that works is: do not edit files outside this package, and if the change requires one, stop and show me the plan first. A flat ban makes the agent work around the wall. An escape hatch turns the crossing into a decision you approve, which is the outcome you actually want.

What is the right way to make a change that spans several packages?

Split it into ordered passes rather than one sweep. Change the shared package first and get it building and tested on its own, then update each consumer in a separate pass, verifying each package's build before moving on. Splitting commits by package where you can makes the change reviewable by the people who own each piece and makes a revert precise instead of sweeping.

Is it better to use one long session or several short ones in a monorepo?

Several short ones, scoped per task and per package. A reused session carries the previous task's files and assumptions into the next one, and in a monorepo those assumptions are frequently wrong for a different package. Separate sessions also make it obvious which change caused a problem, because each scope maps to its own set of commits.

• An AI agency website needs six sections: the one-line offer, who it is for, what you actually deliver, proof, price signal, and a single next step.
• The most common failure is a site that lists technologies instead of outcomes, which makes the buyer do the translation work and they will not.
• One page beats five. A buyer decides on the first screen whether you solve their problem, and the rest of the site only confirms it.

The Short Answer

An AI agency website needs six sections and nothing else: a one-line offer naming the outcome you deliver, a clear statement of who it is for, a plain description of what the buyer receives, proof that you have done it, a price signal so they can self-qualify, and one next step. Put all six on a single page in that order. The sections most agency sites lead with, meaning the tool list and the founder story, are the two a buyer cares about least.

NOTE: The test for every block on the page: does it help a buyer decide, or does it help you feel professional? Only the first kind earns space above the fold.

Why Most AI Agency Sites Do Not Convert

The typical AI agency site opens with a headline about transforming your business with artificial intelligence, followed by a row of tool logos and three service cards labelled automation, integration, and consulting. Nothing on that page is false. Nothing on it is useful either, because a buyer cannot tell from it what they would receive, what it would cost, or whether you have solved their specific problem before.

This happens because the site is written from the inside. You know what you can build, so you describe capability. The buyer does not have a capability problem, they have a specific business problem, and they are scanning for a sentence that describes it back to them. When the page is a list of what you can do, they have to work out which item applies to them, and a stranger will not do that work for you.

• Listing tools instead of outcomes. Nobody buys a model or a framework. They buy quotes going out the same day instead of next week.
• No named buyer. A site that speaks to everyone reads as a site with no experience of anyone.
• No price signal anywhere. Silence on price does not create curiosity, it creates a suspicion that it is expensive and negotiable.
• Five links to five thin pages. Splitting one page's worth of substance across a menu is the fastest way to make a small agency look emptier than it is.
• A contact form as the only action. Contact us is not a step, it is a request for the buyer to invent their own next move.

Section One: The One-Line Offer

The first line of the page names the outcome, the buyer, and ideally the timeframe. Not a tagline. A sentence someone could repeat to a colleague accurately after reading it once. If your first line survives being pasted onto a competitor's site unchanged, it says nothing and needs rewriting.

TIP: Write the line for the client you most want three more of. Narrowing the headline does not lose you the other work. It wins the work you want and the rest still arrives through referral.

Section Two: Who It Is For, Said Plainly

Directly under the headline, name the buyer in their own words. Two or three lines is enough. Say the size of business, the industry if you have one, and the situation they are in when they need you. This section does two jobs: the right buyer feels recognised, and the wrong buyer leaves without booking a call that would have wasted both of you a week.

Disqualifying people is the part that feels wrong and is worth the most. A line as simple as 'this is for teams of five to fifty who already have the process working manually and want it to stop eating a day a week' removes the enquiries you would have politely declined anyway, and it makes the ones that come through dramatically warmer.

Section Three: What They Actually Get

Describe the deliverable in concrete nouns. Not our process, not our methodology. The things that exist at the end: the tool, where it runs, who has access, what happens when it breaks, and how long it takes to get there. Buyers are trying to picture the finished thing, and a service described only as a process is impossible to picture.

• The artefact. Name it: an internal dashboard, a client portal, a quoting tool, a set of automations connecting the two systems you already pay for.
• The timeline. A real range, honestly stated. Three to four weeks is a commitment. 'Fast turnaround' is not.
• The handover. Who owns the code, where it is hosted, what happens the day after launch. This is where cautious buyers get stuck, and answering it on the page removes the objection before the call.
• The support after. Whether there is a support arrangement and roughly what it covers. It also sets up the retainer conversation without you having to raise it cold.

Section Four: Proof, Even Without a Long Client List

Proof is the section people skip when they are new, and it is the one that decides most deals. If you have client work, show one thing you built, the problem it solved, and one honest sentence about the result. Ideally with a screenshot of the real interface. If you do not have client work yet, show what you have built for yourself with the same specificity, and label it accurately as your own project.

WARNING: Do not invent numbers to fill this section. An invented percentage is the one thing on a website a serious buyer can catch you on, and it costs you the entire page's credibility. A real screenshot of a real thing you built beats a fabricated statistic every time.

The strongest version of this section is not a testimonial wall. It is one build described end to end: what was broken, what you made, what happened afterwards. A buyer reading one specific story concludes you can do it again. A buyer reading six generic praise quotes concludes nothing.

Section Five: A Price Signal

You do not have to publish a price list. You do have to give a number that lets the buyer place themselves. 'Projects typically start at' followed by a real figure does the qualifying work that would otherwise consume two calls. The reason to do it is not transparency for its own sake, it is that price silence attracts the buyers with the smallest budgets, who are the most likely to fill in your calendar with enquiries that go nowhere.

• A starting-from figure for project work, which sets the floor without committing you to a fixed quote.
• A monthly figure if you offer ongoing support, even as a range, so the retainer is a known option rather than a surprise later.
• A short line on what changes the number. Scope, integrations, and how much of the process is already documented are the honest three.

TIP: If publishing a number genuinely feels impossible, publish the range you have actually charged. It is true, it is defensible, and it still filters the enquiries that were never going to be a fit.

Section Six: One Next Step

End with a single action, stated as a specific thing that happens. Not contact us. 'Book a 20 minute call and we will tell you whether this is worth building' is a step, because the buyer knows the length, the format, and the outcome. One action, repeated two or three times down the page, will beat a page offering a call and a form and a newsletter and a download.

Give the same action the whole way down. A buyer who is convinced by the proof section should not have to scroll back up to find the button. Repeating one call to action is not pushy, it is the removal of friction at the exact moments someone becomes ready to act.

Rewrite Your First Screen This Week

Do not rebuild the site. Open the homepage and rewrite only the first screen: the one-line offer and the who-it-is-for. Then add a price signal further down and cut the tool logos entirely. That is an hour of work, and it will change the quality of enquiry more than a redesign would, because the enquiries you get are downstream of the first sentence a stranger reads.

NOTE: Inside the Claude Code Club members post their homepage first screen and we rewrite the offer line together, usually by cutting it in half. Bring yours and we will tell you what a buyer actually understands from it.

FAQ

What should be on an AI agency website?

Six sections, in order: a one-line offer naming the outcome and the buyer, a plain statement of who it is for, a concrete description of what the client receives, proof of something you have built, a price signal, and one next step. Everything else, including tool logos and the founder story, is optional and belongs below those six. A buyer decides on the first screen whether you solve their problem.

Should I put pricing on my AI agency website?

Put a price signal, not necessarily a price list. A starting-from figure or the range you have actually charged lets buyers place themselves before they book a call, which removes the enquiries that were never going to fit. Price silence does not create intrigue, it attracts the smallest budgets and burns your calendar on calls that end at the number.

How many pages does an AI agency site need?

One good page beats five thin ones, especially early. Splitting a single page's worth of substance across a menu makes a small agency look emptier than it is and adds a click between the buyer and the decision. Add pages later when you genuinely have more to say, such as a real case study or a service that deserves its own explanation.

What do I put on the site if I have no clients yet?

Show what you have built for yourself, described with the same specificity you would use for client work, and label it honestly as your own project. One real build explained end to end, with a screenshot of the actual interface, is more persuasive than a testimonial section with nothing behind it. Never invent numbers or results, because that is the one thing a serious buyer can catch and it costs you the whole page.

Should I list the AI tools and models I use?

Only far down the page, if at all. Buyers do not purchase a tool, they purchase an outcome, and a logo row asks them to translate technology into a benefit that you should have stated yourself. The exception is a buyer with a hard technical requirement, and even then a single line naming what you work with is enough.

• Claude Code vs Gemini CLI comes down to whether your work is one-off or ongoing. Gemini CLI is an open-source terminal agent that is excellent for quick, self-contained tasks. Claude Code is built around a project that keeps existing after today.
• Gemini CLI's biggest advantage is the barrier to entry: it is open source, it installs in one command, and you can start with a personal Google account.
• Claude Code's biggest advantage is persistence. A CLAUDE.md file, skills, subagents, and permission rules mean the agent starts every session already knowing your project's conventions instead of being re-briefed.
• If you never open the terminal, that alone decides it. Claude Code ships as a desktop app; Gemini CLI is terminal-only by design.

Claude Code vs Gemini CLI: The Short Answer

Use Gemini CLI when the task starts and finishes in one sitting, and use Claude Code when the project has to survive past this week. Gemini CLI is Google's open-source coding agent that runs in your terminal, and it is genuinely good at the shape of work where you describe a task, watch it happen, and move on. Claude Code is built around the assumption that you will come back to this codebase tomorrow, next month, and after someone else has touched it.

That single distinction explains almost every other difference between them. One is optimized for the session. The other is optimized for the project.

NOTE: Both products change fast, and their plans and limits change faster than any article can track. Check the current pricing and usage limits on each product's own site before you commit money or build a workflow around a free tier.

Where They Actually Differ

The two agents overlap heavily on the basics. Both read your files, write code, run commands, and connect to external tools through MCP. The differences that change your day are about where the agent lives and what it remembers.

Read that table again with one question in mind: how many times will you explain your project's conventions? On Gemini CLI, the answer trends toward once per session. On Claude Code, the answer is once, in a file, and never again.

What Gemini CLI Is Genuinely Better At

Gemini CLI is better at the cold start. There is no purchase decision on day one, the install is a single command, and it runs against a Google account most people already have. For a developer who wants to test whether an agent is useful at all, that is the lowest-friction entry point available right now.

• Open source, which means you can read exactly what it does before you let it touch a repository. For anyone whose employer asks that question, this is not a small detail.
• No commitment to evaluate. You can find out whether agentic coding fits your work before anyone approves a spend.
• Terminal-native, which is an advantage if you already live in a terminal multiplexer and want the agent in the same pane as everything else.
• Easy to script around. An open-source CLI is a normal Unix citizen, so wiring it into existing shell workflows is straightforward.

The honest summary: if your work is mostly self-contained tasks in repositories you already know well, Gemini CLI does that job and costs you nothing to find out.

What Claude Code Is Genuinely Better At

Claude Code is better at the second week. Everything it does that Gemini CLI does not is aimed at the same problem: an agent that forgets your project is an agent you have to manage forever. The features that look like extras on day one are the entire point by day thirty.

• A CLAUDE.md file the agent reads every session, so the conventions of your project are permanent instead of retyped. See our guide to the [Claude Code CLAUDE.md file](/blog/claude-code-claude-md-file) for what belongs in it.
• Skills, which package a repeatable procedure into something the agent invokes on its own when the situation matches. Read [how to create a Claude Code skill](/blog/how-to-create-a-claude-code-skill).
• Subagents, which let a long task be split into isolated workers so one agent's context does not poison another's. See [Claude Code subagents](/blog/claude-code-subagents).
• Permission rules that persist, so the agent can act freely inside the boundaries you set and stop cold outside them. See [Claude Code permissions explained](/blog/claude-code-permissions-explained).
• A desktop app, which matters enormously if you are not a terminal person and have been quietly excluded from every agent tool until now.

The trade is that all of this is configuration you did not have to do on Gemini CLI. Setting up a CLAUDE.md and a permission policy is thirty minutes you spend once. If the project is a weekend script, that thirty minutes was wasted. If the project is a client build, it pays back inside the first week.

The Desktop App Question

Gemini CLI is a command line tool. That is not a criticism, it is the product's name and its design. But it does mean that if you are not comfortable in a terminal, the tool has a floor you have to clear before you get any value from it at all.

Claude Code ships as a desktop app where you type what you want in plain English and watch the work happen in a window. The terminal is available and plenty of people use it, but it is optional rather than mandatory. Inside Claude Code Club this is the single most common reason someone gets unstuck: they assumed they needed to learn shell commands first, and they did not.

TIP: If you have avoided agentic coding because every tutorial opens with a terminal window, start with the desktop app. The skill you actually need is describing what a project should do, which has nothing to do with the command line.

How to Choose in Sixty Seconds

Answer three questions honestly and the decision makes itself.

1. Will anyone open this project again in a month? If no, Gemini CLI is fine and free. If yes, the persistent-memory features are the whole reason to pay for anything.
2. Do you work in the terminal by choice? If yes, either tool fits. If no, Claude Code's desktop app removes a barrier that Gemini CLI does not have a plan to remove.
3. Does someone need to approve the tool before it touches your code? If yes, an open-source agent is a much shorter conversation with a security team than a closed one.

Notice that none of those questions is about which model is smarter. Model quality moves every few months and both of these are backed by frontier labs. The thing that will still be true a year from now is the shape of the tool around the model.

Using Both Without Making a Mess

Running both is reasonable and a lot of people do. The mistake is letting two agents write to the same repository under two different sets of conventions, because you end up with a codebase that argues with itself.

• Pick one agent as the owner of each repository. Ownership means that agent's convention file is the source of truth for that project.
• Use the other one for throwaway work: a script in a scratch folder, a one-off data conversion, a quick investigation of an unfamiliar library.
• Never let a second agent make structural changes to a project the first agent maintains without updating the convention file first.

This is the same discipline you would apply to two developers on one repository, and it works for the same reason. The problem was never the second contributor. It was two contributors with no shared written standard.

Where to Go From Here

If you are still deciding, the cheapest experiment is to take one real task you have been putting off and run it through whichever tool has the lower barrier for you today. A single completed task tells you more than any comparison article, including this one.

Inside Claude Code Club, members bring exactly this question every week, usually with a half-finished project and a deadline attached. We look at the actual repository, decide what belongs in the convention file, and get the project to a state where the agent stops needing to be re-briefed. If you want that conversation about your project, come and post it at claudecodeclub.ai for $9 a month.

FAQ

Is Gemini CLI free?

Gemini CLI is open source and offers a free tier you can start on with a personal Google account. Free tiers and their limits change regularly, so confirm the current terms on Google's own page before you plan work around them.

Is Claude Code better than Gemini CLI?

Neither is better in general. Gemini CLI is better for self-contained tasks and for teams who need an open-source tool they can inspect. Claude Code is better for projects that continue past one session, because its memory, skills, and permission features exist specifically to stop you re-explaining the project every time.

Can I use Claude Code without the terminal?

Yes. Claude Code ships as a desktop app where you describe what you want in plain English. The terminal is an option, not a requirement, which is the main practical difference for anyone who is not already a command line user.

Do both support MCP servers?

Yes, both connect to external tools and data through MCP. The difference is what sits on top: Claude Code adds a plugin layer and skills that can invoke those tools automatically when a task matches, rather than only when you ask directly.

Can I run both on the same project?

You can, but assign one agent as the owner of each repository so there is a single convention file that is the source of truth. Two agents writing to one project under two different standards produces a codebase that contradicts itself.

Which one should a complete beginner start with?

If you are not comfortable in a terminal, start with the Claude Code desktop app, because it removes the step most beginners stall on. If you are already a terminal user and want to test agentic coding before spending anything, Gemini CLI is the lower-friction way to find out.

• When a Claude Code MCP server is not working, check the MCP status first. It tells you whether the server failed to start, started and then disconnected, or started fine and simply shows no tools.
• Those three states have completely different causes, and treating a disconnect as a config error is why most people spend an hour on a five-minute problem.
• The five usual causes, in the order worth checking: the command is not on the PATH Claude Code sees, a required environment variable is missing, the config file has a syntax error, the server is scoped to a different project, or the server is printing to stdout and corrupting the protocol.
• Restarting Claude Code after any config change is not superstition. Server definitions are read at startup, so an edit made mid-session has not been loaded.

First, Find Out Which Failure You Have

Before changing anything, check the MCP status inside Claude Code. Every server will be in one of three states, and the fix depends entirely on which one you are looking at. Guessing at this step is the single biggest time sink in MCP troubleshooting.

1. Failed to start. The process never launched. This is a command, path, or config problem, and it is the easiest of the three to fix.
2. Connected, then disconnected. The process launched and then died or broke the protocol. This is usually a missing credential or something the server printed to stdout.
3. Connected, but no tools appear. The server is fine. Your problem is scope, permissions, or the fact that the tools are there and you are looking in the wrong place.

WARNING: If you skip this step and start editing config for a server that is actually connected, you will break a working setup and then be debugging two problems instead of one. Read the state first.

Cause One: The Command Is Not on the PATH Claude Code Sees

This is the most common cause by a wide margin, and it produces a failed-to-start state. Your MCP config names a command to run. Claude Code launches that command in its own environment, which is not necessarily the same environment as the terminal where you tested it.

The classic version of this is a tool installed by a version manager. Your shell profile puts it on the PATH when you open a terminal, but the desktop app was launched by the operating system and never read your shell profile. The command works when you test it and fails when Claude Code runs it, which feels like the tool is lying to you.

• Test the exact command from the config, not a shortened version of it. If the config names a runner plus a package, run that whole line.
• If it works in your terminal but fails in Claude Code, replace the command with its full absolute path in the config.
• Find the absolute path by asking your shell where the command lives, then paste that path in verbatim.

An absolute path is less elegant and dramatically more reliable. On a machine that will run this setup unattended, take the reliability.

Cause Two: A Missing Environment Variable

This produces the connected-then-disconnected state. The server starts, tries to authenticate against whatever it wraps, gets nothing, and exits. Because it technically started, the status often reads as a disconnect rather than an error, which sends people looking at the wrong file.

MCP servers do not inherit your shell environment, for the same reason the PATH problem happens. If a server needs an API key, that key has to be declared in the server's own configuration block, not exported in your shell profile.

WARNING: Do not paste a live API key into a config file that is committed to a repository. Keep secrets in a file your version control ignores, and reference them. Our guide to [Claude Code environment variables](/blog/claude-code-environment-variables) covers the safe patterns.

One detail that catches people: a key that is present but expired produces exactly the same symptom as a key that is missing. If the variable is definitely set and the server still disconnects, test the credential directly against the service before you touch the config again.

Cause Three: The Config File Has a Syntax Error

A single trailing comma or an unclosed brace will stop every server in the file from loading, not just the one you were editing. The symptom is alarming and misleading: servers that worked yesterday all disappear at once after you added one new entry.

• If several servers vanish together right after an edit, assume a syntax error before you assume anything else.
• Validate the file rather than reading it. Human eyes skip over a missing brace reliably, and a parser never does.
• Add one server at a time and restart between each. Batch-adding four servers and then debugging is a false economy.

This is also the easiest failure to prevent. Keep a known-good copy of the config before you edit it, so that reverting is a file copy and not an act of memory.

Cause Four: The Server Is Scoped Somewhere Else