DEV Community: Alex Cloudstar

Claude Code GitHub Actions: Setup, @claude Mentions and Automatic PR Review

Alex Cloudstar — Thu, 29 Oct 2026 16:59:43 +0000

Claude Code GitHub Actions: Setup, @claude Mentions and Automatic PR Review

The first time you tag @claude on a GitHub issue and watch a pull request show up twenty minutes later, it feels a little like cheating. You wrote two sentences. Something read the repo, made a branch, ran the checks and left a comment explaining what it did.

Then the second feeling arrives. Who exactly is allowed to trigger that? What is it allowed to touch? And what does each of those twenty minutes cost?

This guide covers the Claude Code GitHub integration end to end: the one-command setup, the manual setup, the @claude workflow, an automatic pull request review workflow, the difference between the open-source action and the managed Code Review product, how to cap the bill, and the security settings I would not skip. I checked it against Anthropic's documentation on October 29, 2026. The action and the app change fast, so where this page and the docs disagree, trust the docs. Sources are at the bottom.

What "Claude Code GitHub" Actually Means

Claude Code GitHub Actions is a GitHub Action, anthropics/claude-code-action, that runs Claude Code inside your repository's workflows. It responds to @claude mentions and can also run a prompt automatically on any GitHub event.

The confusing part is that several things share the Claude Code name on GitHub. The docs say this outright, and it is worth getting straight before you configure anything:

The GitHub Action (this guide). You add workflow files to the repo, and the job runs on your GitHub runners with your credentials.
Code Review. A managed service that reviews every pull request on Anthropic infrastructure. No workflow file. It is for Team and Enterprise plans.
The /code-review command. You run it inside a local Claude Code session on your own branch. Any plan.
Claude Code in the cloud. Sessions that run on cloud infrastructure instead of your laptop, including auto-fix for pull requests.
The Agent SDK. The action is built on it. You use it directly when you want automation outside GitHub.

If your goal is "tag Claude in an issue and get a PR", you want the action. If your goal is "every PR gets a review without anyone maintaining YAML", look at Code Review, which I cover further down. If you only want a review of your own branch before you push, the local command is enough.

Everything below is the action unless I say otherwise.

Quick Setup With /install-github-app

The fastest path is one slash command. You need admin access to the repository, and the GitHub CLI installed and authenticated with gh auth login. Claude Code checks for gh and warns you if it is missing.

cd your-repo
claude

Then inside the session:

/install-github-app

Follow the prompts. Claude Code does four things for you:

Installs the Claude GitHub App on the repository.
Sets up an authentication secret. If Claude Code already has an API key it reuses it and offers to keep an existing ANTHROPIC_API_KEY secret. Otherwise you pick between creating a long-lived token tied to your Claude subscription or pasting an API key.
Saves the credential as a repository secret, named ANTHROPIC_API_KEY for a key or CLAUDE_CODE_OAUTH_TOKEN for a subscription token.
Pushes a branch with the workflow files you selected, already wired to that secret, and opens GitHub in your browser with a pull request ready to create.

Merge that pull request and @claude works in the repo. That is the whole setup.

A few details from the docs that save you time:

github.com only. If your remote is on GitLab or Bitbucket, the command prints a notice and exits. GitLab has its own CI/CD integration.
You can bail out. Press Esc to stop partway. A step already running finishes, nothing later starts, and the closing message lists what already happened, such as a pushed branch or a saved secret.
You can install the app now and finish later. Choose "Skip for now" after the app install, then run /install-github-app again when you are ready for the workflow and secret.
It can update old workflows. If the repo already has a claude.yml, rerun the command and choose "Update workflow file with latest version". It opens a fresh PR with the new files.
The review workflow is optional. If you select it during setup, Claude posts each review on the PR as inline comments, or one summary comment when it finds nothing. Before v2.1.229 it wrote reviews only to the workflow run log, so if your review workflow was generated earlier, update it.

Quick setup works with the Claude API and Claude subscriptions. If you run Claude Code through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, the setup is different and covered in the cloud providers section below.

Manual Setup: App, Secret, Workflow File

Use the manual path when you do not run Claude Code locally, when the command fails, or when you want full control of the files.

1. Install the Claude GitHub App. Install it on the repository. The action relies on three of its permissions: Contents (read and write), Issues (read and write) and Pull requests (read and write).

2. Add a secret. Add one of these as a repository secret:

ANTHROPIC_API_KEY: a key from the Claude Console.
CLAUDE_CODE_OAUTH_TOKEN: a token that authenticates with your subscription, available on Pro, Max, Team and Enterprise. Generate it by running claude setup-token locally.

In workflow files, the API key goes to the anthropic_api_key input and the token goes to claude_code_oauth_token.

3. Copy the workflow. Take examples/claude.yml from the action's repository into .github/workflows/. As committed it responds to @claude mentions using ANTHROPIC_API_KEY. If you use the OAuth token instead, change that one line to claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Test it by tagging @claude in an issue or PR comment.

API Key or Subscription Token?

This is the choice people get wrong, so here is how I would decide:

Solo repo, personal project: the subscription token is fine. Runs use your subscription instead of API billing, which means they also count against your allowance. If you have ever hit the wall, read how Claude Code usage limits work before you let a bot spend it for you on every PR.
Team repo or organization: use an API key. The docs make the point directly: an OAuth token is tied to the subscription of the person who ran claude setup-token. When that person leaves or changes plan, every repo using their token breaks, and their personal allowance is what is paying for the team's reviews.
No long-lived secret at all: use workload identity federation. The action exchanges the workflow's GitHub OIDC token for API access through a Claude Console service account. You set anthropic_federation_rule_id and anthropic_organization_id, optionally the service account and workspace IDs, and grant the job id-token: write.

The @claude Workflow, Line by Line

Here is the workflow from the docs for responding to mentions:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The parts that are not boilerplate:

id-token: write is required for the action's default GitHub App authentication.
actions: read lets Claude read CI results on pull requests. That is how it can say "the tests failed on this line" instead of guessing.
actions/checkout gives Claude a local copy of the repo to work in.
if: contains(...) keeps runners from starting on comments that do not mention @claude. The action also checks the trigger phrase itself, but the if saves you a runner spin-up on every unrelated comment.

Once it is merged, you talk to it in plain language:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Claude replies in a comment on the same issue or PR and updates that comment as it works. The trigger phrase is @claude by default and can be changed with trigger_phrase.

One thing the docs state that is easy to miss: the comment must contain @claude as a complete word. /claude and @claude-bot do not count.

What Makes a Good @claude Request

The action is only as good as the instruction. The cost section below says the same thing from the money side: specific requests need fewer turns. Three habits that help:

Point at files and symptoms. "Fix the TypeError in UserDashboard.tsx when user.profile is null" beats "fix the dashboard bug".
Say what done looks like. "Add a test that fails before the fix" gives it a finish line.
Ask questions first when the design is open. @claude how would you approach this? costs less than a branch you throw away. It is the same logic as plan mode: decide before you build.

Interactive Mode vs Automation Mode

The action picks its mode from your workflow, with no mode input to set.

Interactive mode. No prompt input. Claude waits for the trigger phrase in an issue comment, a PR comment, a PR review, or the title or body of a newly opened issue, then responds. Progress and results show up as a comment.
Automation mode. You provide a prompt. Claude runs on whatever event triggers the workflow, without anyone mentioning it. By default the output goes to the workflow run log, not a comment. It can post to the issue or PR only when your prompt tells it to and it has a tool that can post.

That second point trips people up. You set up an automatic reviewer, the job goes green, and nothing appears on the pull request. The review is in the run log. Posting is opt-in, and the next section shows how.

Automatic Pull Request Review

This is the workflow most teams actually want. It runs on every pull request and posts a review. The docs example uses the official code-review plugin:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-plugins-official.git"
          plugins: "code-review@claude-plugins-official"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Two lines decide where the review goes:

--comment makes Claude post the review on the PR, as an inline comment on each issue or one summary comment when it finds none. Leave it off and nothing is posted.
claude_args with --allowedTools has to stay, even though the skill names the same tool in its own frontmatter. The action only starts the MCP server that posts inline comments when --allowedTools in claude_args names it.

Notice the permissions. This job gets contents: read and pull-requests: read, not write. A reviewer does not need to push code. Giving it less is free and removes a whole class of surprises.

What it skips, per the docs: draft and closed pull requests, pull requests it judges not to need a review (automated or trivial ones), and pull requests that already have a comment from Claude.

Two practical limits:

Fork PRs on public repos. GitHub withholds secrets from runs triggered by fork pull requests, so this review only runs on PRs from branches in the same repository.
It is not a merge gate. Treat the output as a second reader, not an approver. My own take is that it should never be the only review on code that touches auth, billing or data deletion. The pull request manifest I wrote about earlier is a better way to make agent-written PRs checkable by a human, whichever tool wrote them.

You are not locked into the plugin either. The prompt input accepts plain text or a skill invocation. For a skill that lives in your repo's .claude/skills/ directory, run actions/checkout first and pass /skill-name as the prompt. If you want to write your own review skill with your team's rules in it, writing a Claude Code skill walks through the format.

Claude Code Action vs Managed Code Review

There are two ways to get automatic reviews on GitHub, and they are different products. This table is the short version:

	GitHub Action (this guide)	Managed Code Review
Setup	Workflow files in your repo	An Owner turns it on in admin settings
Runs on	Your GitHub runners	Anthropic infrastructure
Plans	Anyone with an API key or cloud credentials	Team and Enterprise
Billing	Actions minutes plus API tokens or subscription	Managed, with a monthly spend limit
Customization	Your prompt, plugins, `CLAUDE.md`, any trigger	`REVIEW.md` and `CLAUDE.md`
Beyond review	Edits code, pushes commits, runs any prompt	Review only, read-only access, never pushes

How the managed product works, per the docs: several agents read each change alongside the surrounding code, a verification step checks the findings against the code to filter false positives, the rest are deduplicated and ranked by severity, and the results land as inline comments, a summary and a check run called Claude Code Review. The check run does not conclude as a failure, and a review never approves or blocks the PR. There are three review levels, Quick, Standard (the default) and Deep, and more thorough means more cost.

It is not available to organizations with Zero Data Retention enabled or with the HIPAA configuration applied, and a review works only by reading the diff and the surrounding code. It does not build or run your code.

My rule of thumb: if you are on Team or Enterprise and the only thing you want is reviews, use the managed product and delete the YAML you would otherwise maintain. If you want Claude to also take tickets, fix CI or run scheduled jobs, you need the action anyway, and you can run both. For a wider look at the review tool market, see the AI code review tools comparison.

Teach It Your Standards With CLAUDE.md

Claude reads your CLAUDE.md on every run. That makes it the cheapest lever you have over review quality. Put in the things a human reviewer on your team would say out loud: code style rules, what counts as a blocker, patterns to prefer, directories nobody should touch.

Two cautions from the docs and from common sense:

Keep it short. The docs list a concise CLAUDE.md as a cost saver precisely because it is read on every run. A 600-line file is a token tax on every pull request.
Move workflow detail into skills. Rules about how to do a task belong in a skill that loads on demand. Rules about what the project is belong in CLAUDE.md.

For the managed Code Review product, REVIEW.md is read from the base or default branch and never from the pull request's own changes. That detail matters: it means a contributor cannot edit the review instructions inside the PR they want reviewed.

Run Claude on a Schedule

With a prompt and a schedule trigger, the action becomes a cron job that can think. The docs example generates a daily report of commits and open issues:

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

Things to know before you rely on it:

No tools by default for a plain-text prompt. Claude has no shell or GitHub API access until you grant tools with --allowedTools or a permissions.allow rule in the settings input. A skill invocation can use the tools its own frontmatter grants.
Default branch only. GitHub runs scheduled workflows only from the default branch.
60-day shutoff on public repos. GitHub disables the schedule after 60 days without repository activity.
Output goes to the run log unless you tell it to post somewhere.
The actor check still applies. GitHub attributes scheduled runs to a repository user, usually the one who last changed the cron line. If that user is a bot, list it in allowed_bots.

Good scheduled jobs are boring ones: a weekly dependency report, a stale-issue triage summary, a changelog draft. Anything that mutates the repo on a timer deserves a second look.

Who Can Trigger It, and What It Can Touch

This is the part to read twice. You are letting text typed into a GitHub comment start a process that has write access to your code and a billable credential. The action has guardrails, and you should know exactly what they are.

Two checks run before Claude starts. The run fails if either rejects the actor:

Write access. On issue and pull request events, the triggering user must have write access to the repo. To allow specific users without it, set allowed_non_write_users and pass your own github_token.
Human actor. On every event, a bot actor is rejected unless it is in allowed_bots. This is what stops bots from triggering Claude in a loop.

The app has a wide permission set. This surprised me when I first read it. The Claude GitHub App is shared by every Claude feature that integrates with GitHub, so installing it grants Actions, Checks, Contents, Discussions, Issues, Pull requests, Workflows and Repository hooks at read and write, plus Administration, Members, Merge queues, Metadata and Statuses at read. GitHub does not let you accept a subset. If your organization only allows what the action itself needs (Contents, Issues, Pull requests), the docs say to create a custom GitHub App with just those. Note that a custom app covers only the action. Code Review and web auto-fix still need the official app.

What I would do on top of the defaults:

Give every job the minimum permissions block. The review workflow above is read-only on purpose. Only the @claude workflow needs write.
Treat issue and PR text as untrusted input. Anyone who can comment can put instructions in front of the model. The write-access check limits who that is, but a repo with many collaborators still has many people who can steer it. This is my reasoning, not a quote from the docs: assume a hostile sentence will eventually reach the prompt, and make sure the damage is bounded by the token's permissions and --allowedTools. The least-privilege guide for coding agents goes deeper on that thinking.
Never put a key in the repo. Secrets only, referenced as ${{ secrets.ANTHROPIC_API_KEY }}. The docs repeat this one for a reason.
Review everything before merging. Branch protection should still require a human approval. Claude's PRs are PRs.
Pin the action. The docs use @v1. For a job that holds write permissions, pinning a full commit SHA is the standard GitHub hardening advice, and the cost is updating it on purpose.

If you want a hard stop on specific commands inside the job, Claude Code hooks work in CI the same way they work on your machine.

What a Run Costs and How to Cap It

Each run spends two different things:

GitHub Actions minutes. The job runs on GitHub-hosted runners and uses your Actions minutes.
Tokens. Based on prompt and response length, task complexity and codebase size. With an API key you pay API rates. With an OAuth token, runs use your Claude subscription.

The docs list the levers. I would turn most of them on from day one:

--max-turns in claude_args caps iterations. claude_args: "--max-turns 5 --model claude-sonnet-5" is the docs' own example.
Workflow timeout-minutes stops a runaway job. Pick a number you would be annoyed to exceed, say 15.
Concurrency controls limit parallel runs so five comments in a row do not start five jobs. A group keyed on the issue or PR number works:

concurrency:
  group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
  cancel-in-progress: false

A concise CLAUDE.md, since it is read on every run.
Specific requests and issue templates so Claude needs fewer turns to find the problem.
A cheaper model for routine jobs. Review and triage rarely need the largest model. Set it with --model in claude_args, or leave it off to use the Claude Code default.

For org-wide tracking, the docs point to the analytics dashboard and the monitoring page. If you are on a subscription token and your allowance keeps vanishing, the reason is probably in what drains Claude Code usage fastest: long contexts, subagents and large models, all of which a busy CI job can hit.

Roll It Out Across an Organization

Quick setup and manual setup both work one repo at a time. For many repos:

Install the Claude GitHub App once at the organization level, on all repos or a selected list.
Store the secret as an organization-level Actions secret. Use an API key, not an OAuth token, for the reason covered earlier.
Add the workflow to each repo that should run it, or define the job once as a reusable workflow that each repo calls. The reusable route means one place to fix the version pin or the --max-turns value.

Bedrock, Vertex and Foundry

By default the action calls the Claude API directly. To route inference through your own cloud account instead, set one input:

use_bedrock: "true" for Amazon Bedrock
use_vertex: "true" for Google Cloud's Agent Platform
use_foundry: "true" for Microsoft Foundry

All three authenticate through OIDC identity federation, so no static cloud credentials sit in the repository. The setup has its own page in the docs, including a custom GitHub App with APP_ID and APP_PRIVATE_KEY secrets, and I would follow that page step by step instead of improvising.

Troubleshooting

Claude does not respond to @claude.

Check the GitHub App is installed on the repo and workflows are enabled.
Check the secret exists in repository secrets.
Check the comment has @claude as a whole word.
Check the commenting user has write access.

CI does not run on Claude's commits. GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} to the action, remove it so the action authenticates as the Claude GitHub App, or pass a custom app token. Also check that your CI triggers include the events Claude's pushes produce, such as push or pull_request. This one bites almost everyone: Claude opens a PR, the checks never start, and the PR looks stuck.

Authentication errors. Test the key or token locally with claude before debugging the workflow. A dead credential looks the same as a workflow bug from the outside.

A review job passes but nothing shows on the PR. You are in automation mode without --comment and the inline comment tool. See the review section above.

Still on @beta. Update to v1: change @beta to @v1, remove the mode input, replace direct_prompt with prompt, and move CLI options such as max_turns and model into claude_args. custom_instructions becomes --append-system-prompt.

Where This Fits in Your Workflow

My view is that the action earns its keep in two places and wastes money in a third.

It earns its keep on small, well-specified tickets, where the fix is a paragraph of description and a test. Typos in docs, a missing null check, a dependency bump with a changelog to read. These are the jobs where a twenty-minute wait for a draft PR beats context-switching.

It also earns its keep as a second reader on pull requests, especially on a team where review is the bottleneck. Used that way it is a filter that catches the obvious mistakes before a human spends attention. If review volume is your actual problem, the AI code review bottleneck is worth a read before you add more generated code to the pile.

It wastes money when the task is vague. "Improve the performance of the app" will burn turns, produce a sprawling diff and teach your team to distrust the bot. The fix is the same as in any Claude Code session: smaller tasks, clearer instructions. If you are new to the tool itself, start with how to use Claude Code locally before you hand it your CI.

A sensible rollout looks like this:

Run /install-github-app on one low-risk repo.
Start with the review workflow, read-only permissions, --max-turns set.
Add the @claude workflow once you trust the reviews.
Write the project rules into a short CLAUDE.md.
Add concurrency and a timeout.
Move to an org-level API key and a reusable workflow when a second repo wants it.

Frequently Asked Questions

What is Claude Code GitHub Actions? It is a GitHub Action, anthropics/claude-code-action, that runs Claude Code in your workflows. Mention @claude in a PR or issue comment and it analyzes code, implements changes and pushes commits. With a prompt it can run on any GitHub event.

How do I install Claude Code on GitHub? Run /install-github-app inside Claude Code in your repository. It installs the Claude GitHub App, saves an authentication secret and opens a pull request with the workflow files. You need admin access and the GitHub CLI authenticated with gh auth login.

Is Claude Code GitHub Actions free? The action is open source, but each run uses GitHub Actions minutes and either API tokens or your Claude subscription allowance. Cost depends on prompt length, task complexity and codebase size.

Does Claude Code GitHub integration work with a Claude Pro or Max subscription? Yes. Generate a token with claude setup-token and store it as CLAUDE_CODE_OAUTH_TOKEN. Pro, Max, Team and Enterprise plans can do this. Runs then use your subscription instead of API billing.

Should I use an API key or an OAuth token? Use an API key for shared and team repos. An OAuth token is tied to the subscription of the person who generated it, so it breaks when that person leaves and spends their personal allowance.

How do I trigger Claude in a pull request? Comment @claude followed by your request, from a user with write access to the repository. The trigger phrase is configurable with trigger_phrase.

Can Claude Code review pull requests automatically? Yes, two ways. Add a workflow that runs a review skill on pull_request events, with --comment so it posts to the PR. Or, on Team and Enterprise plans, turn on the managed Code Review product, which needs no workflow file.

What is the difference between Claude Code Review and the GitHub Action? Code Review is a managed service on Anthropic infrastructure for Team and Enterprise plans. It reviews only, with read-only access. The action runs on your runners, works on any plan with a key, and can also edit code, push commits and run any prompt.

Does Claude Code GitHub work on GitLab? /install-github-app works only with github.com repositories. For GitLab pipelines, use Claude Code GitLab CI/CD.

Why is Claude not responding to my @claude comment? Check that the app is installed, workflows are enabled, the secret is set, the comment contains @claude as a full word, and the commenter has write access.

Why does CI not run on Claude's commits? GitHub does not trigger workflows for commits made with the default GITHUB_TOKEN. Remove github_token: ${{ secrets.GITHUB_TOKEN }} from the action so it authenticates as the Claude GitHub App.

Can Claude Code run on a schedule in GitHub Actions? Yes. Add a schedule trigger and a prompt. Scheduled workflows run only from the default branch, and public repos lose the schedule after 60 days without activity.

How do I limit what Claude can do in CI? Set a minimal permissions block on the job, restrict tools with --allowedTools, cap iterations with --max-turns, add a workflow timeout, and require human approval before merge.

Can I use Claude Code GitHub Actions with Bedrock or Vertex? Yes. Set use_bedrock, use_vertex or use_foundry to "true" and authenticate through OIDC federation instead of an API key.

Does the managed Code Review work with Zero Data Retention? No. It is not available to organizations with Zero Data Retention enabled or the HIPAA configuration applied.

Sources, all checked October 29, 2026: Claude Code GitHub Actions, Code Review, the claude-code-action repository with its setup guide and security notes, and the Claude GitHub App.

Claude Code Usage Limits: How the Weekly Limit, 5-Hour Window and Reset Times Work

Alex Cloudstar — Wed, 28 Oct 2026 12:48:14 +0000

Claude Code Usage Limits: How the Weekly Limit, 5-Hour Window and Reset Times Work

Most people find out about the Claude Code usage limit the same way. You are forty minutes into a good session, the agent is mid-refactor, and the terminal says You've hit your session limit · resets 3:45pm. Nothing warned you, or if it did, you were not looking. Now you have a half-finished change and a few hours to think about how it happened.

The frustrating part is that the rules are not complicated. They are just spread across a help center article, a costs page and an errors reference, and none of them gives you a number to plan around. So most advice online is either a table of guessed "prompts per hour" or a rant.

This guide is the version I wanted. It covers how Claude Code usage limits work on Pro and Max, when the weekly limit and the 5-hour window reset, what actually drains them, how to see where you stand, how to make the allowance last, and what your options are when it runs out. I checked everything against Anthropic's documentation on October 28, 2026. Limits and plan details change often, so if something here has drifted, trust the docs over me. I list the sources at the bottom.

How Claude Code Usage Limits Work

On a Pro or Max plan, Claude Code usage is governed by two limits at the same time: a rolling 5-hour session limit and a weekly limit. Claude Code and claude.ai draw from the same pool, so chatting in the browser uses the same allowance as coding in the terminal.

Here is what each part means in practice.

The 5-hour session limit. It is a rolling window, not a clock-hour reset. Your usage counts against it, and when you run out, Claude Code blocks requests until the reset time shown in the error message. Hitting it does not mean you are done for the day. It means you are done until that time.

The weekly limit. This is a second ceiling over a longer period. The errors reference says usage counts against the session and weekly allowances at the same time, and that a large burst of activity can exhaust the weekly allowance before the session window resets. In other words, you can have plenty left in your 5-hour window and still be blocked, because the week is spent.

The shared pool. The help center says all activity in Claude and Claude Code counts against the same limits. That includes the IDE extensions. If you spend the morning in long claude.ai conversations, you start the afternoon coding session with less.

Separate model limits. Max plans also have a separate weekly limit for Fable. On the pricing page, Pro can reach Fable only through usage credits, while both Max tiers get it at 50% of weekly limits. Separately, you can see model-family messages such as You've hit your Opus limit or You've hit your Sonnet limit. Those apply only to that family, and switching to a model outside it keeps you working. The session and weekly limits apply across all models, so switching does nothing there.

One more recent change worth knowing: a promotion that raised Claude Code weekly limits by 50% ran from May 13 through September 13, 2026. It has ended, but Anthropic says part of it stayed. Since September 14, weekly limits in Claude Code are 25% higher than before the promotion. The 5-hour limits were never part of it. If you read an older guide that mentions a 50% boost or an August cutoff, it is out of date.

When Does the Claude Code Usage Limit Reset?

When you hit a limit, the message includes the reset time:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am

Those are the examples from Anthropic's error reference. The times are examples, not a schedule. The docs do not spell out exactly when a window starts counting, so do not do the arithmetic yourself. Read the reset time from the message, or run /usage, which shows your plan limits and reset times.

Two things worth knowing about resets:

The weekly limit and the 5-hour window are independent. The 5-hour window resetting does not refill the weekly allowance. If the weekly limit is what stopped you, the 3:45pm reset in your head is wrong.
There is no documented way to reset early. What the docs describe instead are ways to keep working: usage credits (/usage-credits), a model outside the affected family for Opus and Sonnet limits, API billing, or a higher plan. I cover each below.

If you stay in the session, Claude Code can wait for the reset and pick the task back up on its own. That is covered in the section on hitting the limit.

What Are the Claude Code Limits Per Plan?

This is the question most pages answer with a confident table, and it is where I will disappoint you. Anthropic does not publish exact token or message counts for Pro, Max 5x or Max 20x. The help center article describes the structure (a 5-hour limit and a weekly limit) and says nothing about capacity in numbers. Any "you get 45 messages per window" figure you see is a third-party estimate, and the estimates disagree with each other.

What is official is the price and the relative size:

Plan	Price	Usage compared with Pro	Claude Code
Pro	$20/month ($17/month billed annually)	Baseline	Included
Max 5x	$100/month	5x	Included
Max 20x	$200/month	20x	Included
API (Console)	Pay per token	No plan window, billed per token	Pay as you go

The Max price points match the table in my June pricing survival guide. The practical reading is simple: Max 5x gives you five times the room Pro gives you, and Max 20x gives you twenty times. Since nobody publishes what the Pro baseline is in tokens, the honest way to size a plan is empirical. Use it for a week and watch /usage.

Anthropic's own upgrade advice is similarly empirical. The help center suggests Pro users consider Max 5x if they "consistently hit limits and need more capacity for larger repositories," and Max 5x users consider Max 20x if they keep hitting limits. Notice the phrase "larger repositories." Repository size matters because it changes how much context every request carries, which is the next section.

Claude Code limits on the Pro plan

Pro includes Claude Code, with the same two limits as Max, only smaller. Three Pro details from the help center and pricing page:

Fable is available on Pro only through usage credits, not the plan allowance.
The "wrapping up" allowance is more limited on Pro. If you hit the 5-hour limit mid-response, Claude Code may finish the step in progress, and on Pro that can happen up to once per weekly usage period. On Max it can apply each time you reach a 5-hour limit. The help center says this is rolling out gradually, so you may not have it yet.
The suggested upgrade path is Max 5x if you consistently hit limits, especially on larger repositories.

If Pro is your plan, the habits in the stretching section matter more, because you have the least headroom for a long session.

For teams, the allowance works the same way at a per-seat level: a rolling five-hour window and a weekly window, shared with chat and Cowork, with the size depending on the seat tier (Standard or Premium).

What Burns Through Your Claude Code Limit Fastest

The limit is a usage allowance, and usage is tokens, not messages. That one fact explains most "I barely did anything and I'm out" stories. The costs page lists the real causes, and I have put them roughly in the order they bite.

1. Long context. Claude Code sends your whole conversation with every request, and every tool use sends another request carrying that batch of tool results. Prompt caching means the history is re-read at the cheaper cached rate, but it is still re-read. The docs spell out the consequence: a one-line question in a session that has been open all day still draws usage for the entire conversation. A session you never clear is the most common way to burn an allowance without noticing.

2. Cache misses after a break. Your first message after a pause longer than the cache lifetime misses the cache and reprocesses the full context. Coming back from lunch to a huge session is more expensive than the same question in a fresh one.

3. Subagents and agent teams. Every subagent sends its own requests on top of the main conversation. The docs say subagent requests "still draw on your usage." Agent teams are heavier: they use roughly 7x more tokens than a standard session when teammates run in plan mode, because each teammate keeps its own context window. I like subagents for keeping noisy output out of the main context, but they are a trade, not a free lunch.

4. Model and thinking effort. Sonnet handles most coding work and costs less than Opus. Extended thinking is on by default and thinking tokens bill as output tokens, with a default budget that can reach tens of thousands of tokens per request. The docs note that on current models you cannot turn thinking off, so the lever is the effort level, not an on/off switch.

5. Heavy background habits. Session-scoped scheduled tasks fire on their interval even while the session is idle, and each firing sends your full context. Messages from other sessions and goal check-ins can start new turns on an idle session too. A /loop you forgot about is a slow leak.

6. Bloated setup. A long CLAUDE.md is loaded at the start of every session and sits in context for every request. MCP servers add overhead too, though tool definitions are deferred by default now so only names and server instructions enter context until a tool is used.

7. Compaction itself. /compact reads the whole conversation it summarizes, so compacting a huge context is a large request. When you want a clean slate rather than continuity, /clear costs nothing.

If I had to pick one lesson from that list, it is that long sessions are the tax. Almost every other item gets worse as the context grows. The 32,784-line workflow post is about shipping a lot of code in short, scoped steps, and part of why that works is that small steps keep each request cheap.

How to Check Your Claude Code Usage

You do not have to guess where you stand. There are three places to look.

The /usage command

Run /usage inside Claude Code. On Pro, Max, Team and Enterprise plans it shows your plan usage bars, activity stats and a breakdown of what counts against your limits. The pieces worth knowing:

Attribution. Recent usage broken down by skills, subagents, plugins and individual MCP servers, each as a percentage of the total.
Recommendations. Suggested changes, one per row, each starting with a share of your recent usage (at least 10%), for example 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request. The share tells you how much of your usage the row applies to, not how much the change saves.
Loops. The heaviest scheduled tasks that ran recently, with how often they fire and how many tokens they used.
Time range. Press d or w to switch between the last 24 hours and the last 7 days.
The f shortcut. When the footer shows a hint like f to fix 2 of 3, pressing f has Claude Code act on the recommendations it can, such as running an /effort change. It needs Claude Code v2.1.305 or later.

Two caveats. The figures are approximate and computed from local session history on the machine you are using, so usage from other devices or claude.ai is not included. And the Session block at the top shows a dollar figure computed at list price. That is meant for API users, so on a subscription ignore the dollar number and look at the plan bars.

/cost still works as an alias in older write-ups, and the commands cheat sheet covers the rest of the slash commands. The help center also points at /status for monitoring your remaining allocation, so if /usage looks different on your version, try that.

Warnings before you hit the wall

Claude Code can warn you before a window runs out, with messages like You've used 85% of your session limit · resets 3:45pm. They are easy to miss in a busy terminal, which is why I prefer a permanent display.

A status line that shows it

A custom status line can show both limits all the time. Status line scripts receive rate_limits.five_hour.used_percentage, rate_limits.seven_day.used_percentage and rate_limits.five_hour.resets_at. These fields only appear for claude.ai Pro and Max subscribers and only after the first API response, so give them a fallback. My status line guide has a full walkthrough, including a setup that stays quiet until the 7-day limit crosses a threshold.

If you only do one thing from this post, put the 5-hour percentage in your status line. Knowing you are at 80% before you start a big refactor changes what you start.

How to Make Your Claude Code Limit Last Longer

None of these are magic. They all do the same thing: send fewer tokens per request, or send fewer requests. Ordered by how much they usually save.

Clear between unrelated tasks. Use /clear when you switch work. Stale context taxes every message that follows. Run /rename first so you can /resume the old session later. This is the highest-value habit on the list, and it costs nothing.

Compact on purpose. When you want continuity, /compact summarizes the conversation. You can steer it: /compact Focus on code samples and API usage tells Claude what to keep. You can also pin the behavior in CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

Compact before a long break, not after. Coming back to a big context after the cache expires is the expensive version.

Use plan mode for anything non-trivial. A wrong first step is the most expensive thing in a session, because you pay for the wrong diff and then pay again to redo it. Planning first is cheap insurance. The plan mode guide covers the details, including opusplan, which uses Opus for planning and switches to Sonnet for the edits.

Pick the model for the job. Run /model to switch mid-session or set a default in /config. Sonnet for the bulk of the work, Opus for hard architectural decisions. One detail from the docs that people miss: a switch to Opus also applies to subagents that inherit your session's model. For simple subagent tasks you can set model: haiku in the subagent configuration.

Lower the effort level. For simple tasks, /effort reduces how much thinking each request does. The /usage recommendations will even suggest it when it spots a pattern, for example Switch from max to high effort · /effort high.

Keep CLAUDE.md lean. The docs suggest under 200 lines, with specialized instructions moved into skills, which load on demand rather than at session start. Detailed workflows for PR reviews or database migrations do not need to be in context while you fix a CSS bug.

Disable MCP servers you are not using. Run /mcp to see what is configured, and /context to see what is eating space. Where a CLI tool exists, such as gh or aws, the docs say it is still more context-efficient than an MCP server because it adds no per-tool listing.

Filter noisy output before Claude sees it. A hook can grep a 10,000-line log down to the error lines before they enter context. The costs page has a working PreToolUse example that trims test output to failures only, and the hooks guide shows how to build your own.

Write specific prompts. "Improve this codebase" triggers broad scanning. "Add input validation to the login function in auth.ts" does not. A tight prompt means fewer file reads.

Stop wrong turns early. Press Esc the moment Claude heads the wrong way, and use /rewind to go back to a checkpoint. Letting a bad direction run for ten minutes is paid for twice.

Delegate noisy work, carefully. Running tests or reading logs in a subagent keeps the verbose output out of your main context. That saves context, but the subagent's own requests still count, so pair it with a smaller model.

Be careful with parallel sessions. Running several sessions or git worktrees at once is great for throughput, but every session burns the same shared allowance. Three sessions working at once pull from that one allowance together, so I treat parallelism as something to spend deliberately, not a default.

What Happens When You Hit the Claude Code Limit

When you run out, the message tells you which limit you hit and when it resets:

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

Claude Code blocks further requests until the reset time shown. Your options, in the order I would think about them:

Let it wait for you. On Claude Code v2.1.234 or later, in an interactive session signed in with a claude.ai subscription, Claude Code can wait in the open session and continue the interrupted task on its own after the limit resets. You will see lines like Usage limit reached · limit resets 3:45pm and Continuing automatically at 3:45pm · Esc to cancel. Keep the session open. A few details from the docs: it prompts Claude to pick the task up where it stopped rather than resending your last message, it still asks for permissions as usual so it can stall on a prompt while you are away, and it gives up after hitting the limit again twice in a row. Press Esc at an empty prompt to cancel, or use /rate-limit-options to manage it.

Switch model families, if it is an Opus or Sonnet limit. Run /model and pick a model outside that family. This does not help with the session or weekly limits, which are shared across models. It also has a cost: each model has its own prompt cache, so the next request re-reads the whole conversation.

Buy usage credits. Run /usage-credits to turn on or manage extra usage on Pro and Max. It opens the usage settings on claude.ai, where you can switch usage credits on, set a monthly spend limit and check your balance. Credits are billed at standard API rates, which are different from your plan pricing. They cover the five-hour, weekly and Fable weekly limits. On Team and Enterprise, the same command sends a request to your admin.

Upgrade. Pro to Max 5x, or Max 5x to Max 20x, if you keep hitting the wall. Upgrade only after a few weeks of data. A habit change is cheaper than $80 a month.

Move to API billing. You can switch to a Console account and buy API credits. There is a trap here: if an ANTHROPIC_API_KEY environment variable is set, Claude Code uses it instead of your subscription, and you get API charges without noticing. If a bill surprises you, run env | grep ANTHROPIC_API_KEY to see whether the variable is set.

Use something else for the gap. If your work cannot stop, a second tool is a legitimate answer. I compared the realistic options in Claude Code alternatives, and the Claude Code vs Codex comparison covers how the two handle plans and limits.

Claude Code Usage Limits vs Rate Limits (429 Errors)

People search for "Claude Code rate limit" and mean two different things.

A usage limit is the subscription allowance above: the 5-hour window and the weekly cap. The message starts with You've hit your... and gives a reset time.

A rate limit is a short-lived throttle on how fast you send requests, and it is unrelated to your allowance. Server is temporarily limiting requests and Request rejected (429) are this kind. Claude Code retries temporary 429s automatically, up to 10 times with exponential backoff by default, and the spinner shows Retrying in Ns · attempt x/y. A 529 overloaded error is a capacity problem on Anthropic's side and does not count against your quota. Wait and retry before you assume you are out.

On API and Console billing, rate limits are the real constraint. The costs page gives per-user starting points for requests-per-minute and tokens-per-minute by team size, for example 200k to 300k TPM and 5 to 7 RPM per user for teams of 1 to 5. Those apply at the organization level, so one user can briefly exceed their share when others are idle.

Claude Code vs Codex: Which Has the Better Limits?

I get asked this one, and the honest answer is that a number-for-number comparison is not possible. Neither side publishes exact capacity, and the third-party tables that claim otherwise are estimates. What you can compare is structure. Claude Code runs a rolling 5-hour window with weekly limits on top. Codex on Plus meters local messages per 5-hour window and calls those numbers estimates, and my notes say its Pro tiers currently have no 5-hour limit. Those details move, so check the vendor pages before you pay. My Claude Code vs Codex comparison goes through plans, models and limits side by side. If you want the wider field, Claude Code alternatives covers the rest.

What About Headless Mode and the Agent SDK?

If you run claude -p, the Agent SDK or Claude Code in CI, the picture is murkier, and it has changed more than once. Anthropic announced that this usage would move to a separate monthly credit pool, then paused the change. As of the last update in that guide, Max and Team plans include monthly API credits covering the Agent SDK, claude -p, the Claude API and Managed Agents. I walk through the whole timeline in the pricing survival guide, and I would read that before you build anything on automated usage.

A Sensible Routine for Staying Under the Limit

If you want something concrete to copy, this is the routine I would give a developer on Pro or Max:

Add the 5-hour and 7-day percentages to your status line.
Start each new task in a clean session with /clear.
Use plan mode when the change touches more than a couple of files.
Default to Sonnet. Use Opus on purpose.
Keep CLAUDE.md short and move workflow detail into skills.
Compact before you step away, not when you come back.
Run /usage once a week and follow the top recommendation.
Leave a session open if you hit the limit mid-task, so auto-continue can pick it up.

That is it. None of it costs quality, and most of it makes sessions faster as well as cheaper, because smaller contexts are quicker to process.

Frequently Asked Questions

What are the Claude Code usage limits? On Pro and Max, two limits apply at once: a rolling 5-hour session limit and a weekly limit. Both are shared with claude.ai. Anthropic does not publish exact token counts per plan.

How long is the Claude Code usage limit? The session limit is a rolling 5-hour window, and there is a separate weekly limit. The error message shows the exact reset time, for example resets 3:45pm.

When does Claude Code usage reset? The reset time is shown in the limit message, and /usage shows your plan limits and reset times. Claude Code can wait and continue your task automatically after the reset if the session stays open.

When does the Claude weekly limit reset? The weekly limit message shows its own reset time, for example resets Mon 12:00am in Anthropic's docs. Read the time from your message or /usage, because it is independent of the 5-hour window.

Can you reset the Claude Code usage limit early? There is no documented way. You can keep working past the limit with usage credits (/usage-credits), API billing, a model outside the affected family for Opus and Sonnet limits, or a higher plan.

What are the Claude Code Pro limits? Pro has the same two limits as Max, at the smallest allowance. Anthropic does not publish token counts, Fable is available only through usage credits, and the suggested upgrade is Max 5x if you consistently hit the wall.

What is the difference between a usage limit and a rate limit? A usage limit is the 5-hour and weekly subscription allowance. A rate limit, such as a 429 or Server is temporarily limiting requests, is a short throttle that Claude Code retries automatically.

Which has better limits, Claude Code or Codex? Neither publishes exact capacity. Compare plans and structure in the Claude Code vs Codex comparison, and test on the cheap tier first.

Do Claude and Claude Code share the same limit? Yes. The help center says all activity in both tools counts against the same limits, including IDE usage.

Does switching models fix a session or weekly limit? No. Those limits are shared across all models. It only helps with model-family limits such as the Opus limit or Sonnet limit.

How do I check my Claude Code usage? Run /usage. It shows plan usage bars, a breakdown by skills, subagents, plugins and MCP servers, and recommendations. You can also show the 5-hour and 7-day percentages permanently in a custom status line.

Why did I hit my limit so fast? Usually a long, never-cleared session, subagents or agent teams, Opus with high effort, or a cache miss after a long break. Run /usage and read the attribution and recommendation rows.

What is the difference between Pro, Max 5x and Max 20x? Price and relative capacity. Pro is the baseline at $20 a month. Max 5x gives five times Pro's usage at $100 a month, and Max 20x gives twenty times at $200 a month.

Can I keep working after hitting the limit? Yes. You can buy usage credits with /usage-credits, switch to a model outside an affected family, move to API billing, or upgrade your plan. Usage credits are billed at standard API rates.

Will Claude Code continue my task after the limit resets? On v2.1.234 or later, in an interactive session signed in with a claude.ai subscription, it waits and continues automatically. Keep the session open, and cancel with Esc if you do not want it.

Does the Agent SDK or claude -p count against my limit? It has changed more than once. See the pricing survival guide for the current state and how I would plan for it.

Sources, all checked October 28, 2026: Use Claude Code with your Pro or Max plan, Manage costs effectively, Claude Code error reference, Interactive mode, Claude pricing, and the Claude Code weekly limit promotion article.

Claude Code Plan Mode: How It Works, How to Use It, and When to Skip It

Alex Cloudstar — Tue, 27 Oct 2026 06:53:08 +0000

Claude Code Plan Mode: How It Works, How to Use It, and When to Skip It

The most expensive Claude Code mistake I know is not a bad edit. It is a confident edit. You ask for a refactor, the agent picks an approach in about four seconds, and twenty minutes later you are reading a diff across twelve files that solves a slightly different problem than the one you had. Nothing is broken. It is just wrong, and the cost of finding that out is the whole diff.

Plan mode is the fix for that, and it costs almost nothing. Claude reads your code, writes down what it intends to do, and waits. You read the plan, change it if it is off, and only then does anything get edited. I wrote a short section on it in the beginner guide and a one-line entry in the commands cheat sheet, but it deserves its own page, because most of what makes it useful is in the details.

This guide covers how to turn it on, what Claude can and cannot do inside it, the approval menu, how to edit a plan, the settings that change its behavior, and the cases where I skip it. I checked everything against the official permission modes documentation on October 27, 2026. Claude Code changes often, so treat the docs as the source of truth if something here has drifted.

What Claude Code Plan Mode Is

Claude Code plan mode is a permission mode where Claude researches your codebase and proposes changes without making them. It can read files, run shell commands to explore, and write a plan. It cannot edit your source files until you approve the plan.

That is the whole idea. The mode changes one thing: whether Claude is allowed to change your code. Everything else about the session stays the same, including your CLAUDE.md, your tools and your conversation history.

It helps to think of it as two phases. In the first, Claude gathers context and reasons. In the second, after you approve, it executes with the permissions of whichever mode you picked on the approval screen. The plan is the handoff between the two, and it is also the thing you get to review, which is the point.

How to Turn On Plan Mode in Claude Code

There are several ways in, and which one you use depends on whether you want it once, for a session, or by default.

Method	How	Scope
Keyboard	`Shift+Tab` until the status bar shows `⏸ plan mode on`	Current session
Slash command	`/plan`, or `/plan fix the auth bug` to start straight away	One prompt
Startup flag	`claude --permission-mode plan`	The whole session
Settings default	`permissions.defaultMode` set to `"plan"`	Every terminal session in the project
Desktop app	Pick Plan in the mode selector	Current session
Web	Pick Plan in the dropdown for cloud sessions	Current session

A few notes on those.

Shift+Tab cycles modes. In default mode the cycle runs default, then acceptEdits, then plan, so you usually press it twice. If you have auto mode available, the first press from auto drops you to default first. Watch the status bar instead of counting. Press Shift+Tab again to leave plan mode without approving anything. On Windows, if Shift+Tab does not cycle because your Node or Bun runtime does not enable VT input mode, use Alt+M.

/plan is the one I use most. Typing /plan followed by a description puts Claude in plan mode and gives it the task in one move. The slash command has to be at the very start of the message, like every slash command. The full list of what else lives at that level is in the commands cheat sheet.

To make plan mode the default for a project, put this in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

VS Code is the exception. VS Code sessions do not read the project setting for the starting mode. Set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.

Do I recommend plan mode as a default? Not for most people. Every session starts with a plan step, including the ones where you just want a typo fixed. I would use it as a default in one case: a repo you are new to, where every change should start with Claude proving it understood the code.

What Claude Can and Cannot Do in Plan Mode

Inside plan mode, Claude can:

Read files and search the codebase.
Run shell commands to explore, such as git log, ls or a test listing.
Ask you clarifying questions.
Write the plan itself.

It cannot edit your source files until you approve the plan. That is the guarantee, with one important exception covered in the section on limits below.

Shell commands are where it gets less obvious, because "run commands to explore" still needs a rule for which commands count. The docs describe three cases, and the first one that matches applies:

Interactive terminal with bypass permissions available. Neither the classifier nor a prompt applies to planning commands. Claude is told not to edit, but anything it attempts runs. Explicit ask rules and critical-path rm removals still prompt.
Auto mode available and useAutoModeDuringPlan on (the default). The classifier reviews shell commands instead of prompting you. Approved ones run, rejected ones are blocked.
Auto mode not available, or useAutoModeDuringPlan off. Commands outside the built-in read-only set prompt for approval.

In practice, on a normal setup, you will see Claude run read-only commands freely and ask before anything that could change state. That is what you want from a planning phase.

The Plan Approval Menu

When the plan is ready, Claude presents it and asks how to proceed. The options you will see:

Yes, and use auto mode. Approves the plan and starts auto mode, where a classifier approves routine actions. If auto mode is not available to your session, this reads Yes, auto-accept edits instead.
Yes, manually approve edits. Approves the plan, but you review each edit one by one.
No, keep planning. Stays in plan mode so you can tell Claude what to change.

If your session started with bypass permissions enabled, the first option instead reads Yes, and switch to BYPASS PERMISSIONS (no further prompts) for this session. Read that label before you press Enter. It is the same switch as running with --dangerously-skip-permissions.

There is also an optional option that clears the planning context. When showClearContextOnPlanAccept is enabled, a new first option appears that approves the plan and clears the conversation used to build it. That sounds odd until you have done a long planning session: the research, the dead ends and the back-and-forth all sit in the context window, and none of them help the implementation. Starting clean with just the approved plan can leave the execution phase with more room to work and fewer old assumptions to trip over. If you often plan for a long time, turn it on.

Approving exits plan mode and moves you to whatever mode the option describes. To plan again, cycle back with Shift+Tab or prefix a prompt with /plan. Accepting a plan also gives the session a title generated from the plan, unless you already named it.

Edit the Plan with Ctrl+G

This is the feature most people never find. Press Ctrl+G while a plan is on screen and Claude opens it in your default text editor. Change it, save, close, and Claude proceeds with your version.

Why bother, when you could just reply and ask for changes? Because some corrections are faster to make than to describe. Deleting a step you do not want is one keystroke. Reordering two steps is a cut and paste. Adding a constraint like "do not touch the public API" is one line. Telling the model to do any of that and waiting for it to rewrite the plan is slower and risks it rewording things you did not ask it to change.

Plan files for the current session live in ~/.claude/plans/, or in the directory set by the plansDirectory setting. Writes to ~/.claude/plans/ are exempt from the protected .claude directory rule, which is why Claude can save a plan there even in modes that guard that folder. If you want plans in the repo so teammates can read them, point plansDirectory at a project folder.

A Plan Mode Workflow That Works

Here is the loop I use, with a real-shaped example. The task: add rate limiting to an Express API that already has auth middleware.

1. Start with the goal and the constraints, not the solution.

/plan Add per-user rate limiting to the API. Use the existing Redis client.
Do not change the auth middleware's public behavior. Show me which files
you would touch before touching any.

Giving Claude the constraints up front is what keeps the plan from drifting. "Use the existing Redis client" saves me from a plan that adds a second dependency.

2. Let it read, then read the plan critically.

A useful plan names files, in order, and says why. A weak one says "update the relevant middleware." Here is the shape of a good one:

1. Add src/middleware/rateLimit.ts using the client from src/lib/redis.ts
2. Key limits by req.user.id, fall back to IP for unauthenticated routes
3. Register it after auth in src/app.ts so req.user exists
4. Add tests in src/middleware/rateLimit.test.ts (limit hit, reset, no user)
5. Document the new env vars in README.md

3. Push back before approving.

Questions I ask at this step: what did you not read? What is the riskiest step? What happens to the unauthenticated routes? A plan is cheap to question. Code is not. If an answer surprises me, I say "No, keep planning" and give the correction.

4. Edit with Ctrl+G when the fix is small.

If step 5 is out of scope, I delete it in the editor rather than debating it.

5. Approve with the mode that matches the risk.

For a change this size, I pick manual approval for the first run and auto mode once I trust the plan. The plan has already done the thinking, so the edits become mostly mechanical.

That whole loop adds a few minutes. The first time it catches a wrong assumption about the codebase, it pays for a month of them.

When to Use Plan Mode and When to Skip It

My rule: use plan mode when a wrong first step is expensive.

Use it for:

Changes across more than a couple of files. Refactors, renames that cross module boundaries, anything with a migration.
Code you do not know. A repo you just cloned, or a part of your own app you have not touched in a year. The plan shows you whether Claude understood the structure before it changed anything.
Irreversible or expensive changes. Database migrations, public API changes, dependency upgrades with breaking changes.
Work you will hand off or review. A written plan is an easy thing to put in a pull request description.
When you are not sure what you want. Asking for a plan is a cheap way to see options.

Skip it for:

One-line fixes. A typo, a changed constant, a renamed variable. The plan would be longer than the diff.
Tasks with an obvious single path. "Add this field to this type" does not need a review step.
Throwaway experiments. If you are going to delete it in ten minutes, do not spend three on a plan.
Quick questions. Reading code and answering does not need a mode.

One more mistake worth naming: planning forever. Three rounds of plan revisions on a small task is usually a sign the task needs to be split, not that the plan needs another pass. Approve a smaller plan and do the next piece afterward.

Plan Mode Is Not a Sandbox

This is the caveat people miss, and it is a real one. Plan mode blocks edits by telling Claude not to make them and denying the tools, but in an interactive terminal where bypass permissions is available, those blocks are not enforced. Claude is still told to plan without editing. If it attempts an edit or a shell command anyway, it runs without a prompt.

So the safe reading is: plan mode is a workflow, and a good one, but it is not a security boundary. If the point is to guarantee nothing changes, do not start the session with --dangerously-skip-permissions. And if you need real limits on what an agent can touch, that is a permissions and sandbox question, which I cover in the least-privilege guide for coding agents.

Plan mode keeps its blocks everywhere that runs without an interactive terminal: claude -p runs, Agent SDK sessions and the VS Code chat panel.

Plan Mode Settings Worth Knowing

Setting	What it does	Default
`permissions.defaultMode`	Set to `"plan"` to start every terminal session in plan mode	`default`
`useAutoModeDuringPlan`	Lets the auto mode classifier review shell commands during planning instead of prompting you	On
`showClearContextOnPlanAccept`	Adds an approve-and-clear-context option to the approval menu	Off
`plansDirectory`	Where plan files are saved	`~/.claude/plans/`
`claudeCode.initialPermissionMode`	VS Code user setting for the starting mode	n/a

I would change two of those. Turn on showClearContextOnPlanAccept if your planning sessions run long, and set plansDirectory to a project folder if you want plans in version control. Leave the rest alone until you have a reason.

Using Plan Mode in Headless Runs

The --permission-mode flag works with -p, so this is the headless form:

claude -p --permission-mode plan "Plan how to migrate the users table to UUID primary keys"

Because plan mode keeps its blocks in non-interactive runs, nothing gets edited, which makes this a decent way to run a read-only analysis in a script or CI job. The docs do not describe an interactive approval step for -p runs, so treat it as a one-shot "give me the plan" call rather than a plan-then-execute flow.

Plan Mode with opusplan and Subagents

Two features pair well with plan mode.

opusplan is a model alias that uses Opus while you are in plan mode and switches to Sonnet for the edits. It matches how the work splits: planning is the part where a stronger model pays off, and executing an approved plan is mostly mechanical. Pick it with /model. My Claude Code vs Codex comparison covers the model lineup and what each plan includes.

Subagents help when the research phase is large. Claude Code's built-in Plan subagent is read-only, with Write and Edit denied, and it is used for research during plan mode. Custom subagents can do the same job with their own prompts and tools, and they keep the exploration out of your main context window. The subagents guide shows how to write one.

Common Plan Mode Problems

Shift+Tab skips plan mode or does nothing. The cycle depends on which modes are available to you, so count by the status bar, not by presses. On Windows, use Alt+M if Shift+Tab is not recognized.

The plan is vague. "Update the relevant files" is a signal that Claude did not read enough. Ask: "Which files did you read? Name the exact files you will change and why." Or point it at the starting files with @.

It plans something huge. Ask for a smaller first slice: "Plan only the data layer. We will do the API after." Splitting the work gives you plans you can actually verify.

It edited something anyway. Check whether bypass permissions was on. In that setup plan mode is advisory, as described above. Use Esc twice or /rewind to undo, and start the next session without the bypass flag.

The execution drifts from the plan. Long planning sessions leave a lot of context. Turn on the clear-context option so the execution phase starts from the approved plan alone, and consider running /compact mid-task if it still drifts.

Plan Mode vs Just Asking for a Plan

You can type "write a plan first, do not edit anything" in the default mode, and sometimes that is enough. The difference is enforcement and workflow. In plan mode the edit tools are denied, there is a defined approval step, and you get the menu and Ctrl+G. In default mode with a polite request, Claude can forget the instruction two messages later, or interpret "plan" loosely and start changing files. If the cost of an unreviewed edit is real, use the mode. If you only want an outline to think with, asking is fine.

Plan mode also pairs well with the other habits in the 32,784-line workflow post: a written plan, small steps and a review between each. The plan is the cheapest checkpoint in the whole loop.

Frequently Asked

What is plan mode in Claude Code? A permission mode where Claude reads your code and writes a plan but does not edit source files until you approve it.

How do I enter plan mode in Claude Code? Press Shift+Tab until the status bar shows plan mode, type /plan with an optional description, start with claude --permission-mode plan, or set permissions.defaultMode to "plan" in settings.

How do I exit plan mode? Approve the plan from the menu, or press Shift+Tab again to leave without approving. To plan again later, cycle back or prefix a prompt with /plan.

Can Claude edit files in plan mode? Not source files, until you approve the plan. The exception is an interactive terminal session with bypass permissions available, where the block is not enforced.

Can I edit the plan before approving it? Yes. Press Ctrl+G to open it in your default text editor, edit it and save.

Where are Claude Code plans saved? In ~/.claude/plans/ by default, or the folder set by the plansDirectory setting.

Does plan mode cost more tokens? It adds a planning pass, so a task uses more tokens up front. It often saves them overall by avoiding a wrong implementation that has to be rewritten. If usage is your worry, opusplan and a clear-context approval help.

Should I use plan mode for every task? No. Use it when a wrong first step is expensive, and skip it for small, obvious changes.

Does plan mode work in headless mode? Yes, with claude -p --permission-mode plan. Nothing is edited, and the run is a read-only analysis.

Source: Claude Code permission modes, checked October 27, 2026.

Claude Code Commands Cheat Sheet: Every Slash Command, Shortcut and CLI Flag

Alex Cloudstar — Mon, 26 Oct 2026 15:50:05 +0000

Claude Code Commands Cheat Sheet: Every Slash Command, Shortcut and CLI Flag

Type / in Claude Code and the menu scrolls past a hundred entries. Most people learn six of them, never look at the rest, and wonder why their sessions feel slow and expensive. The commands are not hard. The list is just long, badly sorted for a newcomer, and changing every few weeks.

This is the cheat sheet I wanted when I started: slash commands grouped by what you are trying to do, the keyboard shortcuts that matter on macOS and Windows, the CLI commands and flags you run from your shell, how custom commands work now, and the commands that were removed so you stop looking for them. I checked it against the official commands, interactive mode and CLI reference pages on October 24, 2026. Claude Code ships updates constantly, so treat the docs as the source of truth if a command here has drifted.

Claude Code Commands at a Glance

Claude Code commands fall into three layers. Slash commands are typed at the start of a message inside a session, such as /clear or /compact. Keyboard shortcuts and prefixes are typed in the prompt, such as Shift+Tab, ! for a shell command, and @ for a file. CLI commands and flags are typed in your terminal before or while launching, such as claude -c or claude --model.

Layer	Where you type it	Example	What it controls
Slash commands	Start of a message in a session	`/compact`	The session: context, model, plans, reviews
Shortcuts and prefixes	The prompt	`Shift+Tab`, `!`, `@`	How you interact: modes, shell, files
CLI commands and flags	Your shell	`claude -c`, `--permission-mode plan`	How a session starts and runs

Two details save confusion. A slash command is only recognized at the very start of your message, and anything after the name becomes its arguments. And some entries in the menu are not built in at all: /batch, /loop, /simplify, /code-review and others are bundled skills. They behave like commands, but they are prompts Claude follows, which is why they can do multi-step work.

The Ten Claude Code Commands to Learn First

If you only learn ten things, learn these. They cover most of what separates a smooth session from a messy one.

Command	What it does	When to reach for it
`/init`	Generates a starter `CLAUDE.md` for the project	First session in any repo
`/clear`	Starts a new conversation with empty context	Switching to an unrelated task
`/compact`	Summarizes the conversation to free context	Mid-task, when history gets long
`/context`	Shows what is filling the context window	Before you decide to compact
`/model`	Switches the model	A task needs more or less power
`/plan`	Enters plan mode	Anything touching more than a file or two
`/rewind`	Rolls code and conversation back to a checkpoint	Claude went down the wrong path
`/resume`	Reopens an earlier conversation	Coming back the next day
`/permissions`	Manages allow, ask and deny rules	Tired of approving the same command
`/usage`	Shows session cost, plan limits and activity	Watching your limits

Two shortcuts belong on that list: Shift+Tab cycles permission modes, and pressing Esc twice rewinds. Both are covered below. If you want the guided version of this list, with an install and a first session, start with my Claude Code tutorial and come back here for the full reference.

Claude Code Slash Commands by Task

The official page lists them alphabetically. That is fine for lookup and bad for learning, so these are grouped by the moment you need them. Aliases are noted because the same command often has two or three names.

Start a project and set the rules

Command	What it does
`/init`	Generates a starter `CLAUDE.md`. Set `CLAUDE_CODE_NEW_INIT=1` for an interactive flow that also covers skills, hooks and personal memory files
`/memory`	Edits `CLAUDE.md` files, turns auto memory on or off and shows its entries
`/permissions`	Opens a dialog to view, add and remove allow, ask and deny rules. Alias: `/allowed-tools`
`/mcp`	Manages MCP server connections and OAuth. `/mcp reconnect all` retries every server that failed or needs auth
`/add-dir <path>`	Adds a working directory for file access during the session. Most `.claude/` configuration in that directory is not picked up
`/config`	Opens settings for theme, model, output style and more. It also accepts `key=value` pairs
`/import`	Brings config from Codex, Gemini CLI or Cursor into Claude Code, including instruction files, MCP servers and skills

The order the docs suggest for a first session is /init, then /memory to refine the file, then /mcp for any servers, then /permissions. The CLAUDE.md part is the one that pays off most, and I walk through what belongs in it in the tutorial. For MCP specifically, see the MCP server developer guide.

Control context and cost

Context is the budget you spend every turn, so this group matters more than it looks. I wrote about the bigger picture in context engineering for AI coding. The commands themselves are simple.

Command	What it does
`/clear [name]`	Starts a new conversation with empty context. Pass a name to label the old one in the `/resume` picker. Aliases: `/reset`, `/new`
`/compact [instructions]`	Summarizes the conversation so far. Add focus instructions to steer what the summary keeps
`/context [all]`	Draws your context usage as a colored grid and flags memory bloat and context-heavy tools
`/usage`	Shows session cost, plan limits and activity stats. Aliases: `/cost`, `/stats`
`/btw [question]`	Asks a side question without adding it to the conversation
`/rewind`	Rolls back the conversation, the code, or both to an earlier point. Aliases: `/checkpoint`, `/undo`
`/recap`	Generates a one-line summary of the session on demand
`/autocompact`	Sets how full the context window gets before compaction runs automatically
`/export [filename]`	Exports the conversation as plain text
`/copy [N]`	Copies the last assistant response, or the Nth-latest with a number

/clear versus /compact is the decision people get wrong. /clear throws the conversation away and keeps project memory, so use it when the next task is unrelated. /compact keeps a summary and continues the same task. Running /context first tells you whether compaction is even worth it. /btw is the quiet winner of this group: you get an answer without paying for it in the main thread's history.

Switch the model and effort

Command	What it does
`/model [model]`	Switches the model and saves it as your default for new sessions. With no argument it opens a picker, and pressing `s` on a row switches for the current session only
`/effort [level]`	Sets reasoning effort from `low` to `xhigh`, `max`, or `auto`. `status` prints the current level. `max` lasts only for the session
`/fast [on or off]`	Toggles fast mode
`/advisor [model or off]`	Turns on an advisor tool that consults a second model at key moments

If you are weighing models by price and capability, my cache pricing review of Fable 5.1 covers what switching mid-session costs. There is a catch the docs call out: changing model or effort mid-conversation can invalidate your prompt cache, and Claude Code warns you before it does.

Plan, review and ship

Command	What it does
`/plan [description]`	Enters plan mode from the prompt. Add a description to start straight away, such as `/plan fix the auth bug`
`/diff`	Shows the changes in your working tree, including Claude's edits so far
`/code-review [level] [target]`	Reviews the current diff for correctness bugs. Takes a level from `low` to `max`, plus `--fix`, `--comment` and a PR number, branch or path. Alias: `/review`
`/security-review`	Checks the diff between your branch and the default branch for vulnerabilities such as injection, auth issues and data exposure
`/simplify [target]`	Reviews changed code for cleanup and applies the fixes
`/batch <instruction>`	Splits a large change into independent units and runs them in parallel, each in its own worktree
`/ultrareview [PR or branch]`	Runs a deep multi-agent review in a cloud sandbox
`/autofix-pr [prompt]`	Starts a cloud session that watches your PR and pushes fixes when CI fails or reviewers comment
`/verify`	Builds and runs your app to confirm a change works, instead of trusting tests alone

Plan mode is the habit I would push hardest. Having Claude write the approach before it edits anything catches a wrong turn while it is still cheap, and /plan gets you there without remembering the keyboard cycle. For multi-file work in parallel, /batch leans on git worktrees, and the review commands pair with the problems in the AI code review bottleneck.

Run work in parallel and in the background

Command	What it does
`/tasks`	Lists background work in the session, including finished subagents. Alias: `/bashes`
`/background [prompt]`	Detaches the whole session as a background agent and frees your terminal
`/fork [prompt]`	Copies the conversation into a new background session and keeps you working here
`/subtask <task>`	Spawns a forked subagent that inherits the conversation and works while you continue
`/agents`	Prints a reminder to ask Claude to create or manage subagents. On v2.1.197 and earlier it opened an interactive screen
`/goal [condition]`	Keeps Claude working across turns until a condition is met. `/goal clear` removes it
`/loop [interval] [prompt]`	Repeats a prompt while the session stays open, for example `/loop 5m check if the deploy finished`
`/schedule [description]`	Creates, lists or runs cloud scheduled tasks

The /agents row is a good example of why a cheat sheet goes stale. If an older tutorial tells you /agents opens a manager, check your version. Subagents are covered properly in the subagents guide, and the broader idea of delegating work to run unattended is in background AI coding agents.

Move between sessions and devices

Command	What it does
`/resume [session]`	Resumes a conversation by ID or name, or opens the picker. Alias: `/continue`
`/branch [name]`	Branches the conversation here so you can try another direction and keep the original
`/rename [name]`	Names the current session. With no name it generates one from the conversation
`/teleport`	Pulls a cloud session into this terminal. Alias: `/tp`
`/remote-control`	Makes this session controllable from claude.ai or the Claude app
`/desktop`	Continues the session in the Claude Code desktop app on macOS or x64 Windows. Alias: `/app`
`/exit`	Exits the CLI. Alias: `/quit`

Set up, diagnose and customize

Command	What it does
`/doctor`	Runs a setup checkup for installation, settings, extensions and `CLAUDE.md` problems
`/debug [description]`	Turns on debug logging and troubleshoots from the session log
`/status`	Opens the Status tab: version, model, account and connectivity
`/statusline`	Configures the status line. See my status line guide
`/hooks`	Shows your hook configuration. Hooks themselves are in the hooks guide
`/skills`	Lists available skills, with filtering and sorting by token cost
`/skill-doctor`	Shows what each skill costs in context and how often it is used
`/plugin [subcommand]`	Manages plugins. See the plugin marketplace guide
`/reload-plugins` and `/reload-skills`	Apply plugin or skill changes without restarting
`/theme`, `/color`, `/tui`	Change the color theme, prompt bar color and terminal renderer
`/terminal-setup`	Installs a `Shift+Enter` newline binding in VS Code, Cursor, Alacritty, Zed and others
`/keybindings`	Opens your keyboard shortcuts file
`/sandbox`	Toggles sandbox mode on supported platforms
`/login`, `/logout`	Sign in to or out of your Anthropic account
`/help`, `/release-notes`	Show help, or browse the changelog by version
`/feedback`, `/bug`	Report a bug or send feedback, with a consent step before anything is sent

Claude Code commands that were removed or changed

Old blog posts still list these. They no longer work the way they describe.

Command	Status
`/vim`	Removed in v2.1.92. Use `/config` and set Editor mode to switch between Vim and Normal editing
`/pr-comments`	Removed in v2.1.91. Ask Claude directly to view the pull request comments
`/ultraplan`	Removed. Use plan mode instead
`/cost` and `/stats`	Still work, but they are aliases for `/usage` now
`/agents`	Prints a reminder on v2.1.198 and later instead of opening a manager
`--enable-auto-mode` (flag)	Removed in v2.1.111. Auto mode is in the `Shift+Tab` cycle by default

Some commands are also hidden from the menu until you type the full name, such as /setup-bedrock and /setup-vertex. That is the closest thing to a secret command. Run /help or type / and keep typing to filter, and you will see everything your plan and platform allow.

Claude Code Keyboard Shortcuts

Shortcuts are where Claude Code feels fast. The ones worth learning first are Shift+Tab, Esc, Ctrl+O and the ! prefix. A note first: on macOS, any shortcut that uses Option as Alt (Alt+B, Alt+F, Alt+D, Alt+Y, Alt+P) needs your terminal set to treat Option as Meta. Without that setting they do nothing, and it is the most common reason a shortcut seems broken.

Core controls

Shortcut	What it does
`Esc`	Interrupts Claude mid-turn. The work done so far is kept, so you can redirect
`Esc` then `Esc`	With text in the prompt, clears it and saves the draft to history. With an empty prompt, opens the rewind menu
`Shift+Tab`	Cycles permission modes: `default`, `acceptEdits`, `plan`, then `bypassPermissions` and `auto` when available
`Ctrl+C`	Interrupts a running operation. With nothing running, the first press clears the prompt and a second exits
`Ctrl+D`	Exits the session. Press twice within 800ms
`Ctrl+O`	Toggles the transcript viewer with detailed tool usage and timestamps
`Ctrl+R`	Reverse-searches your command history
`Ctrl+G` or `Ctrl+X Ctrl+E`	Opens your prompt in your default text editor
`Ctrl+B`	Backgrounds running Bash commands and agents. Tmux users press it twice
`Ctrl+T`	Shows or hides Claude's task checklist
`Ctrl+S`	Stashes the prompt, or restores it when pressed again on an empty prompt
`Ctrl+L`	Redraws a garbled screen without losing your conversation
`Ctrl+Z`	Suspends Claude Code to your shell on Unix. Run `fg` to resume
`Ctrl+X Ctrl+K`	Stops all background subagents. Press twice within 3 seconds

Model and mode toggles

macOS	Windows and Linux	What it does
`Option+P`	`Alt+P`	Switches model without clearing your prompt
`Option+T`	`Alt+T`	Toggles extended thinking. The docs say it has no effect on Opus 5.5, Sonnet 5.5, Haiku 5.5 or the Fable models, which always use it
`Option+O`	`Alt+O`	Toggles fast mode

Prefixes and multiline input

Input	What it does
`/` at the start	Runs a command or skill
`!` at the start	Shell mode: runs the command directly and adds its output to the session
`@`	Triggers file path autocomplete
`?` on an empty prompt	Shows the shortcut help panel
`\` then `Enter`	Newline that works in every terminal
`Shift+Enter`	Newline. Native in iTerm2, WezTerm, Ghostty, Kitty, Warp, Apple Terminal and Windows Terminal
`Ctrl+J`	Newline that works in any terminal with no setup
`Ctrl+V` (`Cmd+V` in iTerm2, `Alt+V` on Windows and WSL)	Pastes an image from the clipboard

The ! prefix is underrated. Typing ! npm test runs it right away, puts the output in the conversation, and lets Claude respond to the result, with no approval step and no model tokens spent deciding to run it. It supports Ctrl+B backgrounding too.

Editing the prompt

Shortcut	What it does
`Ctrl+A` and `Ctrl+E`	Jump to the start or end of the line
`Ctrl+K`	Deletes to the end of the line
`Ctrl+U`	Deletes to the start of the line. Repeat to clear across lines
`Ctrl+W`	Deletes back to the previous whitespace, so one press removes a whole path or `--flag=value`
`Ctrl+Y`	Pastes the text you last deleted. `Alt+Y` cycles earlier deletions
`Alt+B` and `Alt+F`	Move back or forward one word
`Ctrl+_`	Undoes the last input edit

On Windows, if Shift+Tab does not cycle modes because your Node or Bun runtime does not enable VT input mode, use Alt+M. Customizing any of these goes through /keybindings.

Claude Code CLI Commands and Flags

These run in your shell, outside the session. The docs list around 85 flags, and you will use about fifteen. Here are the commands first.

Command	What it does
`claude`	Starts an interactive session
`claude "query"`	Starts a session with an initial prompt
`claude -p "query"`	Runs the query non-interactively, prints the result and exits
`cat file \	claude -p "query"`
`claude -c`	Continues the most recent conversation in this directory
`claude -r "name" "query"`	Resumes a session by ID or name
`claude update`	Updates to the latest version
`claude install [version]`	Installs or reinstalls the native binary, such as `claude install stable`
`claude auth login`, `logout`, `status`	Sign in, sign out, or print auth status as JSON
`claude mcp`	Configures MCP servers
`claude plugin`	Manages plugins
`claude agents`	Opens agent view to monitor and dispatch parallel background sessions
`claude attach`, `logs`, `stop`, `respawn`, `rm`	Manage background sessions from the shell
`claude doctor`	Prints read-only install and settings diagnostics without starting a session
`claude setup-token`	Generates a long-lived OAuth token for CI and scripts
`claude ultrareview [target]`	Runs ultrareview non-interactively

The flags that earn their place:

Flag	What it does
`--continue`, `-c` and `--resume`, `-r`	Pick a conversation back up. Add `--fork-session` to resume into a new session ID
`--name`, `-n`	Names the session so it is easy to find in `/resume`
`--model`	Sets the model for the session
`--effort`	Sets the effort level for the session
`--permission-mode`	Starts in a mode: `default`, `acceptEdits`, `plan`, `auto`, `dontAsk` or `bypassPermissions`
`--allowedTools`	Tools that run without prompting, such as `"Bash(git log *)" "Read"`
`--tools`	Restricts which built-in tools Claude can use at all
`--add-dir`	Adds extra working directories
`--worktree`, `-w`	Starts in an isolated git worktree under `.claude/worktrees`
`--print`, `-p`	Non-interactive mode for scripts and pipes
`--output-format`	Print mode output: `text`, `json` or `stream-json`
`--max-turns` and `--max-budget-usd`	Cap agentic turns or spend in print mode
`--json-schema`	Returns validated JSON matching a schema in print mode
`--append-system-prompt`	Adds text to the default system prompt
`--bg`	Starts the session as a background agent and returns immediately
`--from-pr`	Opens the picker filtered to sessions linked to a pull request
`--bare`	Minimal mode: skips auto-discovery of hooks, skills, plugins, MCP servers and memory
`--safe-mode`	Starts with all customizations disabled, for troubleshooting a broken config
`--debug` and `--verbose`	Debug logging, or full turn-by-turn output
`--version`, `-v`	Prints the version

A few invocations I would actually save:

claude -c
claude -r "auth-refactor" "finish this PR"
claude -w feature-auth
claude --permission-mode plan
git diff main | claude -p "review this diff for bugs"
claude -p "list every TODO" --output-format json --max-turns 5

If you script with -p, the Agent SDK guide is the next step. For worktree-based parallel work, see the worktree guide.

Custom Claude Code Commands Are Skills Now

You can still write your own commands, but the mechanism changed. The docs say custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing command files keep working. Skills add a folder for supporting files, frontmatter that controls whether you or Claude can invoke them, and automatic loading when relevant. If a command file and a skill share a name, the skill wins.

A minimal custom command is a markdown file:

---
description: Review a file for bugs and missing tests
---

Review $ARGUMENTS for correctness bugs and missing tests.
List findings by severity, most serious first.

Save it as .claude/commands/review-file.md and run /review-file src/auth.ts. $ARGUMENTS expands to everything after the command name. You can also address arguments by position with $0, $1 and so on, counting from zero, and wrap multi-word values in quotes. Put files in .claude/ to share them with a project, or ~/.claude/ to keep them personal.

For anything you will reuse or share, write a skill instead. I cover the full format in the skill developer guide, and the plugin marketplace guide shows how to package and install them.

How to Allow Commands Without Approval Prompts

People search for "claude code allow all commands" because the prompts get old. There are four sane answers, from narrowest to widest.

Allow specific commands. Run /permissions and add allow rules for the commands you trust, such as Bash(git diff *). This is the right default. The rules persist.
Switch the mode. Press Shift+Tab to move to acceptEdits so file edits stop prompting, or to auto, which uses a classifier to approve routine actions. On a file permission prompt, Shift+Tab also picks the option that allows the action for the rest of the session, when the prompt offers it.
Allow per run. Start with --allowedTools "Bash(git log *)" "Read" for a scripted session that should never prompt for those.
Skip all checks. --dangerously-skip-permissions is equivalent to --permission-mode bypassPermissions. Only use it in a throwaway container or sandbox, never on a machine with credentials you care about.

Blanket allow-all is the option I would avoid, and the reason is practical: one bad command in an unattended session is hard to undo. The least-privilege guide for coding agents goes through how to scope permissions without drowning in prompts, and a PreToolUse hook can block the dangerous commands while allowing the rest.

Build the Habit, Not the Memory

You do not need to memorize any of this. A short daily loop covers most of it:

Start with claude -c to pick up yesterday's work, or claude for something new.
Press Shift+Tab to plan before any change that touches more than a couple of files.
Run /context when a session feels sluggish, then /compact with focus instructions, or /clear if the task changed.
Use ! for quick shell checks instead of asking Claude to run them.
Press Esc twice when a direction is wrong, instead of arguing with it.

The same pattern applies to the less common commands. Learn them when a problem shows up. /rewind makes sense the first time a refactor goes sideways, and /btw makes sense the first time you want a quick answer without polluting a long thread. For a full worked example of how far this loop can go, see the 32,784-line workflow post.

Frequently Asked

What are some useful commands in Claude Code? Start with /init, /clear, /compact, /context, /model, /plan, /rewind, /resume, /permissions and /usage. Add the ! shell prefix, @ file mentions, Shift+Tab and double Esc.

Are there secret commands in Claude Code? Not really. A few are hidden from the menu until you type their full name, such as /setup-bedrock and /setup-vertex, and several useful ones are just overlooked, like /btw, /recap and /powerup. /help and /skills list what is available to you.

How do I run a command in Claude Code? Type / at the very start of a message, then the command name and any arguments. To run a shell command instead, start the message with !. A slash command is only recognized at the start of the message.

How do I allow commands in Claude Code? Use /permissions to add allow rules, press Shift+Tab to change the permission mode, or pass --allowedTools when you launch. Avoid --dangerously-skip-permissions outside a sandbox.

What are the Claude Code keyboard shortcuts on Windows? Most match macOS with Alt in place of Option: Alt+P switches model, Alt+T toggles extended thinking and Alt+O toggles fast mode. Use Alt+V to paste an image, and Alt+M for the mode cycle if Shift+Tab does not work in your runtime.

What does Ctrl+O do in Claude Code? It toggles the transcript viewer, which shows detailed tool usage and timestamps, and expands lines that collapse by default. Ctrl+G is a different shortcut: it opens your prompt in your default text editor.

What is the difference between a command and a skill? Custom commands have been merged into skills. A markdown file in .claude/commands/ and a skill in .claude/skills/ both create the same /name command. Skills add supporting files, invocation controls and automatic loading, and the docs recommend them for new work.

Where do I see every command? Type / and keep typing to filter, run /help, or run /skills for the skills list. The full reference is the official commands page.

Sources: Claude Code commands, Interactive mode, CLI reference and Skills, checked October 24, 2026.

Claude Code Alternatives in 2026: 8 Tools Worth Switching To, and When Not To

Alex Cloudstar — Mon, 26 Oct 2026 15:50:04 +0000

Claude Code Alternatives in 2026: 8 Tools Worth Switching To, and When Not To

Nobody searches for Claude Code alternatives because they are happy. They search after a usage limit lands in the middle of a refactor, or after a bill, or after a coworker says their open source setup does the same job for free. Sometimes the reason is plainer: you just want to use a different model.

I use Claude Code every day, on client work and on my own products. That makes me biased, and I will say where. It also means I know exactly where it hurts. I have not run the other tools here as daily drivers, so there are no benchmarks in this post and I will not invent any. What I did is check every tool against its own docs, GitHub page and pricing page on October 26, 2026, because this market rewrites its prices and plans every few weeks. Where something changed recently, I say so.

Eight tools made the list. Each one gets what it is, what it costs, where it beats Claude Code and where it does not.

The Best Claude Code Alternatives at a Glance

The best Claude Code alternatives in 2026 are OpenCode for free, open source and any-model use, Codex if you already pay for ChatGPT, Cursor or Kilo Code if you work inside an editor, GitHub Copilot CLI if you are already on Copilot, Aider for git-first pair programming, and Cline for approval-heavy control. Gemini CLI is no longer a free option for individuals.

Tool	Where it runs	Models	Entry price
OpenCode	Terminal, desktop, IDE, web	75+ providers plus local models	App is free. Go is $10/month
Codex	CLI, IDE, cloud	OpenAI models	Included in ChatGPT Free, Go ($8), Plus ($20)
Cursor	Editor, CLI, cloud agents	Grok on Plus, third-party models billed by usage	Free, Plus $8, Premium $30
GitHub Copilot CLI	Terminal	Models from your Copilot plan	Included in every plan, Pro is $10
Antigravity CLI (was Gemini CLI)	Terminal	Google models	Free tier with a weekly cap
Aider	Terminal	Almost any LLM, local too	Free, you pay the model provider
Cline	VS Code, JetBrains, CLI, desktop	Any major provider or local	Free, you pay the model provider
Kilo Code	VS Code, JetBrains, CLI, cloud	500+ models	Free, no markup on model prices

Open source in this list means OpenCode (MIT), Codex CLI (Apache-2.0), Aider, Cline (Apache-2.0) and Kilo Code (MIT), plus the old Gemini CLI (Apache-2.0). Cursor, Copilot and Antigravity CLI are the closed ones.

Why People Leave Claude Code

Five reasons come up again and again, and all five are checkable. Knowing which one is yours matters, because each points to a different tool.

Usage limits. Claude's pricing page says limits reset on a rolling five-hour window, and paid plans also have weekly limits. Claude Code shares that pool with your chats. When you hit the limit you wait, upgrade, or turn on usage credits billed at standard API rates. If you work in long sessions, this is the number one complaint. I wrote about how to stay under it in the Claude Code workflow post.

No free plan. Claude Code is included in Pro ($20 a month, or $17 billed annually), Max (from $100 a month), Team and Enterprise. The Free plan does not have it. Several alternatives do have a free path.

One model family. Claude Code runs Anthropic models. If you want GPT, Gemini, Kimi, DeepSeek or a model on your own machine, it is the wrong tool. Anthropic's gateway docs also say it does not support routing Claude Code to non-Claude models through any gateway.

Closed source. Claude Code is not open source. If you want to read the harness, fork it or audit what it sends, you need a different tool.

You live in an editor. Claude Code is terminal-first. It has IDE extensions, but if you want inline edits, tab completion and a diff view as the main experience, an editor-first tool fits better.

Your reason decides your pick. Limits and cost point to OpenCode or Codex. Model freedom points to OpenCode, Cline, Kilo Code or Aider. Editor-first points to Cursor, Cline or Kilo Code. Open source points to everything except Cursor and Copilot.

1. OpenCode: The Open Source Claude Code Alternative

OpenCode is the closest open source equivalent to Claude Code. It is MIT licensed, runs in the terminal, a desktop app, your IDE or a web app, and connects to 75+ model providers through Models.dev, including local models.

The numbers on its homepage are big: over 220,000 GitHub stars, 950 contributors, and a claim of over 16 million developers a month. I treat the monthly figure as a vendor number, but the star count and the contributor list are easy to verify on GitHub. It installs with curl -fsSL https://opencode.ai/v2/install | bash, or through npm, bun or brew.

What it does well:

Any model. Connect Claude, GPT, Gemini, xAI and dozens more, or point it at a local model through Ollama or LM Studio. Both are documented as custom providers with an OpenAI-compatible base URL.
Subscription logins. You can sign in with a ChatGPT Plus or Pro plan, or with GitHub Copilot, and use those models without a separate API bill.
Parallel agents. The homepage lists multi-session support, so you can run several agents on the same project at once.
A cheap bundle. OpenCode Go costs $10 a month and Go Plus costs $40. The Go page lists 29 models, from Kimi, GLM, MiniMax and DeepSeek to Claude Haiku 5.5, GPT 6 Luna and Gemini 4 Argon. Limits are spread across rolling windows: 20 percent of the monthly allowance per five hours, 50 percent per week and 100 percent per month. The page gives estimated request counts per model, and they vary a lot, so read the table for the model you actually want.

One trap, and it matters if you are leaving Claude Code because of cost. You cannot use a Claude Pro or Max subscription in OpenCode. The provider docs say to create an API key in the Anthropic Console, and warn that Anthropic prohibits subscription login in third-party tools. Anthropic's own docs say OAuth authentication is for Claude plan purchasers using Claude Code and native apps, and that developers building on Claude should use API keys. So if OpenCode is your way to keep Claude models, you pay per token, which can cost more than the $20 plan. My token cost guide shows how fast that adds up in long agent sessions.

The "OpenCode vs Claude Code" question is the most searched comparison on this list, and the honest answer is that they are different bets. OpenCode bets on openness and model choice. Claude Code bets on one model family and a deep, first-party feature set. I use Claude Code because of that depth, not because the model is the only good one.

Pick OpenCode if: you want a free, open source terminal agent, or you want to switch models without switching tools.

2. Codex: The Alternative If You Already Pay for ChatGPT

Codex is OpenAI's coding agent, with a CLI, an IDE extension and cloud tasks. It is Apache-2.0 licensed, has about 131,000 GitHub stars, and signs in with a ChatGPT plan or an API key.

Install it with npm install -g @openai/codex or brew install --cask codex, then run codex. There is also a curl install script for macOS and Linux and a PowerShell script for Windows.

It is the alternative with the easiest money story. Codex is included in ChatGPT Free, Go ($8 a month), Plus ($20 a month), Pro (from $100 a month), Business, Edu and Enterprise. So if you already pay for ChatGPT, trying Codex costs nothing extra, and a free tier exists for light use. The CLI has MCP support through codex mcp, a /permissions command to control what it can edit or run without asking, and subagents for delegating focused work.

I wrote a full head-to-head already, so I will not repeat it here. The short version: both start at $20, Claude Code goes deeper on customization, and Codex has the free tier and a cloud-first task queue. The Claude Code vs Codex comparison has the feature table, pricing breakdown and a pick-by-situation list.

Pick Codex if: you already live in the ChatGPT ecosystem, or you want the cheapest way to try a second agent.

3. Cursor: The Editor-First Alternative

Cursor is the best Claude Code alternative if you want AI inside the editor first and the terminal second. It is a VS Code fork with an agent, tab completion and a CLI.

The Cursor CLI installs with curl https://cursor.com/install -fsS | bash and starts with agent. It has three modes: Agent (the default, full tool access), Plan (designs an approach and asks questions before coding) and Ask (read-only). Switch with Shift+Tab, /plan or --mode=ask. The -p flag runs it non-interactively for scripts and CI, and starting a prompt with & hands the task to a cloud agent.

Pricing changed, so ignore older articles that quote a flat $20 Pro plan. The current pricing page lists Free, Plus at $8 a month (Grok models only), Premium at $30, Super at $100 and Ultra at $200. Third-party models are not included in those monthly prices and are billed by usage. That is the catch if you want Claude models inside Cursor: the plan price is not the whole bill.

The Cursor vs Claude Code question is less of a fight than it sounds. Claude Code ships a VS Code extension that installs into Cursor too, and many people run both. My view, from the longer Claude Code vs Cursor vs Copilot comparison: Cursor wins on fast file-level edits and UI work, Claude Code wins on large multi-file jobs and unattended runs.

Pick Cursor if: you want the editor to be the main thing and the agent to be one feature of it.

4. GitHub Copilot CLI: The Alternative Already on Your Account

GitHub Copilot CLI is the lowest-friction alternative if your team already pays for Copilot. The plans page says all plans include Copilot CLI.

Individual plans listed on GitHub's docs: Copilot Free, Pro at $10 a month, Pro+ at $39 and Max at $100. They come with a monthly allowance of GitHub AI Credits (1,500 on Pro, 7,000 on Pro+, 20,000 on Max), and usage-based billing applies. This is a recent change. GitHub moved from counting premium requests to token-based credits on June 1, 2026, and some annual subscribers stayed on the legacy premium request model, where each prompt to Copilot CLI uses one premium request at the default model rate. If you read an article quoting 300 or 1,500 premium requests, it describes the old model.

The strongest argument for Copilot is not the CLI. It is that your organization already approved it, it is already in your billing, and it runs from the same account as your editor features. If you are in a company with a compliance process, that beats almost any feature difference.

Pick Copilot CLI if: you are already on a Copilot plan, or procurement decides your tools.

5. Gemini CLI and Antigravity CLI: Read This Before You Install

Gemini CLI is no longer a free alternative for individuals. Google replaced it with Antigravity CLI for free, Google AI Pro and Google AI Ultra users on June 18, 2026.

The Gemini CLI GitHub page carries the notice: "Gemini CLI was replaced by Antigravity CLI on June 18th, 2026." The old tool is Apache-2.0 licensed with about 108,000 stars, and it still works if you bring a paid Gemini API key, Vertex AI, or an enterprise Code Assist license. For everyone else the new tool is Antigravity CLI. Reporting from The New Stack describes it as a move from the open source Gemini CLI to a closed source CLI, and secondary coverage says it is a Go rewrite with a weekly compute-based cap in place of the old 1,000-requests-per-day limit.

I could not find a published daily number for the free tier, and several comparison pages still repeat the old 1,000 requests a day figure. Those pages are stale. If you search for "Gemini CLI vs Claude Code" and land on a post that calls Gemini CLI free with a generous limit, check its date.

Pick Antigravity CLI if: you want to try Google's models and you accept a closed source tool with a capped free tier. For a free, open source terminal agent, use OpenCode.

6. Aider: The Git-First Alternative

Aider is a terminal pair programmer that commits every accepted change to git with a sensible message. It connects to almost any LLM, including local models, and costs nothing beyond the model you use.

Install it with python -m pip install aider-install followed by aider-install. Aider's site shows about 44,000 GitHub stars, 6.8 million installs and 15 billion tokens processed per week. It builds a repo map of your codebase so it can work on larger projects, lints and tests after each change, supports over 100 languages, and accepts images and web pages as context. It even has voice-to-code.

Aider is older and calmer than the agent-heavy tools above. It is built around a loop: you ask, it edits, it commits, you review the diff and undo with normal git commands. That makes it predictable and easy to audit. It also means less autonomy. If you want a tool that works through a long task alone, spawns subagents and runs hooks, Aider is not that. If you want small, reviewable, committed steps, it may suit you better than Claude Code does.

Pick Aider if: you think in commits, you want full model freedom, and you prefer a tool that stays on a short leash.

7. Cline: The Approval-First Alternative

Cline is an Apache-2.0 coding agent with about 70,900 GitHub stars that runs in VS Code, JetBrains, a CLI and a desktop app. File edits and terminal commands need your approval by default.

Install the CLI with npm i -g cline, or get the extension from the VS Code Marketplace or the JetBrains plugin store. It has a Plan mode that explores the codebase, asks questions and proposes a strategy, and an Act mode that carries it out. Providers include Anthropic, OpenAI, Google, OpenRouter, AWS Bedrock, Azure and Vertex, Groq, Cerebras, Ollama and LM Studio, and any OpenAI-compatible API.

The approval-by-default design is the point. You see each file change and each command before it runs, and you can switch on auto-approve when you trust the task. If that sounds like the permission system in Claude Code, it is a similar idea with different defaults. My post on coding agent permissions covers how to set that up safely in either tool.

One caveat that applies to Cline and every other tool that takes your own API key: pricing becomes whatever the provider charges. Free software, variable bill.

Pick Cline if: you want an editor extension that asks first, and you want to bring your own model.

8. Kilo Code: The Multi-Mode Open Source Alternative

Kilo Code is an MIT licensed agent with about 27,800 GitHub stars that runs in VS Code, JetBrains, a CLI and a browser-based cloud agent. It supports 500+ models and charges the provider's rate with no markup.

Install the CLI through npm, curl, Homebrew or a prebuilt binary and run kilo in your project. Its built-in agents are Code (the default), Plan, Ask and Debug, and you can define custom ones. You can switch models in the middle of a task, which is handy when you want a cheap model for exploration and a stronger one for the final change.

It sits in the same family as Cline, with a wider spread of surfaces and a model catalog that includes the current flagships from Anthropic, OpenAI, Google, xAI and DeepSeek. Because its star count is lower than Cline's, check the recent commit history on GitHub before you build a workflow around it. That advice applies to any open source agent in this list.

Pick Kilo Code if: you want Cline-style control with more modes and a cloud option, and you do not want a markup on model prices.

Which Claude Code Alternative Should You Pick?

Match the tool to your reason for leaving:

You want free and open source: OpenCode first. Aider, Cline or Kilo Code if you prefer their style.
You want to keep your current spend flat: Codex if you pay for ChatGPT, Copilot CLI if you pay for Copilot.
You want an editor, not a terminal: Cursor, Cline or Kilo Code.
You want maximum model choice: OpenCode, Cline, Kilo Code or Aider.
You want small, reviewable commits: Aider.
You need to pass a compliance review: whatever your company already approved, which is often Copilot.
You want a free Google option: try Antigravity CLI, and read its limits first.

If you cannot decide, install OpenCode and Codex. Both are free to try, they cover the two big bets (open and any-model versus a second vendor), and you will know within a week which one fits your habits. Spend your effort on three real tasks from your own repo, not on someone's leaderboard.

When Not to Switch Away From Claude Code

This is my bias, so read it as opinion. I stay on Claude Code because of the layer around the model: skills, hooks, subagents, plugins and a permission system I have tuned over months. The alternatives are catching up on pieces of it, and some pieces are better elsewhere. But if your workflow depends on hooks that block bad commands, subagents that split big tasks, or shared skills across a team, switching means rebuilding that setup. That is a cost nobody puts in the comparison tables.

I would not leave if:

Your only complaint is the five-hour limit. Long, bloated sessions burn through it faster, so try /compact and /clear at the right moments before you change tools. The commands cheat sheet covers both.
You are leaving because of a bad week. Tools in this category change monthly. A limit that annoyed you in September may look different in November.
You plan to keep paying per token for Claude models in another tool. That often costs more than the subscription you are escaping.

I would leave, or at least add a second tool, if you need open source for policy reasons, you want models Claude Code cannot run, or you are on a team that standardized on something else.

The best setup for a lot of people is two tools, not zero. Use Claude Code for the big jobs and a cheap or free alternative for everything else. If you are just starting out with the main tool, the Claude Code tutorial is the place to begin.

Frequently Asked

What is the best alternative to Claude Code? For most people leaving over cost or model lock-in, OpenCode: it is MIT licensed, supports 75+ providers and local models, and has a $10 monthly Go bundle. If you already pay for ChatGPT, Codex costs nothing extra. If you live in an editor, Cursor, Cline or Kilo Code fit better.

What is a free alternative to Claude Code? OpenCode, Aider, Cline and Kilo Code are free software, and you pay only for the model tokens you use, or use a local model for nothing. Codex has a free tier through ChatGPT Free. Copilot has a Free plan that includes Copilot CLI. Gemini CLI's free tier for individuals ended on June 18, 2026.

Is there an open source alternative to Claude Code? Yes. OpenCode (MIT), Codex CLI (Apache-2.0), Cline (Apache-2.0), Kilo Code (MIT) and Aider are all open source. Claude Code is not.

Is OpenCode better than Claude Code? I have not benchmarked them, and I will not claim a winner on code quality. OpenCode gives you open source and any model. Claude Code gives you one model family and a deeper first-party feature set. Pick based on which of those matters to you.

Can I use my Claude Pro or Max subscription in OpenCode? No. OpenCode's docs say to use an Anthropic API key and note that Anthropic prohibits subscription login in third-party tools. Anthropic's docs say developers building on Claude should use API key authentication.

Is Gemini CLI still free? Not for individuals. Google replaced it with Antigravity CLI for free, AI Pro and AI Ultra users on June 18, 2026. Gemini CLI itself still works with a paid Gemini API key, Vertex AI or an enterprise Code Assist license.

Can I use other models inside Claude Code? Not officially. Claude Code can connect through an LLM gateway, but Anthropic's docs say they do not support routing Claude Code to non-Claude models through any gateway. If you want other models, use a tool built for it.

Is Cursor or Claude Code better? They solve different problems. Cursor is better for fast file-level edits and UI work inside an editor. Claude Code is better for large multi-file changes and long agent runs. Many people use both, and Claude Code installs a VS Code extension that works in Cursor.

Is Claude Code worth $20 a month? It depends on your usage. If you code with an agent daily, a flat plan is easier to predict than per-token billing, which can add up fast in long sessions. If you use it a few times a week, a free tier elsewhere may be enough.

Sources, all checked October 26, 2026: OpenCode, OpenCode Go, OpenCode providers docs, Codex on GitHub, Codex CLI docs, Cursor CLI docs, Cursor pricing, GitHub Copilot plans, Copilot premium requests, Gemini CLI on GitHub, The New Stack on Antigravity CLI, Aider, Cline, Kilo Code, Claude pricing, Claude Code legal and compliance and Claude Code LLM gateways.

I Shipped 32,784 Lines of Code in 2 Days With Claude Code. Here Is What the Number Hides

Alex Cloudstar — Fri, 23 Oct 2026 21:51:53 +0000

I Shipped 32,784 Lines of Code in 2 Days With Claude Code. Here Is What the Number Hides

I shipped 32,784 lines of code in two days with Claude Code. I put that number in a LinkedIn post, and the first thing I wrote right after it was that lines of code is a weak metric. I meant it. The number is the least useful fact about the project, and this post is about the facts that matter more.

Here is what the two days covered: a full rebuild of this site on Next.js 16, 228 blog posts rewritten against real keyword data, 543 tests passing, and zero broken URLs. Two years ago a project like that would have taken me weeks. This time the typing was not the slow part. Neither was the writing.

The slow part was deciding what to build, and what to leave out. That is the real Claude Code workflow lesson, and it is the one I want to spend most of this post on.

The Short Answer: What Actually Changed

With Claude Code, the cost of producing code dropped close to zero for me. The cost of deciding which code should exist did not move. That is the whole shift in one sentence.

In practice it meant my days looked different. Less time typing and debugging syntax. More time writing down constraints, reading diffs, saying no to features, and checking that the output matched what I actually wanted. I spent most of the two days acting as a reviewer and an editor, with the agent as a very fast and very literal builder.

If you only take three things from this post:

Write the constraints before you write the prompt. The agent will happily break anything you forgot to mention.
Treat tests as the contract, not as an afterthought.
The most valuable thing you ship is often a deletion.

What 32,784 Lines of Code Actually Covered

Here is the honest breakdown of what the work was, because "32,784 lines" tells you nothing.

A full rebuild on Next.js 16. The site started as an Astro project in December 2025. The new version runs on Next.js 16 with Cache Components, a light redesign, a shared breadcrumb component, new icons, and a rewritten set of main pages. Nearly every route had to be rebuilt, and every route that the old site served had to keep working.

228 posts rewritten against keyword data. The blog is the part of the site that earns search traffic, so each post's title, meta description, headings and intro got reworked against real query data instead of my gut. More on that below.

543 tests passing. The repo has tests for the metadata rules, the structured data, the sitemap, the llms.txt output, the tag pages, the proxy, the markdown negotiation and a lot more. They are what let me merge quickly without holding my breath.

Zero broken URLs. This one sounds boring and it was the hardest requirement. Every URL the live site serves has to keep returning a 200 with real content. Indexed pages are the asset. A pretty redesign that 404s half of them is a net loss.

All of that landed in roughly 100 commits and 11 merged pull requests. The first commit was late on October 21 and the last one was the morning of October 23.

Why Lines of Code Is a Weak Metric (and What I Track Instead)

Lines of code has been a bad measure of developer output for a long time. DX's write-up on the metric makes the old argument well: teams end up optimizing the number instead of the outcome. AI makes the problem worse, because generating lines is now nearly free. InfoWorld made a related point in its piece on AI agents and bad productivity metrics: the real bottleneck has moved to validation and integration, not writing.

My own number is a good example of why. Some of those 32,784 lines are:

Generated or reformatted content in 228 MDX posts
Test files and fixtures
Code I wrote, shipped and then deleted a day later

That last category is the interesting one, and I will get to it. The point is that if I had been measured on lines, deleting code would have counted against me, and deleting code was one of the best decisions of the project.

So what do I look at instead?

Do the tests pass, and do they test behavior? A green suite that checks nothing is worse than no suite.
Does every previously indexed URL still return 200? This is a binary check I can automate.
Did the change reduce the surface area I have to maintain? Fewer routes, fewer concepts, fewer places to be wrong.
Can I explain every decision in the diff? If I cannot, I did not review it, I just approved it.

The same gap shows up in the research. In the METR study I wrote about in the AI productivity paradox, experienced developers using AI tools took 19 percent longer on their own repositories while believing they were faster. Output feels like progress. It often is not. I did not escape that trap by being smarter. I escaped it by measuring things that are hard to fake.

My Claude Code Workflow: Best Practices From a Two-Day Rebuild

I am not going to pretend there is a magic prompt. By "workflow" I mean my working habits, not Anthropic's dynamic workflows feature. What worked was a handful of Claude Code best practices, and most of them are about the work around the agent, not the agent itself. If you are new to the tool, start with my Claude Code tutorial and come back.

Write the constraints down before the first prompt

The most expensive mistakes with an agent are the ones where it does exactly what you asked and breaks something you never mentioned.

For this rebuild the constraints were mostly negative. Do not break any URL the live site serves. Keep the heading wrap on the homepage and page titles stable. Never use certain phrases in titles or metadata. Keep the page metadata rules enforced by tests. I kept them in the instructions and notes the agent reads at the start of a session, and I added to them every time I caught a violation.

This is the practical core of context engineering. The agent is only as good as what is in its context. A constraint that lives in my head does not exist as far as the agent is concerned.

Make tests the contract

When you generate code this fast, you cannot read every line with the same care. You need something that reads it for you.

Tests do that. The page metadata test fails if a title or description breaks the rules I agreed on. The structured data tests fail if the JSON-LD changes shape. The sitemap test fails if a route disappears. None of these are clever. They are cheap to write, and each one turns a rule I would otherwise have to remember into a failing build.

The rule I follow: when I catch the agent breaking something, I do not just fix it. I add the test that would have caught it, and then the next session cannot make the same mistake silently.

Keep every merge small enough to review

The 100 commits and 11 merged PRs were not an accident. Big diffs are where bugs hide, and an agent can produce a big diff in minutes. If I let one session run for hours and then opened a single pull request, I would be approving code I had not understood.

So I merged in slices: the redesign, the copy audits, the routing fixes, the review follow-ups. After one batch I ran a review pass and fixed the findings before moving on. This is the same problem I covered in AI code review is the new bottleneck. Generation speed is not the constraint. Your ability to review is, so size the work to fit it.

Use audits as a loop, not a final step

A lot of the project was a loop: have the agent audit the site against a checklist, read the findings, decide which ones are real, fix those, and run the audit again. Copy audits, metadata audits, project page audits.

The decision step is the important one. The audit produces a list, and agents are good at producing lists. They are not good at knowing which items are worth your time. If you accept everything an audit says, you have outsourced the judgment, not the typing.

Delegate in parallel, but only what is cleanly separable

Subagents and parallel sessions pay off when the tasks do not touch the same files. Rewriting the copy on one page and fixing the sitemap logic are separable. Changing the layout and the metadata helper at the same time is not. If you want the mechanics, I wrote guides on subagents and hooks. The catch is that parallelism multiplies your review load, so only split work when the review stays easy.

Claude Code tips from this project, in one list

If you only want the checklist:

Put your hard rules where the agent reads them at the start of every session.
Turn every mistake you catch into a test.
Merge in small slices and review each one before starting the next.
Run audits, then decide for yourself which findings are real.
Split work across agents only when the tasks touch different files.
Ask "should this exist?" before "can the agent build it?"

The Best Thing I Shipped Was a Deletion

Here is the story I mentioned. On the morning of October 23 I had a public JSON API on the site. Posts, projects, an OpenAPI spec, the works. Hours earlier I had spent a commit versioning it under /api/v1 and adding deprecation headers to the old paths. It was clean, documented and tested.

Then I deleted all of it.

The reason is in the commit message: the site is a portfolio, and the API added no SEO value and no value for AI discovery, while generating about 500 extra static pages. Agents that want to read the site are already served by llms.txt and Markdown content negotiation. Removing the API took the static page count from 1,093 down to 596.

Think about what that means. Claude Code built the versioning, the headers, the serializers and the tests in a very short time. It was easy. It was also pointless. The agent had no way to tell me that, because the question "should this exist?" is not a coding question. It is a product question, and it depends on what the site is for.

That is the pattern I keep seeing. When building was expensive, the cost forced a filter. You only built what you were sure about, because you could not afford otherwise. When building is nearly free, the filter is gone, and it is easy to ship a lot of well-made things nobody needs. Other people are noticing the same shift. A common theme across recent writing on this is that the question has moved from "can I build this?" to "should I build this?". I came to the same conclusion by deleting my own work.

If you are curious about the same dynamic at the startup level, my post on why AI wrapper startups are failing covers the market version of it. Cheap building makes weak ideas more visible, not less.

Real Keyword Data Beat My Gut on 228 Posts

The 228-post rewrite is where I let data make the decisions I would normally make by feel.

I pulled keyword data from DataForSEO: volumes, difficulty scores, live search results and which domains were ranking. The whole research run was 313 API calls and cost $4.37. For that I got a map of which queries the blog could realistically win and which ones were a waste of time.

A few things that came out of it:

Specific tool comparisons are winnable. Queries like "cursor vs claude code" have low difficulty, and small solo blogs already rank for them. Head terms like "cursor" or "javascript" are not worth chasing.
Hiring-intent queries matter more than brand. I do not need to rank for my own name. I need the right people to find me when they search for what I do.
Existing posts were often right but badly titled. Several posts covered a high-volume query without leading with it. The fix was a title and heading rewrite, not a new post.

This is also where taste came in. The data showed one phrase with about 720 searches a month that fit my situation. I decided not to use it anywhere on the site, because I did not like how it sounded. A tool that optimizes only for volume would have used it. That decision cost me a bit of traffic and I would make it again.

The agent can run the analysis, cluster the posts and draft the rewrites. It cannot tell me which version of myself I want the site to present. That part is mine.

Where Claude Code Got It Wrong

I do not want this to read like a victory lap, so here is what went wrong.

It broke URLs I told it to protect. Early in the rebuild, the new design did not need the paginated blog pages or a few hidden project pages. So the agent redirected the pagination and turned the hidden projects into 404s. From a design point of view that made sense. From an SEO point of view it was wrong, because both sets of pages are indexed on the live site. I caught it, and the fix became a commit titled "Keep every URL main serves." It became a standing rule, and I checked the old sitemap against the new routes after every routing change.

It followed its own logic over my intent. The agent kept optimizing for the cleanest structure. I kept needing the structure that preserved what already worked. Those are different goals, and it only knew about one until I wrote the other down.

A passing build is not proof the page is right. Compiling and passing tests tells you the code is consistent with itself. Only a person looking at the page can tell you it says the right thing.

None of these were disasters, because I had tests and small merges to catch them. That is the argument for the workflow above: it is not there to make the agent better, it is there to make its mistakes cheap.

Is Judgment Really the Bottleneck Now?

I have eight years of engineering behind me, and for most of that time I treated execution as the hard part. Knowing how to build the thing, and having the stamina to build it, was the scarce resource. Nobody asked whether I should build it, because the building itself was the filter.

That has flipped for me. Execution is no longer the hard part. These days the hard parts are:

Judgment. Which problem is worth solving, and which one to skip. The JSON API is the perfect example. I could have built ten more things like it in the same two days.

Taste. Knowing when something is good enough, when copy sounds like a person and when it sounds like a template, when a page feels right. An agent will produce competent output forever. Competent is the problem.

Distribution. Shipping a rebuilt site does not mean anyone reads it. When everyone can build quickly, the people who get found are the ones who thought about where their audience is. A big part of this rebuild was making sure search engines and AI tools could read the site properly, which is why llms.txt and the keyword work got real attention. I looked at whether that file actually helps in does llms.txt work for AI visibility.

The honest caveat is that this does not make engineering skill irrelevant. It is the opposite. I could only trust the output because I know what good looks like. I could write useful constraints because I understood what could break. I could review a diff quickly because I have read thousands of them. Agentic coding rewards experience, because the job moves from typing to directing and verifying, and both of those need judgment you have to earn some other way.

If you are earlier in your career, that is worth thinking about carefully. The skills that matter most are the ones the tool cannot give you: reading code critically, understanding systems, and developing opinions about what to build.

Common Questions About This Kind of Project

Can Claude Code rebuild a whole website? Yes. The rebuild described here is evidence. But "can" is not "should unsupervised." It rebuilt the structure quickly and also broke indexed URLs and built features that I deleted. Treat it as a fast builder that needs constraints and a reviewer.

How good is Claude Code at making websites? Very good at the structure, components, routing and tests, as this Next.js 16 rebuild showed. Weaker at the parts that depend on context it cannot see: which URLs are indexed, what the site is for, what sounds like you. Those are the parts you have to supply.

What is the best workflow in Claude Code? There is no single best one, but the pattern that held up for me was constraints first, tests as the contract, small merges, and a human decision on every audit finding. The checklist is in the workflow section above.

What is the biggest bottleneck in AI coding? It depends on the team. For a lot of teams it is review, as I covered in AI code review is the new bottleneck. For a solo builder like me, it moved one step earlier: deciding what is worth building at all.

How long does it take to rebuild a website with Claude Code? For this project, about two days from the first to the last commit, with a lot of review in between. That is far shorter than it would have taken me alone, but a good chunk of the time was decisions and checks, not generation. The time you save is the typing. The time you still need is the thinking.

Is lines of code a good metric for AI coding? No. It was a weak metric before AI and it is worse now, because generating lines costs almost nothing. Track outcomes: working tests, intact URLs, less surface area, decisions you can explain.

What is the most important Claude Code habit? Writing constraints down where the agent reads them. Most of the failures I hit were the agent doing something reasonable that I had never ruled out.

Do you still need to know how to code? Yes, probably more than before. You are reviewing at speed, so you need to recognize bad code, fragile design and silent regressions quickly.

What I Would Do Differently

If I ran this project again, I would change three things.

I would write the URL-preservation test on day one instead of discovering the need for it mid-project. A script that diffs the old sitemap against the new routes would have caught the pagination and hidden-project problem immediately.

I would decide earlier what the site is for. The JSON API existed because I never wrote down the purpose of the site clearly enough to rule it out. A one-paragraph statement of purpose at the top of the instructions file would have saved a day of building.

I would spend even less time on code and more on the two things the tool cannot do for me: choosing what to publish and getting it in front of people.

Where Is Your Bottleneck Right Now?

That was the question at the end of my LinkedIn post, and I mean it as a real one. If you build software, try this: pick your last three projects and write down where the time went. Not the hours on the calendar, the actual friction. Was it typing, debugging, reviewing, waiting, deciding, or promoting?

For most of my career, my answer was typing and debugging. Now it is deciding and distributing. Yours might be different, and the answer should change what you practice.

If you have a product that needs this kind of rebuild, or you want a second opinion on what to build before you build it, tell me what you are working on. I will give you an honest read, and sometimes the honest read is that you should skip the feature.

Sources: DX on lines of code, InfoWorld on AI agents and productivity metrics. Project numbers come from this site's git history and DataForSEO usage log, checked October 23, 2026.

llms.txt Does Not Get You Cited. Here Is What It Is Actually For.

Alex Cloudstar — Thu, 22 Oct 2026 22:18:26 +0000

llms.txt Does Not Get You Cited. Here Is What It Is Actually For.

There is a small text file being sold as a shortcut through a problem that has no shortcuts.

Put llms.txt at the root of your site, the pitch goes, and ChatGPT, Claude, Gemini, and Perplexity will finally understand what you do. You will get cited. Your rankings will move. The robots will stop overlooking you.

That would be a lovely product feature. It is not how this works.

Does llms.txt work? For AI-search rankings and citations, there is no convincing evidence that it does, and no major answer engine has said it uses the file. For developer documentation it can help coding agents find the right pages. Treat llms.txt as docs hygiene, with an example file near the end of this post.

The best public crawl data we have says the major answer engines barely request llms.txt at all. One recent study of more than 100,000 sites found an association between the file and AI visibility, but association is exactly what you would expect when technically mature sites do many sensible things at once. Other server-log studies found that crawlers request robots.txt hundreds of times more often, and that most llms.txt requests come from SEO tools checking whether the file exists.

So should you create one? Probably. It takes twenty minutes. Just stop treating it as a growth strategy.

What llms.txt Actually Is

The proposal is simple: a Markdown file at /llms.txt that gives a language model a compact map of your site. A heading, a sentence explaining the product, links to important documentation, maybe a list of endpoints or guides.

That is a reasonable convention. Documentation is full of navigation, sidebars, marketing copy, version selectors, and JavaScript that sometimes makes the useful part harder to extract. A clean Markdown index can be genuinely helpful to a coding agent that is trying to answer, "How do I authenticate with this API?"

This is why Stripe and other developer-first companies have something in the shape of an LLM-friendly docs entry point. Their use case is not search ranking. It is making the correct current information easier to retrieve when an agent is already reading their documentation.

That distinction matters:

llms.txt can help an agent navigate your docs after it arrives.
It does not make the agent arrive.
It does not prove that your claims are true.
It does not turn a site nobody mentions into a recommended product.

The file is documentation hygiene. Good hygiene matters. It does not replace a product, a reputation, or pages that answer a real question better than the alternatives.

Does llms.txt Improve AI Visibility?

Not in a way anyone has shown convincingly.

No major answer engine has said that llms.txt is a ranking factor or a citation input. Google has been especially clear that its ordinary search guidance still applies to AI features. Make pages accessible. Make them useful. Use descriptive titles. Give users a reason to choose them. The answer is boring because the answer has always been boring.

The temptation to believe otherwise is understandable. Zero-click search is now the majority of Google searches, so a file that promises a direct line to the answer box feels like a thing you should not miss.

But a file cannot solve the actual citation question: why should a model name you rather than the company it has already seen in documentation, reviews, Reddit threads, comparison pages, editorial coverage, and its own training data?

It cannot.

The strongest signal in the studies is not file format. It is clarity plus corroboration. Brands that appear in several independent, trustworthy places get named more often. Brands whose own site states exactly who they serve, what they do, how they compare, and what it costs are easier to cite accurately once the model encounters them. That is work. A text file is not.

The Correlation Trap Is Doing Most of the Selling

Here is how a bad conclusion becomes a marketing claim.

Someone scans 100,000 websites. Sites with llms.txt score better in an AI visibility tool. They publish the graph. A software company turns the graph into "add an llms.txt file to increase citations." Another company builds a scanner that gives you a red warning until you add one.

What the graph actually captures is that a team that publishes an LLM file is more likely to also have:

documentation that is current and crawlable
schema markup and clean canonical URLs
comparison pages with a clear category definition
an active product with reviews, backlinks, and community mentions
someone who notices when a page is broken

Those things have a chance of helping. The file is a useful proxy for "this team cares about its website," not evidence of causation.

You can see the same problem with the whole category of AI visibility dashboards. A graph showing that your competitor was cited 18 times and you were cited 6 times is a diagnosis, not a plan. That gap is exactly why I built beseen.so: I wanted the missing page and rewrite, not a more decorative thermometer.

When You Should Publish llms.txt

I would add it in three cases.

You have developer documentation. If your users paste prompts into coding agents, a compact entry point reduces the odds that the agent follows an old blog post, a deprecated endpoint, or a random answer from Stack Overflow. Point to versioned guides and make the current path obvious.

Your site is large or hard to navigate. A docs site with hundreds of pages, a dashboard that renders client-side, or a product with multiple APIs can benefit from an explicit map. It is the same argument for a good README: people should not have to play scavenger hunt to understand the system.

You can keep it current. An inaccurate llms.txt is worse than no file. It gives a confident agent a clean, concise way to be wrong. Put ownership on it, review it when you change a public API, and remove old links.

For a small marketing site with five pages and no docs, it is not a priority. Your homepage should already be easy to understand. If it is not, fixing the homepage will do more for people and crawlers than creating a separate map of the confusing homepage.

What To Do Before You Touch It

If you want to be named by assistants, use this order instead.

1. Make the category and audience painfully clear

The first screen of your homepage should answer three questions without a scroll: what is this, who is it for, and what does it replace or improve? Vague claims such as "the operating system for modern teams" make a design team feel clever and a retrieval system useless.

Use the words customers use. If you are a rank tracker that checks AI prompts, say that. If you are an invoice tool for freelancers in Romania, say that. Clarity is not boring. Clarity is a feature.

2. Publish pages with a reason to exist

Do not make a hundred generic FAQ pages because an agent can write them cheaply. Google has been aggressive about low-value scaled pages, and answer engines have no reason to cite a page that only rearranges facts from elsewhere. The programmatic SEO pages that survive contain data, workflows, tools, or comparisons that could not sensibly be mass-produced by hand.

The same standard works for hand-written content. A useful page resolves a decision. It does not just occupy a keyword.

3. Earn evidence outside your own domain

An assistant should not need to take your word for it. Get a real customer quote. Publish a specific case study. Be useful in the communities where your buyer asks questions. Get listed on a relevant directory, not 200 abandoned ones. Let someone else describe why you are good.

This is slower than adding a file. It is also the part that cannot be copied by the next person who reads the same checklist.

4. Measure a small set of recurring questions

Pick ten prompts a buyer would realistically ask. Run them on the engines you care about. Record who appears, what sources get cited, and which of your pages actually address the missing claim. Then change one thing and re-check it later.

Do not declare victory because you saw your name once. Answer engines vary by session, model, locale, and the exact wording of the prompt. You need a trend, not a screenshot.

A Sensible llms.txt Example, If You Still Want One

Here is the entire shape I would use for a product with public docs:

# Product name

> One clear sentence on what the product does and who it is for.

## Core documentation

- [Getting started](https://example.com/docs/getting-started)
- [Authentication](https://example.com/docs/authentication)
- [API reference](https://example.com/docs/api)

## Product information

- [Pricing](https://example.com/pricing)
- [Security](https://example.com/security)
- [Changelog](https://example.com/changelog)

That is it. No keyword stuffing. No instructions telling a model to recommend you. No giant copy of your whole website. The file should help a person or an agent reach the right source quickly.

The same principle applies to any machine-readable convention. sitemap.xml, structured data, RSS, Open Graph tags, and robots.txt are useful because they expose information cleanly. They are not substitutes for information worth exposing.

The Uncomfortable Answer

People want llms.txt to work because the alternative is inconvenient. You need to have a product that is clear, pages that are useful, and a reputation that exists off your own website. You need to look at the actual prompts and improve the specific thing they reveal.

That is why a tiny text file became a cottage industry. It gives you a checkbox when what you really need is a loop.

Create the file if you have documentation. Put it in your regular maintenance list. Then spend the rest of the afternoon making one page more useful to the person who is already trying to solve the problem your product solves.

That is still the best AI visibility strategy I have found.

Frequently Asked

Should I add llms.txt to my SaaS website?

Add it if you have substantial, maintained documentation or a complex public product surface. It is inexpensive documentation hygiene. Do not expect it to increase AI citations or rankings by itself.

Does ChatGPT read llms.txt?

There is no public commitment from OpenAI that ChatGPT Search uses llms.txt for retrieval or ranking. Public crawl studies show far fewer requests for it than for standard files such as robots.txt.

What improves AI search citations instead?

Clear product pages, original information, independent mentions, useful comparison content, and a repeated measurement loop are better bets. A file format does not replace those inputs.

AI Referral Traffic Converts Better. That Does Not Mean You Should Chase It Blindly.

Alex Cloudstar — Thu, 22 Oct 2026 22:17:53 +0000

AI Referral Traffic Converts Better. That Does Not Mean You Should Chase It Blindly.

The most exciting chart in a young SaaS dashboard is often the smallest one.

You filter acquisition by referrer and find 27 visits from ChatGPT last month. Two of them signed up. Your organic traffic sent 400 visitors and converted at a lower rate. Suddenly the conclusion feels obvious: AI search is the channel. We should optimize for citations. We should make more comparison pages. We should find an agency with "GEO" in its name before the window closes.

Slow down.

The conversion pattern is real. Across several 2026 benchmarks, AI-referred sessions convert better than ordinary organic sessions. That makes intuitive sense. A traditional searcher often arrives while exploring. A person who clicked after an assistant recommended a specific product has already outsourced a chunk of the evaluation. They arrive later in the decision.

But a better conversion rate on 27 visits is not a growth engine. It is a useful signal. Treat it like one.

Why AI Referrals Convert Well

An assistant recommendation has context that a search result does not.

Someone might ask, "What is a simple way to track whether ChatGPT recommends my competitors?" If the answer names a product, the user usually arrives with a framed problem, a category, and a reason to believe this option might fit. They have skipped the phase where they read five unrelated listicles and decide whether the problem even matters.

That means the visit can look unusually qualified. It is similar to a strong word-of-mouth referral. The person is not giving you trust from zero. Some of it has been borrowed from the system that named you.

There are three caveats.

The assistant may have made a bad recommendation. If your landing page does not match the claim, the conversion advantage disappears fast. An assistant calling you a complete analytics suite when you only track a narrow prompt set gives you a visitor and a disappointment.

Referrer data misses a lot. Some apps strip or hide referrers. A user may ask on one device, remember your name, and type it into a browser later. You will see direct traffic, branded search, or nothing measurable. The report is a lower bound, not a census.

The volume is still tiny for most sites. AI referral traffic has grown quickly from a very small base. That means a 300% increase can be the difference between five visits and 20. It is a good reason to pay attention, not a reason to fire the other channels.

The zero-click problem is still the other half of this story. Answer engines are taking clicks away from ordinary results at a scale that referrals do not yet replace. One good cited visit is valuable. It does not pay back every visit that never reaches you.

The Metric Stack That Keeps You Honest

Do not make citation count your north-star metric. A citation is an intermediate event. You need to know whether it produced the kind of visitor who can become a customer.

For each assistant referrer you can observe, track these six things monthly:

Metric	Why it matters
Sessions	The visible size of the channel
Signup or demo rate	Whether the recommendation created intent
Activation rate	Whether the product matched the promise
Paid conversion	The thing that keeps the business alive
Branded search trend	A partial signal for invisible AI influence
Prompt coverage	Which buyer questions name you or a competitor

Do not read the first two without the next two. A referral source can send people who eagerly sign up and quickly churn because the assistant oversold what you do. That is not a channel win. It is a positioning mismatch with a free top-of-funnel layer.

For the first few months, keep the data simple. Create a channel group for known assistant domains. Annotate the date you changed a page or launched a feature. Add a short, optional question to onboarding: "How did you first hear about us?" Let the answer be free text. People will say ChatGPT even when the referrer did not survive the trip.

None of this creates perfect attribution. Perfect attribution is the bait. You are trying to make better decisions, not win an argument with a spreadsheet.

The Landing Page Is Where the Recommendation Gets Tested

The most common mistake in AI visibility work is trying to win the answer while ignoring the page the answer sends people to.

Read the recommendation you are getting. What exact phrase does the assistant use? Then open the landing page cold and check whether the first screen confirms it.

If the answer says "use this to compare your AI visibility against competitors," the page should not lead with a vague slogan about the future of search. It should show who gets compared, which engines are checked, what output appears, and how someone starts.

This is particularly important for comparison prompts. When a model names you alongside known tools, the user will expect an honest difference. Give them the difference. A page that pretends to beat every incumbent on every dimension destroys the trust the recommendation created.

This is why beseen.so is explicit about what it does not do. No backlink index. No keyword research suite. No auto-publishing. A product page that tells a narrow truth can lose some casual clicks and gain the customers who were actually looking for that narrow thing.

How To Improve the Channel Without Gaming It

The boring work is also the durable work.

Answer real buyer questions directly

Build pages around decisions a customer makes. Alternatives, integrations, pricing tradeoffs, setup guides, and case studies all give an assistant something specific to retrieve. Do not churn out definition pages that can be summarized above the result with no reason to click.

The best test is whether someone would still find the page useful after an assistant summarized its first paragraph. If the answer is no, the page probably does not have enough original value.

Make claims easy to verify

If you say your product supports four engines, show the four engines. If you say a workflow takes two minutes, show the steps or state the constraint. If you compare yourself with another tool, say when that tool is the better choice.

Assistants are not fact-checkers in the way people wish they were, but external evidence makes their summaries more stable and makes human visitors less likely to bounce after clicking.

Earn mentions where buyers already look

An assistant's training and retrieval universe is not your sitemap. Reviews, community discussions, documentation, directories with actual editorial standards, and genuine customer stories all teach the world that the product exists.

Do not turn this into fake Reddit answers or a directory-submission marathon. Relevant directory placements can help, but the value is the audience and validation, not a follow link you can count.

Measure prompts, not just sessions

Ask the questions your buyer asks, in fresh sessions, on a regular cadence. Record who is named, which page is cited, and whether the wording matches your product. Then improve the missing page and wait long enough for it to be recrawled.

This is the feedback loop a good visibility tool should support. The output is not "we were cited 14 times." The output is "we are absent from the three comparison prompts that precede our highest-value signup, and our pricing page does not answer the concern those prompts expose."

The Trap: Optimizing for the Mention Instead of the Customer

The ugly version of AI search optimization is already familiar. Pages written to stuff keywords. Fake reviews. Claims with no source. A hundred shallow answers that all say the same thing. It may produce a momentary citation, just like it sometimes produced a momentary rank.

The strategy collapses because it optimizes an intermediate metric. A system might name you, but a person still has to decide whether you are worth money.

The healthy version is almost boring: make the product legible, publish information nobody else can provide, tell the truth about fit, and track whether referral visitors activate and stay. Those practices improve ordinary search, word of mouth, sales calls, and the product itself at the same time.

That is why I am cautiously optimistic about the conversion numbers. They are a hint that recommendation-driven discovery can send unusually good traffic. They are not permission to stop building everything else.

A Practical 30-Day Experiment

If you want to test this without building an entire AI visibility department, do this:

Pick ten questions a qualified buyer would ask before choosing a product like yours.
Run them in the assistants your customers use, from clean sessions.
Choose one question where you are absent or badly described.
Improve one existing page or write one new page that answers the missing decision with real evidence.
Add an annotation to analytics and wait three to four weeks.
Compare prompt coverage, known assistant referrals, activation, and paid conversions with the prior month.

One cycle will not prove causation. It will teach you more than a dashboard that converts every citation into a score.

If you see a repeatable lift, do another cycle. If you do not, you still made a better page. That is a decent downside for a growth experiment.

Frequently Asked

Does AI referral traffic convert better than Google organic traffic?

Often, yes. Users may arrive after receiving a recommendation and therefore have more intent. The result varies by product and volume is still small for most sites, so compare activation and paid conversion, not only click-to-signup rate.

How do I track traffic from ChatGPT or Perplexity?

Create an analytics channel group for known assistant referrers, track it monthly, and ask new users how they heard about you. Referrers are incomplete, so combine both signals.

Should I optimize only for AI search now?

No. AI citations are one discovery path. Clear product pages, original content, customer evidence, direct distribution, and ordinary SEO remain necessary, especially while AI referral volume is low.

How to Use Claude Code: A Practical Tutorial From Install to Productive

Alex Cloudstar — Thu, 22 Oct 2026 22:17:20 +0000

How to Use Claude Code: A Practical Tutorial From Install to Productive

Most Claude Code tutorials stop at "type a prompt and watch it work." That gets you through the first ten minutes. It does not get you to the point where the tool saves you real time, because that depends on a handful of habits: giving it a project file to read, checking its plan before it edits, and knowing which commands keep a long session healthy.

I have used Claude Code daily since it launched in 2025, on side products and client work. This is the tutorial I would hand to a developer who has never opened it. Everything here is checked against the official docs on October 23, 2026, and I mark the places where behavior changes by plan or install method.

How to Use Claude Code: The Short Answer

To use Claude Code, install it with the native installer (curl -fsSL https://claude.ai/install.sh | bash on macOS, Linux and WSL), run claude in a project folder, and sign in with a paid Claude plan or Console account. Describe a task in plain English, review each proposed edit, and approve what looks right.

The rest of this post expands each step: the install options per operating system, what to type in your first session, how permissions work, and which settings are worth changing early.

What Claude Code Is (and What It Is Not)

Claude Code is Anthropic's agentic coding tool. It reads your codebase, edits files, runs commands and works with git. It started as a terminal CLI and now also runs in VS Code, JetBrains IDEs, a desktop app and the browser. All of those surfaces use the same engine, so your CLAUDE.md files, settings and MCP servers carry across them.

The terminal is where I spend most of my time, so this guide follows the terminal path. If you prefer a graphical interface, the desktop app includes Claude Code and does not need the CLI installed separately. The VS Code extension also installs into Cursor.

It is not an autocomplete tool. It does not suggest the next line as you type. You give it a task, it explores the repo, proposes changes, and you decide what lands. If you are still choosing between tools, my Claude Code vs Cursor vs GitHub Copilot comparison covers where each one wins.

How to Install Claude Code

The official docs recommend the native installer. It needs no Node.js, and it auto-updates in the background.

Method	Command	Auto-updates
Native, macOS, Linux, WSL	`curl -fsSL https://claude.ai/install.sh \	bash`
Native, Windows PowerShell	`irm https://claude.ai/install.ps1 \	iex`
Native, Windows CMD	`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`	Yes
Homebrew	`brew install --cask claude-code`	No
WinGet	`winget install Anthropic.ClaudeCode`	No
npm	`npm install -g @anthropic-ai/claude-code`	See note below

A few details that save you a debugging session:

PowerShell vs CMD. The two Windows commands are not interchangeable. If you see The token '&&' is not a valid statement separator, you ran the CMD command in PowerShell. If you see 'irm' is not recognized, you ran the PowerShell command in CMD. Your prompt shows PS C:\ in PowerShell.
Git for Windows. It is recommended on native Windows so Claude Code can use the Bash tool. Without it, Claude Code uses PowerShell as its shell tool. WSL setups do not need it.
Homebrew has two casks. claude-code tracks the stable channel, usually about a week behind. claude-code@latest gets releases as soon as they ship. Upgrade with brew upgrade claude-code or brew upgrade claude-code@latest.
npm needs Node.js 22 or later. The package installs the same native binary as the standalone installer. Never use sudo npm install -g, since it causes permission problems. To upgrade, run npm install -g @anthropic-ai/claude-code@latest.
Linux package managers. apt, dnf and apk repositories exist for Debian and Ubuntu, Fedora and RHEL, and Alpine. They do not auto-update through Claude Code.
Requirements. macOS 13.0 or later, Windows 10 1809 or later, Ubuntu 20.04 or later, Debian 10 or later, or Alpine 3.19 or later, with 4 GB of RAM or more.

The install command prints no progress while it downloads. When it finishes, open a new terminal and check it worked:

claude --version

If your shell says claude is not found, the install directory is not on your PATH yet. For a deeper check, claude doctor prints installation and settings diagnostics without starting a session.

To update by hand, run claude update. Native installs also update themselves on startup and periodically while running.

Log In and Pick a Plan

Run claude in any folder and it prompts you to sign in through your browser. Credentials are stored, so you only do this once. To switch accounts later, type /login inside a session.

You need one of these accounts:

A Claude Pro, Max, Team or Enterprise subscription
A Claude Console account (API access with pre-paid credits)
Access through a supported cloud provider: Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry

The free claude.ai plan does not include Claude Code. That is the single most common reason a first login fails.

Prices I confirmed on claude.com/pricing today: Pro is $20 per month billed monthly, or $17 per month billed annually. Max starts at $100 per month. Team standard seats are $25 per seat per month billed monthly, or $20 billed annually. Enterprise is $20 per seat per month billed annually with a 20-seat minimum, plus usage at API rates. Pricing changes often, so check the page before you commit.

Subscription plans use a rolling usage window rather than a per-token bill. If you want to understand where usage goes before you hit a limit, I wrote about it in the AI agent token cost guide.

Claude Code Tutorial: Your First Session in a Real Repo

Open a terminal in a project and start Claude Code:

cd path/to/your/project
claude

The prompt shows the version, the current model and the working directory. You do not need to feed it files. It reads what it needs as it goes.

Start by asking questions

Do not start by asking it to change anything. Ask it to explain the project first. These come straight from the quickstart and they work:

what does this project do?

explain the folder structure

where is the main entry point?

This does two jobs. You learn whether it understood the codebase, and you find gaps in your own docs. If its summary is wrong, a change request would have gone wrong too.

Then make a small change

Pick something low risk, like adding a function or a test:

add a unit test for the parseDate helper, then run it

Claude Code finds the file, shows you the proposed change, and asks before applying it. Read the diff. If it looks right, approve it. If it does not, tell it what is wrong in plain language and it revises.

Be specific. The quickstart gives a good example: instead of "fix the bug," try "fix the login bug where users see a blank screen after entering wrong credentials." The more concrete the symptom and the expected result, the fewer rounds you spend.

Use git through the conversation

It works with git directly, so these prompts are fine:

what files have I changed?

commit my changes with a descriptive message

I still read the commit message before it goes in, and I only let it push when I ask for that explicitly.

Press Shift+Tab to change how much it asks

The session's permission mode sets which actions run without asking. Shift+Tab cycles through the modes mid-session. The next two sections cover the two that matter most when you are starting out: plan mode and the default manual mode.

Plan Mode: Review the Approach Before Any Edits

Plan mode is the habit I would build first. In plan mode, Claude reads files and writes a plan but does not edit your source until you approve the plan.

Three ways to enter it:

Press Shift+Tab until the status bar shows plan mode.
Type /plan at the prompt, optionally followed by a description, such as /plan fix the auth bug.
Start a session in it with claude --permission-mode plan.

Press Shift+Tab again to leave without approving.

Use it when the change touches more than a couple of files, when you do not fully know the codebase, or when the first idea might be the wrong one. Reading a plan takes a minute. Unwinding a wrong 12-file edit takes much longer. For one-line fixes, skip it.

Write a CLAUDE.md So It Knows Your Project

Every session starts with a fresh context window. CLAUDE.md is how you carry instructions across sessions: build commands, test commands, conventions, things not to touch. Claude reads it at the start of every conversation.

The fastest way to create one:

/init

/init analyzes your codebase and generates a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting. The docs also document an interactive variant: set the CLAUDE_CODE_NEW_INIT environment variable to 1 before running /init, and it asks which artifacts to set up (CLAUDE.md files, skills and hooks).

Where CLAUDE.md files live

Scope	Location	Shared with
User	`~/.claude/CLAUDE.md`	Only you, all projects
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Your team, via git
Local	`./CLAUDE.local.md`	Only you, this project (add it to `.gitignore`)

Files in the directory tree above your working directory are loaded at launch. Files in subdirectories load on demand when Claude works with files there.

What to put in it

Treat it as a short onboarding note for a new teammate:

# Project notes

## Commands
- Install: bun install
- Test: bun test
- Lint: bun run lint

## Conventions
- TypeScript strict mode, no `any`
- Named exports only
- Server code lives in /lib, UI in /components

## Do not
- Edit generated files in /generated
- Commit .env files

Two rules from the docs are worth following. First, keep it under about 200 lines per file, since longer files consume more context and reduce how well instructions are followed. Second, be specific: "run bun test before finishing" beats "make sure things work."

You can also import other files with @path/to/file syntax, for example See @README for project overview and @package.json for npm commands. Imports organize a long file, but they do not reduce how much context it uses.

One more thing to know: CLAUDE.md is context, not enforcement. Claude treats it as guidance. If something must never happen, use a hook or a permission deny rule instead, which I cover in the level-up section below.

Claude Code also keeps its own notes, called auto memory, based on corrections and preferences it picks up. You can view and toggle it with /memory. If your repo already has an AGENTS.md for other tools, Claude Code can read that when there is no CLAUDE.md.

Slash Commands Worth Learning First

Type / to see everything available, and keep typing to filter. A slash command only works at the start of your message. These are the ones I use all the time, all from the official commands reference:

Command	What it does
`/help`	Shows help and available commands
`/init`	Generates a CLAUDE.md for the project
`/clear`	Starts a new conversation with empty context
`/compact`	Summarizes the conversation to free up context. Accepts optional focus instructions
`/model`	Switches the model. With no argument it opens a picker
`/plan`	Enters plan mode from the prompt
`/resume`	Resumes a past conversation by ID or name, or opens the picker
`/rewind`	Rewinds the conversation and/or code to an earlier point
`/diff`	Shows changes in your working tree, including Claude's edits
`/context`	Shows current context usage as a grid
`/usage`	Shows session cost, plan usage limits and activity stats. `/cost` is an alias
`/memory`	Edits CLAUDE.md files and toggles auto memory
`/permissions`	Manages allow, ask and deny rules
`/mcp`	Manages MCP server connections
`/doctor`	Runs a setup checkup and proposes fixes
`/exit`	Exits the CLI

Two of these deserve a note. /clear is the one to reach for when you switch tasks. Old context from a finished task makes the next one worse and costs you usage. /compact is for when you want to keep going in the same task but the conversation has grown long.

/rewind is the safety net. If a round of edits went the wrong way, you can roll the conversation and the code back to an earlier point instead of untangling it by hand.

Choose and Switch Models

Claude Code uses model aliases. The ones the docs list: default, best, fable, sonnet, opus, haiku, opusplan, plus sonnet[1m] and opus[1m] for a 1M-token context window.

On the Anthropic API, opus resolves to Opus 5.5, sonnet to Sonnet 5.5 and haiku to Haiku 5.5. On Pro, Max, Team and Enterprise, the default is Opus 5.5. Fable is not the default on any plan, so you have to select it.

Two ways to switch:

/model sonnet

claude --model opus

With no argument, /model opens a picker. In the picker, Enter saves your choice as the default for new sessions, and s switches for the current session only. You can also set a model key in a settings file or the ANTHROPIC_MODEL environment variable.

opusplan is a handy one for beginners. It uses Opus while you are in plan mode, then switches to Sonnet for the edits.

My rough rule: use the strongest model for planning, debugging and cross-file changes, and a faster one for small, well-defined edits. That is my experience, not a benchmark. If you want to see how the options compare on cost, my Claude Code vs Codex comparison has the plan-level numbers side by side.

There is also an effort setting. /effort accepts low, medium, high, xhigh and max, and the available levels depend on the model. Leave it alone until you have a reason to change it.

Permissions: What Claude Code Can Do Without Asking

The default mode is called Manual in the interface and default in config. Reads run freely. Edits, shell commands and network access ask for approval. Writes to protected paths such as .git, .claude, .bashrc and .mcp.json always prompt in this mode.

Here are the six modes, from the permission modes docs:

Mode	What happens
`default` (Manual)	Reads run freely, everything else asks
`acceptEdits`	Also auto-approves file edits and common filesystem commands like `mkdir`, `mv` and `cp` in your working directory
`plan`	Researches and proposes, no edits until you approve
`auto`	A classifier model reviews actions so routine prompts are skipped
`dontAsk`	Anything that would prompt is denied. Good for CI
`bypassPermissions`	Everything runs without checks. Isolated containers or VMs only

As a beginner, stay on default and plan. Move to acceptEdits once you trust it on a task you are reviewing anyway.

You can pre-approve specific commands so you stop getting asked about the safe ones. Rules live in a settings file under permissions.allow:

{
  "permissions": {
    "allow": ["Bash(npm test)"]
  }
}

Deny rules block in every mode, including bypassPermissions. Run /permissions to see and edit your rules in an interactive dialog.

Do not reach for --dangerously-skip-permissions to get rid of prompts. If the problem is prompt fatigue, look at auto mode and a tight allow list first. I go through the flag, the access ladder and a least-privilege settings.json in my coding agent permissions guide.

Headless Mode: claude -p for Scripts and Pipes

Everything so far is interactive. Claude Code also runs non-interactively with -p (print mode). It answers once and exits, which makes it easy to use in scripts and pipes:

claude -p "explain what this function does"

cat logs.txt | claude -p "summarize the errors in this log"

git diff main --name-only | claude -p "review these changed files for security issues"

A few documented flags that matter for scripts:

--output-format accepts text, json or stream-json.
--max-turns limits the number of agentic turns and exits with an error when it hits the limit.
--allowedTools lists tools that run without prompting, for example "Bash(git log *)" "Read".
--max-budget-usd stops the run once estimated spend reaches the cap. The docs note it is a client-side estimate that can differ from your bill.
claude -c -p "query" continues the most recent conversation non-interactively.

In print mode with no permission mode set, calls that need approval are denied unless you allow them. So give a headless run the specific tools it needs with --allowedTools, and do not rely on a prompt that nobody will answer.

Other shell commands from the CLI reference that you will use early: claude "task" starts a session with an initial prompt, claude -c continues the most recent conversation in the current directory, and claude -r opens the picker to resume an older one.

Level Up: Skills, Hooks, Subagents, MCP and More

Once the basics feel natural, these are the features that turn Claude Code from a helpful assistant into part of your workflow. I have a dedicated guide for each, so I will keep this section to what each one is for.

Skills package a repeatable workflow into a SKILL.md file you can invoke as a slash command. Good for things you ask for the same way every time, like a release checklist. See how to write a Claude Code skill.
Hooks run shell commands before or after Claude Code actions, such as formatting after every edit. They are also the reliable way to block an action, since CLAUDE.md is only guidance. See my Claude Code hooks guide.
Subagents are separate Claude instances with their own context and instructions, useful for side tasks like code review or searching a large codebase without filling your main conversation. See the subagents guide.
MCP (Model Context Protocol) connects Claude Code to outside tools and data, such as issue trackers and databases. You manage servers with claude mcp and /mcp. See the MCP developer guide.
Status line puts useful session info, like the model and context use, at the bottom of the terminal. See the status line guide.
Git worktrees let you run several sessions on separate branches without them stepping on each other. Claude Code supports this directly with claude --worktree (short form -w). See my git worktree guide.
Permissions are worth a second pass once you are comfortable. See the least-privilege guide.

Add these one at a time. Each one is useful on its own, and stacking five new features in a week makes it hard to tell what helped.

Common Mistakes (and How to Avoid Them)

These are the mistakes that cost the most time and usage.

Vague prompts. "Fix the tests" gives it too much room. Name the failing test, the error and what the right behavior is.

Skipping the read-only warm-up. If you ask for a change in an unfamiliar repo, you are betting the model guessed the architecture right. Ask it to explain the relevant area first, or use plan mode.

Never clearing context. One long session across five unrelated tasks gets worse as it fills up, and it costs usage. Run /clear between tasks. Use /compact when you are mid-task and the history is long.

Approving edits without reading them. The approval prompt exists so you can catch mistakes. A diff you did not read is a diff you own anyway.

Giant tasks in one prompt. "Rebuild the whole auth system" is a project, not a prompt. Break it into steps, and ideally plan first. The quickstart recommends this too: step-by-step instructions work better for complex work.

A bloated or missing CLAUDE.md. No file means it rediscovers your test command every session. A 600-line file means it follows less of it. Aim for short and specific.

Treating CLAUDE.md as a guardrail. It is guidance. Things that must not happen belong in deny rules or hooks.

Reaching for bypass mode. If the fix for annoying prompts is switching off every safety check, you have picked the wrong fix. Use an allow list or auto mode.

Using it on the wrong plan. If you plan to use it all day, test on a lower tier first, then move up if you hit limits. Check /usage to see where you stand.

Tips That Make the Daily Loop Faster

Describe the outcome, not the implementation, then refine.
Ask it to run the tests and fix what fails, so the loop closes in one prompt.
Use claude -c to pick up where you left off, and /rename to name sessions you want to find later.
Run /diff before you commit. Seeing the full change at once catches things the individual diffs hid.
Commit a lean project CLAUDE.md. It is one of the cheapest ways to improve a whole team's sessions.

Frequently Asked

How do I install Claude Code? Use the native installer. On macOS, Linux and WSL, run curl -fsSL https://claude.ai/install.sh | bash. On Windows PowerShell, run irm https://claude.ai/install.ps1 | iex. You can also use Homebrew (brew install --cask claude-code), WinGet (winget install Anthropic.ClaudeCode) or npm (npm install -g @anthropic-ai/claude-code, Node.js 22 or later). Verify with claude --version.

Is Claude Code free? No. The free claude.ai plan does not include it. You need a Pro, Max, Team or Enterprise subscription, a Claude Console account billed at API rates, or access through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. Pro is $20 per month billed monthly or $17 per month billed annually.

What is the difference between Claude Code and Claude in the browser? Claude in the browser chats with you about code. Claude Code runs on your machine, reads your repo, edits files and runs commands, with your approval. It also has a web version at claude.ai/code that runs tasks in the cloud.

What does /init do in Claude Code? It analyzes your codebase and generates a starting CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting the file.

How do I switch models in Claude Code? Type /model sonnet (or opus, haiku, fable) inside a session, run /model alone for a picker, or start with claude --model opus. You can also set a model key in settings or the ANTHROPIC_MODEL environment variable.

How do I run Claude Code in a script or CI? Use print mode: claude -p "your task". Add --output-format json for structured output, --max-turns to cap the loop, and --allowedTools to pre-approve the tools the job needs. Use claude setup-token to generate a long-lived token for CI.

How do I stop Claude Code from asking permission for everything? Add allow rules for the safe commands you run all the time, such as Bash(npm test), under permissions.allow in a settings file, or switch to acceptEdits mode for edit-heavy work. Try auto mode before bypassPermissions. Details are in my permissions guide.

Is Claude Code better than Cursor? It depends on the work. Claude Code is stronger on large multi-file tasks and autonomous runs, and Cursor is better for editor-first work. The full breakdown is in my Claude Code vs Cursor vs GitHub Copilot comparison.

Sources: code.claude.com/docs (overview, quickstart, advanced setup, CLI reference, commands, memory, permission modes, model configuration) and claude.com/pricing, all checked October 23, 2026.

Claude Code Hooks: Every Event, the Config Format and Five Working Examples

Alex Cloudstar — Thu, 22 Oct 2026 22:17:19 +0000

Claude Code Hooks: Every Event, the Config Format and Five Working Examples

A line in CLAUDE.md that says "always run the formatter after editing" works most of the time. Most of the time is the problem. The model reads the instruction, weighs it against everything else in the context, and sometimes decides this edit is too small to bother.

Hooks fix that by taking the decision away from the model. This post covers what Claude Code hooks are, every event the docs list, how to configure them, how exit codes and JSON output control Claude, and five examples you can paste into a settings file. I checked the details against the official hooks reference and hooks guide on October 23, 2026. Hooks change often, so treat the docs as the source of truth if anything here has drifted.

What Are Claude Code Hooks?

Claude Code hooks are user-defined handlers that Claude Code runs automatically at specific points in its lifecycle, such as before a tool call, after a file edit, or when Claude finishes responding. Most hooks are shell commands. Because the harness runs them, not the model, they fire every time, which makes them deterministic.

That last part is the whole point. A skill or a CLAUDE.md rule is a suggestion the model may follow. A hook is code that runs whether the model remembers it or not. If you want a rule enforced, you write a hook. If you want a rule suggested, you write a skill.

If you are still sorting out how hooks sit next to skills, plugins and MCP servers, my plugin and skills marketplace guide has the short version, and this post is the long one.

Claude Code Hook Events and When They Fire

The hooks reference lists 33 events. Each one is a key you put inside the hooks object in a settings file. These are the events as the docs list them, in the order they appear there.

Event	When it fires
`SessionStart`	A session begins or resumes
`Setup`	Started with `--init-only`, or with `--init` or `--maintenance` in `-p` mode
`UserPromptSubmit`	A prompt is submitted, before Claude processes it
`UserPromptExpansion`	A command you typed expands into a prompt, before it reaches Claude
`PreToolUse`	Before a tool call runs. Can block
`PermissionRequest`	A tool call needs a permission decision
`PermissionDenied`	Auto mode denies a tool call
`PostToolUse`	After a tool call succeeds
`PostToolUseFailure`	After a tool call fails
`PostToolBatch`	After a full batch of parallel tool calls resolves, before the next model call
`Notification`	Claude Code sends a notification
`MessageDisplay`	While assistant message text is displayed
`SubagentStart`	A subagent is spawned
`SubagentStop`	A subagent finishes
`TaskCreated`	A task is being created with `TaskCreate`
`TaskCompleted`	A task is being marked completed
`Stop`	Claude finishes responding
`StopFailure`	The turn ends because of an API error
`TeammateIdle`	An agent team teammate is about to go idle
`InstructionsLoaded`	A `CLAUDE.md` or `.claude/rules/*.md` file is loaded
`ConfigChange`	A configuration file changes during a session
`CwdChanged`	The working directory changes
`DirectoryAdded`	A working directory is added mid-session with `/add-dir`
`FileChanged`	A watched file changes on disk
`WorktreeCreate`	A worktree is being created
`WorktreeRemove`	A worktree created by a `WorktreeCreate` hook is removed
`PreCompact`	Before context compaction
`PostCompact`	After context compaction completes
`PreModelSwitch`	Before a requested model switch is applied. Can block
`PostModelSwitch`	After the session's model changes
`Elicitation`	An MCP server requests user input during a tool call
`ElicitationResult`	After a user responds to an MCP elicitation
`SessionEnd`	A session terminates

Most people need PreToolUse, PostToolUse, Stop, SessionStart and Notification. The rest cover narrower jobs like auditing config changes or reacting to compaction.

A few details from the docs that save you debugging time. PreToolUse and PostToolUse fire on every tool call in the agentic loop. Stop fires whenever Claude finishes responding, not only when the task is truly done, and it does not fire on user interrupts. And a PostToolUse hook cannot undo anything, because the tool has already run.

Where Claude Code Hooks Are Configured

Hooks live in JSON. You can put them in several places, and the entries merge across levels instead of replacing each other.

Location	Scope	Shareable
`~/.claude/settings.json`	All your projects	No
`.claude/settings.json`	Single project	Yes, committed to the repo
`.claude/settings.local.json`	Single project	No, gitignored
Managed policy settings	Organization-wide	Yes, admin-controlled
Plugin `hooks/hooks.json`	While the plugin is enabled	Yes
Skill frontmatter	The rest of the session once the skill is invoked	Yes
Subagent frontmatter	While that subagent runs	Yes

I put personal conveniences like notifications in ~/.claude/settings.json, and team rules like a formatter in the committed .claude/settings.json.

You can browse what is active by typing /hooks at the Claude Code prompt. It opens a read-only browser of your configured hooks. If a new hook does not appear after a few seconds, restart the session.

The JSON shape

Three levels: an event, a matcher group, and one or more handlers.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-bash.sh"
          }
        ]
      }
    ]
  }
}

If your settings file already has a hooks key, add the new event as a sibling of the existing ones. Each event name is a key inside the single hooks object. Overwriting the whole object is the most common way to delete a hook you forgot you had.

Hook types

The type field decides what the handler does.

command runs a shell command and passes the event JSON on stdin.
http POSTs the event JSON to a URL.
mcp_tool calls a tool on a configured MCP server.
prompt sends your prompt and the event data to a Claude model for a single-turn yes or no decision.
agent spawns a subagent that can use tools to verify a condition. The docs mark this one experimental.

Shared fields include if, timeout, statusMessage and once. Command hooks add args (exec form, no shell), async, shell and onFailure. Timeouts default to 600 seconds for command, http and mcp_tool, 30 for prompt and 60 for agent, so set timeout on anything slow.

Matchers: Choosing Which Calls a Hook Sees

The matcher field filters when a group fires. How it is evaluated depends on what it contains.

Matcher value	Evaluated as
`"*"`, `""`, or omitted	Match everything
Only letters, digits, `_`, `-`, spaces, commas and pipes	Exact string, or a list separated by pipes or commas
Any other character	JavaScript regular expression, unanchored

What the matcher is compared against depends on the event. For PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest and PermissionDenied, it is the tool name, like Bash, Edit or mcp__memory__.*. MCP tools are named mcp__<server>__<tool>, and matching every tool from one server needs the .*.

For SessionStart it is how the session started: startup, resume, clear, compact or fork. For Notification it is the notification type, such as permission_prompt or idle_prompt. UserPromptSubmit, Stop and several others take no matcher and always fire.

On tool events there is also an if field that uses permission-rule syntax, like "Bash(git *)" or "Edit(*.ts)". It holds one rule and no boolean operators. The docs call it best-effort and say to use the permission system when you need a hard allow or deny.

Exit Codes: How a Hook Blocks Claude

A command hook talks to Claude Code through its exit code, stdout and stderr.

Exit 0 means success. If stdout is a single JSON object, Claude Code reads its fields. Plain stdout is added to Claude's context only for UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch. Claude never sees stderr on exit 0.
Exit 2 is a blocking error. On events that can block, the action stops and stderr becomes the reason. Exit 2 wins even if JSON on stdout says "allow".
Any other code is a non-blocking error. The action proceeds, and the first line of stderr shows in the notice.

Which events can actually be blocked matters. By the docs, exit 2 blocks on PreToolUse, UserPromptSubmit, UserPromptExpansion, Stop, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted, ConfigChange (except policy settings), PostToolBatch, PreCompact, PreModelSwitch, Elicitation, ElicitationResult, WorktreeCreate and WorktreeRemove.

It cannot block PostToolUse, PostToolUseFailure, PermissionRequest (use a decision instead), Notification, SessionStart, SubagentStart, SessionEnd, PostCompact and the other observational events. On those, exit 2 shows stderr to you and execution continues.

One gotcha from the guide: exit 0 from a PreToolUse hook does not approve the call. The tool call still goes through the normal permission flow.

JSON output for finer control

Exit codes are blunt. If you need more, exit 0 and print one JSON object to stdout. Print only the JSON. Anything else on stdout, like output from a shell profile, breaks parsing. The docs say to pick one approach per hook: exit 2 with stderr, or exit 0 with JSON.

Universal fields are continue (set false to stop Claude entirely), stopReason, systemMessage, suppressOutput and terminalSequence. Event-specific decisions go in different places. PreToolUse uses hookSpecificOutput with permissionDecision set to allow, deny, ask or defer, plus permissionDecisionReason. PostToolUse and Stop use a top-level decision: "block" with a reason.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

A field at the wrong level is a common reason a hook silently does nothing: permissionDecision belongs inside hookSpecificOutput, not at the top.

What a hook receives and which variables it can use

Command hooks get JSON on stdin. Common fields include session_id, transcript_path, cwd, permission_mode and hook_event_name. Tool events add tool_name, tool_input and tool_use_id, which is how a script finds the file path or command Claude is about to use. SessionStart hooks also get a source, and UserPromptSubmit hooks get the prompt text.

Environment variables the docs list for hooks:

CLAUDE_PROJECT_DIR: the project root where the session started
CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA: a plugin's install and data directories
CLAUDE_PLUGIN_OPTION_<KEY>: a plugin's user-config values
CLAUDE_ENV_FILE: a file a SessionStart or CwdChanged hook can write environment variables into, which Claude Code runs as a preamble before each Bash command

Use ${CLAUDE_PROJECT_DIR} in script paths so they work from any directory.

Five Claude Code Hook Examples

These are examples, adapted from the official hooks guide. Test each in a throwaway project before you commit it to a repo your team uses.

Example 1: Get a desktop notification when Claude needs input

The Notification event fires when Claude is waiting for input or permission. This is the guide's macOS version. Put it in ~/.claude/settings.json.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

The empty matcher fires on every notification type. To narrow it, set the matcher to a type like permission_prompt or idle_prompt. The guide gives notify-send for Linux and a PowerShell variant for Windows. On macOS, if nothing appears, osascript routes through Script Editor, and the docs say to enable notifications for Script Editor in System Settings.

Example 2: Format every file Claude edits

This PostToolUse hook runs Prettier on the file Claude just wrote. It goes in .claude/settings.json in the project root.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

jq pulls the path out of the stdin JSON and Prettier does the rest. It needs jq installed. One limit the guide calls out: Claude can also change files through shell commands, which an Edit|Write matcher never sees. If your hook must see every change, add a Stop hook that checks the working tree once per turn.

Example 3: Block dangerous Bash commands

This PreToolUse hook exits 2 when a command matches a pattern you never want Claude to run. The guide's own script blocks edits to protected files with the same mechanism. I adapted it to read tool_input.command for the Bash tool.

Save this as .claude/hooks/block-dangerous.sh:

#!/bin/bash
# block-dangerous.sh (example adapted from the hooks guide's protect-files.sh)

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

BLOCKED_PATTERNS=("rm -rf" "git push --force" "DROP TABLE")

for pattern in "${BLOCKED_PATTERNS[@]}"; do
  if [[ "$COMMAND" == *"$pattern"* ]]; then
    echo "Blocked: command matches '$pattern'. Ask the user before running it." >&2
    exit 2
  fi
done

exit 0

Make it executable with chmod +x .claude/hooks/block-dangerous.sh, then register it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

Claude Code blocks the call before it runs and passes your stderr message to Claude, so it can pick another approach. Substring matching is crude. A command like rm -rf with two spaces slips past it. Treat this as a tripwire for honest mistakes, not as a security boundary, and read the next section before you rely on it.

The docs add one useful fact: a PreToolUse hook that returns a deny blocks the tool even in bypassPermissions mode or with --dangerously-skip-permissions. That is why hooks pair well with the permission setup in my least-privilege guide.

Example 4: Inject context at SessionStart

Compaction summarizes a long conversation and can lose details. A SessionStart hook with the compact matcher puts critical context back. This is the guide's version, in .claude/settings.json.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Plain text a SessionStart command writes to stdout goes into Claude's context. Swap the echo for something dynamic, like git log --oneline -5. The docs point out that if you want the same context on every session start, CLAUDE.md is the better home. Use the hook when the context is dynamic or only needed at a specific moment. Change the matcher to startup to inject on a fresh session instead.

Example 5: Run tests before Claude stops

A Stop hook can refuse to let Claude finish. This one runs the test suite and, if it fails, exits 2 with the failure output so Claude keeps working. It is an example I built from two pieces of the docs: the exit-2 behavior for Stop, and the guide's stop_hook_active check.

Save this as .claude/hooks/tests-on-stop.sh:

#!/bin/bash
# tests-on-stop.sh (example)

INPUT=$(cat)

# Stop hooks can re-trigger themselves. Bail out if we already blocked once.
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi

cd "$CLAUDE_PROJECT_DIR" || exit 0

if ! OUTPUT=$(bun test 2>&1); then
  echo "Tests are failing. Fix them before finishing:" >&2
  echo "$OUTPUT" | tail -n 30 >&2
  exit 2
fi

exit 0

Swap bun test for your own test command. Then register it:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tests-on-stop.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

The stop_hook_active guard matters. The docs say Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call in between, and the cap can be raised with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP. Because Stop fires after every response, a slow test suite will run more often than you expect. For a lighter touch, the guide shows a prompt hook on Stop that asks a model whether all requested tasks are done.

Security: Hooks Run With Your Permissions

A command hook is a shell command that runs as your user, with your environment and access to your files. There is no sandbox around it unless you build one. That has a few consequences.

Read every hook you did not write. A hook in a shared .claude/settings.json or a plugin's hooks/hooks.json runs on your machine once you trust the project or enable the plugin. Cloning a repo and accepting its settings means running its commands. The docs say project hooks in settings files and frontmatter are subject to workspace trust, and frontmatter hooks in project subagents run only after you accept the trust dialog. Treat that dialog the way you treat running an install script.

Quote your variables. The hook input contains file paths and commands the model chose. A path with a space or shell metacharacter in it will break an unquoted script or, worse, run something you did not intend. The docs recommend exec form with args for paths, and they note shell form needs careful quoting.

Do not mistake if or substring matching for enforcement. The if field is best-effort by the docs' own words. For hard rules, use permission rules and managed settings, and use hooks as one more layer.

For teams, managed settings add controls. allowManagedHooksOnly blocks user, project, local and plugin hooks, and allowedHttpHookUrls limits which URLs HTTP hooks can reach. I would also read the plugin security page in the docs before enabling any third-party marketplace, since plugin hooks run with the same authority as the ones you write yourself.

Hooks vs Skills vs Permissions vs CLAUDE.md

These four get confused because they all "tell Claude what to do". They differ in who enforces the rule.

	Hooks	Skills	Permissions	CLAUDE.md
What it is	Handlers that run at lifecycle events	Folders with a `SKILL.md` of instructions	Allow, ask and deny rules for tool calls	A markdown file of standing instructions
Who enforces it	The harness, every time	The model, when the description matches	The harness	The model, as context
Can it block an action	Yes, on events that can block	No	Yes	No
Runs code	Yes	Only through tools Claude already has	No	No
Best for	Formatting, guards, notifications, checks	Teaching a repeatable workflow	Limiting what Claude may touch	Project conventions and commands

The practical split: use CLAUDE.md for conventions, skills for workflows, permissions for the allowed surface, and hooks for anything that must happen or must not happen regardless of the model. If I find myself writing "always" or "never" in a CLAUDE.md rule and it keeps getting ignored, that rule probably wants to be a hook. I wrote about building skills in the skill developer guide.

A Notification hook is a cousin of the status line, which shows state continuously instead of alerting you once. And SubagentStart and SubagentStop let you hook into delegated work, which is covered in the subagents guide.

If a hook does nothing, run /hooks to confirm it is listed, validate the JSON (no trailing commas), check the script is executable, and make sure nothing else prints to stdout before your JSON. Pipe sample JSON into a script to test it outside a session, for example echo '{"tool_input":{"command":"rm -rf /tmp/x"}}' | .claude/hooks/block-dangerous.sh, then check echo $?.

Frequently Asked

What are Claude Code hooks? They are user-defined handlers that Claude Code runs at specific lifecycle events, such as before a tool call, after an edit, or when Claude finishes responding. Most are shell commands, and because the harness runs them, they fire every time instead of depending on the model.

Where do I put Claude Code hooks? In a settings file: ~/.claude/settings.json for all projects, .claude/settings.json for one project (committed), or .claude/settings.local.json for one project (gitignored). Plugins can ship them in hooks/hooks.json, and skills and subagents can define them in frontmatter.

How do I block a tool call with a hook? Use a PreToolUse hook. Exit with code 2 and write the reason to stderr, or exit 0 and print JSON with permissionDecision set to deny inside hookSpecificOutput. Either way, Claude Code stops the call before it runs.

Can a hook run when Claude finishes a task? Yes, with the Stop event. It fires whenever Claude finishes responding, not only at task completion, so check stop_hook_active in the input to avoid loops.

Do hooks work with --dangerously-skip-permissions? A PreToolUse hook that denies a call still blocks it in bypassPermissions mode or with that flag, according to the hooks guide. That makes hooks useful for policy people cannot switch off by changing permission mode.

Sources: Claude Code hooks reference and Automate actions with hooks (hooks guide), checked October 23, 2026.

Claude --dangerously-skip-permissions: What It Does and How to Set Up Permissions Safely

Alex Cloudstar — Thu, 22 Oct 2026 22:16:45 +0000

Claude --dangerously-skip-permissions: What It Does and How to Set Up Permissions Safely

The dangerous permission prompt is usually the convenient one.

Your coding agent asks whether it can run commands without asking again. You are halfway through a bug. You have already approved git status, bun test, and one harmless file read. You click "allow for this session" because confirming every command is annoying, and ten minutes later the agent has enough authority to install a package, read an environment file, send a request anywhere on the internet, and push a branch if you forgot what was in your shell.

Nothing bad may happen. That does not make it a good security model.

claude --dangerously-skip-permissions starts Claude Code in bypassPermissions mode. Permission prompts and safety checks are switched off, so every tool call runs immediately, including writes to protected paths like .git and .claude. Deny rules still apply. Anthropic's docs say to use it only inside isolated containers or VMs.

An agent is not just a text editor with opinions. Once it can act, its effective permission is the combination of every tool you gave it. Read access to the repo plus a shell plus your credentials plus network access is not four small permissions. It may be enough authority to inspect, modify, and send out everything the current user can reach.

The goal is not to make agents useless. The goal is to give them the narrowest set of abilities that completes the task in front of them, then widen it deliberately when the task changes.

What --dangerously-skip-permissions actually does

The flag is the same thing as claude --permission-mode bypassPermissions. Here is what the docs say about the details, checked on October 22, 2026:

Allow rules stop mattering. Everything is allowed already. Deny rules still block, which is the useful part for the setup later in this post.
A few things still prompt. Tools matched by an explicit ask rule, AskUserQuestion, MCP tools that require user interaction, and recognized rm and rmdir removals of critical paths.
Protected paths are writable. In every other mode, writes to .git, .claude, .bashrc and .mcp.json are prompted, routed to a classifier, or denied. Here they just happen.
Plan mode is not enforced. In an interactive terminal session with bypass available, Claude is still told to plan without editing, but an edit or shell command it attempts during planning runs without a prompt.
Prompt injection gets no extra protection. The docs say the mode offers no protection against prompt injection or unintended actions.
You get one warning. The first interactive session shows a dialog asking you to accept responsibility. Accepting sets skipDangerousModePermissionPrompt to true in ~/.claude/settings.json. Declining exits.
Root is refused. On Linux and macOS, Claude Code will not start in this mode as root or under sudo, unless it detects a recognized sandbox. The error reads --dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons.

The name is accurate. It is not a faster approval button. It removes the only checkpoint between a confused model and your shell, which is why the rest of this post is about narrowing what that shell can reach.

The permission modes, briefly

Claude Code has six permission modes. You set one at startup with claude --permission-mode <mode>, as a default with permissions.defaultMode in a settings file, or cycle through some of them with Shift+Tab in the terminal.

Mode	What runs without a prompt	Best for
`default` (Manual)	Reads only	Reviewing every action yourself
`acceptEdits`	Reads, file edits and common filesystem commands such as `mkdir`, `touch`, `mv`, `cp`	Iterating on code you are reviewing
`plan`	Reads	Exploring a codebase before changing it
`auto`	Everything, with background safety checks	Long tasks without prompt fatigue
`dontAsk`	Reads in working directories and pre-approved tools. Anything that would prompt is denied	Locked-down CI and scripts
`bypassPermissions`	Everything	Isolated containers and VMs only

If your problem is prompt fatigue rather than a throwaway environment, look at auto before you reach for the dangerous flag. The docs recommend it when you want far fewer prompts with background safety checks still running. It shows up in the Shift+Tab cycle only when it is available for your account.

When It's Safe: Containers, Worktrees and Throwaway VMs

The docs name the safe place directly: containers, VMs, or dev containers, ideally without internet access, where Claude Code cannot damage your host. I would put it like this.

Safe enough:

A container or dev container with only the project mounted. No home directory, no SSH keys, no cloud credentials, and ideally restricted network. This is the setup the docs use in their own example for unattended runs: claude -p "<prompt>" --dangerously-skip-permissions inside a container.
A throwaway VM you can delete afterwards, with a scoped token for the one thing it needs.
CI runners that start clean and hold nothing but the checkout and a scoped credential. See sandboxing AI-generated code execution for the isolation options.

Not safe on its own:

A git worktree. Worktrees are great for running parallel Claude Code sessions (claude --worktree feature-auth creates one under .claude/worktrees/, and my git worktree guide covers the commands). But they isolate file edits and branches, nothing else. The worktree docs are explicit that checks cover edits and git commands, and that a command like cp or a shell redirect is treated like any other shell command under your permissions and sandbox settings. A worktree still runs as you, with your network, your SSH agent and your environment variables. Use worktrees to keep sessions from colliding, not as a security boundary.
Your daily laptop. Anything reachable by your user is reachable by the agent: ~/.ssh, ~/.aws, browser profiles, every repo you have checked out.
A machine where you are logged in to production tooling. One injected instruction plus a logged-in CLI is enough.

If you want a middle ground on your own machine, Claude Code has a built-in OS-level sandbox for shell commands (turn it on with /sandbox or sandbox.enabled). It restricts which files and network domains those commands can reach, on macOS, Linux and WSL2. It covers shell commands only: Claude's file tools, MCP servers and hooks run outside it. That is a real improvement over nothing, and it is not the same as putting the whole process in a container.

The Level 7 rule from the ladder below still applies inside a container: do not put production credentials in there just because the box is disposable. A disposable environment protects your host, not the services your credentials reach.

The Permission Question Nobody Asks

Before enabling an agent, ask one question in a very literal way:

What could it read, change, execute, or send if it made the worst plausible decision while following an untrusted instruction?

That last clause matters. An agent that browses an issue, a webpage, a dependency README, or a support ticket may encounter text that tries to redirect it. It does not need to be a malicious hacker note. A misleading install command or a stale docs page can do enough damage when the agent has broad permissions.

The model cannot reliably infer a safe authorization boundary from the task alone. Research into coding-agent permission boundaries has found the same uncomfortable pattern: models can omit a permission required by a task while also granting unrelated sensitive permissions. More reasoning does not make that tradeoff disappear. Authorization needs to come from policy and tooling, not the agent's confidence.

That is just least privilege, applied to a new kind of collaborator.

The Access Ladder: Least-Privilege Access for Coding Agents

I think about agent access in seven levels. Start at the lowest level that makes the task possible. Move up only when the next level has a clear, named reason.

Level 1: Read the working tree

The agent can inspect the project files, configuration, and relevant logs. It cannot change anything.

This is enough for code review, explaining a system, making a plan, diagnosing a failing build, and locating the likely source of a bug. It is the right default when somebody asks, "What is wrong?" rather than, "Fix it."

The trap at this level is scope. Reading the repository is not the same thing as reading your whole home directory. A project folder often contains more than code: local exports, test fixtures, screenshots, customer samples, and accidentally committed secrets. Mount only the directory the task needs.

Level 2: Edit the working tree

The agent can create and change files inside the project, but it cannot run arbitrary commands.

This is suitable for a content change, a small refactor, a documentation update, or a component you will review manually. It is more powerful than it sounds. File writing can modify configuration, CI workflows, scripts, and code that runs later, so treat it as a real change permission rather than a harmless drafting permission.

Keep package manifests and CI configuration in the review scope even if the task seems unrelated. Dependency changes are code changes with a delayed execution path.

Level 3: Run a constrained local command set

The agent can run the checks that prove its change works: type checking, unit tests, a formatter, a local build, or a narrowly scoped development server.

This is where I draw the first hard boundary. bun run build and bun test are not the same category as an unrestricted terminal. Know which package manager the repository uses. Know what the scripts run. Do not assume a test command is harmless because it has the word test in it. A project script can execute migrations, call a remote service, rewrite snapshots, or do anything else a shell command can do.

Use an allowlist for predictable commands. Let the agent propose everything else. This creates a little friction, and the friction is doing work for you.

Level 4: Local browser and localhost

The agent can open the application it is running, inspect the rendered UI, and test a local flow. It cannot log into external services or browse arbitrary sites.

Visual verification belongs here. A code change that looks right in a diff can be broken in the browser. This level is still local: the agent can test localhost, capture the error, and go back to the source without carrying your authenticated browser profile along with it.

Keep the distinction between local browser access and your daily browser profile. The second one includes every active session you have forgotten about. Your inbox, GitHub, banking tab, billing dashboard, and customer admin panel are not test fixtures.

Level 5: Narrow outbound network access

The agent can reach a listed domain for a concrete reason. Maybe it needs official framework docs, a package registry, or a staging API endpoint.

The right setting is not "internet access". It is an allowlist of domains, methods, and where possible paths. An agent changing a React component does not need the ability to post to Slack, download a binary from an arbitrary release page, or call every service reachable from your laptop.

This is also where you should make a decision about package installation. Dependency installation is remote code execution from a supply chain you did not author. It may be warranted, but it deserves its own approval, a pinned version, and a look at whether a small local utility solves the problem instead.

Level 6: Source control and third-party tools

The agent can create a branch, commit code, open a pull request, read an issue tracker, or call an MCP server.

Give read and write access separately. Reading a GitHub issue does not require pushing to main. Reading a calendar does not require creating an event. Searching a CRM does not require exporting every contact.

This is where tool design becomes access control. In my guide to agent tool design, I argued that tool schemas need to state what they do and when not to use them. Permissions need the same clarity. A tool called manage_repository is a permission accident waiting to happen. create_pull_request_from_current_branch is a much narrower promise.

If a tool offers a write action, make the write target visible before it runs. The model should not be the only place where the difference between reading a record and deleting it exists.

Level 7: Deployments, customer data, and production

The agent can affect real users or access secrets.

This is not a normal default. It should be an exceptional, task-specific permission with a human confirmation at the final boundary. A staging deployment is not production. A read-only production query is not a write. A token that may access one test project is not a token that can access every customer account.

The word "production" hides too much. Break it down into deploy, read logs, read metrics, read data, write data, rotate credentials, and change infrastructure. An agent may need exactly one of those. Giving it the bundle because a dashboard offers one API key is a design failure, not a necessity.

Secrets Are Not Agent Input

The cleanest rule I have found is this: agents need access to a capability, not the secret that represents it.

Do not paste API keys into prompts. Do not let the agent print environment files to prove it found the configuration. Do not attach a production .env to a context window. Once a secret becomes model input, you have widened the exposure from a process boundary to every system that handles the conversation.

Use short-lived, scoped credentials injected into the execution environment. Prefer a service identity that can call one staging endpoint over your own personal token. Rotate the credentials when the task finishes if they were minted for it. Log the action, but never log the secret.

This is less dramatic than it sounds. Most of the time it means creating a narrower token once instead of reusing the convenient admin token forever.

A Permission Set Should Expire

Long-lived approval is where convenience turns into permission creep.

The task that needed package registry access last Tuesday does not prove the next task needs it. The temporary database credential that made a migration review easier does not belong in a reusable configuration. Agents are unusually good at turning a small convenience into a repeated action because they follow the environment we leave behind.

Make permission state part of the cleanup:

remove temporary tokens
stop local servers
revoke network exceptions
remove copied fixtures containing customer data
review changed workflow files and package manifests
record what the agent was allowed to do when it mattered

That last point helps incident response and ordinary debugging. When a surprising change lands, you want to know whether the agent could have made it, not reconstruct the answer from a vague chat transcript.

Claude Code Permissions: A Recommended settings.json

Here is a starting point I would use for ordinary application work, not a copy of any one machine's config. It follows the ladder: reads and local checks are allowed, installs and pushes need a decision, secrets and network downloads are blocked.

{
  "permissions": {
    "allow": [
      "Bash(bun run test *)",
      "Bash(bun run typecheck)",
      "Bash(bun run lint *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)"
    ],
    "ask": [
      "Bash(bun add *)",
      "Bash(bun install *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  }
}

Save it as .claude/settings.json in the project to share it with the team, or in ~/.claude/settings.json for your own defaults. Swap bun for your package manager and adjust the script names to match your package.json.

A few things to know before you rely on it:

Order matters. Rules are evaluated deny first, then ask, then allow, and the first match wins. A broad deny can't be carved out by a narrower allow.
Deny survives bypass mode. Even with --dangerously-skip-permissions, deny rules still block. If you must run in bypass mode inside a container, a deny list like this is your remaining safety net.
The * placement matters. Put it after the subcommand. Bash(git log *) allows git log commands only, while Bash(git *) allows every git command.
Bash patterns are not a hard boundary. The docs warn that Bash rules that constrain arguments are fragile, and that a deny on curl does not match /usr/bin/curl or sh -c 'curl ...'. For network restrictions that must hold, pair deny rules with the sandbox network allowlist.
Read deny rules cover Claude's file tools and recognized file commands like cat and head. They do not stop a script that opens the file itself. A .env you really need protected should not be on the machine.
There is no .claudeignore. Per the docs, it has no effect. Use Read deny rules.
Precedence is deny-wins across scopes. If user settings allow something and project settings deny it, it is denied. Managed settings sit on top of everything.

For other agents, the same ideas apply even though the syntax differs: allowlist the checks, make installs and pushes explicit, and keep secrets out of reach. Securing AI agents in production goes deeper on the production side.

The Default Setup I Would Use Today

For ordinary application work, I would start an agent with project-only file access, edit permission, a small allowlist of local checks, and localhost browser access. No external browser profile. No arbitrary network. No deployment. No production data. No Git write access until the change has passed review.

Then I would grant more only in response to a need I can name. "It needs to read the official Next.js documentation" is a reason. "It might be useful" is not.

That setup does not prevent every bad outcome. Nothing does. It reduces blast radius, makes approvals meaningful, and keeps one confused instruction from becoming a company-wide event.

An agent that must ask before doing something consequential is not less autonomous in the way that matters. It is working inside a boundary you understand.

Frequently Asked

Is --dangerously-skip-permissions safe? Not on a normal development machine. It turns off permission prompts and safety checks, and the docs say it gives no protection against prompt injection. It is reasonably safe inside a container or throwaway VM that holds only the project and a scoped credential, with deny rules still in place. Anything the agent can reach from there, it can use.

How do I turn off --dangerously-skip-permissions? Exit the session and start Claude Code again without the flag, or with claude --permission-mode default. If you made it the default, remove "defaultMode": "bypassPermissions" from your user settings. To see the warning dialog again, remove skipDangerousModePermissionPrompt from ~/.claude/settings.json. Administrators can block the mode for everyone with "permissions": { "disableBypassPermissionsMode": "disable" } in managed settings, and claude --restricted refuses it (v2.1.248 or later).

What is the difference between --dangerously-skip-permissions and auto mode? Both reduce prompts. Bypass mode removes the checks entirely. Auto mode runs background safety checks on actions and only prompts when needed. Anthropic's docs point to auto mode when you want fewer prompts without giving up the checks.

Do deny rules still work with --dangerously-skip-permissions? Yes. The docs say deny rules still block in bypass mode and allow rules have no effect. Tools matched by an explicit ask rule still prompt too. That is why a deny list for secrets and pushes is worth keeping even in a container.

Why does Claude refuse --dangerously-skip-permissions as root? On Linux and macOS, Claude Code refuses to start in this mode as root or under sudo, because root makes a mistake far more destructive. The check is skipped inside a recognized sandbox. The docs recommend their dev container, which runs as a non-root user.

Should a coding agent have access to my .env file? Usually no. Give it the required capability through a scoped, temporary environment instead. Secrets should not be copied into prompts, logs, or model context.

Is it safe to enable unrestricted terminal commands for a coding agent? Only in an isolated environment with no sensitive files, credentials, or broad network access. In a normal development machine, allow predictable checks and require approval for the rest.

Can I let an agent deploy to production? Only for a tightly defined deployment path with a final human confirmation, scoped credentials, and clear rollback. Deployment access should not imply access to production data or infrastructure administration.

Git Worktree Guide: Parallel Branches and Claude Code

Alex Cloudstar — Thu, 22 Oct 2026 22:16:44 +0000

Switching branches in the middle of a task is annoying. You stash, you checkout, you fix the thing, you checkout back, you pop the stash and hope. Git worktrees remove that whole loop, and since AI coding agents arrived they have become the standard way to run several of them at once without collisions.

I touched on worktrees in my post on git tricks that save my day. This is the full version.

What is a git worktree?

A git worktree is an extra working directory linked to the same repository. Each worktree has its own checked-out branch, files and index, but they all share one .git history, so commits, branches and remotes are visible everywhere. You can work on two branches at the same time, in two folders, with no stashing.

The main checkout you cloned is the main worktree. Every extra one is a linked worktree. The official manual describes the linked worktree as sharing the repository with the main one, except for per-worktree files such as HEAD and index.

How do you use git worktree? Commands reference

This is the synopsis from the git-worktree manual, trimmed to what you use day to day.

Command	What it does
`git worktree add <path> [<commit-ish>]`	Create a linked worktree at the path and check out the commit-ish
`git worktree list`	Show the main worktree first, then each linked one
`git worktree remove <worktree>`	Delete a linked worktree directory and its admin data
`git worktree prune`	Clear admin data for worktrees whose directories are gone
`git worktree move <worktree> <new-path>`	Move a linked worktree to a new location
`git worktree lock <worktree>`	Protect a worktree from pruning, moving or deleting
`git worktree unlock <worktree>`	Undo a lock
`git worktree repair`	Fix links that broke after you moved a directory by hand

git worktree add

git worktree add ../project-hotfix hotfix/login-bug
git worktree add -b feature-x ../project-feature-x main
git worktree add -d ../scratch

The first line checks out an existing branch in a new folder. The second creates a new branch feature-x from main. The third creates a worktree with a detached HEAD, which is handy for throwaway experiments.

Useful add options from the manual:

Option	Effect
`-b <new-branch>`	Create a branch. Refuses if it already exists.
`-B <new-branch>`	Create the branch, or reset it to the commit-ish if it exists
`-d`, `--detach`	Detached `HEAD`
`--orphan`	Empty worktree and index on a new unborn branch
`--lock`	Lock the worktree at creation (add `--reason` for a note)
`--no-checkout`	Skip checkout, for example to set up sparse-checkout first
`--track`, `--no-track`	Control upstream tracking when creating a branch

If you leave out the commit-ish and pass no -b, -B or --detach, git names the new branch after the basename of the path, creating it from HEAD if it does not exist. There is also remote-branch guessing: if the name matches a remote-tracking branch on exactly one remote, git treats the command as add --track -b against that remote.

git worktree list

git worktree list

Output shows the path, the short commit hash and the branch, with annotations such as locked and prunable. Use -v to see lock reasons. For scripts, use git worktree list --porcelain, which the manual says has a stable format across git versions (add -z for NUL-terminated lines if paths could contain newlines).

git worktree remove and prune

git worktree remove ../project-hotfix
git worktree remove --force ../project-hotfix
git worktree prune -v

remove only works on a clean worktree (no untracked files, no modified tracked files) unless you pass --force. The main worktree cannot be removed. A locked worktree needs --force twice.

If you delete a worktree folder with rm -rf instead, git keeps its admin data in $GIT_DIR/worktrees. It cleans that up automatically after gc.worktreePruneExpire, or right away with git worktree prune. Use git worktree prune -n for a dry run and --expire to only prune entries older than a given time.

git worktree move, lock and repair

git worktree move ../project-hotfix ../hotfix
git worktree lock --reason "on external drive" ../project-hotfix
git worktree repair

Lock is for worktrees on storage that is not always mounted, such as a USB drive or network share, so a prune does not wipe their admin data. move cannot move the main worktree or a linked worktree that contains submodules. If you moved a directory manually, repair fixes the broken links. Run it inside the moved worktree, or pass the new paths from anywhere.

Git worktree vs branch vs stash

These three solve related problems and people mix them up. A branch is a pointer to commits. A worktree is a folder where a branch is checked out. A stash is a shelf for uncommitted changes.

	Branch	Worktree	Stash
What it is	A named pointer to a commit	A separate working directory	Saved uncommitted changes
Needs a checkout	Yes, one per working directory	It provides one	No
Two active at once	Not in one folder	Yes, one per folder	Not applicable
Keeps uncommitted work	No, you carry it or stash it	Yes, in its own folder	Yes, until popped
Disk cost	Almost none	A full set of files	Almost none
Best for	Organizing history	Parallel tasks, hotfixes, agents	Quick context switch

So "git worktree vs branch" is not either/or. You still need a branch for every worktree (or a detached HEAD). The worktree is what lets two branches be checked out at once. Use a stash when you have a ten-second interruption. Use a worktree when the interruption will take a while, or when you want two long-running tasks side by side.

Git worktree gotchas

You cannot check out the same branch twice. git worktree add refuses when the branch is already checked out in another worktree. --force overrides the safeguard, but I would not: two folders writing to one branch is how you lose commits. Make a new branch instead.

Dependencies are not shared. A worktree is a fresh checkout. node_modules, build output and virtualenvs are untracked, so they are not there. Run your install command in each worktree.
Untracked config is not copied. Your .env and .env.local are gitignored, so they do not appear in the new worktree. Copy them over, or script it.

Ports and databases collide. Two dev servers on port 3000 will fight. Give each worktree its own port and, if you use a local database, its own database name.

Submodules are rough. The manual says multiple checkout is still experimental, submodule support is incomplete, and it does not recommend making multiple checkouts of a superproject. remove needs --force for worktrees with submodules, and move does not work on them.

Shared and per-worktree state. Branches and tags (refs/heads/*, refs/tags/*) are shared. HEAD and the index are per worktree. So are refs/bisect/*, which means you can bisect in one worktree without disturbing another.

Config is shared by default. The repo config file applies to all worktrees. If you need per-worktree settings, such as core.sparseCheckout, enable extensions.worktreeConfig and use git config --worktree. Older git versions refuse to open repositories that use that extension.

Do not delete the folder by hand. Use git worktree remove. If you did delete it, run git worktree prune.

Does Claude Code have a worktree feature?

Yes. Claude Code has a built-in --worktree flag (short form -w). According to the Claude Code worktree docs, it creates an isolated worktree and starts the session in it:

claude --worktree feature-auth

Defaults from the docs:

The worktree is created under .claude/worktrees/<name>/ at the repo root, on a new branch named worktree-<name>.
If you omit the name, Claude generates one (the docs give bright-running-fox as an example).
New worktrees branch from the repository's default branch on the remote (worktree.baseRef is "fresh" by default). Set worktree.baseRef to "head" in settings to branch from your current local HEAD instead.
The repository needs at least one commit first.
The docs suggest adding .claude/worktrees/ to .gitignore.

You can also ask Claude mid-session to "work in a worktree" and it uses its EnterWorktree tool. You can pass a pull request to --worktree (for example claude --worktree "#1234") and it fetches that PR's head into .claude/worktrees/pr-<number>.

Two details solve gotchas from the previous section. A .worktreeinclude file at the project root, in .gitignore syntax, lists gitignored files (like .env) that Claude copies into each new worktree it creates. Dependencies are still on you: the docs tell you to install them in the new worktree, or ask Claude to.

On exit, Claude checks the worktree. A clean unnamed session removes the worktree and branch automatically. If there is work in it, Claude asks whether to keep or remove it.

If you prefer plain git, that works too, and the docs show it: git worktree add ../project-feature-a -b feature-a, then cd in and run claude.

How do you run parallel AI agents with git worktrees?

The pattern is one worktree per agent session, each on its own branch. The agents cannot overwrite each other's files because they are in different folders. You review and merge branches like any other.

A workflow that works with Claude Code:

Pick tasks that touch different files. Parallel agents on the same file still produce merge conflicts.
Start a session per task in its own worktree:

claude --worktree fix-login-bug

In a second terminal, start another:

claude --worktree add-export-csv

Let each agent work, run tests and commit on its own branch.
Review each branch as a normal pull request.
Remove the worktrees you no longer need with git worktree remove, or accept Claude's prompt on exit.

The Claude Code docs also cover subagents running in their own worktrees. Ask Claude to "use worktrees for your agents", or set isolation: worktree in a custom subagent's frontmatter. Each subagent gets a temporary worktree that is removed automatically if it finishes without changes.

Worktrees isolate file edits only. They do not isolate your machine. Agents still share ports, databases and anything outside the checkout, and the docs note that a shell command like cp writing into the main checkout is not blocked by the worktree checks. Treat permissions as a separate problem, which I cover in coding agent permissions and least privilege.

For the bigger picture on agents that run unattended, see background AI coding agents. If you run several sessions, a status line that shows the model, context and branch helps you tell them apart. I wrote a Claude Code status line guide for that.

When should you not use a worktree?

The task is a two-minute detour. A stash is faster.
The repo is huge and a second full checkout is expensive on disk or install time.
The project uses submodules heavily, given the manual's warnings.
Your parallel tasks all touch the same files. You will pay the setup cost and still hit conflicts.

Frequently Asked

What is a git worktree? A linked working directory attached to the same repository, with its own checked-out branch and index. It lets you have several branches checked out at once in different folders.

What is the difference between git worktree and git branch? A branch is a pointer to a commit. A worktree is a folder where a branch is checked out. You need a branch (or detached HEAD) per worktree, and worktrees let multiple branches be active at the same time.

What is the difference between git worktree and git clone? A clone copies the whole repository, history included. A worktree shares the existing repository's history, so it is cheaper, and branches and commits show up in every worktree immediately.

How do I list git worktrees? Run git worktree list. Add -v for lock reasons, or --porcelain for stable machine-readable output.

How do I delete a git worktree? Run git worktree remove <path>. It refuses if there are untracked or modified files unless you add --force. If you already deleted the folder, run git worktree prune.

Can I check out the same branch in two worktrees? Not by default. Git refuses, and --force overrides the check. Create a new branch for the second worktree instead.

Does Claude Code support git worktrees? Yes. Use claude --worktree <name> (or -w) to start a session in a new isolated worktree under .claude/worktrees/. Subagents can also run in their own worktrees with isolation: worktree.

How do I run multiple Claude Code sessions at once? Start each one with claude --worktree and a different name, in separate terminals. Each gets its own folder and branch.

Are node_modules shared between worktrees? No. A worktree is a fresh checkout, so install dependencies in each one.

Does a worktree include my .env file? No, because it is untracked. With Claude Code, list such files in a .worktreeinclude file and Claude copies them into worktrees it creates.