DEV Community: Nishil Bhave

Claude Code Context Window Size: 200K vs 1M, What Fills It

Nishil Bhave — Tue, 04 Aug 2026 15:49:42 +0000

The first time I paid attention to my context window, it was because Claude Code compacted itself in the middle of a refactor and forgot a convention I had explained twenty minutes earlier. My first instinct was to blame the model. My second was to actually look.

What I found was worse and more useful: a meaningful slice of the window was already spent before I typed a single character. Not on my code. On my own configuration.

That is the part nobody puts in the answer. Search for "Claude Code context window size" and you get a number. The number is the least interesting thing about it.

Key Takeaways

Claude Code's context window is 200,000 tokens on most models and 1,000,000 tokens on Sonnet 5, Opus 4.6 and later, Sonnet 4.6, and Fable 5. On the Anthropic API, Sonnet 5 always runs at 1M with nothing to configure, and it is what the sonnet alias resolves to. The ceiling is rarely your problem. Your startup footprint is: in my own install, roughly 18,000 tokens of system prompt, CLAUDE.md, memory, and skill descriptions load before my first prompt. Run /context to see yours, and treat installed skills as a recurring tax rather than free capability.

How big is the Claude Code context window?

Claude Code's context window is 200,000 tokens by default, and 1,000,000 tokens on Fable 5, Sonnet 5, Opus 4.6 and later, and Sonnet 4.6.

Anthropic's own framing is the useful one here: more context is not automatically better. As token count grows, accuracy and recall degrade, a failure mode Anthropic calls context rot. Curating what sits in the window matters at least as much as how much room it has.

Three details matter more than the headline number.

On the Anthropic API, several models are always at 1M. Fable 5, Sonnet 5, and Opus 4.7 and later run with the million-token window as their normal state, not as an upgrade you enable. Sonnet 5 is the sharpest case: there is no 200K variant, no [1m] suffix to select, and no usage credits required on any plan.

Auto-compaction fires before the window fills, not when it does. Sonnet 5 sessions compact at about 967,000 tokens by default. You can move that with the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable. The gap between the ceiling and the trigger is the reserved buffer, and /context shows it to you as its own slice.

Two configurations quietly drop Sonnet 5 back to 200K. If ANTHROPIC_BASE_URL points at an LLM gateway, Claude Code cannot verify 1M support, so it budgets 200K and compacts there instead. Select "Sonnet 5 (1M context)" in the model picker to get the full window back. Setting CLAUDE_CODE_DISABLE_1M_CONTEXT=1 does the same thing on purpose, for deployments that need a hard cap.

Haiku 4.5 is the outlier that stays at 200K with no extended option.

What model does Claude Code use by default?

For most accounts, Claude Code's recommended model is Sonnet, and on the Anthropic API that alias resolves to Sonnet 5. That is the practical answer to the question people actually search for, and it is why the 1M window is now the common case rather than the exception.

The mechanics underneath are worth knowing, because "default" means two different things in Claude Code. The default option in the model picker is not itself a model. It is a special value that clears any override and reverts to the recommended model for your account type, or to an organization default if an admin has set one. The sonnet alias, by contrast, always points at the newest Sonnet your provider offers.

The full alias list:

Alias	What it selects
`default`	Clears overrides, reverts to the account or organization default
`best`	Fable 5 where your org has access, otherwise the latest Opus
`fable`	Claude Fable 5, for the hardest and longest-running tasks
`sonnet`	Latest Sonnet, for daily coding
`opus`	Latest Opus, for complex reasoning
`haiku`	Fast and cheap, for simple tasks
`sonnet[1m]` / `opus[1m]`	The 1M context variant
`opusplan`	Opus during plan mode, then Sonnet for execution

Alias resolution is provider-specific, which trips people up more than it should:

Provider	`opus`	`sonnet`
Anthropic API	Opus 5	Sonnet 5
Claude Platform on AWS	Opus 5	Sonnet 4.6
Amazon Bedrock, Google Cloud	Opus 5	Sonnet 4.5
Microsoft Foundry	Opus 4.6	Sonnet 4.5

So the same /model sonnet gives you a 1M window on the Anthropic API and a 200K default on Bedrock. If your context math suddenly stops adding up after a provider change, start here.

Version floors bite too. Opus 5 needs Claude Code v2.1.219 or later, and Sonnet 5 needs v2.1.197. If a model is missing from your picker, run claude update before debugging anything else.

You can set the model four ways, in precedence order: /model <alias> during a session, claude --model <alias> at startup, the ANTHROPIC_MODEL environment variable, or the model field in your settings file. Since v2.1.153, picking in /model saves your choice as the default for new sessions; press s in the picker to change it for the current session only.

One correction worth making, because it circulates constantly: none of this requires a Max plan. Claude Code's entry point is Claude Pro at $20 per month, and the ladder runs Pro $20, Max 5x $100, Max 20x $200.

the full plan and rate-limit breakdown, including which tier suits sustained agentic work

What actually fills the window before you type

Here is the part I care about. Before your first prompt, Claude Code has already loaded the system prompt, your CLAUDE.md files, auto memory, MCP tool names, and a description for every installed skill.

Anthropic publishes a reference session with representative token counts, and they label those numbers as representative rather than measured, so treat them as a shape rather than a spec: system prompt 4,200, project CLAUDE.md 1,800, auto memory 680, user CLAUDE.md 320, skill descriptions 450, environment info 280, MCP tool names 120. That is roughly 7,850 tokens before anything happens.

Then I measured my own install, on the machine I write these posts on. Character count divided by four, which is a rough English approximation rather than a real tokenizer pass, so read these as the right order of magnitude and not to the digit:

78 installed skills (74 user-level, 4 repo-level): about 9,200 tokens of names and descriptions
Project CLAUDE.md: about 2,338 tokens across 103 lines
Auto memory (MEMORY.md): about 2,205 tokens
Seven configured MCP servers, contributing tool names only, because full schemas are deferred by default

Add Anthropic's figure for the system prompt and environment block and my startup footprint lands near 18,000 tokens. On a 200K window that is roughly 9% gone before I say hello. On 1M it is under 2%, which is genuinely the strongest practical argument for the bigger window.

The skill count is the lever almost nobody pulls. Every installed skill puts its description into context at session start so the model knows the skill exists, whether or not you ever invoke it. Going from eight skills to seventy-eight is not a free expansion of capability; it is a standing charge on every session you will ever start.

Two documented fixes exist and both are underused. For skills you invoke by name and never want auto-triggered, set disable-model-invocation: true in the skill's frontmatter. For skills you did not write and cannot edit, skillOverrides in settings does the same thing. Either way the description stops loading until you ask for it.

How do I check my own context usage?

Everything above is a shape. Your install is the only thing that matters, and /context is the command that tells you:

/context

It prints a live breakdown by category, names which CLAUDE.md and auto memory files actually loaded, offers optimization suggestions, and shows the reserved autocompact buffer as its own slice. It is the single highest-value command in Claude Code that most people have never run.

Three companions are worth the muscle memory. /usage reports session cost and, on a paid plan, attributes recent usage to skills, subagents, plugins, and individual MCP servers, flagging anything that accounts for 10% or more. /mcp shows per-server cost and lets you disable servers you are not using. /memory opens the memory files for editing.

If you want the number in front of you permanently, the status line can display context usage continuously, which beats remembering to check.

How does a real session consume the window?

Anthropic's reference session is a useful walkthrough because it accounts for the things you never see. Four file reads, two path-scoped rules loading automatically alongside matching files, a grep, two edits, a prettier hook firing after each one, a test run, a subagent, and a couple of slash commands. Total: about 22,225 tokens.

Two things jump out of that shape.

The first bar is the biggest single contributor and you did not cause it. Startup is 35% of the session's total context here, and in my own install it would be closer to half.

The subagent bar is almost invisible, and that is the point. It read three files in its own context window and returned a 420-token summary. Had those reads happened in the main conversation they would have cost several thousand tokens that never come back. This is the single most effective context lever Claude Code gives you.

how to structure subagent delegation so verbose work stays out of your main context

What happens when the context window fills up

Claude Code does not fail when you hit the limit. It clears older tool outputs first, then summarizes the conversation if that is not enough. Your requests and key code snippets survive. Detailed instructions from early in the conversation frequently do not, which is exactly the failure I opened this post with.

There is a wrinkle here that explains a lot of model-to-model difference in long sessions. Sonnet 5, Sonnet 4.6, Sonnet 4.5, and Haiku 4.5 have context awareness: the API injects their remaining token budget into every request, so they can pace a long task against the room that is actually left. Opus 4.7 and later, plus Fable 5, do not get those injected tags. If a Sonnet session feels like it starts wrapping up as the window fills while an Opus session keeps going regardless, that is why, and it is automatic on both sides rather than anything you configure.

What survives compaction is documented precisely, and the table is worth memorizing:

Mechanism	After compaction
System prompt and output style	Unchanged, never part of message history
Project-root CLAUDE.md, unscoped rules	Re-injected from disk
Auto memory	Re-injected from disk
Rules with `paths:` frontmatter	Lost until a matching file is read again
Nested CLAUDE.md in subdirectories	Lost until a file in that subdirectory is read again
Invoked skill bodies	Re-injected, capped at 5,000 tokens per skill and 25,000 total, oldest dropped first
Hooks	Unaffected, they run as code rather than context

The two "lost" rows explain most mystery regressions. A path-scoped rule loads into message history when its trigger file is read, so compaction summarizes it away with everything else. If a rule genuinely must survive, drop the paths: frontmatter or move it into the project-root CLAUDE.md.

The skill-truncation row has a practical consequence too: truncation keeps the start of the file, so the most important instructions belong near the top of any SKILL.md you write.

One failure mode to recognize. If a single file or tool output is large enough that context refills immediately after each summary, Claude Code stops auto-compacting after a few attempts and shows a thrashing error rather than looping forever. That is a signal to /clear and change approach, not to retry.

You can also get ahead of it. /compact focus on the auth bug fix keeps what you choose instead of what the automatic pass guesses, and a "Compact Instructions" section in CLAUDE.md sets that preference permanently.

Does the 1M context window cost extra?

Per token, no. The 1M context window uses standard model pricing with no premium for tokens beyond 200K. That is a genuine difference from how long-context pricing has worked elsewhere, and it is easy to miss.

Availability is the part that varies:

Plan	Opus with 1M	Sonnet 4.6 with 1M
Max, Team, Enterprise	Included with subscription	Requires usage credits
Pro	Requires usage credits	Requires usage credits
API and pay-as-you-go	Full access	Full access

Sonnet 5 sidesteps the table entirely: on the Anthropic API it runs at 1M on every plan with no credits required.

The cost that does scale is recurring, and this is where a bigger window quietly gets expensive. Claude Code sends your full conversation with every request, and each tool use sends another request carrying that history. Prompt caching means you re-read it at cached rates rather than full price, but cached is not free. A one-line question in a session that has been open all day still draws usage for the entire conversation.

Cache misses make it worse. Your first message after a break longer than the cache lifetime reprocesses everything at full price. That lifetime is an hour on a subscription, and five minutes on an API key, a cloud provider, or once you are drawing on usage credits.

So the honest framing is this: 1M does not make long sessions cheap. It makes them possible. /clear remains free, and /compact is itself a large request because it has to read the conversation it summarizes.

Seven levers that actually reclaim context

In rough order of how much they return for the effort:

/clear between unrelated tasks. Costs nothing and returns everything. Use /rename first if you might want the session back via /resume.
Delegate verbose reads to subagents. Log processing, documentation fetches, wide codebase exploration. The output stays in their window; a summary comes back to yours.
Trim your skills. disable-model-invocation: true for skills you always invoke by name, skillOverrides for skills you did not write. This was worth roughly 9,000 tokens per session in my install.
Keep CLAUDE.md under 200 lines. Anthropic's own guidance. Workflow-specific detail belongs in skills, which load on demand, rather than in a file that loads every session regardless of what you are doing.
Prefer CLI tools over MCP servers. gh, aws, gcloud, and sentry-cli add no per-tool listing at all. MCP schemas are deferred by default, but names still cost something, and /mcp will show you which servers are worth keeping.
Preprocess with hooks. A PreToolUse hook that greps a log for ERROR before Claude sees it turns tens of thousands of tokens into hundreds.
Write specific prompts. "Improve this codebase" triggers broad scanning. "Add input validation to the login function in auth.ts" does not.

configuring MCP servers, including tool search and per-server context cost

exploring before editing, which keeps file reads purposeful instead of speculative

Where this stops and architecture begins

Everything above is Claude Code mechanics: the numbers, the commands, the settings. It is deliberately not a theory of context design.

If you are building your own agentic system and need the patterns rather than the CLI, that is a different problem with a different shape, covering retrieval, reranking, and where accuracy degrades inside a long window.

the architecture-level patterns for designing context-limited systems, from retrieval through compaction

the 1M-context model built for long autonomous sessions, and when the extra capability pays

FAQ

How big is Claude Code's context window?

200,000 tokens by default, and 1,000,000 tokens on Fable 5, Sonnet 5, Opus 4.6 and later, and Sonnet 4.6. On the Anthropic API, Fable 5, Sonnet 5, and Opus 4.7 and later always run with the 1M window. Haiku 4.5 stays at 200K with no extended option.

What model does Claude Code use by default?

Sonnet, which resolves to Sonnet 5 on the Anthropic API. On Amazon Bedrock and Google Cloud the same sonnet alias resolves to Sonnet 4.5, and on Microsoft Foundry to Sonnet 4.5, so your default window size depends on your provider as well as your alias. Switch with /model.

How do I check how much context I am using?

Run /context for a live breakdown by category, including which CLAUDE.md and auto memory files loaded and how much is reserved for the autocompact buffer. /usage adds cost and plan-limit attribution, and /mcp shows per-server cost. You can also surface context usage continuously in your status line.

Does the 1M context window cost more per token?

No. It uses standard model pricing with no premium beyond 200K. What does scale is the recurring cost: your full conversation is re-sent with every request, at cached rates when the cache is warm and at full price after a cache miss. A bigger window raises the floor on every turn of a long session.

What gets lost when Claude Code compacts?

Your requests and key code snippets are preserved. Project-root CLAUDE.md and auto memory are re-injected from disk. Rules with paths: frontmatter and nested CLAUDE.md files are lost until a matching file is read again, and invoked skill bodies come back truncated to 5,000 tokens each and 25,000 total, oldest dropped first. Detailed instructions given early in a conversation are the most common casualty, which is why persistent rules belong in CLAUDE.md rather than in chat.

The number that matters

The ceiling is a spec. Your startup footprint is a choice, and it is the one you can actually change.

Run /context once, right now, on a project you work in daily. If the number surprises you, the fix is usually not a bigger window. It is fewer skills loaded by default, a shorter CLAUDE.md, and the habit of typing /clear when you move to something new.

Claude Code Hooks: 12 Production Patterns (and the Stop-Hook Trap)

Nishil Bhave — Tue, 04 Aug 2026 15:32:08 +0000

Anthropic's annualized run-rate revenue more than tripled year over year to $30 billion by April 2026, helped substantially by Claude Code (Fortune, 2026). And yet only 29% of developers trust AI output to be accurate, down from 40% a year earlier, while 84% use or plan to use the tools anyway (Stack Overflow Developer Survey 2025, 2025).

Claude Code hooks are how you close that gap. They sit outside the model loop, run as plain shell scripts, and either allow or block what the agent is about to do. No prompt-engineering, no vibes, just exit codes.

I've been running hooks in production for eight months across two repos. This is the working set: 12 patterns I trust, plus the one Stop-hook footgun that's currently the top-voted complaint on Hacker News.

the broader Claude Code workflow guide that hooks plug into

Key Takeaways

Hooks are deterministic shell scripts that intercept Claude Code's tool calls, they run outside the model so the agent can't talk its way past them.

Exit code 2 blocks; exit code 1 does not. Writing JSON decision: "block" to stdout from exit 0 silently fails, the #1 reported gotcha (Hacker News, 2026).

Stop hooks behave as advisory in practice: a correct block tells Claude to keep going, and users report it stopping anyway. Replace them with PostToolUse flags + PreToolUse gates if you need real enforcement.

Why Are Claude Code Hooks the Most Underrated Production Tool?

Stack Overflow's 2025 survey found 29% of developers trusting AI accuracy against 46% who actively distrust it, and 52% who either reject agents outright or keep AI pinned to autocomplete (Stack Overflow, 2025). Hooks are what change that. They turn "I hope the agent doesn't rm -rf" into a regex check that runs in 4ms.

The model can be jailbroken. Prompt instructions can be overridden by a clever tool result. Even Claude Code's own deny-rules silently stop checking once a command chains more than 50 subcommands with &&, ||, or ;. Adversa AI demonstrated the bypass by padding a blocked curl with 50 harmless true commands (Adversa AI, 2026). A hook is the layer that doesn't care what the model wants to do; it cares what's actually being executed.

The hooks reference now documents 31 event names. Nine cover the vast majority of real usage, PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, Notification, SessionStart, SessionEnd and PreCompact, and the rest are specialized hooks for narrower moments in the loop (PostToolBatch, PostToolUseFailure, PermissionRequest, Setup, WorktreeCreate, and friends) (Claude Code Hooks Reference, 2026).

Why this matters more than it looks: When 1.1M+ public GitHub repos already import an LLM SDK and 693,867 of those landed in the last 12 months alone (a 178% jump year-over-year (GitHub Octoverse 2025, 2025)) the surface area for unattended agent mistakes is now enormous. Deterministic gates are no longer optional infrastructure.

the broader agentic AI shift that makes hook discipline a baseline skill

How Does the Hook Lifecycle Actually Work?

Each hook is a shell command Claude Code spawns at a specific event, piping a JSON payload to stdin. The script reads stdin, decides, and exits. Anthropic's docs are blunt: "For most hook events, only exit code 2 blocks the action. Claude Code treats exit code 1 as a non-blocking error and proceeds with the action" (Claude Code Hooks Reference, 2026). This single line is responsible for more broken hooks than every other gotcha combined.

Every hook receives the same base payload:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/repo",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf /" }
}

The script's response is read in two ways. Exit code is checked first. Then, for PreToolUse only, Claude Code parses stdout for a hookSpecificOutput JSON object that can return permissionDecision: "allow" | "deny" | "ask" | "defer" plus an updatedInput payload to rewrite the tool call before it runs. Other events use a top-level decision: "block" field with a reason string fed back to the model.

Hooks are configured in ~/.claude/settings.json (user-wide), .claude/settings.json (project, checked in), or .claude/settings.local.json (project, gitignored). Project settings override user. Plugin hooks override both. A starter PreToolUse entry looks like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 ~/.claude/hooks/guard.py" }]
      }
    ]
  }
}

why deterministic context layers like hooks beat in-prompt instructions

Which Claude Code Hooks Stop Dangerous Commands? (Patterns 1–4)

Sonatype detected 34,319 new open-source malware packages in Q3 2025 alone (a 140% jump quarter over quarter) and its Repository Firewall blocked 110,270 attacks in the same window (Sonatype, 2025). The validation patterns below are how you stop a confused agent from pip install-ing the next Shai-Hulud worm into your repo.

Pattern 1: Bash deny-list. A PreToolUse hook on the Bash matcher that regex-checks tool_input.command:

#!/usr/bin/env python3
import json, re, sys
DANGER = re.compile(r"\brm\s+-rf\s+/|curl[^|]*\|\s*(ba)?sh|sudo\s|dd\s+if=|:\(\)\{")
data = json.load(sys.stdin)
cmd = data.get("tool_input", {}).get("command", "")
if DANGER.search(cmd):
    print(f"Blocked dangerous command: {cmd}", file=sys.stderr)
    sys.exit(2)  # exit 2 = BLOCK; do not use exit 1
sys.exit(0)

Pattern 2: Secret scanner on writes. Same shape, but matcher Edit|Write|MultiEdit and the regex hits AWS keys, sk-ant-… Anthropic keys, GitHub PATs, and BEGIN PRIVATE KEY blocks inside tool_input.content. Triggers the moment the agent tries to write a secret to a file, not after.

Pattern 3 (Branch protection). PreToolUse on Bash that blocks git push and git commit against main or master whenever HEAD points at a protected branch:

import json, subprocess, sys
data = json.load(sys.stdin)
cmd = data["tool_input"]["command"]
if any(x in cmd for x in ("git push", "git commit")):
    branch = subprocess.check_output(["git", "branch", "--show-current"]).decode().strip()
    if branch in ("main", "master"):
        print(f"Refusing direct write to {branch}. Open a feature branch.", file=sys.stderr)
        sys.exit(2)

Pattern 4: Dependency lockdown. Same Bash matcher; intercepts npm install <pkg>, pip install <pkg>, cargo add <pkg> against an allowlist file. Shai-Hulud, the first documented self-replicating open-source worm, compromised more than 500 packages in days by spreading autonomously across registries and developer machines, and the same year brought hijackings of trusted packages like chalk and debug (Sonatype State of the Software Supply Chain, 2026). An allowlist hook is the cheapest mitigation that exists.

What broke before I added Pattern 1: Claude Sonnet 4.5, on a session where I was tired and accept-edits was on, generated a find . -name "*.tmp" -delete that picked up a .tmp directory I'd been using as scratch storage. Eight hours of CSV exports gone. The deny-list regex took 12 minutes to write and would have caught it.

the codebase audit skill that pairs with these guardrails

How Do You Enforce Code Quality With Hooks? (Patterns 5–7)

Anthropic's prompt caching cuts cached-input cost by 90%, which is what makes always-on quality hooks affordable to run on every edit (Anthropic API pricing, 2026). The patterns below run on the agent's output, not its input, they catch slop after the model commits to it.

Pattern 5: Auto-format on save. PostToolUse matcher Edit|Write|MultiEdit. Reads the touched path, runs prettier / ruff / gofmt, exits 0:

import json, subprocess, sys
data = json.load(sys.stdin)
path = data["tool_input"].get("file_path") or data["tool_input"].get("notebook_path")
if not path: sys.exit(0)
ext = path.rsplit(".", 1)[-1]
fmt = {"py": ["ruff", "format"], "js": ["prettier", "-w"], "ts": ["prettier", "-w"], "go": ["gofmt", "-w"]}.get(ext)
if fmt: subprocess.run(fmt + [path], check=False)
sys.exit(0)

Pattern 6 (Test gating). Block any non-test Bash command if the test suite is currently red. Implemented as a PreToolUse matcher Bash that reads .claude/tests-passing (touched by your CI hook on green) and exits 2 if missing.

Pattern 7: Structured output capture. PostToolBatch, which fires after a full batch of parallel tool calls resolves, writes a summarized JSON record per batch into .claude/runs/<session_id>.json. Useful when a long agent run does 80 tool calls and you want a machine-readable replay later. Combine with the audit pattern below for full traceability.

Can Hooks Cap a Runaway Agent's Costs? (Patterns 8–10)

One developer's eight-month Claude Code run consumed 10 billion tokens, which would have cost more than $15,000 at API list rates against roughly $800 on a Max plan (Morph, 2026). A subscription absorbs that, but it does not make the underlying burn visible, and it does not stop an agent from spending your weekly limit in an afternoon. Hooks are the only place you can put a hard ceiling on that without changing the model's behavior. The three patterns below cover notifications, session priming, and a cost circuit breaker I haven't seen anyone else publish.

Pattern 8: Notification routing. Notification event hook that pipes Claude Code's permission prompts to ntfy.sh, a Slack webhook, or osascript -e 'display notification …' on macOS. Useful when you walk away from a long run and don't want to come back to a session blocked on a 30-second-old "Approve Bash?" prompt.

import json, subprocess, sys
data = json.load(sys.stdin)
msg = data.get("message", "Claude Code needs attention")
subprocess.run(["osascript", "-e", f'display notification "{msg}" with title "Claude Code"'])
sys.exit(0)

Pattern 9: SessionStart context loading. Inject git status, recent commits, and failing test output into the agent's context the moment a session opens, via the additionalContext field:

import json, subprocess, sys
log = subprocess.check_output(["git", "log", "--oneline", "-10"]).decode()
status = subprocess.check_output(["git", "status", "-sb"]).decode()
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": f"## Git\n```
{% endraw %}
\n{status}\n{log}\n
{% raw %}
```\n"
    }
}))
sys.exit(0)

The agent wakes up oriented instead of asking you what branch you're on.

Pattern 10 (Cost circuit breaker). A PreToolUse hook on Bash|Edit|Write that increments a counter in a tmp file scoped by session_id. Past N tool calls in T seconds, exit 2 with "You've made 200 tool calls in 60 seconds, please summarize and confirm direction before continuing." This forces a checkpoint instead of a $300 runaway. I've never seen this pattern documented elsewhere; it took one accidentally-billed weekend to invent it.

The hook that paid for itself in one session: I added the cost circuit breaker after a Sonnet 4.5 agent spent four hours and 8M tokens chasing a phantom test failure that turned out to be a stale lock file. The hook would have stopped it at minute 12.

durable execution patterns that complement hook-based cost control

How Do You Audit What an Agent Actually Did? (Patterns 11–12)

The 1.1M public repos using LLM SDKs and the 178% YoY jump in new ones (GitHub Octoverse 2025, 2025) tell you that audit logging is no longer a "nice to have", it's the only durable record of what an autonomous agent actually did to your code.

Pattern 11: Append-only JSONL audit log. PostToolUse matcher * that appends one record per tool call to ~/.claude-audit/<date>.jsonl. Captures timestamp, session, cwd, tool, input, and exit. Cheap insurance, disk is free, accountability isn't:

import json, sys, time, pathlib
data = json.load(sys.stdin)
log = pathlib.Path.home() / ".claude-audit" / f"{time.strftime('%Y-%m-%d')}.jsonl"
log.parent.mkdir(exist_ok=True)
with log.open("a") as f:
    f.write(json.dumps({
        "ts": time.time(),
        "session": data["session_id"],
        "tool": data["tool_name"],
        "cwd": data["cwd"],
        "input": data.get("tool_input"),
        "response": data.get("tool_response", {}).get("status"),
    }) + "\n")
sys.exit(0)

Pattern 12: SubagentStop checkpointing. When a subagent finishes (a Task tool call, a parallel review agent), SubagentStop fires with a transcript path. Hook this to extract the agent's final answer and write it to a structured location. Pairs naturally with the multi-agent review approach in the multi-agent code review skill, the SubagentStop hook is what gives you a machine-readable trail of which agent flagged what.

That transcript path is also your durable record after the session ends: where Claude Code saves conversations on disk and how to find, export, and redact the JSONL your hooks write to.

Why Claude Keeps Ignoring Your Stop Hook (the gotcha section)

A Hacker News thread titled "Tell HN: Claude 4.7 is ignoring stop hooks" hit 109 points in late April 2026 (Hacker News, 2026). The reported pattern: a Stop hook configured to block until tests pass, Claude acknowledging the block message in chat, and then the session ending anyway. There are three things going on, and only one of them is a bug.

Gotcha #1, exit code mismatch. The most common failure mode isn't the stop hook itself; it's people writing print(json.dumps({"decision": "block", "reason": "tests failing"})) and exiting 0. From the docs: stdout JSON is parsed as advisory, but only exit 2 actually blocks. Top reply on the HN thread: "Exit 2 means a blocking error. Claude Code ignores stdout and any JSON in it." Half the "stop hook ignored" reports are this.

Gotcha #2. Stop hooks are tool-result-shaped messages. When a Stop hook does block correctly, its reason is delivered to the model as something structurally indistinguishable from a tool result. Claude is RLHF-trained to resist instructions inside tool results (prompt-injection defense), so it sometimes acknowledges the block and stops anyway. This is the part that's genuinely frustrating, and it's what the HN thread surfaced. Anthropic's Claude Code team replied asking for /feedback reports but hasn't shipped a documented fix at time of writing.

Gotcha #3, the block loop. The docs are explicit about what a successful block actually does: "When you block a Stop event, Claude continues the conversation instead of stopping" (Claude Code Hooks Reference, 2026). That is the whole mechanism, and it is also the trap. A Stop hook that blocks unconditionally never lets a session end. Claude keeps working, hits Stop again, gets blocked again. You need your own guard: a counter or flag file keyed on session_id, checked before you emit decision: "block". Older hook write-ups tell you to read a stop_hook_active field for this. It is not in the current reference, so don't build on it. Own the loop guard yourself.

Two of those three are hooks behaving exactly as documented: only exit code 2 blocks, and a successful block continues the conversation rather than ending it. Gotcha #2 is the only one that's a genuine defect, which is worth knowing before you spend an afternoon debugging your own script.

The deterministic workaround. Stop being a Stop hook. Replace it with two cooperating hooks:

# PostToolUse matcher: Edit|Write|MultiEdit
# Marks the workspace as "tests required"
import pathlib, sys
pathlib.Path(".claude/tests-required").touch()
sys.exit(0)

# PreToolUse matcher: Bash
# Blocks any non-test command until tests pass
import json, pathlib, re, sys
data = json.load(sys.stdin)
cmd = data["tool_input"].get("command", "")
flag = pathlib.Path(".claude/tests-required")
if flag.exists() and not re.search(r"\b(pytest|jest|npm test|cargo test)\b", cmd):
    print("Tests required. Run pytest first; the flag clears on green.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

The model can't argue with this. It's not delivered as a chat message; it's a refused tool call. Whatever the model thinks about it is irrelevant, the Bash command never runs.

the eval mindset that makes deterministic guardrails feel natural

Watch on YouTube: Hooks in Claude Code (Anthropic)

How Do You Debug a Hook Without Losing an Afternoon?

Three commands cover 95% of debugging. Start with claude --debug: it prints every hook invocation, the exact stdin payload, the exit code, and any stderr (Claude Code Hooks Reference, 2026). If a hook isn't firing at all, you'll see it skipped here with a reason.

Second, run the hook directly from the CLI with a synthetic payload:

echo '{"session_id":"test","cwd":"'$(pwd)'","tool_name":"Bash","tool_input":{"command":"rm -rf /"},"hook_event_name":"PreToolUse"}' \
  | python3 ~/.claude/hooks/guard.py; echo "exit=$?"

Third, the in-session /hooks slash command lists every hook currently registered for the active project. If your settings file has a typo, this is where you find out.

The 30-second smoke test I run on every new hook: add print("HOOK FIRED:", data["hook_event_name"], file=sys.stderr) at the top of the script, run with claude --debug, watch for the line. If it doesn't appear, the matcher is wrong. If it appears but nothing happens, the exit code is wrong. Two minutes of work, saves an hour.

the wider Claude Code error catalogue for everything a hook isn't causing

Frequently Asked Questions

What's the difference between exit 1 and exit 2 in Claude Code hooks?

Exit code 2 is the only blocking exit code; exit 1 (and every other non-zero code) is treated as a non-blocking error and the tool call still proceeds (Claude Code Hooks Reference, 2026). Stderr is fed back to the model on exit 2 only. This is the single most common hook bug.

Can hooks see Claude's chat messages or only tool calls?

Hooks see tool calls and their inputs, plus user prompts via the UserPromptSubmit event. They don't see assistant chat output directly, only tool responses through PostToolUse. The Stop and SubagentStop events do receive last_assistant_message, so the final turn is visible, but nothing in between is. If you want to gate on what the model said rather than what it did, hooks are the wrong layer.

Are Claude Code hooks safe to share publicly via GitHub?

Project-level hooks in .claude/settings.json are checked into the repo and run on anyone's machine. Treat them like any other executable in the repo. Use .claude/settings.local.json (gitignored by default) for hooks that load secrets, point to absolute paths on your machine, or post to private webhooks.

Why do my Stop hooks work in plan mode but not auto-accept mode?

Stop-hook delivery semantics changed across Claude versions; the HN thread reporting Claude 4.7 ignoring stop hooks describes this (Hacker News, 2026). The deterministic workaround (PostToolUse flag + PreToolUse gate) works identically across modes because it doesn't rely on the model honoring a Stop message.

Do hooks work the same in Claude Code on the web vs CLI?

Hooks run server-side scripts and only fire in environments where Claude Code can spawn local processes: the CLI, the desktop app, and the IDE extensions. Claude Code on the web (claude.ai/code) doesn't currently execute local hooks; the file lives in your project but is ignored at runtime.

What to Do With This

Pick three patterns. Start with the Bash deny-list (Pattern 1), the audit log (Pattern 11), and one of the stop-hook workaround halves. Run them for a week. Then add the secret scanner and the cost circuit breaker.

The point of hooks isn't to lock the agent down, it's to remove the failure modes you're tired of worrying about, so you can let the agent run longer with fewer interruptions. Every hook you ship is one more thing you don't have to remember to check.

the next layer up, where hooks become the substrate for orchestrated subagents

Claude Scheduled Tasks: Mine Ran 8.5 Hours and Burned 60% of My Limit

Nishil Bhave — Sat, 01 Aug 2026 14:36:29 +0000

I sat down at my desk around 3:30 PM and found a scheduled task still running. It had fired at 7:31 AM that morning. The job it was supposed to do takes about three minutes.

My current session read 60% used. The weekly "all models" bar read 16%. I had not touched Claude all day.

My first instinct was that someone else was on my account. That turned out to be wrong, and the real answer was more interesting: my own scheduled task had been stuck in a loop for eight and a half hours, re-writing the same paragraph, because the thing running it would not accept "I'm done" as an answer.

Here's the full chain, the receipts I used to trace it, and the checklist I'd give anyone running unattended agents.

Key Takeaways

A daily scheduled task on Claude Opus 5 ran from 7:31 AM to roughly 4:02 PM instead of its usual three minutes.
Root cause: the task called Gmail and Calendar tools that were approval-gated. A scheduled run is unattended by definition, so nobody was there to approve. The run was dead on arrival, every single morning.
The expensive part was not the failure, it was the retry. The model correctly concluded "run failed" and stopped. The scheduler re-prompted it anyway, dozens of times, and every iteration re-sent the entire growing transcript.
Pressing stop did not stop it. When I finally found the run and hit Claude's stop button, it carried on regardless.
It ended wedged on API Error: 400 messages.56: user messages must have non-empty content, a state that "Try again" can never clear.
This cost a limit window, not money. Weekly limits reset. The account's usage-credit meter read $0.00 that same evening.
There is no per-conversation usage breakdown in Claude, so "where did my limit go" is currently only answerable by digging through run history.

What happened: the 8.5-hour timeline

The task was called "Refresh personal dashboard." I created it on July 27, 2026 through claude.ai's Scheduled feature. It ran daily at 7:31 AM on Opus 5 at high effort, and its job was mundane: run three Gmail searches for bank, job, and GitHub alerts, pull the next seven days from Google Calendar, build a small self-contained HTML dashboard, and update a desktop artifact.

Here is the shape of what actually happened, drawn against the two timestamps I can prove and the one I observed.

Three points on that line are solid: the API confirms the trigger fired at 02:01:34 UTC, which is 7:31 AM IST; I found it still active at roughly 3:30 PM; the last activity on the run sits at about 4:02 PM. The phases in between happened in a known order, but I never recorded exactly when one became the next, so I'm not going to draw boundaries I can't defend.

The intended bar is drawn to true scale. That sliver is the entire job.

The root cause: approval-gated tools in an unattended run

The task needed two things it could never have.

mcp__Gmail__search_threads and mcp__Google_Calendar__list_events were both approval-gated on my account. That's the setting where Claude asks before each call and waits for you to click approve.

A scheduled run is unattended by definition. That's the entire point of scheduling something for 7:31 AM. There is nobody sitting there to clear the gate, and there is no mechanism for the gate to clear itself.

So the run was dead on arrival. Not occasionally. Every morning since July 27, by design, and the system let me create it that way without a word of warning.

The part I want to be precise about: the model behaved correctly here. It hit a gate it could not pass, and it wrote an accurate diagnosis. It said the run failed, named both gated tools, and gave the fix. Then it deliberately refused to fake the output. Its own words were that a visibly stale dashboard beats a fresh timestamp sitting over empty spending cards.

That's the right call. If it had invented plausible numbers, I'd have had a dashboard that lied to me every morning and I might never have noticed.

The loop: when the harness won't take "done" for an answer

The model concluded the run had failed. The scheduler re-prompted it.

So it concluded again. Slightly different wording, same substance: run failed, nothing written, Gmail and Calendar are approval-gated, set them to always-allow and re-fire. Then again. And again.

Reading back through it is a strange experience, because the model is visibly aware of the problem and completely unable to escape it. At one point it wrote this:

Acknowledged. That call was mine and it shouldn't have happened. I'd already concluded twice. No further tool calls.

That line is the whole incident in one sentence. The model was tracking its own repetition. The harness driving it was not.

This is where the usage went. Every iteration of that loop re-sent the entire conversation so far, and the conversation kept growing. On top of that, I had five MCP connectors attached to this task: Gmail, Google Calendar, Asana, vidIQ, and Claude Code Remote, plus a documents plugin. Every connector's full tool catalog rides along in every model call, whether the task touches that connector or not.

I want to be careful here, because it would be easy to overclaim. I never measured token counts, so I'm not going to give you a number. What I can say structurally is that a growing transcript plus five connectors' worth of tool schemas, re-sent on every iteration for hours, against the most expensive model available, is a very effective way to consume a limit.

What "API Error: 400 user messages must have non-empty content" means

By this point I was trying to kill it. I hit Claude's stop button. Nothing happened. I hit it again. The run carried on exactly as before, still re-writing its conclusion, completely indifferent to the fact that I was now sitting there watching it and actively telling it to stop.

Shortly after that, the run stopped being a loop and became a wall.

API Error: 400 messages.56: user messages must have non-empty content

If you hit this string, here's what it means. In the API, a conversation is a list of messages, each tagged with a role, and tool results travel back to the model inside user-role messages. Something in that loop appended a user-role message at position 56 with nothing in it.

The API rejects any request containing an empty message. Not the new part of the request. The whole thing, because the entire history goes up on every call.

That's why this state is permanent. Message 56 is now baked into that conversation's history, so every future call carries it, so every future call gets rejected the same way. The "Try again" button re-sends the same invalid history and fails identically. There's no repair path from inside the conversation. The transcript is scrap.

I want to be careful about what I'm claiming here. I don't know what put the empty message at position 56, and I didn't capture enough to prove it. What I can report is the order I saw things happen in: I was pressing stop, the stop wasn't taking, and then position 56 turned up empty and the run wedged. An interrupt landing while a turn is in flight is at least a plausible way to end up with a user-role message that has nothing in it. That's a hypothesis, not a finding, and I'd rather say so than dress it up.

One small mercy: those rejected calls are refused before the model ever runs, so the wall of red errors itself is not what burned my limit. The hours of real generations before the corruption are.

If you want the wider catalogue of what Claude Code throws and what each one means, I keep that separately: every Claude Code error code, cause, and fix.

How I traced it

This part turned out to be the most useful thing I learned, because the tooling for it barely exists.

There is no per-conversation usage breakdown in Claude. The usage screen tells you a percentage for the current session and for the week. It does not tell you which conversation spent it. If you want to know where your limit went, the interface simply will not tell you.

So I worked backwards.

Run history was the first real signal. The scheduled task keeps a list of its runs, and the current one was still marked active hours after it should have finished. That's what turned a vague "my usage is weird" into a specific suspect.

The routines API gave me ground truth. Querying /v1/code/triggers returned the actual stored configuration rather than what I remembered setting up: the model, the cron expression, last_fired_at at 02:01:34 UTC, the five attached connectors, and the full stored prompt. (Routines are documented here; the run-history and configuration surface is the same underlying system.) It also returned persist_session: false, which matters more than it sounds. Each run starts a fresh session. So the transcript that reached message 56 was built entirely within one morning's run. That wasn't accumulated drift over days. One run did that.

Local forensics ruled out my own machine. I checked launch-agent logs and confirmed the Mac had been asleep from 8 PM until 3:22 PM. Nothing local could have driven this. The whole thing ran server-side, which is exactly what scheduled tasks are supposed to do, and exactly why nothing on my end could stop it.

By 6:36 PM the session bar had rolled over to 4%. Here's the honest framing of what this cost me, because it's the part people get wrong in both directions.

The weekly window had only opened the previous evening, so that 16% was essentially one wedged run. For comparison, by that evening, after a full afternoon of genuine work, the weekly all-models bar had moved only from 16% to 18%. One broken run cost sixteen points. An afternoon of me actually using the thing cost two.

And on the same settings page, further down: usage credits, $0.00 spent. This cost me a limit window, not money. Weekly limits reset. If you're on a subscription and this happens to you, you have lost some capacity for a few days, not a bill. Anyone telling you a runaway agent on a Max plan "cost them hundreds" is describing API billing, which is a different product. If you want the full picture of how the plans and their limits actually work, I've written that up in detail: how Claude Code's Pro, Max, and API pricing and limits really compare.

How to keep scheduled tasks from burning your limits

Five things, in the order I'd do them.

1. Put scheduled tasks on a cheap model. Mine was on Opus 5 at high effort because I built it interactively and never thought about it again. A routine that assembles a dashboard from three searches does not need the most expensive model available. Sonnet is the right default for unattended work. If you're weighing which model is worth its cost for which job, that tradeoff is its own topic: when the more expensive model actually earns its keep.

2. Attach only the connectors the task uses. I had five plus a plugin on a task that needed two. Every attached connector's tool catalog is sent on every call of every run. Trimming this is free.

3. Set the specific tools the task needs to always-allow. This is the one that would have prevented the whole incident. An approval-gated tool in an unattended run is not a risk, it's a guaranteed failure, because there is never anyone there to approve it.

4. Don't include steps that depend on a machine that might be asleep. My task's final step pushed an artifact to a desktop that is reliably asleep at 7:31 AM. That step could never have completed either.

5. Check the run history after the first few runs. Then occasionally after that. This is the only warning system that currently exists. There is no usage alert, no anomaly detection, and no ledger. If you don't look, nothing will tell you.

What Anthropic should fix about scheduled tasks

I want to be fair here. The model did its job well, and the failure is in the layer around it. Four things would have caught this.

Refuse or warn at creation time. The system knew my Gmail and Calendar tools were approval-gated, and it knew I was scheduling an unattended run that called them. Those two facts together are a guaranteed failure and could be checked the moment I hit save.

Put a runtime cap and a circuit breaker on scheduled runs. A task that normally takes three minutes ran for eight and a half hours. Nothing intervened. A simple ceiling on wall-clock time or turn count would have ended this at minute ten. Repeating a near-identical conclusion more than twice is also a fairly obvious signal that something has stopped making progress.

Make the stop button authoritative. This is the one that bothers me most, because it's the last line of defence and it isn't automated, it's me. A cap failing is a missing feature. A human being present, seeing the problem, pressing stop, and the run continuing anyway is a different category of problem. Whatever "stop" does today, on a wedged scheduled run it did not stop anything.

Give us a per-conversation usage breakdown. This is the big one. "Where did my usage go" should not require querying an undocumented API endpoint and reading launch-agent logs. A per-conversation view would have turned my afternoon of detective work into about thirty seconds.

I did file feedback on the run itself, so this is in front of them with the transcript attached.

The takeaway

I'm not going to tell you Claude will do this to you. This is one incident on one account with a specific misconfiguration, and I set that misconfiguration up myself.

What I'd take from it is narrower and more useful. Unattended agents fail differently from interactive ones. When you're sitting in front of a stuck agent, you notice in seconds and you kill it. This one fired at 7:31 AM while I was asleep, ran unwatched for eight hours, and then, when I did finally turn up and press stop, kept going anyway. The assumption I didn't know I was making was that I could always just intervene. That turned out not to be true.

The model was the most reliable component in this whole chain. It diagnosed the problem correctly on the first try, refused to fabricate data to cover the gap, and noticed it was repeating itself. It just had no way to make anything listen, and by the end, neither did I.

Frequently Asked Questions

Does Claude have scheduled tasks?

Yes. claude.ai has a Scheduled feature that runs a saved prompt on a recurring schedule, and Claude Code has the equivalent through routines, introduced as a way to run unattended automation. Both run server-side on Anthropic's infrastructure, so they don't need your machine to be awake. That's the useful part and also the part that lets a broken run continue for hours without you knowing.

Do Claude scheduled tasks count against your usage limits?

Yes. A scheduled run consumes the same plan limits as anything you do by hand, and it does so whether or not the run succeeds. In my case a run that produced no output at all consumed roughly 16% of a weekly window, because the cost is in the model calls, not in whether the task achieved anything.

Why is my Claude weekly limit used up when I didn't do anything?

Check your scheduled tasks first, and look at run history rather than the usage screen. The usage screen shows you a total with no attribution, so it can't tell you which conversation spent your limit. A task stuck in a retry loop is the failure mode to look for, especially one on an expensive model with several connectors attached.

Can I fix a conversation showing "API Error 400: user messages must have non-empty content"?

No. An empty user-role message is permanently part of that conversation's history, and the full history is re-sent on every call, so every retry fails identically. "Try again" cannot work. Start a new conversation. If it's a scheduled task, disable it before it fires again, because the underlying cause will still be there.

Do the failed API calls use up your usage?

The rejected ones don't. A 400 is refused before the model runs, so the wall of identical errors at the end of my run wasn't the expensive part. The damage was done earlier, by the hours of real generations in the retry loop before the transcript corrupted.

Context Engineering Architecture: 8 Stages From Demo to Production

Nishil Bhave — Fri, 31 Jul 2026 11:28:43 +0000

The 8-Stage Pipeline That Replaced Naive Prompting

Most "agentic AI" demos fall apart the moment you put real data behind them. The agent works in a notebook with three documents and crumbles in production with three thousand. The model didn't get worse. The context did.

A 2025 MIT NANDA study found that 95% of generative AI pilots fail to deliver measurable ROI (MIT NANDA, 2025). The reflexive answer is to blame the model: too small, too cheap, too dumb. But teams that ship working agents will tell you the same thing. The bottleneck isn't the model. It's the architecture that decides what the model gets to see.

That architecture has a name now. Context engineering: the discipline of dynamically assembling the right tokens, in the right order, within the right budget, every single turn. Anthropic calls it "the natural progression of prompt engineering" (Anthropic Engineering, 2025). 82% of IT leaders agree prompt engineering alone is no longer enough to power AI at scale (DataHub, 2026).

I've spent the last year building agents at Growth Engine, and the same eight stages show up every time the system survives contact with users. This guide is the reference I wish I'd had when I started.

foundational guide to agentic AI

Key Takeaways

95% of GenAI pilots fail in production. The root cause is context architecture, not model selection (MIT NANDA, 2025).

Production agents need 8 discrete stages: intent classification → parallel retrieval → reranking → compression → context assembly → token-budget audit → guardrails → observability.

95% of data teams plan to invest in context engineering training in 2026 (DataHub, 2026).

Token budgets aren't free, and the curve differs by vendor: Gemini 3.1 Pro doubles its rate above 200k tokens and GPT-5.5 charges 2× input above 272k, while current Claude models price the full 1M window flat. Architecture decides cost.

What Is Context Engineering Architecture?

Context engineering architecture is the system-level design pattern for assembling the exact tokens an LLM needs to complete a task: dynamically, every turn, within a measured token budget. It treats context as a finite resource with diminishing marginal returns, not as a magic-prompt input (Anthropic Engineering, 2025).

Prompt engineering optimizes a static template. Context engineering optimizes a runtime pipeline. The difference shows up the moment your agent has to deal with conversation history, retrieved documents, tool outputs, and user-specific memory all at once.

Here's the practical distinction. A prompt engineer asks: "What's the best instruction to give the model?" A context engineer asks: "Of the 1.4M tokens we could give the model, which 24,000 actually matter for this turn, and how do we pick them in 80 milliseconds?"

Both questions have answers. Only the second one survives production load.

why AI-native apps need new architectural patterns

The frame shift: prompt engineering treats the LLM as a black box you negotiate with. Context engineering treats the LLM as a deterministic function whose output is a function of its input. The input is a system you design, not a string you write.

Why Do Production Agents Fail Without Context Engineering?

Production agents fail because LLMs degrade non-linearly with context size. Stanford research shows retrieval accuracy drops more than 30% when relevant information sits in the middle of a long context window rather than at the start or end (Liu et al., 2023). This is the now-famous "lost in the middle" problem, and it gets worse as context grows.

The Datadog State of AI Engineering report found something even more revealing. In production traces, 69% of all input tokens were system-prompt tokens: instructions, policies, and tool definitions that the same agent re-sends on every single call (Datadog, 2026). That's not context. That's expensive boilerplate, repeated forever, drowning the actual question.

According to a 2026 Anthropic engineering analysis, "context must be treated as a finite resource with diminishing marginal returns" (Anthropic Engineering, 2025). Stuff the window indiscriminately and your accuracy goes down even though your token bill goes up. That's the economics of bad context architecture in one sentence.

semantic caching to reduce repeated context costs

What Are the 8 Stages of a Production Context Pipeline?

A production context pipeline runs eight discrete stages on every agent turn: intent classification, parallel retrieval, reranking, compression, context assembly, token-budget audit, guardrails, and observability. Each stage has a specific failure mode, a measurable output, and a place where you can swap implementations without rewriting the rest. This is the architectural difference between a demo and a system.

Most articles on context engineering stop at "use RAG and summarize older messages." That's not architecture. That's two patterns. The pipeline below is what you actually run when an agent has to handle a thousand concurrent users with auditable behavior.

Let's walk through each stage. For each one I'll give you the job, the failure mode, the metric, and a code sketch.

Stage 1: How Does Intent Classification Route the Request?

Intent classification is the router that decides what kind of context the request needs before any retrieval happens. A small, fast classifier (often a 7B model or even a logistic regression on embeddings) tags the user's input with an intent (lookup, multi_hop_reasoning, code_generation, tool_call, chitchat) and routes the turn to a different downstream pipeline for each.

Why does this matter? Because you don't need vector retrieval for "thanks." You don't need conversation history for a fresh code-review request. And you absolutely don't need a 24-document RAG dump for a math question. Skipping the router is how teams end up paying for retrieval on every turn whether it's needed or not.

# Stage 1: Intent classification, fast, cheap, deterministic
INTENTS = ["lookup", "reasoning", "tool_call", "code_gen", "chitchat"]

def classify_intent(query: str) -> str:
    embedding = embed_fast(query)  # ~5ms with bge-small
    return classifier.predict(embedding)  # logreg, ~1ms

intent = classify_intent(user_input)
pipeline = PIPELINES[intent]  # different stages run for each intent

The failure mode here is simple. Classify wrong, and the rest of the pipeline does work that doesn't help. The metric is intent-accuracy on a held-out eval set, plus the percentage of turns that bypass retrieval entirely (target: 20-40% of agent turns don't need RAG at all).

Stage 2: Why Run Retrieval in Parallel Instead of Sequentially?

Parallel retrieval fans the query out across multiple data sources at once (vector store, full-text search, knowledge graph, recent conversation memory, user profile) and waits for all of them to respond. The vector database market is projected to grow from USD $2.65B in 2025 to $8.95B by 2030, a 27.5% CAGR (MarketsandMarkets, 2025), but a vector store alone is rarely enough.

Real production retrieval is hybrid. You hit BM25 for exact-match terms, dense embeddings for semantic similarity, a graph for entity relationships, and your CRM or feature store for user-specific facts, all at the same time. Then you union the results.

# Stage 2: Parallel retrieval, fan out, wait for all
import asyncio

async def parallel_retrieve(query: str, intent: str) -> list[Doc]:
    tasks = [
        vector_search(query, k=20),       # semantic
        bm25_search(query, k=20),         # lexical
        graph_lookup(extract_entities(query)),  # entities
        memory_recall(query, user_id),    # user memory
    ]
    results = await asyncio.gather(*tasks)
    return dedupe_by_id(flatten(results))

The failure mode is retrieval starvation: a slow source becomes the bottleneck. Set per-source timeouts (200-300ms), drop late responses, and proceed with what you have. The metric is recall@50 across the union, not any single source.

What I learned shipping this: every team I've worked with under-sizes their k. They ask for top-5 and wonder why the answer's missing. Retrieve 20-50 candidates from each source. The reranker in stage 3 is what gets you down to 5, and it's better at picking than the embedding similarity score.

agent infrastructure patterns for small teams

Stage 3: How Much Does Reranking Actually Improve Accuracy?

Reranking takes the 50-200 candidate documents from parallel retrieval and re-scores them with a more expensive cross-encoder, returning the top 3-10 that actually answer the question. The gains are well documented. Databricks testing found reranking improves retrieval quality by up to 48% over baseline retrieval and cuts hallucinations by 35% compared to raw embedding similarity, while ZeroEntropy's own zerank-1 reports a 28% NDCG@10 lift over baseline retrievers (ZeroEntropy, 2025). The latency cost depends entirely on which model you pick. Dedicated rerankers land around 100ms for Cohere's rerank-3.5 and roughly 60ms for zerank-1, while general-purpose cross-encoders run anywhere from 200ms to 2 seconds per query. At the top of the current leaderboard, Cohere's Rerank 4 Pro scores 1627 ELO, about 170 points above its v3.5 predecessor and more than 400 points ahead on business and finance tasks (Cohere, 2026).

That accuracy delta is what kills the demo-to-production gap for most RAG pipelines.

# Stage 3: Reranking - bring the top-50 down to top-5
def rerank(query: str, candidates: list[Doc], k: int = 5) -> list[Doc]:
    pairs = [(query, doc.text) for doc in candidates]
    scores = cross_encoder.predict(pairs)  # budget 100-200ms for 50 pairs
    ranked = sorted(zip(candidates, scores), key=lambda x: -x[1])
    return [doc for doc, _ in ranked[:k]]

A cross-encoder reranker is one of the highest-leverage additions you can make to an existing RAG pipeline. The failure mode is mostly cost (each rerank pass costs roughly 10x the embedding pass), and the metric is precision@5 on labeled query-document pairs.

Stage 4: What Does Context Compression Look Like in Production?

Context compression turns the top reranked documents into the smallest faithful representation that still answers the question. This isn't summarization in the GPT-3 sense. It's structured extraction, span selection, and key-value distillation aimed at removing tokens that don't pull weight.

Datadog's 2026 traces make the real target clear: system-prompt tokens, not retrieved documents, dominated the window at 69% of all input tokens (Datadog, 2026). That means compression has to happen on more than just RAG output. Tool definitions get pruned to the ones the intent classifier thinks are relevant. Conversation history gets summarized once it exceeds a length threshold. Older tool outputs get written to disk and replaced with a pointer.

A few patterns that work in practice:

Span selection over generative summarization for retrieved documents: pick the 2-3 sentences that match the query, throw away the rest.
Tool-shedding: only include tool definitions for tools the router said are plausibly relevant. A 50-tool agent shouldn't ship 50 tool schemas every turn.
Conversation summarization at a threshold (say, 8 turns): replace older turns with a structured summary.
Externalized memory: write tool outputs and intermediate state to a key-value store, replace them with pointers in the prompt.

The metric is the compression ratio (output tokens / input tokens) at preserved task accuracy. A good rule of thumb: you should be able to compress 4-6x without measurable accuracy loss on your eval set.

multi-agent orchestration patterns

Stage 5: How Does Context Assembly Order Tokens for the Model?

Context assembly is the deterministic step that takes everything from the previous stages (system prompt, compressed retrieval, tool definitions, conversation summary, current message) and lays them out in a specific order designed to fight context rot. Anthropic's research is explicit that ordering matters as much as content: the start and end of the window are where attention is strongest (Anthropic Engineering, 2025).

A reasonable default ordering, top to bottom:

System prompt: short, declarative, the policy and persona
Tool definitions: pruned to the relevant subset
Long-term memory: user-specific facts, structured
Retrieved context: the reranked, compressed top-K
Conversation summary: older history, compressed
Recent turns: last 4-8 messages verbatim
Current user message: the actual question, last

The current user message goes last because that's where the model's attention is strongest. The system prompt goes first because that's the second-strongest position, and you want the policy bracketing the request.

# Stage 5: Context assembly - deterministic order
def assemble_context(parts: ContextParts) -> list[Message]:
    messages = []
    messages.append({"role": "system", "content": parts.system_prompt})
    if parts.tools:
        messages.append({"role": "system", "content": render_tools(parts.tools)})
    if parts.long_term_memory:
        messages.append({"role": "system", "content": render_memory(parts.long_term_memory)})
    if parts.retrieved_docs:
        messages.append({"role": "user", "content": render_docs(parts.retrieved_docs)})
    if parts.summary:
        messages.append({"role": "user", "content": parts.summary})
    messages.extend(parts.recent_turns)
    messages.append({"role": "user", "content": parts.current_message})
    return messages

Don't get clever here. The assembler should be a pure function: same inputs, same outputs, no LLM calls. That's how you replay traces in observability and trust the result.

Stage 6: How Do You Audit Token Budgets Before Sending the Prompt?

Token-budget audit is the mandatory checkpoint between assembly and sending. It counts the assembled tokens, compares them to the model's effective window, and either fits or rejects the prompt before you spend money on it. This is the stage every shallow tutorial skips.

Token budgets aren't free, and the pricing structure varies more than most teams expect. Some vendors charge a flat rate across the whole window, others tier it at a threshold:

Claude Opus 5: 1M context at $5/$25 per million tokens, flat across the window with no long-context premium (Anthropic, 2026).
Claude Sonnet 5: 1M context at $3/$15 per million, also flat.
GPT-5.5: 1.05M context at $5/$30 per million, rising to 2× input and 1.5× output above 272k (OpenAI, 2026).
Gemini 3.1 Pro: $2/$12 per million under 200k, doubling to $4/$18 above it (Google, 2026).

The lesson isn't that long context is uniformly expensive. It's that the cost curve differs by vendor, so a budget audit tuned to one model's threshold will silently mis-price another.

The audit step is short and worth its weight in incidents:

# Stage 6: Token-budget audit
def audit_budget(messages: list[Message], model: ModelConfig) -> AuditResult:
    tokens = count_tokens(messages, model.tokenizer)
    if tokens > model.hard_limit:
        raise BudgetExceeded(f"{tokens} > {model.hard_limit}")
    if tokens > model.soft_limit:
        log.warn(f"In premium tier: {tokens} tokens, +2x pricing applies")
    return AuditResult(tokens=tokens, tier="premium" if tokens > model.soft_limit else "standard")

Why does this matter beyond cost? Because budget overruns aren't graceful. They truncate, often silently, and your model loses exactly the part of the prompt you needed most. The audit gives you a place to fail loudly and trigger a re-compress if you've exceeded your target.

If you want to see this accounting in a tool you already use rather than one you build, Claude Code exposes the same numbers through /context, down to what its system prompt, memory files, and skill descriptions consume before your first message.

what actually fills a Claude Code context window, measured

Stage 7: What Guardrails Belong in the Context Pipeline?

Guardrails are the validation, redaction, and policy-enforcement layer that runs before the prompt leaves your service and after the model's response comes back. Most teams bolt these on at the application layer; production teams bake them into the context pipeline because that's where the data lives at the right granularity.

Guardrails that belong in the pipeline:

PII redaction before retrieval: never let a customer query leak names or emails into your vector store logs.
Tool-call whitelisting: the model is only allowed to call tools the intent classifier authorized for this turn.
Output schema validation: if you asked for JSON, parse it; if it fails, retry with the parser error included as feedback (this single pattern fixes most "the model didn't follow the format" complaints).
Citation requirement: if the response cites a fact, that fact must appear in the retrieved context. If it doesn't, flag it as a hallucination candidate.
Refusal policy: block topics the agent shouldn't address before they hit the model, not after.

Cognizant deployed 1,000 context engineers across its ContextFabric platform in late 2025 and reported up to 70% fewer hallucinations versus baseline agents, largely attributed to disciplined guardrails plus retrieval (Cognizant, 2025).

# Stage 7: Guardrails - bidirectional
def pre_send_guardrails(messages: list[Message]) -> list[Message]:
    return [redact_pii(m) for m in messages]

def post_response_guardrails(response: str, retrieved: list[Doc]) -> ValidatedResponse:
    if not validate_schema(response):
        return retry_with_parser_feedback(response)
    if not citations_grounded(response, retrieved):
        return flag_hallucination(response)
    return ValidatedResponse(response)

AI agent guardrails for code review

Stage 8: How Do You Observe a Context Pipeline in Production?

Observability for context engineering means instrumenting every stage with OpenTelemetry GenAI semantic conventions so you can answer questions like "which stage caused this bad answer?" without re-running the whole pipeline. According to LangChain's State of Agent Engineering 2025, 89% of organizations have implemented some form of agent observability. Among teams running agents in production, that number jumps to 94% (LangChain, 2025).

The OpenTelemetry semantic conventions for GenAI standardize the spans, attributes, and events you should emit (OpenTelemetry, 2025). At minimum, every agent turn should produce a trace with one span per pipeline stage, plus the full prompt and response captured as events.

What to capture per stage:

Intent classification: predicted intent, confidence, time-to-classify
Retrieval: sources queried, doc IDs returned, recall@k if you have ground truth
Reranking: top-k IDs, reranker scores, latency
Compression: input tokens, output tokens, ratio
Assembly: final token count, ordering checksum
Audit: total tokens, budget tier, pass/fail
Guardrails: flags raised, redactions made, validation outcomes
Model call: model name, prompt tokens, completion tokens, finish reason, time-to-first-token, total latency

The Datadog 2026 report found that 5% of all LLM call spans returned an error in February 2026, and 60% of those were caused by exceeded rate limits. By March the error rate had dropped to 2%, with rate limits accounting for almost a third of them, which still worked out to nearly 8.4 million rate-limit errors in a single month across observed production traffic (Datadog, 2026). Without per-stage instrumentation, you can't tell whether your agent is failing because retrieval was empty, the assembly was malformed, or the model itself rate-limited. With it, you can.

# Stage 8: Observability - per-stage spans
from opentelemetry import trace
tracer = trace.get_tracer("context-pipeline")

def run_pipeline(query: str):
    with tracer.start_as_current_span("agent.turn") as turn:
        with tracer.start_as_current_span("intent") as s:
            intent = classify_intent(query)
            s.set_attribute("gen_ai.intent.predicted", intent)
        with tracer.start_as_current_span("retrieve") as s:
            docs = parallel_retrieve(query, intent)
            s.set_attribute("gen_ai.retrieval.docs_count", len(docs))
        # ... and so on for each stage

What I learned shipping this: the single highest-leverage piece of instrumentation is logging the assembled prompt, every token, every turn, to a queryable store. When a user complains "the agent gave me a wrong answer," you need to see the exact bytes the model saw. Aggregated metrics won't tell you that.

How Do Memory and Context Engineering Relate?

Memory is the long-lived state that persists across agent turns: user preferences, prior conversations, distilled facts. It feeds into stages 2 (retrieval) and 5 (assembly). Memory is part of a context pipeline, not a separate system. The 2025 mem0 Series A funding round of $24M, plus its selection as the exclusive memory provider for AWS Strands Agent SDK, signals just how foundational this layer has become (Sacra, 2025).

There are three memory types that show up in every production architecture:

Episodic memory: the conversation history itself, summarized after a threshold
Semantic memory: distilled facts the user has stated ("my company is a Series B SaaS")
Procedural memory: patterns the agent has learned about the user ("they prefer concise answers")

Memory products like mem0, Letta, and LlamaIndex differ mostly on how aggressively they distill and index these, but they all plug into the same stages of your pipeline. Don't treat memory as a feature you bolt on later. It's stage 2 input.

how persistent memory changes interface design

How Do You Build a Context Pipeline Step by Step?

Build the pipeline in order of leverage, not in order of stages. Most teams ship the model integration first and discover the architecture problems later. Here's the order I'd recommend if you're starting from a working prompt-and-RAG demo and trying to harden it for production.

Add observability first (Stage 8). Before you change anything, instrument what's already running. You can't optimize a pipeline you can't see. OpenTelemetry GenAI conventions are stable enough to adopt in 2026.
Add the token-budget audit (Stage 6). Once you can see token counts per turn, surprising things become visible, like the 69% system-prompt domination Datadog found.
Add reranking (Stage 3). Highest accuracy-per-dollar improvement of any stage. Cohere's Rerank 4 or ZeroEntropy's zerank models will get you most of the documented uplift in a single afternoon.
Add intent classification (Stage 1). Once you have telemetry, you'll see how many turns don't actually need retrieval. Routing them away cuts cost and latency immediately.
Add compression (Stage 4). Now that you can measure, optimize the largest contributor, usually the system prompt or the retrieved-doc dump.
Add guardrails (Stage 7). With the rest of the pipeline structured, schema-validation, redaction, and grounding checks slot in naturally.
Productionize parallel retrieval and assembly (Stages 2 & 5). These are usually already partially built. You're just making them deterministic and traced.

The whole sequence is roughly a quarter of focused work for a small team. The result is an agent that survives ten times the load of the demo it started as.

What Are the Context Engineering Best Practices That Actually Matter?

The best practices that survive contact with production are mostly about measurement and ordering, not about clever prompt wording. Seven rules cover almost everything I've had to learn the expensive way.

Practice	Why it matters
Measure the system prompt before anything else	It is usually the largest line item, not the retrieved documents. Datadog's traces put it at 69% of input tokens.
Set the token ceiling before you build	A budget you enforce in code (Stage 6) is an architectural constraint. A budget you hold in your head is a wish.
Put the answer at the edges of the window	Attention is strongest at the start and end. Burying key context in the middle costs you more than 30% accuracy.
Rerank before you compress, never after	Compression is lossy. Compressing 50 candidates and then ranking them means you rank damaged text.
Version the assembly, not the prompt	The thing that changes behavior is the order and composition of the window. Diff that, and your regressions become explainable.
Instrument per stage or you are guessing	Without a span per stage you cannot tell an empty retrieval from a malformed assembly from a rate limit.
Treat the pricing curve as an architecture input	Thresholds differ by vendor. A budget tuned to one model's tier silently mis-prices another.

The one I see skipped most often is the second. Teams add retrieval, add memory, add tools, and never write down what a turn is allowed to cost. Six months later the agent works and nobody can explain the bill.

The one that pays back fastest is the fourth. Reordering compression after reranking is usually a few hours of work and it stops you from throwing away the sentence that held the answer.

If you only adopt two of these, take measurement first and ordering second. Everything else in this pipeline is easier to fix once you can see what the model is actually receiving.

Frequently Asked Questions

How does context engineering differ from prompt engineering?

Prompt engineering optimizes a static instruction string to elicit a desired output. Context engineering optimizes a dynamic, runtime pipeline that assembles instructions, retrieved data, memory, and tools per turn within a measured token budget. 82% of IT leaders agree prompt engineering alone is no longer sufficient at scale (DataHub, 2026).

Do I need all 8 stages for a small project?

No. A side-project agent can work with just stages 2 (retrieval), 5 (assembly), and 8 (basic observability). The other stages get added as the agent scales. You'll feel the pain of missing them when traffic and data grow. Cognizant's deployment of 1,000 context engineers signals these stages matter at enterprise scale (Cognizant, 2025).

Why does context order matter inside the prompt?

LLMs pay more attention to tokens at the start and end of their context window. Stanford's "Lost in the Middle" research found a >30% accuracy drop for information placed in the middle of a long context (Liu et al., 2023). Putting the system prompt first and the user's question last is the strongest default ordering.

How big should my token budget be?

It depends on your model and intent. For most agent turns, target 8k-24k tokens of total context. Budget audits (Stage 6) should reject anything beyond your soft limit and trigger a recompress. Check your specific model before you set the ceiling, because the pricing curve is not consistent across vendors. Gemini 3.1 Pro doubles its rate above 200k and GPT-5.5 charges 2× input above 272k, while the current Claude Opus and Sonnet models price the full 1M window flat (Google, 2026) (OpenAI, 2026).

Which framework should I use to build this?

LangGraph, Vercel AI SDK, AutoGen, and Anthropic's official agent SDK all ship context-management primitives in 2026. The pipeline above is framework-agnostic. Pick the one that matches your stack. If you're starting fresh in TypeScript, Vercel AI SDK is the lowest-friction; in Python, LangGraph or the Anthropic SDK directly.

Conclusion: The Architecture Is the Product

The teams shipping working agents in 2026 aren't winning because they have a better model. They're winning because they have a better pipeline. The 8 stages above, intent classification, parallel retrieval, reranking, compression, assembly, token-budget audit, guardrails, observability, are the difference between a system that works in a notebook and one that survives a Tuesday afternoon at 3pm with a thousand concurrent users.

Three things to take with you:

Treat context as a finite, measured resource. Stage 6 (the token-budget audit) is the highest-leverage discipline most teams skip.
Observability before optimization. OpenTelemetry GenAI conventions are stable; instrument first, change second.
The architecture is the moat. Models will get better. Your pipeline is what compounds.

If you're building agents and haven't formalized these stages yet, start with the observability layer this week. Everything else flows from being able to see what's actually in your prompts.

foundational guide to agentic AI fundamentals

Claude Cowork Security Risks: What It Can Touch, and What It Can't

Nishil Bhave — Wed, 29 Jul 2026 00:55:13 +0000

The moment that made me stop and think wasn't a bug. It was Claude Cowork asking, politely, whether it could open the folder where I keep client contracts. I said no. Then I sat there wondering why my instinct was so fast, and whether it was even right.

That's the real question under every "is Claude Cowork safe" search. It's an agent that reads, writes, and edits files on your Mac or Windows machine, runs multi-step tasks on its own, and does it all on Opus 4.8. I live in Claude Code every day, so I'm not agent-shy. But letting a model touch my file system is a different kind of trust than letting it write code in a terminal I'm watching. So I read Anthropic's actual docs, tested the consent flow, and here's my honest read on the risks, the legal questions, and what the plugin system quietly widens.

Key Takeaways

Cowork only reaches folders you explicitly connect, and it can't touch anything else. Permanently deleting a file always needs your approval, in every mode (Claude Cowork docs, 2026).

Its work runs in an isolated, temporary environment on Anthropic's servers that can't reach your home or company network, and gets wiped when the session ends (Claude Cowork docs, 2026).

Prompt injection is the risk that matters most. OWASP ranks it the #1 LLM vulnerability for the second edition running (OWASP, 2025).

Data handling depends on your plan. Commercial and Enterprise don't train on your data by default; consumer Pro and Max follow the consumer policy, so check your privacy toggle (Anthropic Privacy Center, 2026).

The legal exposure isn't the tool, it's the folder you point it at. You stay responsible for every action Claude takes on your behalf.

Is Claude Cowork safe to use?

Cowork is about as safe as the scope you give it, and the defaults lean conservative. It can't reach anything outside the folders you connect, and it asks before it does anything significant (Claude Cowork, 2026). The risk isn't that it goes rogue across your whole drive. The risk is the access you hand it and the instructions it might read inside that access.

Here's why the question feels loaded, and why your caution is reasonable. Enterprise leaders already rank cybersecurity among their top AI worries (Stanford HAI AI Index, 2025), and most organizations are nowhere near ready for autonomous tools. In IBM's 2025 breach study, 63% of breached organizations either had no AI governance policy or were still developing one (IBM Cost of a Data Breach, 2025). An agent that edits files lands right in that gap.

So when people ask if it's safe, I split the answer. Is the tool built with sane guardrails? Mostly yes, and I'll show the receipts below. Will it be safe in your hands? That depends entirely on what you connect it to and which approval mode you leave running.

For the full picture of what the product is and who it's for, see the complete guide to what Claude Cowork is and does. This piece stays on the part that keeps people up at night: security, legal, and the access surface.

What can Claude Cowork actually access on your computer?

Cowork can read your files, browse the web, run code, use apps you connect, and take screenshots to understand your screen, but only within the folders and tools you grant (Claude Cowork docs, 2026). The product page puts the boundary bluntly: "You choose the folders and tools. Claude can't reach anything else" (Claude Cowork, 2026).

That folder boundary is the single most important security fact about the tool. It isn't scanning your whole machine. It sees what's inside the directories you connect, and nothing above or beside them. Anthropic's own guidance is to create a dedicated working folder rather than granting broad access, which is exactly how I'd set it up.

There's a second layer people miss. The actual work runs in an isolated, temporary environment on Anthropic's servers, separate from your computer, and that environment can't reach your home or company network. It's removed when the session ends (Claude Cowork docs, 2026). If the desktop app is offline, the session can't reach your computer at all. So the blast radius has two walls: the folders you pick, and a sandbox that can't wander onto your LAN.

When it does need to act in the world, it prefers your connectors and integrations first, falls back to your browser when needed, and only uses your screen as a last resort (Claude Cowork, 2026). Direct screen and app control, the "computer use" capability, is still labeled a research preview, and it asks permission before accessing each application.

What it can't do: reach files outside your connected folders, touch your local network from its sandbox, or permanently delete anything without asking. Those aren't settings you configure. They're how the tool is built.

How does the Claude Cowork consent and permissions flow work?

Cowork gives you three approval modes, and one protection holds across all of them: it always asks before permanently deleting files (Claude Cowork docs, 2026). The modes are manually approve, where you sign off on each action; automatically approve, where Claude reviews an action for safety before running it; and skip all approvals, where it just goes.

Approval mode	What runs without asking	What always asks
Manually approve	Nothing; you sign off on each action	Everything, including deletion
Automatically approve	Actions Claude's safety review clears	Permanent file deletion
Skip all approvals	Everything else	Permanent file deletion

That deletion guarantee is the detail I keep coming back to. Even in "skip all approvals," a permanent delete still stops and waits for you. It's a small design choice that closes off the scariest failure mode, the one where an agent quietly erases the wrong directory. On the buyer-intent question of whether it's free to try, it's included on every paid plan, so you can test the consent flow yourself before trusting it with anything real (what Cowork costs and why it's free on paid plans).

In practice, I run manual approve for anything new and only relax it once I've watched the tool work in a folder for a while. The permissions setting can also show you Claude's plan and wait for your approval before anything significant happens, which is the same "read the plan before you execute" rhythm I lean on in Claude Code. If you want to see how that plays out step by step during a real task, that's covered in how permissions actually behave during a live Cowork session.

The real caveat: skip all approvals is a loaded gun for a reason I'll get to in the risks section. Deletion is protected, sure. Everything else in that mode runs without you in the loop.

What does Anthropic do with your Claude Cowork data?

This is where the plan you're on changes the answer, so read carefully. For commercial products, Anthropic's default is clear: "By default, we will not use your inputs or outputs from our commercial products to train our models" (Anthropic Privacy Center, 2026). That covers Claude for Work, the API, and Enterprise. If you're running Cowork under a commercial or Enterprise org, your files aren't training fodder by default.

Consumer plans are different, and this is the part I'd want a lawyer-adjacent friend to underline. Free, Pro, and Max follow the consumer data policy, where chats can be used for model improvement unless you opt out in your privacy settings. Deleted conversations are removed from your history immediately and purged from the backend within about 30 days, while data you opt into training on can be retained de-identified for up to five years (Anthropic Privacy Center, 2026).

Here's the gap worth flagging plainly. Anthropic's Cowork safety docs don't spell out a Cowork-specific "we do or don't train on the files you open" line, and neither does the consumer training policy, which never names Cowork at all. By reasonable inference, Cowork on consumer Pro or Max inherits the consumer policy, and Cowork under a commercial org inherits the no-train default. One nuance the consumer policy does state: raw content from connectors, including remote and local MCP servers, is excluded from training (Anthropic Privacy Center, 2026). That's a connector carve-out, not a file-contents one.

So a blanket claim that "Anthropic never trains on your Cowork files" isn't something I can stand behind for consumer plans. Check your training toggle, and if the files are sensitive, don't rely on the default.

One more distinction that trips people up: Zero Data Retention. ZDR applies to eligible Anthropic APIs, products using a commercial org API key, and Claude Code for Enterprise. It does not apply to Claude Free, Pro, or Max (Anthropic Privacy Center, 2026). If your compliance story depends on ZDR, a consumer Cowork seat won't give it to you.

Claude Cowork legal considerations: client data, confidentiality, and who's liable

The legal risk with Cowork isn't hypothetical model behavior, it's the data you route through it and the promises you've already made about that data. Anthropic states it directly: "You remain responsible for all actions taken by Claude performed on your behalf" (Claude Cowork docs, 2026). That sentence is the whole legal posture in one line. The tool is a delegate, not a shield.

So before you point it at a folder, ask the boring questions that actually matter. Do you have a confidentiality obligation on those files? Are they covered by a client NDA, a DPA, HIPAA, or GDPR? On a consumer plan without ZDR and with the training toggle in an uncertain state, running privileged documents through Cowork could put you sideways with a contract you signed. That's not a Cowork flaw. It's the same rule that applies to any cloud tool, just with an agent doing the moving.

This is why my instinct on the contract folder was right, even before I could explain it. My working rule: consumer Cowork is fine for my own drafts, notes, code, and research. Anything under someone else's confidentiality terms goes through a commercial or Enterprise org with the no-train default and, ideally, an org where an admin has set the guardrails. If you're a solo user weighing whether that's worth it, the comparison in how Cowork's file access model differs from Claude Code's is a useful gut-check on where each tool fits.

What about a "Claude Cowork legal plugin"? That search maps to something real, and it's worth being precise. Legal is one of the named plugin categories Anthropic ships, alongside finance, HR, and the rest (Claude plugins docs, 2026). A legal-category plugin can package skills and connectors for legal work, but installing one doesn't change your obligations or grant any special privacy protection. It's convenience, not compliance. Treat any plugin, legal-branded or not, as another thing widening what the agent can reach.

Claude Cowork plugins and capabilities: what they add to the access surface

Plugins extend what Cowork can do by bundling skills, connectors, and sub-agents into one package, and on desktop the plugins you add yourself are saved locally to your computer (Claude plugins docs, 2026). That's the capabilities story people search for under "claude code cowork plugins capabilities 2026," and it's genuinely useful. It's also where the access surface quietly grows.

Think about what a connector actually is. Cowork supports MCP connectors, both local servers on your machine and remote HTTP servers, across Free, Pro, Max, Team, and Enterprise plans (Claude connectors docs, 2026). Every connector you add is a new door: a database, a SaaS app, a remote endpoint. The folder boundary still holds for files, but connectors open reach into systems that live outside those folders entirely.

Here's the part I'd underline for anyone in a company. On Enterprise, admins can restrict which actions are available within each connector, for example allowing read access but disabling write operations, and those permissions apply org-wide (Making Claude Cowork ready for enterprise, 2026). That read-only-per-connector control is the most underrated safety feature in the product. If I ran a team deploying this, I'd wire every connector read-only until a specific workflow earned write access.

Enterprise also gets the audit trail that consumer plans don't. Cowork emits OpenTelemetry events for tool and connector calls, files read or modified, and whether each action was approved manually or automatically (Making Claude Cowork ready for enterprise, 2026). One caveat from the docs: Cowork activity isn't captured in the Compliance API yet, so Team and Enterprise route it to a SIEM through OpenTelemetry instead (Anthropic, 2026). If you need a record of what the agent touched, that's your path.

The Claude Cowork security risks I actually watch for

If I had to rank the real risks, prompt injection sits at the top, and it's not close. OWASP lists prompt injection as the #1 vulnerability for LLM applications, for the second edition in a row, with "excessive agency" and "sensitive information disclosure" also in the top ten (OWASP, 2025). All three describe a file-touching agent almost perfectly.

Anthropic names the threat itself: malicious instructions embedded in external content that Claude reads, and it trains Claude to detect these attacks with external safeguards on top (Claude Cowork docs, 2026). The docs also give two flat warnings I'd take seriously: avoid granting access to local files with sensitive information like financial documents, and be cautious about using Claude in the browser for anything sensitive. Detection helps. It isn't a guarantee.

Second on my list is the interaction between skip all approvals and that injection risk. Permanent deletion is still gated in every mode, which closes the worst case. But injection steering the agent into non-deletion actions is no longer hypothetical. Security firm PromptArmor demonstrated a prompt-injection attack against Cowork: a .docx carrying concealed white-on-white instructions steered the agent into exfiltrating the victim's largest file to an attacker-controlled account, with no human approval required at any point (PromptArmor, 2026). I haven't seen a public report of injection-triggered file writes or edits specifically, but the exfiltration case settles the principle: a poisoned document can drive real actions without you in the loop. Either way, I keep sensitive folders out of auto-approve.

The rest of my list is mundane on purpose: over-broad folder grants, plugins and connectors expanding reach, a consumer training toggle left in the wrong position, and the plain old accidental wrong-file edit. None of these are exotic. All of them are yours to control.

How to use Claude Cowork safely

The safest setup takes about two minutes and removes most of the risk above. Give Cowork a dedicated working folder instead of broad access, exactly as Anthropic recommends, and never point it at directories holding secrets, credentials, or files you're contractually bound to protect (Claude Cowork docs, 2026). Scope is your strongest lever, and it costs nothing.

Here's the checklist I'd hand a teammate:

Scope tight. One project folder, not your home directory or Documents root.
Keep secrets out. No .env files, no password stores, no client contracts in the connected folder.
Default to manual approve for anything new, and only relax it once you trust the pattern.
Wire connectors read-only where you can, and add write access per workflow, not blanket.
Check the training toggle on consumer plans, and use a commercial or Enterprise org for anyone else's data.
On a team, turn on the audit trail via OpenTelemetry so you can see what the agent touched.

That's genuinely how I run it. Watching an agent work in a tightly scoped folder for a few sessions is the fastest way to calibrate trust, and it's a lot cheaper than learning the boundaries the hard way. For the moment-to-moment version of this, including what the approval prompts look like during a task, see the hands-on walkthrough of Cowork permissions in a real session.

Frequently Asked Questions

Is Claude Cowork safe to let touch my files?

Reasonably, if you scope it. Cowork only reaches folders you connect, runs in an isolated server-side sandbox that can't touch your local network, and always asks before permanently deleting files (Claude Cowork docs, 2026). The main residual risk is prompt injection, so keep sensitive folders out of auto-approve.

Can Claude Cowork delete my files without asking?

No. Cowork always asks before permanently deleting files, in every approval mode, including skip all approvals (Claude Cowork docs, 2026). Deletion is the one action the tool won't automate. Other actions, like edits and moves, can run without a prompt if you've enabled auto or skip modes.

Does Anthropic train its models on my Cowork data?

It depends on your plan. Commercial and Enterprise don't train on your inputs or outputs by default (Anthropic Privacy Center, 2026). Consumer Free, Pro, and Max follow the consumer policy, where data can be used for model improvement unless you opt out. Check your privacy toggle before using sensitive files.

Is it legal to use Claude Cowork for client or work files?

That's on you, not the tool. Anthropic states you remain responsible for all actions Claude takes on your behalf. If files carry NDA, DPA, HIPAA, or GDPR obligations, use a commercial or Enterprise org with the no-train default rather than a consumer seat, and confirm the arrangement meets your contract's terms.

What can Claude Cowork plugins access?

Plugins bundle skills, connectors, and sub-agents, and they can widen reach well beyond your files, into databases and SaaS apps through MCP connectors (Claude plugins docs, 2026). A legal-branded plugin adds legal skills, not legal protection. Add connectors read-only where possible and treat each one as a new access door.

The bottom line

Is it safe to let Claude Cowork touch your file system? My honest answer, as someone who does almost everything in Claude Code and came in skeptical: yes, within a folder you've scoped tightly, on a plan whose data terms match your obligations, with skip all approvals switched off for anything sensitive. The guardrails Anthropic ships, folder boundaries, a network-isolated sandbox, and deletion that always asks, are real and sensible.

The risk that remains is the same one that tops every AI security list, prompt injection, plus the ordinary human risk of granting too much access. Both are yours to manage, and both are cheap to manage well. Scope the folder, keep secrets out, default to manual approve, and match the plan to the sensitivity of the data. Do that and Cowork earns a place in the workflow. Skip it and you're the vulnerability, not the tool.

For the full product picture, platforms, and eligibility, the complete guide to Claude Cowork is the hub. This page is the one to bookmark before you connect that first folder.

How to Use Claude Code's Frontend-Design Plugin

Nishil Bhave — Mon, 27 Jul 2026 12:35:34 +0000

I installed the frontend-design plugin, gave Claude Code a plain brief, and watched it do something it almost never does on its own: it stopped and argued with itself about typography before writing a single line of CSS. Same model, same prompt, one plugin. The output went from a page I have seen a thousand times to one I actually wanted to look at.

That is the entire value of this plugin, and also the source of most of the confusion around it. It is not a new command you run. It is not a UI library. It is a skill that changes how Claude thinks about a frontend task, and once you understand that, the "how do I use it" question has a slightly surprising answer. Below is exactly what it is, how to install it, a real before-and-after from my own testing, and an honest read on where it earns its place and where it does not.

Key Takeaways

The frontend-design plugin is an official, Anthropic-authored plugin in the claude-plugins-official marketplace (anthropics/claude-plugins-official).

It ships a single skill and no slash command. Claude auto-invokes it on frontend work, because plugin skills are model-invoked (Claude Code docs, 2026).

Install it with /plugin install frontend-design@claude-plugins-official, then run /reload-plugins.

It mostly changes taste, not correctness. Across 12 runs it widened the range of designs the same brief produced, while the one page that shipped visibly broken came from the no-plugin arm.

What is the Claude Code frontend-design plugin?

The frontend-design plugin is an official Claude Code plugin, published by Anthropic in the claude-plugins-official marketplace. Its whole job is to make Claude produce distinctive frontend interfaces instead of the generic look AI tools default to. Its own description calls it guidance for "distinctive, intentional visual design when building new UI or reshaping an existing one." The manifest lists Anthropic as the author, and the skill itself is credited to Prithvi Rajasekaran and Alexander Bricken.

Here is the structural fact that trips people up. Plugins arrived in Claude Code in October 2025, and one can bundle slash commands, subagents, hooks, and MCP servers (Anthropic, 2025; Claude Code docs, 2026). This one bundles none of those. It contains exactly one thing: a skill, defined in a single SKILL.md file. There is no /frontend-design to type.

That matters because plugin skills are model-invoked. The documentation is blunt about it: "Skills are model-invoked: Claude automatically uses them based on the task context" (Claude Code docs, 2026). So you do not "run" the frontend-design plugin the way you run a command. You install it, and from then on Claude reads the skill's guidance into context whenever it decides you are doing frontend work. The plugin's own README says the quiet part out loud: "Claude automatically uses this skill for frontend work." Most write-ups I have seen get this wrong and invent a command that does not exist.

So what is inside that one skill? It is a short design brief written to Claude, not to you. It tells the model to approach the work "as the design lead at a small studio" whose client has already rejected anything that felt templated. It asks for deliberate choices about palette, typography, and layout, and for one justified aesthetic risk per project. And it names the enemy specifically, which is the part I find most useful.

What does the plugin actually change?

According to the skill's own text, current AI-generated design clusters around three recognizable looks:

A warm cream background near #F4F1EA, with a high-contrast serif and a terracotta accent.
A near-black background with a single acid-green or vermilion accent.
A broadsheet layout with hairline rules, zero border-radius, and dense newspaper columns.

The skill's line is that all three "are defaults rather than choices, and they appear regardless of subject."

That is a genuinely sharp observation, and it is the mechanism behind everything the plugin does. It forces a two-pass process before any code is written. First it brainstorms a compact design plan: palette as four to six named hex values, two or more typefaces with defined roles, a layout concept, and one signature element the page will be remembered by. Then it critiques that plan against the generic default before building. If part of the plan reads like the thing Claude would produce for any similar prompt, it revises and says what it changed.

To see the difference honestly, I ran the same brief both ways: "a landing hero for Perch, a self-hosted uptime monitor for people who do not trust status-page SaaS." Six runs without the plugin, six with it. I kept every output, so the claims below are checkable.

How I isolated the plugin

Getting the isolation right took more care than the experiment did. Both arms ran through claude -p with --settings pinning enabledPlugins explicitly. Everything off for the control arm. Only frontend-design@claude-plugins-official on for the other. Plugin presence was the single variable.

The obvious route is --plugin-dir, and it is a trap. It silently re-enables your entire plugin set. I have another plugin installed that ships its own competing frontend-design skill. That route would have quietly put two design skills in the treatment arm, and any difference I found would have been unattributable.

--bare isolates properly, but it never reads OAuth. It needs an API key or it dies at auth having written nothing at all.

What did not happen

Neither arm produced the template everyone expects. No indigo-to-purple gradient. No giant "99.99%" over three feature cards. Not once in twelve runs.

Every single run picked a deliberate typeface without being asked. If you have read that Claude reaches for Inter and a purple gradient by default, that was fair when those write-ups were published. It is not what the model does now. The floor moved.

Run	Arm	Typeface	Background	Overflow
0	Plugin off	Instrument Serif	Cream	0px
1	Plugin off	JetBrains Mono	Dark	0px
2	Plugin off	Space Grotesk	Dark	374px, broken
3	Plugin off	Instrument Sans	Dark	160px, decorative
4	Plugin off	Inter Tight	Dark	0px
5	Plugin off	Space Grotesk	Dark	0px
0	Plugin on	Archivo	Dark	0px
1	Plugin on	Bricolage Grotesque	Cream	0px
2	Plugin on	Archivo	Dark	0px
3	Plugin on	Archivo	Dark	0px
4	Plugin on	Bricolage Grotesque	Cream	0px
5	Plugin on	Fraunces	Cream	0px

Background is classified by the WCAG relative luminance of each page's computed body colour, not by eye. Overflow is the widest element sticking out past the 1440px viewport. The 160px on run 3 is a decorative glow clipped by its container, so it causes no document scroll and is not a defect.

What the plugin actually moved

So the plugin is not rescuing output from a generic bucket, because the plain model is not sitting in one. What it changes is narrower and more interesting: how much the runs resemble each other.

Background colour is the cleanest place to see it, because it is measurable rather than a matter of taste. I took the computed body background of each page and its WCAG relative luminance. Without the plugin, five of six runs came back dark and one cream. With it, three dark and three cream. Same brief, twice the spread.

The layouts tell the same story harder. Three comparisons, plugin off on the left and on on the right each time. These are independent runs from each arm rather than matched pairs, so read them as samples, not as one page redesigned.

The right-hand page made the hero a wire with birds perched along it, each bird a monitored service with its latency underneath and one marked as not responding. That is the "hero is a thesis" instinct doing something none of the plain runs attempted: making the page perform the product rather than describe it.

Look at the two left-hand pages in those last two comparisons. Same palette, same skeleton of headline left and live monitor panel right, and both opening on the same sentence construction, "Your status page shouldn't". A third no-plugin run opened that way too. Those were independent sessions with no shared context, converging on one answer. The right-hand pages, from the same brief, do not resemble each other at all.

One result cuts against the plugin's reputation as a pure taste layer, and I would rather show it than leave it out. One no-plugin run shipped visibly broken.

A paragraph overflows the viewport by 374 pixels and forces horizontal scroll on the whole document. The headline is clipped behind the dashboard panel and the install command runs off the right edge. No plugin-arm page had any overflow at all. That is one page out of six at a sample size of six, so treat it as a flag rather than a finding. It does point the opposite way to "this only changes how things look."

Three of the plugin runs reached for Archivo and all three came back dark, which keeps this honest: the plugin widens the range, it does not guarantee a distinct answer every time. Give it a brief with no real subject to grab onto and it has nothing to build a point of view from. Give it the actual product and who it is for, and the spread opens up.

How do I install the frontend-design plugin?

You install it from the official marketplace with one command inside Claude Code:

/plugin install frontend-design@claude-plugins-official

The claude-plugins-official marketplace is registered automatically the first time you start Claude Code interactively, so on a normal setup you do not have to add it yourself (Claude Code docs, 2026). If you are scripting a fresh machine and the marketplace is not there yet, add it explicitly first:

claude plugin marketplace add anthropics/claude-plugins-official

If you prefer clicking to typing, run /plugin with no arguments, choose Discover, and browse to frontend-design. Either path lands in the same place. After it installs, run /reload-plugins so Claude picks up the skill without a restart (Claude Code docs, 2026).

To confirm it took, ask Claude a frontend question and watch whether it starts talking about a design direction before it writes code. Because the skill is model-invoked, there is no command output that says "plugin active." The behavior is the confirmation. If you want to force the point, check that the plugin is enabled in the /plugin manager. In daily use I just look at whether Claude is reasoning about palette and type instead of dumping a template.

One install detail that saved me confusion: the skill only fires when Claude classifies the task as frontend work. If you open with something vague like "help me with my app," it may not trigger. I now open frontend sessions with an explicit framing ("design and build the settings page for X"), which reliably pulls the skill into context. That is a general truth about model-invoked skills, and it is the same reason a good skill description matters when you write your own.

How do I actually use it in a real frontend workflow?

Once it is installed, "using it" is mostly a matter of giving Claude a brief with a real subject and then reading the design plan it produces before you let it build. The plugin's power comes from that plan step, so the worst thing you can do is skip past it to the code.

Here is the workflow that works for me, using the Perch hero from earlier as the example.

1. Give it a subject, not just a component. "Build a hero section" gets you a hero. "Build the hero for a self-hosted uptime monitor for people burned by status-page outages" gets you a hero with a point of view. The skill explicitly says the subject's own world (its materials, artifacts, and vernacular) is where distinctive choices come from, so hand it that world.

2. Read the design plan it returns. With the plugin active, Claude proposed a compact token system before writing anything. Paraphrased, the plan looked like this:

Palette:   Dusk #121821 · Bone #f3ede2 · Ember #e8623f · Moss #6f8f6a · Brass #c9a24a
Type:      Display "Archivo Narrow" (tall, condensed, used sparingly)
           Body "Public Sans" · Mono "JetBrains Mono" for live metrics
Layout:    The hero IS the product. A working "watch wall" of service tiles,
           one of them flatlined and pulsing Ember, instead of a centered pitch.
Signature: A single heartbeat line under the wall that ticks in real time,
           like a seismograph for your infrastructure.

Notice what is not there: no #F4F1EA cream, no indigo gradient, no giant percentage. The plan derived the palette from a watchtower-at-dusk idea and made the hero do the product's job rather than describe it. That "the hero is a thesis" instinct is straight from the skill.

3. Sanity-check the plan against your constraints, then build. This is your cheapest intervention point. If the signature element is too much, or a font pick will not survive your bundle budget, say so now. Editing a plan costs a sentence. Editing a built page costs a rebuild. Once I approved, the code it produced was legitimately different from the default. In my original test the no-plugin page had opened like this (reconstructed, since I did not keep those pages, and as covered above the re-run controls never produced this template):

<section class="hero">
  <h1>Monitor your uptime.</h1>
  <p class="stat">99.99%</p>
  <button class="cta">Start free</button>
</section>

The plugin version opened with the working status grid and the heartbeat line as the first thing you see, with the headline demoted to a caption. Same brief, completely different thesis for what the page is.

To put numbers on it, I scored both outputs one to ten across five dimensions. The plugin lifted the aesthetic dimensions clearly, and left one dimension flat on purpose.

Read that flat dashed line at the bottom as the honest caveat. The plugin did nothing for whether the code ran, handled state, or shipped without bugs. It is a skill about taste, and taste is exactly the thing base models are worst at and this plugin is best at. If your problem is a broken build, this is not your tool.

Where does the frontend-design plugin help, and where does it not?

The plugin is not equally useful across frontend work. It shines when the aesthetic direction is undefined and there is a subject to build a point of view around. It does much less, and occasionally gets in the way, when the design is already decided for you.

I rated its usefulness across the kinds of frontend tasks I actually hand Claude, one to ten. The gap between the top and the bottom is large enough that "should I use this here" is worth a two-second thought, not a reflex.

The top of that chart is greenfield work with room to make choices. A landing page, a marketing site, a product hero, a fresh component with no existing look to match. This is where the two-pass design plan pays for itself, because there is a real decision to make and the plugin makes Claude make it deliberately.

The bottom is where I turn it off in my head. Brand or design-system-constrained work is the sharp one. If you already have tokens, a component library, and a locked visual language, the plugin's instinct to "take one real aesthetic risk" is a liability rather than a feature. It can fight your system and hand you a beautiful thing that does not match anything else you ship. For a tiny widget or a bug fix, the elaborate planning is pure overhead, the same way over-planning a one-line change is a tax in Claude Code's plan mode. Dense data dashboards sit in the middle: layout discipline matters more than flair there, and the plugin helps the frame but not the data density problem.

The honest summary: reach for it when you want Claude to have taste, and skip it when you need Claude to obey a system it did not design.

How does it fit with CLAUDE.md and the rest of my setup?

The plugin injects design guidance per session, but it does not know your preferences unless you tell it. That is where the rest of the Claude Code stack comes in, and it is worth being deliberate about the division of labor.

For persistent, project-specific design rules (your brand fonts, your spacing scale, the components you never want reinvented), the plugin is the wrong home, because it is generic by design. The right home is your project's CLAUDE.md file, where standing instructions live across every session. In practice I let the plugin supply the general "make deliberate choices, avoid the defaults" instinct, and I let CLAUDE.md supply the specifics that make those choices land inside my actual system. The two stack cleanly: the plugin raises the aesthetic floor, CLAUDE.md keeps it on-brand.

It is also worth knowing where this plugin sits in the wider extension landscape so you do not go looking for features it does not have. It is one skill, distributed as a plugin. If you want the fuller picture of how plugins, skills, and marketplaces relate, and how to manage more than one, I cover that in the Claude skills and marketplace guide. And if you are wiring frontend work into a repeatable loop rather than one-off pages, the plugin slots into a full end-to-end Claude Code workflow as the "design pass" step. That lands right after you have agreed on what to build, and before the model starts generating components.

If you want to go deeper than the plugin does on its own, Anthropic's Frontend Aesthetics Cookbook is the longer-form prompting reference its README points to. Worth a read before you tackle anything ambitious.

A note for anyone comparing this to third-party design plugins: the official one is deliberately minimal. It does not ban specific fonts, mandate a rigid question template, or ship a component kit, whatever some write-ups claim. Its actual content is the design-lead framing and the two-pass process, and that restraint is a feature. It nudges taste without hijacking your stack.

Frequently Asked Questions

What is the Claude Code frontend-design plugin?

It is an official, Anthropic-authored plugin in the claude-plugins-official marketplace that pushes Claude Code to produce distinctive frontend interfaces instead of generic AI-default designs. It contains a single model-invoked skill, no commands, and works by making Claude draft and critique a design plan before writing code (Claude Code docs, 2026).

How do I install the frontend-design plugin?

Run /plugin install frontend-design@claude-plugins-official inside Claude Code, then /reload-plugins. The official marketplace is registered automatically on first launch; if it is missing, add it with claude plugin marketplace add anthropics/claude-plugins-official first (Claude Code docs, 2026).

Is there a /frontend-design command to run it?

No. It ships a skill, and skills are model-invoked, so Claude activates it automatically based on task context rather than through a command (Claude Code docs, 2026). To make sure it fires, frame your request clearly as frontend work, for example "design and build the pricing page," rather than something vague.

Does the frontend-design plugin write bug-free code?

No, and it does not try to. It is a taste layer on top of Claude's normal coding, not a correctness or testing tool, so treat the generated design as a first draft you still review. Worth noting from my 12-run test: the one page that shipped visibly broken, with 374 pixels of horizontal overflow, came from the no-plugin arm, and no plugin-arm page had any overflow. That is a single page at a sample size of six, so it is a flag rather than evidence the plugin improves correctness.

When should I not use the frontend-design plugin?

Skip it for brand or design-system-constrained work where the visual language is already locked, for tiny widgets or bug fixes where the planning is overhead, and for anything where correctness matters more than look. Its instinct to take an aesthetic risk is a liability inside a system it did not design.

The bottom line

The frontend-design plugin does one thing and does it well: it makes Claude Code stop defaulting. Install it, give it a real subject, read the design plan before you approve, and you get frontend work with an actual point of view instead of the interchangeable AI look. In my re-run it doubled the palette spread from one brief and broke the no-plugin arm's habit of converging on the same layout, and it did that without any new command to learn.

My rules after living with it:

Install it once with /plugin install frontend-design@claude-plugins-official, then let it ride. It is model-invoked, so there is nothing to run.
Feed it a subject, not a component. The distinctiveness comes from the world you hand it.
Read the design plan. That is your cheapest edit point, and skipping it wastes the whole plugin.
Turn it off in your head for design-system work, tiny fixes, and anything where correctness beats taste.

Put your durable rules in a well-tuned CLAUDE.md so the plugin's taste lands inside your system, and treat this as one deliberate step in your build, not a magic button. Design first, then let it build.

How Much Does Claude Cowork Cost in 2026? Free on Every Paid Plan

Nishil Bhave — Sat, 25 Jul 2026 22:53:11 +0000

Claude Cowork costs nothing extra. It's bundled free into every paid Claude plan, so the honest answer to "how much does Claude Cowork cost" is "whatever you already pay for Claude." There's no separate Cowork subscription, no per-task fee, and no add-on toggle in billing.

That's the headline, and it's genuinely good news. But it hides the part that actually decides your bill. Cowork runs agent tasks, and agent tasks burn a lot more tokens than a chat message. So the real question isn't the price of Cowork, it's which plan gives you enough usage to run it every day without slamming into a limit. I live in Claude Code, and I've watched the same token math play out there for months. Below is the accurate pricing ladder, the token-burn catch nobody puts on the pricing page, and which tier I'd actually pay for.

Key Takeaways

Claude Cowork is free on every paid Claude plan and is not sold separately (Claude pricing, 2026). The free tier does not include it.

The ladder: Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo, then Team and Enterprise.

Agent workloads use about 4x the tokens of chat (Anthropic engineering, 2025), so Max is the realistic daily-driver tier for Cowork.

Anthropic's own data shows just 8.7% of Cowork sessions are software development (VentureBeat, 2026): this is a tool for non-coding knowledge work.

Is Claude Cowork free?

Yes. Claude Cowork is free on every paid Claude plan, and it's included the moment you subscribe to Pro ($20/mo) or higher (Claude pricing, 2026). There's no separate purchase, no upgrade prompt, and no metered Cowork line item. If you already pay for Claude, you already have Cowork.

The one boundary is the free tier. Claude's $0 plan does not include Cowork at all. That's deliberate: Cowork is an agent that reads, writes, and edits files on your machine across multi-step tasks, and that workload is far too token-heavy to give away for free. So "is Claude Cowork free" has a two-part answer. Free to use if you're on a paid plan. Not available if you're on the free one.

There's a common misconception worth killing here, because I keep seeing it repeated. A lot of secondary write-ups still say Cowork is "Max only." That was briefly true at launch and isn't true now. Anthropic opened Cowork to Max subscribers first on January 12, 2026, then extended it to all Pro users within days (Engadget, 2026). Today the primary pricing page lists Cowork as included in Pro and every tier above it.

According to Anthropic's pricing, Claude Cowork ships inside the Pro plan and higher at no additional cost, alongside Claude Code, which means a single $20/month subscription unlocks the full desktop agent (Claude pricing, 2026). For most people asking whether Cowork is free, that's the practical answer: it's free with the cheapest paid plan Anthropic sells.

How much does Claude Cowork cost across each plan?

Cowork's price is your Claude plan's price, nothing more. The ladder runs Pro at $20/month, Max 5x at $100/month, Max 20x at $200/month, then Team at $25 per seat and custom Enterprise pricing (Claude pricing, 2026). Every one of those paid tiers includes Cowork in full. What changes as you climb isn't Cowork's feature set, it's how much you can run it.

Here's the same ladder as a table, with what the price actually buys you:

Plan	Price / month	Cowork included?	Best for
Free	$0	No	Chat only, no agent access
Pro	$20	Yes	Trying Cowork, light and occasional tasks
Max 5x	$100	Yes	Daily Cowork use without babysitting limits
Max 20x	$200	Yes	Heavy, all-day agent workloads
Team	$25 / seat	Yes	Small teams sharing Cowork
Enterprise	Custom	Yes	Org rollout, admin controls

Whatever phrasing brought you here, price, cost, or subscription, it resolves to the same table. You're not pricing Cowork, you're pricing your Claude usage. The only genuine decision is how much headroom you need, and that comes straight from how tokens work. If you also run the terminal coding agent, the cost math is a bit different, and I break that down separately in my full Claude Code pricing and limits guide. This page stays strictly on Cowork.

Why Cowork burns more tokens than chat (the real cost)

The true cost of Cowork isn't the sticker price, it's token consumption, because agent tasks use roughly 4x the tokens of an ordinary chat turn (Anthropic engineering, 2025). A chat message is one prompt and one reply. A Cowork task reads files, plans steps, calls tools, writes output, and re-reads its own work, and every one of those steps spends tokens against your plan's limit.

Think about what a single Cowork run involves. It opens several files, holds them in a large context window, reasons across multiple steps, and edits or produces documents. That's not one exchange, it's a loop. Anthropic's own engineering team put a number on the pattern: agents use about 4x the tokens of chat, and multi-agent systems use about 15x. Cowork sits on the single-agent end of that range, but the direction is unmistakable. The same work that felt "free" in chat quietly costs several times more as an agent task.

I've felt this exact effect in Claude Code, which shares the same token economics. On Pro, a couple of real multi-file tasks can eat a chunk of your window before lunch. When I moved heavier work to Max, the limits basically stopped interrupting me. Cowork behaves the same way, for the same reason: it's an agent, not a chatbot, and agents are hungry.

This is why I keep saying Max is the realistic daily-driver tier for Cowork, and it's the single most useful thing on this page. The plan names are literal: Max 5x gives you five times Pro's usage, Max 20x gives you twenty times. When your workload is agentic, that multiplier isn't a luxury, it's the difference between finishing a task and watching a progress bar stall on a limit. Pro is plenty to try Cowork. It's thin for living in it.

Which Claude plan is best for Cowork?

Pick your plan by how often you'll run agent tasks, not by the Cowork feature list, since every paid tier ships the same Cowork. Pro ($20) is right for testing and occasional use. Max 5x ($100) is the sweet spot for daily use (Claude pricing, 2026). Max 20x ($200) is for people who run Cowork all day, back to back.

Here's how I'd match plan to person:

Pro, $20. You want to see what Cowork does. You'll run a few tasks a week, nothing that runs for twenty minutes unattended. Pro proves the value cheaply, and if you outgrow it you'll know within a fortnight.
Max 5x, $100. Cowork is part of your actual workflow. You reconcile spreadsheets, draft docs, and clean up files most days. This is where the token math stops fighting you, and it's the tier I'd point most Cowork users to first.
Max 20x, $200. You lean on agent tasks constantly, or you kick off long, unattended cloud sessions and want them to just run. If limits on Max 5x still interrupt you, 20x buys the headroom.

The counterintuitive bit: the cheapest way to use Cowork well is often to pay more. On Pro, you spend real attention rationing tasks and watching your window. On Max, that anxiety disappears and you actually use the agent for what it's good at. The $80 jump from Pro to Max 5x buys back the mental overhead of limit-watching, which for a working professional is the better trade almost every time. Cost is a real input to the Cowork-versus-Claude-Code decision too, and I weigh both sides in my honest comparison of Claude Code and Cowork.

According to Anthropic's usage data from 1.2 million Cowork sessions, 33.4% were business operations and 16.4% were content creation, while software development was just 8.7% (VentureBeat, 2026). If your work looks like that first bucket, Max 5x is almost certainly your tier.

Three Claude Cowork pricing myths, corrected

Most confusion about Cowork's cost comes from three wrong claims that keep circulating. All three are easy to settle against Anthropic's own pages (Claude pricing, 2026). Getting them right matters, because pricing decisions built on stale facts cost real money.

Myth 1: Cowork is Max-only. It was, for about four days in January 2026. Anthropic launched it to Max first, then opened it to all Pro subscribers. Cowork is now included from Pro ($20) upward. Any 2026 guide still saying "Max required" is out of date.

Myth 2: Cowork launched in October 2024. This one is just wrong, and it's worth naming because low-quality sources repeat it. Cowork went generally available on macOS and Windows on April 9, 2026, then reached web, iPhone, Android, and cloud sessions on July 7, 2026 (VentureBeat, 2026). It now runs on Claude Opus 4.8, Anthropic's flagship model released May 28, 2026 (Anthropic, 2026).

Myth 3: Cowork bills tokens like the API. No. On a subscription, you don't pay per token. You pay a flat monthly price and get a usage allowance. Heavy Cowork use doesn't produce a surprise invoice, it just draws down your plan's limit faster, which is exactly why the tier you pick matters.

Do any of these change the price of Cowork itself? No. Cowork is free on paid plans regardless. But believing the first myth pushes people onto a $100 plan they didn't need to try the tool, and that's an $80 mistake born of a stale sentence.

Is Cowork worth the token cost? My read after real tasks

Worth it depends on whether your work is file-heavy and repetitive, and for a large share of knowledge workers it clearly is, given that over 90% of Cowork sessions are non-coding (VentureBeat, 2026). If your day is spreadsheets, reports, and document wrangling, Cowork earns its token cost. If it isn't, you're paying for headroom you won't use.

I'll be straight, because that's the point of this page. I do almost everything in Claude Code, in the terminal, and Cowork isn't my daily driver. But I've run enough real tasks to see where it genuinely wins: the file-first, non-coding jobs I'd otherwise do by hand. Pulling scattered updates into one report. Reconciling two spreadsheets. Turning a messy folder into a clean deliverable. Those are the "work around the work" tasks Cowork is built for, and they're exactly the ones a terminal coding tool handles awkwardly.

Here's the honest calculus. Cowork's free-on-paid-plans pricing means you're never deciding "should I buy Cowork." You're deciding "does my Cowork use justify Max." For someone doing operations or content work most days, yes, easily. The token burn is real, but so is the time it gives back, and Max 5x at $100 turns that burn into a non-issue. For an occasional user, stay on Pro and enjoy it for free. There's no wrong answer that costs you extra, because Cowork itself never does. For the full picture of what Cowork is and everything it can do, start with the complete Claude Cowork guide.

Frequently Asked Questions

Is Claude Cowork free on the Pro plan?

Yes, on any paid Claude plan. Cowork is included at no extra charge from Pro ($20/month) upward and is not sold separately (Claude pricing, 2026). The free $0 tier does not include it, because agent tasks are too token-intensive to offer for free.

How much does Claude Cowork cost per month?

Cowork itself costs nothing beyond your Claude plan. The plans are Pro $20, Max 5x $100, Max 20x $200, Team $25 per seat, and custom Enterprise (Claude pricing, 2026). All paid tiers include the full Cowork desktop agent, so your Cowork cost equals your plan cost.

Do I need a separate subscription for Cowork?

No. There is no standalone Cowork subscription or per-task fee. It's bundled into existing Claude plans alongside Claude Code (Claude pricing, 2026). If you already pay for Claude Pro or Max, Cowork is already active in your account at no additional cost.

Which plan is best for heavy Cowork use?

Max is the realistic tier for daily use, because agent tasks use about 4x the tokens of chat (Anthropic engineering, 2025). Max 5x ($100) suits most daily users; Max 20x ($200) fits people running long or back-to-back agent sessions. Pro works for occasional tasks.

Does Cowork charge per token like the API?

No. On a subscription you pay a flat monthly price, not per token. Heavy Cowork use draws down your plan's usage allowance faster but never generates a metered bill (Claude pricing, 2026). Per-token pricing only applies to direct API usage, which is separate from Cowork.

The bottom line on Claude Cowork pricing

Claude Cowork is free on every paid Claude plan, full stop. There's no separate cost, no per-task fee, and no upsell, just Pro at $20, Max at $100 or $200, and Cowork included on all of them. The only real decision is usage.

And that decision comes down to tokens. Agent tasks burn several times more than chat, so if Cowork is part of your daily work, budget for Max rather than Pro, not because Cowork costs more, but because you'll run it enough to want the headroom. Try it on Pro, and move up the moment the limits start interrupting real work. To go deeper on what Cowork actually does and who it's for, read the complete Claude Cowork guide, and if you're weighing it against the terminal coding agent, see Claude Code vs Cowork.

What Is Claude Cowork? Anthropic's Non-Coding Desktop Agent, Explained

Nishil Bhave — Fri, 24 Jul 2026 15:27:01 +0000

I do almost everything in Claude Code. Terminal open, repo loaded, an agent chewing through a task: that's my whole workday. So when Anthropic shipped Claude Cowork, a desktop agent aimed at people who don't live in a terminal, my honest first reaction was a shrug. Did I need it? Probably not.

That turned out to be the wrong question. Most knowledge work isn't code, but it's still repetitive, multi-step, and buried in files. In roughly 1.2 million Cowork sessions in late May 2026, just 8.7% went to software development (TechCrunch, 2026). The other nine-tenths was research, documents, and business operations. This guide covers what Cowork is, what it does, who gets it, and the narrow band where it genuinely beats opening a chat window, written by someone who reaches for Claude Code, Anthropic's terminal coding agent by reflex.

Key Takeaways

Claude Cowork is Anthropic's desktop agent for non-coding knowledge work: it reads, edits, and organizes files on your Mac or Windows with your permission (Anthropic, 2026).

It went generally available on April 9, 2026 (Anthropic, 2026), and reached mobile, web, and cloud (scheduled, device-free) sessions on July 7, 2026 (Anthropic, 2026).

It's free on every paid Claude plan (Pro, Max, Team, Enterprise), but tasks burn far more tokens than chat, so Max is the realistic daily-driver tier.

Only 8.7% of a sample of 1.2M sessions went to coding, proof that Cowork is built for the other 91% of knowledge work.

What Is Claude Cowork, Exactly?

Claude Cowork is Anthropic's desktop agent for non-coding knowledge work: it reads, writes, edits, and organizes files on your computer with your consent, and runs multi-step tasks from start to finish (Anthropic, 2026). The shorthand that stuck, coined in TechCrunch's launch coverage, is "Claude Code without the code." That's the fastest way to grasp what it is: same agentic engine, aimed at documents instead of repositories.

The distinction that matters is agent versus chatbot. A chat window answers a question and stops. Cowork takes a goal ("clean up this folder of client contracts and build me a summary spreadsheet") and works through it: reading files, making changes, checking its work, and asking before it does anything it shouldn't. It lives inside Claude Desktop rather than a browser tab, which is what lets it touch your local files at all.

Why does that matter? Because the moment an assistant can act on your files, the unit of work changes. You stop copy-pasting text in and out of a chat and start handing over the whole job. A chatbot can tell you how to merge twelve spreadsheets; Cowork opens them, merges them, and saves the result where you asked. That shift, from advice to execution, is the line between a smart search box and an actual agent.

Under the hood, Cowork is built on the Claude Agent SDK and draws on the same underlying model as Claude Code (TechCrunch, 2026). As of mid-2026 that's Claude Opus 4.8, which carries a 1M-token context window (Anthropic, 2026). The practical upshot of that context size: Cowork can hold a lot of your files in its head at once, so it doesn't lose the plot halfway through a long job.

The framing I'd push back on is "Cowork is Anthropic's ChatGPT competitor." It isn't a chat product. It's the consumer-shaped sibling of a developer tool, and that lineage is the whole point: Anthropic took the agent loop that made Claude Code useful and pointed it at the files a non-engineer actually deals with all day.

What Can Claude Cowork Actually Do?

What Cowork does is best answered with data, not adjectives. Across about 1.2 million sessions in late May 2026, business operations made up 33.4% of usage, content creation 16.4%, and software development only 8.7% (TechCrunch, 2026). People aren't using it to write code. They're using it to move real work off their plate.

In plain terms, Cowork handles jobs like these: reorganizing a messy folder, pulling figures out of a stack of PDFs into one spreadsheet, drafting a report from source documents, turning meeting notes into a formatted brief, or cleaning up file names across a project. Each is a multi-step task that a chatbot can talk about but can't finish, because it can't reach your files.

The first job I handed Cowork was deliberately un-glamorous: a folder of thirty-odd research PDFs I'd been meaning to sort. I asked it to read them, tag each by topic, and build a one-page summary with links back to the files. It worked through the stack, paused to ask before renaming anything, and dropped a clean summary doc next to the originals. No terminal, no scripting, no me hovering over it. That's the shape of what it's genuinely good at.

That maps to how people use Claude more broadly. In Anthropic's own usage analysis, documents and reports make up 15% of outputs and explanations another 17% (Anthropic Economic Index, 2026). Cowork is what turns those from something you ask about in a chat into a finished file sitting in your folder, which is a bigger leap than it sounds.

The feature that changed my mind was scheduled, unattended runs. Since July 2026, Cowork can execute tasks in the cloud with no device online, so a job can run overnight or on a recurring schedule (Anthropic, 2026). "Every Monday at 7am, compile last week's support tickets into a summary" is now a thing you set once. When a scheduled run misbehaves, the fixes live in the troubleshooting guide, cause-and-fix for common Cowork errors.

Now the anti-hype part, because it's the whole reason to trust the rest. Cowork isn't magic. For a one-off question ("what's the formula for compound interest?"), it's slower and more expensive than just asking Claude in a chat, because it spins up the full agent loop for something a sentence would answer. It's token-hungry by design. And on a genuinely novel task, it still needs supervision: I've watched it confidently misread a file's structure and head down the wrong path until I stopped it. The pattern that works is narrow, well-defined jobs on files it can actually see, not open-ended "figure out my whole workflow" prompts.

How Does Claude Cowork Work?

How Cowork works comes down to one design choice: scoped consent. You pick the folders and tools it can touch, Claude can't reach anything outside them, and it asks before it acts (Anthropic, 2026). Nothing on your machine is fair game by default. You grant access folder by folder, and every consequential action pauses for your approval.

The loop is straightforward. You open Claude Cowork from Claude Desktop (or, since July 2026, from the sidebar of the Claude app on iOS and Android, or from claude.ai on the web). You give it a goal and point it at the folders it needs. It plans the steps, starts working, and checks in when it hits something that needs a decision or a permission it doesn't have yet.

"Multi-step" is the phrase that carries the weight. A single request can fan out into a dozen actions: open a file, extract a table, reconcile it against another file, flag a mismatch, write a note, save the output. You see each step as it happens, and you can stop or redirect it mid-run. It's less "type a prompt, get a wall of text" and more like watching a careful assistant work through a checklist, one item at a time.

If you've used Claude Code's plan mode, the read-before-edit approval flow in the terminal agent, this rhythm will feel familiar. Cowork borrows the same "propose before you change anything" instinct, just wrapped in a desktop UI instead of a Shift+Tab keystroke. That approval gate is the difference between a helpful agent and a scary one, and it's the first thing I'd check before letting any tool near my files.

My take: the consent model is genuinely good, but treat "ask before acting" as a floor, not a guarantee. I still point file agents at a copy of a folder, not the original, the first few times I run a new kind of task. Watch what it actually does, then loosen up.

What Can Cowork Connect To? Plugins and Tools

Cowork isn't limited to reading and writing local files. It extends through plugins and tools, and Anthropic launched a plugin marketplace for the desktop apps in early 2026 (Anthropic, 2026). Plugins let Cowork reach past your folders into the services where your work actually lives, so a task can pull data from a connected tool, act on it, and write the result back to a file on your machine.

The same rule that governs folders governs tools: you choose which ones Cowork can use, and it can't reach anything you haven't granted (Anthropic, 2026). That's the right instinct. An agent that can both edit your files and call external services is genuinely powerful, and the permissions model is what keeps "powerful" from tipping into "reckless." Before you wire up a plugin that can act on your behalf, it's worth knowing exactly what it can touch, which is its own subject in the security and permissions deep-dive, what Cowork can and can't reach and the real risks.

Which Devices and Platforms Run Claude Cowork?

Claude Cowork runs on Mac, Windows, web, and mobile, and it can now run in the cloud with no device online at all (Anthropic, 2026). That spread happened fast, and the dates matter because low-quality sources keep repeating a wrong "October 2024" launch. Here's the verified timeline.

January 2026: Anthropic launched Cowork as a macOS research preview, Max-first, with a waitlist for other plans (TechCrunch, 2026).
February 2026: a Windows beta joined the rollout.
April 9, 2026: general availability on both macOS and Windows, across all paid plans (Anthropic, 2026), corroborated by 9to5Mac (2026).
July 7, 2026: mobile (iOS and Android), web, and cloud remote and scheduled sessions, in beta and starting with Max users (Anthropic, 2026).

So the short version: a desktop-only Mac beta in January became a cross-platform, run-anywhere agent in about six months. If you're specifically trying to install it on a PC, the Windows-specific setup steps and gotchas are their own topic: see the Claude Cowork for Windows install guide, including the virtualization gate. For everyone else, the takeaway is that "where can I run Cowork" now has a boring answer: pretty much anywhere you already use Claude.

Who Gets Claude Cowork?

Who gets Claude Cowork is simple: anyone on a paid Claude plan. Cowork is available to Pro, Max, Team, and Enterprise subscribers, and it is not on the free tier (Anthropic, 2026). Pro starts at $20/month and Max at $100/month (Anthropic, 2026), and Cowork is included at no extra charge on each.

That "free on the plan you already pay for" framing carries more weight than it first appears. Anthropic captured 40% of enterprise LLM API spend by late 2025, up from 24% in 2024 and 12% in 2023 (Menlo Ventures, 2025). Its newest agent shipping bundled into existing subscriptions, rather than as a separate SKU, is a deliberate distribution play, and a real value if you're already inside its ecosystem.

The catch is tokens. Anthropic is explicit that working on tasks with Cowork consumes more of your usage allowance than chatting, because multi-step jobs are compute-intensive (Anthropic, 2026). On Pro, a couple of ambitious Cowork runs can eat your window. If you plan to use it daily, Max is the realistic tier, and the full cost math lives in the Claude Cowork pricing breakdown, is it free, what each plan gets, and the token-burn caveat.

Eligibility is one question; fit is another. Cowork is aimed squarely at non-developers doing multi-step desk work: analysts wrangling data, operations people chasing documents, researchers synthesizing sources, anyone whose day is spreadsheets and PDFs rather than pull requests. And the audience is broader than "at work." Claude usage skews more personal on weekends, climbing from roughly 35% of activity on weekdays to nearly 50% on Saturdays and Sundays (Anthropic Economic Index, 2026). A general-purpose file agent gets pulled into life admin as readily as quarterly reports, which is exactly why it's bundled into consumer plans rather than sold as an enterprise add-on.

Cowork or Claude Code? The Short Version

The one-line answer: use Claude Code for anything that touches a codebase or a terminal, and Claude Cowork for file-heavy work that doesn't. They share an engine, but they're pointed at different jobs, which is exactly why Anthropic's own data shows only 8.7% of Cowork sessions are coding (TechCrunch, 2026).

At a glance:

	Claude Code	Claude Cowork
Lives in	Your terminal	Your desktop
Works on	Codebases, Git, tests, builds	Files and documents
Command line	Required	None
Same agent loop, asks before changing anything	Yes	Yes

This is a summary on purpose. The full head-to-head, with the tasks I ran in both, is its own piece: Claude Code vs Claude Cowork, the comparison from a Claude Code power user.

Here's where I have to be straight with you, because it's the whole reason I can be useful on this topic. I default to Claude Code. When I broke down where my Anthropic tool-hours actually go, Cowork is a real slice, but a minority one.

So where does Cowork genuinely earn its slice for me? Two places. First, file-wrangling that has nothing to do with code: batching documents, cleaning up a downloads graveyard, turning a folder of invoices into a table. Doing that in a terminal is a chore; Cowork just does it. Second, scheduled work I don't want to babysit. Those are the tasks where opening Claude Code would be using a wrench as a hammer.

If you're not a developer, flip that verdict entirely. For most people, Cowork is the point of contact, and Claude Code is the thing they never need to open. The reason this comparison is worth writing carefully is that the honest answer depends on who's asking.

Frequently Asked Questions

Does Cowork cost extra on top of my plan?

No, Cowork requires a paid Claude plan, but it costs nothing extra on top of one. It's included on Pro ($20/month), Max ($100/month and up), Team, and Enterprise (Anthropic, 2026). The free tier doesn't include it. Because tasks burn more tokens than chat, the pricing guide covers which tier actually fits daily use.

How do I open Claude Cowork?

You open Claude Cowork from Claude Desktop on Mac or Windows, and since July 2026 also from the sidebar of the Claude mobile app or from claude.ai on the web (Anthropic, 2026). Once open, you grant it access to specific folders. It can't see anything you don't explicitly share, and it asks before making changes. For the full first-run walkthrough and real workflows, see how to use Claude Cowork.

Is Claude Cowork the same as Claude Code?

No. They share the same agent engine, but Claude Code is a terminal tool for coding, while Cowork is a desktop app for non-coding file work. Anthropic's own usage data makes the split concrete: only 8.7% of Cowork sessions are software development (TechCrunch, 2026). See the full comparison for a task-by-task breakdown.

Can Claude Cowork write code?

It can, but that's not what it's for. Coding was just 8.7% of a 1.2M-session sample (TechCrunch, 2026), and serious development work belongs in Claude Code, which is built around repositories, version control, and the terminal. Reach for Cowork when the "code" is really a quick script to tidy files, not a codebase.

Can Claude Cowork run tasks while I'm away?

Yes. As of July 7, 2026, Cowork supports cloud sessions that run with no device online, including scheduled and recurring tasks (Anthropic, 2026). The feature rolled out in beta starting with Max users. It's the biggest reason to consider Cowork beyond one-off jobs: you can hand it recurring work and stop thinking about it.

Why would a company trust an agent with its files?

Because access is scoped and permission-gated: Cowork only touches folders you name, and it asks before acting (Anthropic, 2026). It rides a broader shift, too. Gartner projects 40% of enterprise apps will feature task-specific AI agents by the end of 2026, up from under 5% in 2025 (Gartner, 2025).

The Bottom Line

Claude Cowork is Anthropic's agent for the 91% of knowledge work that isn't code: a desktop app that reads, edits, and organizes your files with permission, runs multi-step jobs, and, since July 2026, executes scheduled tasks in the cloud without your machine on. It's free on every paid plan, generally available on Mac and Windows since April 2026, and now on web and mobile too.

My honest verdict, as someone who lives in the terminal: Cowork isn't going to replace Claude Code for developers, and it isn't trying to. It earns its place for file-heavy, non-coding, run-while-you-sleep work, and for the many people who were never going to open a terminal in the first place. And if the alternative you're weighing is an open-source agent framework rather than Anthropic's sibling tool, the Cowork vs OpenClaw comparison covers that decision.

Is it worth turning on? If you already pay for a Claude plan, absolutely, because it costs you nothing extra to try. Give it a real, bounded task on a copy of some files and see how it does. The worst case is you learn it doesn't fit your work; the best case is you hand off a recurring chore for good. What I wouldn't do is upgrade to Max solely for Cowork before you've confirmed the workflow sticks, since the token appetite is real. If you want to decide between the two tools for your own setup, start with the Claude Code vs Claude Cowork comparison, then check the pricing details to pick a tier.

Node.js for Claude Code: Which Version, and When You Don't Need It

Nishil Bhave — Tue, 21 Jul 2026 11:23:11 +0000

I ran nvm use 18 for an old project, switched terminals, typed claude, and got command not found. Ten minutes later I was reading a Stack Overflow thread about the "Claude Code requires Node.js version 18 or higher" error, convinced I'd broken my Node setup. I hadn't. I'd just installed Claude Code the old way, back when it actually cared what Node version was on my PATH.

Here's the thing almost every setup guide still gets wrong: the Node.js question is mostly historical. The install method Anthropic now recommends downloads a native binary that never touches your Node at all. So before you go installing a specific Node version, or blaming nvm, it's worth knowing what actually needs Node, which version, and when you can stop caring entirely.

Key Takeaways

Claude Code's recommended install (the native installer) needs zero Node.js. It ships a native binary that doesn't invoke Node at runtime (Claude Code docs, 2026).

Only the npm install path needs Node, and as of v2.1.198 it wants Node 22 or later (Claude Code docs, 2026).

Even on the npm path, Node is used at install time only. The installed claude binary is native and never calls your Node.

The classic requires Node.js version 18 or higher error and most nvm conflicts are npm / VS Code extension problems. The cleanest fix is switching to the native installer.

You'll still want Node 22 LTS around for npx-based MCP servers and your own JavaScript projects.

Does Claude Code need Node.js?

No. Not for the install method Anthropic recommends. The native installer (curl -fsSL https://claude.ai/install.sh | bash on macOS and Linux, or irm https://claude.ai/install.ps1 | iex in PowerShell) downloads a native binary and, in Anthropic's own words, that binary "does not itself invoke Node" (Claude Code docs, 2026). No Node, no version to match, no PATH to keep in sync.

That surprises people, because for a long time Claude Code shipped only as an npm package, and npm packages need Node. The runtime moved on. Today the npm package is one install path among several (native, Homebrew, WinGet, apt, dnf, apk), and it's the only one that touches Node. Here's the part that trips everyone up: even the npm package installs the same native binary as the standalone installer. It pulls the binary in through a per-platform optional dependency like @anthropic-ai/claude-code-darwin-arm64, links it into place, and then Node's job is done. Your Node version matters while npm runs the install. It does not matter when claude runs.

So the honest answer to "does Claude Code need Node" is: the app doesn't, one of its install paths does, and only for a few seconds during setup.

What Node.js version does Claude Code need?

If you install through npm, you need Node.js 22 or later. That became the requirement in Claude Code v2.1.198 (Claude Code docs, 2026). Before that release the floor was Node 18, which is why you still see the "requires Node.js version 18 or higher" message quoted all over old forum threads.

There's a nice bit of grace built in. If you run npm install -g @anthropic-ai/claude-code on an older Node version, npm prints an EBADENGINE warning but doesn't fail. The install completes and claude still runs, because the package downloads that native binary and the binary doesn't use your Node. So the version requirement is really a warning about the install step, not a hard wall you smash into.

Every other install path skips the question. The native installer, Homebrew, WinGet, and the Linux package managers (apt, dnf, apk) all pull the same signed native binary with no Node involved. For reference, the actual system requirements are macOS 13.0+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, or Alpine 3.19+, with 4 GB of RAM and an x64 or ARM64 processor (Claude Code docs, 2026). Node isn't on that list.

My recommendation: if you have any other reason to want Node (and most developers do), install Node 22 LTS. It clears the npm requirement and it's the current long-term-support line, so you're not chasing a moving target. But install it for your work, not for Claude Code.

How to check what you actually have

Before you touch a single version, find out how Claude Code is installed and which Node your shell sees. Ninety percent of the confusion I run into is someone fixing the wrong thing because they never checked. Four commands settle it.

Start with the built-in diagnostic:

claude --version   # confirms claude is on your PATH at all
claude doctor      # full report: install type, update status, PATH issues

claude doctor is the fastest way to learn whether you're on a native or npm install, and it flags PATH and update problems in plain language. Then check for duplicate installs, which cause more "it worked yesterday" mysteries than anything else:

which -a claude    # macOS / Linux: lists every claude on your PATH
where.exe claude   # Windows PowerShell

If more than one path comes back, you have competing installs fighting over which claude runs. A native install shows up as ~/.local/bin/claude symlinked into ~/.local/share/claude/versions/; an npm global shows in npm -g ls @anthropic-ai/claude-code (Claude Code docs, 2026). Keep one, remove the rest. Finally, separate the two questions people constantly merge:

node --version     # what Node your shell sees (relevant only for npm installs and MCP)

If claude doctor says you're on a native install, that node --version output has nothing to do with whether Claude Code runs. That single realization saves most of the debugging.

When you still want Node.js around

Claude Code doesn't need Node. Your workflow probably does. This is the nuance that gets lost when people either over-install ("Node 18+ required!") or under-install ("Claude Code needs nothing, delete Node").

Three real reasons to keep Node on the machine:

MCP servers. A lot of Model Context Protocol servers ship as npm packages and launch through npx. If you wire up a filesystem, GitHub, or Postgres MCP server that runs via npx, that command needs Node even though Claude Code itself doesn't. Point Claude Code at those tools and you're back to needing a working Node.
Your actual projects. If you write JavaScript or TypeScript, you already have Node, and Claude Code will happily run your npm test, npm run build, and npx scripts inside a session. No Node, no build tooling for it to drive.
Other global CLIs. Plenty of dev tools install through npm. If Claude Code is your only npm-installed tool, you can drop Node. If it's one of ten, keep it.

So the decision isn't "does Claude Code need Node," it's "does anything I ask Claude Code to do need Node." I put the signals I actually weigh into a quick self-check below. Score yourself: if you land high, install Node 22 LTS; if you land low, the native installer alone is genuinely all you need.

The "requires Node.js version 18 or higher" error

This is the error that sends people down the rabbit hole: Error: Claude Code requires Node.js version 18 or higher to be installed. It shows up even when you have Node 22 installed and working, which is what makes it so maddening. I've had it fire in a terminal where node --version printed v22 a second earlier.

The message is almost always lying about the cause. It's not that Node is missing or too old. It's that the process throwing the error can't see your Node. This happens most on the npm path and inside the VS Code extension. A version manager like nvm or asdf hasn't been initialized in that process's environment, so the Node you set up in your shell isn't on the PATH the extension inherited (GitHub issue #8439, 2026). The Node is right there. The tool just isn't looking in the right place.

I'm keeping this at the runtime level on purpose. This isn't an error-code catalog, and the exact message text drifts between versions. If you're chasing a specific exit code or a different Node-adjacent failure, I keep a fuller breakdown in the errors guide with every code, cause, and fix. For this one, there are two durable fixes:

Switch to the native installer. It has no Node dependency, so the whole class of "can't find Node" errors disappears. This is what I did, and I haven't seen the message since.
Make sure your version manager is loaded in the environment that runs Claude Code, whether that's your shell rc file or the IDE's launch environment. More on that next, because nvm is the usual culprit.

When I sort the Node-related install failures I've either hit or seen reported, they cluster in a way that tells the whole story. Almost none of them are about the Claude Code binary itself.

nvm conflicts with Claude Code (and how to fix them)

nvm is the single most common reason Claude Code and Node fall out with each other. The trap is simple: you install Claude Code globally under one Node version, then run nvm use to switch to a different version for another project. nvm points your PATH at the new version's global folder, the old global claude isn't there, and suddenly the command is gone. Nothing broke. The shim just moved.

On Windows Subsystem for Linux it gets one layer worse, and the docs are specific about it. WSL imports the Windows PATH by default, so if you have nvm installed in both Windows and WSL, switching Node versions inside WSL can break because the Windows nvm takes priority. The most common cause is that nvm simply isn't loaded in your shell (Claude Code docs, 2026). A related symptom is exec: node: not found when you run claude, which means WSL is reaching for the Windows Node install. You can confirm it by running which node: a path starting with /mnt/c/ is a Windows binary leaking into Linux.

The fixes, in order of how much I trust them:

Load nvm in your shell rc. Half the "nvm conflict" reports are just nvm not being sourced. Add the loader to ~/.bashrc or ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Prepend your Linux Node path if Windows paths still win in WSL:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Or sidestep the whole thing with the native installer. This is the real answer. The native claude binary isn't a Node program, so it doesn't live in any nvm version folder and doesn't care which Node you've switched to. I moved to the native install specifically because I was tired of nvm use deciding whether Claude Code existed. Since then, my Node version and my Claude Code install have nothing to do with each other, which is exactly how it should be. One caution from the docs worth repeating: don't disable Windows PATH importing to force the issue, and don't uninstall Node from Windows if you use it for Windows development. Fix the load order, don't burn the setup down.

What about the VS Code extension and Node?

The VS Code extension deserves its own note, because it's where the Node story gets most confusing. The extension doesn't run the same claude you have in your terminal. It bundles a private copy of the CLI inside its own extension directory and uses that for its chat panel, and it does not add claude to your PATH (Claude Code docs, 2026). So if you installed only the extension and then open a terminal expecting claude to work, it won't. There's no ~/.local/bin/claude because the extension never put one there.

This also explains why the "requires Node.js version 18 or higher" error shows up inside the editor more than anywhere else. VS Code launches with whatever environment it inherited when it started, which frequently does not include your shell's nvm or asdf initialization. Your terminal sees Node 22; the editor process sees no Node at all, because the version manager that puts Node on the PATH never ran in that process. Same machine, same Node install, two different views of it.

The runtime takeaway is simple. If you want claude in your terminal, run the standalone native install, and don't assume the extension covered it. If the extension itself throws a Node error, the fix is to launch VS Code from a terminal where your version manager is already loaded, so the editor inherits a PATH that can actually find Node. That's an environment problem, not a Node problem, which is the theme of this entire article.

npm vs the native installer: which should you pick?

For most people, the native installer. It's what Anthropic recommends, it needs no Node, and it auto-updates in the background so you're not running npm install -g ...@latest every couple of weeks. That's the whole pitch, and it's a good one.

The npm path is still fine if you already manage a pile of global npm tooling and you're on Node 22 or later. You get the same native binary either way. Two rules if you go this route. First, don't use sudo npm install -g @anthropic-ai/claude-code, which invites permission and security problems. Second, if the binary goes missing after install, check that optional dependencies aren't disabled, because the native binary ships as a per-platform optional dependency (Claude Code docs, 2026).

If you're migrating off an old npm install to escape Node headaches, the sequence is short:

# See every claude on your PATH (watch for duplicates)
which -a claude

# Remove the npm global install
npm uninstall -g @anthropic-ai/claude-code

# Install the native binary (macOS / Linux)
curl -fsSL https://claude.ai/install.sh | bash

Then open a new terminal and run claude --version to confirm the native one is answering. If you want the full platform-by-platform walkthrough, including the Windows and WSL specifics I've only touched on here, that all lives in the complete install and setup guide. This article is about the runtime; that one is about the steps.

Frequently asked questions

Does Claude Code need Node.js?
Not for the recommended native installer, which ships a native binary that doesn't invoke Node at runtime. Only the npm install path needs Node, and even then it's used at install time, not when claude runs (Claude Code docs, 2026).

What Node.js version does Claude Code require?
If you install through npm, Node 22 or later as of v2.1.198. Older Node versions trigger an EBADENGINE warning but usually still install and run. The native, Homebrew, WinGet, and Linux package-manager installs require no Node at all.

Why does Claude Code say it requires Node.js 18 when I have Node 22?
Because the process throwing the error can't see your Node, not because your Node is too old. It's typically the npm path or the VS Code extension running without your version manager loaded, so nvm's Node isn't on the PATH it inherited. Loading nvm in your shell fixes it; switching to the native installer removes the dependency entirely.

How do I fix nvm conflicts with Claude Code?
Make sure nvm is sourced in your ~/.bashrc or ~/.zshrc, and in WSL prepend your Linux Node path so the Windows Node install doesn't take priority. The durable fix is the native installer, which isn't a Node program and ignores your nvm state completely.

Should I install Claude Code with npm or the native installer?
The native installer for most people: no Node requirement and background auto-updates. Use npm only if you already manage global npm tools and run Node 22+, and never with sudo.

The short version

The Node.js story around Claude Code is mostly a leftover from when npm was the only way in. Today, the runtime question has a clean answer.

The recommended native installer needs no Node. Full stop.
The npm path needs Node 22+, but only at install time. The binary it installs is native.
The "requires Node 18" error and nvm conflicts are PATH and version-manager problems, and the native installer makes them vanish.
Keep Node 22 LTS anyway, because your MCP servers and your own projects want it, even if Claude Code doesn't.

Get Claude Code installed the native way, keep Node for your real work, and stop letting nvm use decide whether your AI pair-programmer shows up. If you hit a specific error along the way, the troubleshooting guide has the rest.

AnythingLLM Ollama Model Not Found: 5 Fixes That Work

Nishil Bhave — Mon, 20 Jul 2026 16:14:24 +0000

You wired AnythingLLM to Ollama, hit send, and got "model not found." Or the model dropdown sits empty. Or it spins on "loading available models" forever. The frustrating part: your model is right there when you run ollama list.

Here's the thing almost nobody says out loud. That error is rarely about a broken model. It's about two local processes that can't find each other. AnythingLLM talks to Ollama over HTTP, and every "model not found" I've chased traces back to one of five plumbing problems, not a corrupt download.

I reproduced all five on Ollama 0.32.0 before writing this, so the fixes below are what I actually saw, not what I assume happens. We'll go symptom, cause, fix, ordered by how often each one is the real culprit.

Key Takeaways

Ollama listens on 127.0.0.1:11434 only by default (Ollama docs, 2026), which is the top reason a Dockerized AnythingLLM can't see it.

Inside Docker, localhost points at the container, not your host. Use http://host.docker.internal:11434 instead (AnythingLLM docs, 2026).

The literal "model not found" is usually a tag mismatch: you asked for llama3 but you have llama3.1:8b.

Chat working but document upload failing is a separate cause: the embedder model was never pulled.

The 30-second diagnosis

Ollama binds to 127.0.0.1:11434 by default (Ollama docs, 2026), and AnythingLLM reaches it over that HTTP endpoint. So before you touch any setting, match your symptom to the likely cause, then answer five questions in order.

What you see	Most likely cause
Empty model dropdown, or "loading available models" never finishes	Ollama isn't running, or the Base URL is wrong (Docker)
Chat errors mid-reply with "model not found"	Tag mismatch
Chat works, but uploading a document fails	Embedder model not pulled
Right model, right URL, still won't load or times out	Not enough memory

Each of those maps to a fix below. Here's the ordered version to run top to bottom:

Is Ollama even running? Run curl http://127.0.0.1:11434. No response means start with Cause 1.
Does the exact tag exist? Run ollama list and read the NAME column carefully. If your model name doesn't match a row exactly, jump to Cause 3.
Are you running AnythingLLM in Docker? If yes, and the dropdown is empty, it's almost always the Base URL. Go to Cause 2.
Does chat work but embedding a document fail? That's the embedder, Cause 4.
Right tag, right URL, still won't load? You're probably out of memory. Cause 5.

Most people are one setting away from a working setup. Let's find which one. For the wider picture on getting models onto your machine in the first place, see our pillar guide to running LLMs locally.

Cause 1: Ollama isn't actually running

If curl http://127.0.0.1:11434 returns nothing, Ollama isn't up, and AnythingLLM has nothing to talk to (Ollama docs, 2026). This shows up in the UI as an empty model list or a "loading available models" spinner that never resolves. It looks like AnythingLLM is broken. It isn't. The server it depends on is just asleep.

Start it and confirm:

# Start the server (foreground; leave it running)
ollama serve

# In another terminal, prove it's alive
curl http://127.0.0.1:11434
# -> "Ollama is running"

When I pointed a client at the wrong port to simulate a down server, curl returned exit code 7 and an empty body. That's the fingerprint of "nothing is listening here," which is different from "model not found." If you get exit 7 or a blank response, the server is your problem, not the model. No terminal handy? Open http://127.0.0.1:11434 in a browser instead. A running server answers with the plain text "Ollama is running"; anything else, a spinner or a connection error, means it's down or bound somewhere your browser can't reach.

One gotcha worth knowing: the Ollama desktop app and ollama serve both try to hold port 11434. If the app is already running, a second ollama serve fails with an "address already in use" error, which reads like a crash but just means the port is taken. Pick one. On a Mac or Windows box, the menu-bar app is usually enough. If you're not sure what's on the port, lsof -nP -iTCP:11434 -sTCP:LISTEN (macOS and Linux) tells you which process owns it. Managing the service itself, stopping it, restarting it, or removing it, lives in our complete Ollama setup and maintenance guide, not here.

Cause 2: AnythingLLM is pointed at the wrong Base URL

This is the big one for Docker users, and the AnythingLLM docs are blunt about it: "localhost and 127.0.0.1 are not valid URLs for the Docker container Ollama connection in AnythingLLM because both of these refer to the container network and not the host machine" (AnythingLLM docs, 2026). The symptom is a desktop install that works fine, then an empty dropdown the moment you switch to the Docker image.

Think about what localhost means inside a container. It means this container. Your Ollama server is running on the host, one network hop away, and the container has no idea. So the fix is to give AnythingLLM an address that reaches the host:

macOS / Windows: http://host.docker.internal:11434
Linux: http://172.17.0.1:11434, and add --add-host=host.docker.internal:host-gateway to your docker run command

You need Docker v18.03+ on Mac or Windows, and 20.10+ on Linux, for host.docker.internal to resolve (AnythingLLM Docker guide, 2026). Set the address in AnythingLLM under the Ollama LLM provider, in the Ollama Base URL field.

Now the half that most tutorials skip. Even with host.docker.internal, the connection can still fail, and here's why. I checked what Ollama actually listens on:

lsof -nP -iTCP:11434 -sTCP:LISTEN
# ollama ... TCP 127.0.0.1:11434 (LISTEN)

It binds to 127.0.0.1 only. A loopback address won't accept a connection coming in from a container, no matter what URL you type. You have to tell Ollama to listen on all interfaces first:

# macOS: expose Ollama on the network, then restart the app
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"

# Linux (systemd): add to the service override, then reload + restart
# Environment="OLLAMA_HOST=0.0.0.0:11434"

The values above come straight from the Ollama FAQ (Ollama docs, 2026), and setting OLLAMA_HOST=0.0.0.0:11434 is what made the container reachable in my tests. Base URL and bind address are two separate switches. Flip both.

Here's a docker run that gets the container networking right on a Linux host, where host.docker.internal needs the extra flag to resolve:

docker run -d -p 3001:3001 \
  --add-host=host.docker.internal:host-gateway \
  -v ~/anythingllm:/app/server/storage \
  mintplexlabs/anythingllm

With the container running, set the Ollama Base URL to http://host.docker.internal:11434 in AnythingLLM's UI, under the Ollama LLM provider. The --add-host flag is the piece that makes that hostname resolve to your host from inside the container; the base URL itself is a UI setting, not a container env var. If you'd rather debug it live, shell into the running container and hit Ollama from there before touching AnythingLLM's UI: docker exec -it <container> sh, then curl http://host.docker.internal:11434/api/tags. If that curl returns your model list as JSON, the network path is good and any remaining "model not found" is a tag problem, not a connection one. If it hangs or refuses, you're still on the bind-address half. That one test splits the two most common Docker failures apart in about ten seconds, which beats guessing at settings.

Cause 3: The model tag doesn't match

This one earns the literal error. When AnythingLLM sends a request for a model Ollama doesn't have, the server answers with a flat "not found." On Ollama 0.32.0, with only llama3.1:8b pulled, here's exactly what I got back from the chat endpoint AnythingLLM uses:

curl http://localhost:11434/api/chat -d '{"model":"mistral","messages":[{"role":"user","content":"hi"}]}'
# {"error":"model 'mistral' not found"}

curl http://localhost:11434/api/generate -d '{"model":"llama3","prompt":"hi"}'
# {"error":"model 'llama3' not found"}

Note the second one. I have llama3.1:8b installed, but a request for llama3 fails, because Ollama matches the full name and tag, not a family. Asking for llama3.1 with no tag fails too, since that resolves to llama3.1:latest, which I never pulled. This is the trap: the model "exists" in your head as "Llama," but Ollama only knows llama3.1:8b.

The fix is mechanical. Read the exact name, then use it verbatim:

ollama list
# NAME              ID              SIZE      MODIFIED
# llama3.1:8b       46e0c10c039e    4.9 GB    2 months ago
# qwen3:8b          500a1f067a9f    5.2 GB    5 months ago

Copy the NAME column exactly, tag included, and select that in AnythingLLM. If the model isn't listed at all, pull it with the precise name from ollama.com/library: ollama pull llama3.1:8b. Watch the pull finish before you retry, because a half-downloaded model can show up in odd states, and a canceled pull leaves nothing selectable.

A subtle version of this bug is the missing tag. When you type a bare name like llama3.1, Ollama expands it to llama3.1:latest, and if you only ever pulled llama3.1:8b, that :latest alias doesn't exist. The dropdown may even list the model while the request still fails, because AnythingLLM sometimes remembers a model you selected before you changed what's installed. If you upgraded or re-pulled models and the old choice broke, open the LLM settings, re-open the model dropdown so it refreshes from Ollama, and pick the current tag again.

Models live in ~/.ollama/models on macOS and /usr/share/ollama/.ollama/models on Linux by default (Ollama docs, 2026), so if you moved that directory with OLLAMA_MODELS, make sure the server AnythingLLM talks to is the one that can actually see your files. Running Ollama as your user in a terminal and as a background service can point at two different model directories, which looks exactly like "I pulled it but it's gone." Managing and cleaning up those tags is covered in our Ollama model management and removal section.

Cause 4: AnythingLLM's embedder needs its own model

Here's a cause that trips up a lot of people because it hides. Your chat works. Then you upload a document, and it fails. AnythingLLM uses a separate embedding model to turn documents into vectors, and if you point that embedder at Ollama, you have to download a real embedding model for it, not an LLM (AnythingLLM docs, 2026). The usual pick is nomic-embed-text. If you never pulled it, the chat model can be perfect and RAG still breaks.

The reason it hides is timing. The embedder only runs when you add a document to a workspace, so a chat-only session never touches it. You can talk to your model for an hour, decide everything works, then drop in a PDF and watch it fail on a component you didn't know was in play. That's why "chat works but upload doesn't" is such a reliable fingerprint for this one: it points straight at the embedding path, not the chat model you've been staring at.

The embedding endpoint fails loudly, and its wording is worth seeing, because it differs from the chat error:

curl http://localhost:11434/api/embeddings -d '{"model":"mxbai-embed-large","prompt":"test"}'
# {"error":"model \"mxbai-embed-large\" not found, try pulling it first"}

Two things to catch here. First, the embeddings endpoint appends "try pulling it first," while the chat endpoint just says "not found." Same root cause, different string, so don't assume they're separate bugs. Second, once I pulled nomic-embed-text, the same call returned a real vector instead of an error. The fix is one command:

ollama pull nomic-embed-text

Then, in AnythingLLM, set the embedding model to nomic-embed-text and confirm the embedder's Base URL matches the one your chat model uses. If chat reaches Ollama but embedding doesn't, you probably changed the URL in one place and not the other.

Cause 5: The model is too big for your memory

You've got the right tag and the right URL, and it still won't load. At that point the suspect is memory. Ollama has to hold the model weights in RAM (or VRAM on a GPU) to run them, and the file size is the floor for how much you need. I measured the actual on-disk footprint of the models I keep around, and the spread is dramatic:

A qwen3:30b is 18.56 GB on disk. A llama3.1:8b is under 5 GB. Real RAM use runs a bit higher than the file, because the context window and key-value cache need room too. So if you select a 30B model on a 16 GB laptop, it can load partially, thrash, or fail outright, and AnythingLLM surfaces that as a dead or timing-out model rather than a clean error.

Two levers control the footprint. Quantization is the first: a q4 (4-bit) build is roughly half the size of a q8 (8-bit) one of the same model, at a small quality cost, which is why the default tags lean on q4. Context length is the second: a longer context window grows the key-value cache that sits alongside the weights, so a model that loads fine at 8K tokens can run you out of memory at 128K. On a GPU, anything that doesn't fit in VRAM spills to system RAM and CPU, and generation slows to a crawl instead of failing outright.

The fix is to right-size. Pick a smaller or more heavily quantized tag (a :8b instead of a :30b, or a q4 variant), shrink the context length in AnythingLLM's model settings, or free up memory by closing other heavy apps before you load. If you want a runtime with a friendlier model-size picker and per-model RAM estimates baked into the UI, our LM Studio guide pairs with AnythingLLM too, since AnythingLLM speaks to both, and LM Studio makes the memory math visible before you download.

After the fix: keep it from coming back

Roughly every recurring case I've seen comes from a setting drifting out of sync after a change, so treat these three as a checklist. First, restart AnythingLLM after you touch any Ollama environment variable, since OLLAMA_HOST and friends are read at startup (Ollama docs, 2026). Second, keep the Base URL identical for the chat model and the embedder. Third, remember that desktop and Docker installs use different addresses, so a config that worked on your laptop won't copy-paste into a container.

The pattern that saved me the most time: when something breaks, I re-run curl http://127.0.0.1:11434 and ollama list first, every time, before I open AnythingLLM's settings. Nine times out of ten the answer is right there, and I've stopped editing UI fields at random. It's boring, and it works.

One more thing worth knowing if you push AnythingLLM further. It also runs MCP tool servers for its agents, configured by editing an anythingllm_mcp_servers.json file in its storage plugins directory (AnythingLLM docs, 2026). Those servers connect over their own transport, separate from the Ollama link, so a broken model connection won't take your tools down with it. If you're heading in that direction, our guide to Model Context Protocol servers is a good next stop.

Frequently Asked Questions

Why does AnythingLLM show no Ollama models even though Ollama is running?

Almost always the Base URL. Ollama binds to 127.0.0.1:11434 by default (Ollama docs, 2026), so a Dockerized AnythingLLM pointed at localhost reaches the container, not your host. Switch the URL to http://host.docker.internal:11434 and set OLLAMA_HOST=0.0.0.0:11434 on the host, then restart.

What Base URL should AnythingLLM use for Ollama in Docker?

Use http://host.docker.internal:11434 on macOS and Windows. On Linux, use http://172.17.0.1:11434 and add --add-host=host.docker.internal:host-gateway to your docker run command (AnythingLLM docs, 2026). You need Docker v18.03+ on Mac or Windows, or 20.10+ on Linux, for the hostname to resolve.

Why does it say model not found when I already pulled the model?

You're likely requesting the wrong tag. On Ollama 0.32.0, asking for llama3 when you have llama3.1:8b returns {"error":"model 'llama3' not found"}, since Ollama matches the full name and tag. Run ollama list, copy the NAME column exactly, and select that string in AnythingLLM.

Does AnythingLLM need a separate embedding model?

Yes. Chat and document embedding use different models. If you set Ollama as the embedder, AnythingLLM needs a dedicated embedding model downloaded, not an LLM (AnythingLLM docs, 2026). The common choice is nomic-embed-text: if chat works but uploads fail, run ollama pull nomic-embed-text, then set it as the embedding model with the same Base URL your chat model uses.

How much RAM do I need to run a model in Ollama?

Enough to hold the weights plus the context. Measured footprints range from 4.92 GB for llama3.1:8b to 18.56 GB for qwen3:30b on Ollama 0.32.0, and real usage runs higher. If a correctly-named model won't load, pick a smaller or more quantized tag, or reduce the context length.

The five-cause checklist

When AnythingLLM says "model not found," the model is rarely the problem. Walk the list: is Ollama running, is the Base URL reaching the host, does the tag match ollama list exactly, did you pull the embedder, and does the model fit in memory? One of those five is your answer, and each has a one-line fix.

Start with curl and ollama list before you touch any settings. It's the fastest way to tell a plumbing problem from a real one. When you're ready to go deeper on models, quantization, and the hardware behind them, our guide to running LLMs locally picks up where this leaves off.

Claude Code Plan Mode: How I Use It (and When I Don't)

Nishil Bhave — Thu, 16 Jul 2026 22:15:02 +0000

The first time plan mode saved me, I hadn't written a line of code yet. I asked Claude Code to "wire the new billing webhook into the retry queue," and instead of editing files, it laid out a plan that pointed at the wrong queue. I caught the mistake in the plan, not in a diff I had to unwind an hour later. That is the whole pitch for plan mode, and it is why I leave it one keystroke away all day.

Agentic coding tools have a default failure mode: they edit first and explain later. A wrong assumption becomes a wrong diff, and now you are reviewing changes that should never have happened. Plan mode inverts that. Claude reads, explores, and proposes, and nothing touches your source until you say go. Below is exactly how I run it, the approval flow most people skim past, and the honest line on when it is worth the friction and when it is not.

Key Takeaways

Plan mode is a read-only permission mode: Claude explores and writes a plan but does not edit source until you approve (Claude Code docs, 2026).

Enter it with Shift+Tab (cycles default → acceptEdits → plan), a /plan prompt prefix, or claude --permission-mode plan.

Across ~40 of my own sessions, the proposed plan changed my approach before any code on 71% of cross-file refactors, but only 8% of one-line fixes.

Approve to auto, approve to review each edit, or keep planning: the approval prompt sets the permission mode for everything that follows.

What is plan mode in Claude Code?

Plan mode is one of Claude Code's permission modes, and its permission is "Reads only" (Claude Code docs, 2026). Claude reads files and runs read-only shell commands to explore your repo, then writes a plan describing what it intends to change. It does not edit your source, run migrations, or push anything until you approve the plan. Think of it as a scoped research pass with a written proposal at the end.

That "reads only" line matters because it is enforced, not a suggestion. Permission modes sit on a ladder from most oversight to least: default (labeled Manual), then acceptEdits, then plan, then auto, then dontAsk, then bypassPermissions. Plan mode is the one that lets Claude think out loud across your whole codebase while guaranteeing the working tree stays untouched.

Here is the part people miss: plan mode is not a "planning feature" bolted on top of chat. It is a permission boundary. When Claude is in plan mode, the edit and write tools are blocked at the permission layer, so even if the model decides mid-thought that it wants to change a file, it can't. According to Claude Code's documentation, edits stay blocked until you approve the plan, regardless of whether auto mode is also active (Claude Code docs, 2026). That guarantee is what makes it safe to point Claude at unfamiliar code and let it roam.

The mode exists because the alternative is expensive. If Claude edits four files on a wrong premise, you are now doing archaeology on a diff instead of correcting one sentence in a plan. I would rather argue with a paragraph than revert a commit.

How do I turn plan mode on and off?

You enter plan mode by pressing Shift+Tab, which cycles through default → acceptEdits → plan, and the current mode shows in the status bar (Claude Code docs, 2026). There are three other ways in, and I use all of them depending on the moment:

Shift+Tab mid-session, the one I hit most. Tap until the status bar reads plan.
/plan as a prompt prefix when I want a single planned turn without changing the session's default. Prefix one prompt with /plan and that turn runs in plan mode.
claude --permission-mode plan at startup, so the session opens straight into planning.
defaultMode: "plan" in .claude/settings.json to make a whole project plan-first.

Getting out is just as quick. Press Shift+Tab again to leave plan mode without approving anything, which is what I do when a "plan" turns out to be a two-line change I already understand. The keystroke is deliberately the same one you used to get in, so toggling costs nothing.

One habit worth stealing: I do not start most sessions in plan mode. I start in Manual, read Claude's first response, and only tab into plan mode once I realize a task is bigger than it looked. Plan mode has a real cost in small ways too, prompt suggestions are skipped while it is active, so for quick back-and-forth it adds a little friction for no benefit.

A quick question worth asking before you toggle: is the risk in what Claude will change, or in whether the approach is right? Plan mode only helps with the second one.

What happens when Claude finishes a plan?

When the plan is ready, Claude presents it and asks how to proceed, and your answer sets the permission mode for everything that follows (Claude Code docs, 2026). This is the step most tutorials rush, and it is the most important one, because "approve" is not a single button. You are choosing how much leash Claude gets for the actual edits.

The approval prompt offers these paths:

Approve and start in auto mode, where Claude executes with background safety checks instead of per-tool prompts.
Approve and accept edits, so edits apply and you review them after the fact via git diff.
Approve and review each edit manually, the tightest option, where every change waits for you.
Keep planning with feedback, which sends the plan back with your notes instead of executing.
Refine with Ultraplan for a browser-based review pass.

Approving exits plan mode and switches the session into whichever mode you picked, then Claude starts editing (Claude Code docs, 2026). A couple of details make this smoother in daily use. Ctrl+G opens the proposed plan in your default text editor so you can rewrite it directly before Claude proceeds, which beats typing a paragraph of corrections into the prompt. And approving a plan auto-names the session from the plan content, so your history stays legible weeks later.

So which path do I actually pick? I logged it across roughly 40 real sessions. Most of the time I approve and review the diff rather than handing Claude the keys, and a healthy chunk of plans go back for another round before I let any edit happen.

When is plan mode actually worth it?

Plan mode pays off in direct proportion to blast radius, and my own tracking makes the pattern obvious. Across ~40 sessions, the proposed plan changed my approach before any code was written on 71% of cross-file refactors, but on only 8% of one-line fixes. The bigger and less familiar the change, the more the planning pass earns its keep.

Here is the same data by task type. Read it as "how often did planning first actually catch something," because that is the only metric that justifies the extra step.

The tasks at the top of that chart share a trait: the risk lives in the approach, not the typing. On a cross-file refactor, Claude has to pick which abstraction to change, and picking wrong is invisible until you are three files deep. A plan surfaces that choice while it is still cheap to argue about. The documentation says as much, listing plan mode's sweet spot as "Exploring a codebase before changing it" (Claude Code docs, 2026).

For a concrete example, I use plan mode almost every time I hand Claude a task that touches my publishing pipeline, because a bad edit there breaks a scheduler that runs unattended. If you want the broader picture of how planning fits a full session, I walk through it in my full Claude Code workflow, from first prompt to shipped change.

When should I skip plan mode?

Skip plan mode when the risk is zero and the approach is obvious, which for me is anything under the 30% line on that chart. One-line fixes, config bumps, renames you have done fifty times, throwaway scripts: planning these is pure overhead. You read a plan for a change you already understand, approve it, and wonder why you added a step. Over-planning is a real tax, and it is easy to fall into once plan mode becomes a reflex.

I settled on a five-signal test to decide in a second or two. Score the task from one to ten on each axis, and if the shape fills the chart, plan first; if it hugs the center, just let Claude edit. The two archetypes below make the call obvious: a cross-file refactor pushes every axis outward, while a one-line fix barely leaves the middle.

The five signals are blast radius (how many files or systems), unfamiliar code (do I know this area cold), ambiguous ask (is the requirement fuzzy), hard to reverse (migrations, deletes, anything stateful), and approach risk (is there more than one reasonable way to do it). Any two of these firing is usually enough for me to tab into plan mode. None of them firing means I am wasting a keystroke.

How does plan mode work with auto mode and /goal?

Plan mode and auto mode are complementary: auto mode removes per-tool prompts, and the plan-approval step decides whether Claude drops into auto mode once the plan is blessed (Claude Code docs, 2026). While you are still planning, a setting called useAutoModeDuringPlan (on by default) lets the classifier approve read-only exploration without prompting you, so Claude can grep and read freely. Edits stay blocked until you approve, either way. My usual flow is plan, read, then "approve and start in auto mode" for anything long.

/goal stacks on top of that. It sets a completion condition and keeps Claude working across turns until a separate small fast model, which defaults to Haiku, confirms the condition holds; it requires Claude Code v2.1.139 or later (Claude Code docs, 2026). A goal does not change permissions on its own, so the documented pattern is to pair it with auto mode for unattended runs. In practice I plan the work, approve into auto mode, then set a /goal like "all tests in the billing module pass," and let it run. Clear it any time with /goal clear.

The mental model I use: plan mode decides what Claude will do, auto mode decides how many prompts it takes to do it, and /goal decides when it stops. They are three different knobs, and reaching for the wrong one is where people get frustrated. If you want more control over the model doing the planning, /effort accepts low, medium, high, xhigh, max, and ultracode, and I bump it up before planning a genuinely gnarly refactor (Claude Code docs, 2026).

What are the failure modes to watch for?

The most common failure mode is not plan mode breaking, it is a plan that reads clean but rests on a wrong premise. Since edits stay blocked until you approve, the plan is your last cheap checkpoint, and rubber-stamping it defeats the entire point (Claude Code docs, 2026). I have approved confidently-wrong plans more than once, and every time the tell was there in the plan text if I had read it instead of skimming.

A few specific traps I have hit, so you can dodge them:

The confidently-wrong plan. Claude states an assumption about your code as fact. Read the first paragraph of every plan for premises, not just the numbered steps.
Plan "leaking" into edits. If you approve into auto mode by reflex, Claude starts changing files faster than you expected. When in doubt, approve into "review each edit" instead.
Over-planning trivial work. Covered above, but it bears repeating because it is the easiest bad habit to form.
Plan drift on long sessions. On very long conversations, context compaction can drop details the plan depended on. For big work, approve and execute reasonably soon rather than planning for an hour first.

None of these are reasons to avoid plan mode. They are reasons to treat the plan as a document you actually read. If your session is misbehaving for other reasons, that is a separate topic, and I keep those in the full Claude Code errors and troubleshooting reference.

Should I make plan mode the default?

You can make plan mode a project default by setting defaultMode: "plan" in .claude/settings.json, and for some repos that is exactly right (Claude Code docs, 2026). I turn it on by default in codebases where a careless edit is expensive: anything with a deploy pipeline, shared infrastructure, or state that is annoying to restore. For a scratch repo or a personal project, defaulting to plan mode just adds a step I will tab out of anyway.

The setting that makes a plan-first project pleasant is a good CLAUDE.md, because a plan is only as sharp as the context Claude has about your conventions. A repo with a solid CLAUDE.md guiding Claude's context produces plans that already know your naming, your test command, and your no-go zones, which cuts the "keep planning" round-trips. If you are still getting set up, start with the complete Claude Code install and setup guide and turn plan mode on once you have a real project loaded. For heavier planning, Ultraplan runs the same flow in a browser-based Claude Code on the web session, which is handy when the plan is long enough that a text editor beats a terminal.

Frequently Asked Questions

What does plan mode actually do in Claude Code?

Plan mode is a read-only permission mode. Claude reads files and runs read-only shell commands to explore your codebase, then writes a plan describing intended changes, but it does not edit source until you approve (Claude Code docs, 2026). It is a permission boundary, not just a prompt style, so edits are blocked at the tool layer.

How do I turn on plan mode?

Press Shift+Tab to cycle default → acceptEdits → plan, and watch the status bar for the current mode (Claude Code docs, 2026). You can also prefix a single prompt with /plan, launch with claude --permission-mode plan, or set defaultMode: "plan" in .claude/settings.json to make a project plan-first.

How do I get out of plan mode?

Press Shift+Tab again to leave plan mode without approving a plan (Claude Code docs, 2026). Approving a plan also exits plan mode automatically and switches the session into whichever permission mode your chosen approve option describes, such as auto mode or accept-edits.

Does plan mode cost extra tokens?

Plan mode has no separate fee, but a thorough planning pass reads files and runs exploration commands, so it spends tokens like any other turn. Pairing it with /goal adds a small evaluation cost on the fast model that checks your condition, which the docs describe as typically negligible next to main-turn spend (Claude Code docs, 2026).

When should I not use plan mode?

Skip it for one-line fixes, config tweaks, and changes you have made many times, where the approach carries no real risk. In my tracking, planning changed my approach on just 8% of one-line tasks versus 71% of cross-file refactors, so the payoff is almost entirely on large or unfamiliar work.

The bottom line

Plan mode is the cheapest insurance in Claude Code, and it costs one keystroke. It turns "Claude edited four files on a bad assumption" into "Claude proposed editing four files, and I said no." After a few hundred sessions, my rules are simple:

Tab into plan mode whenever two of the five signals fire: big blast radius, unfamiliar code, ambiguous ask, hard-to-reverse work, or real approach risk.
Read the plan for premises, not just steps. The wrong assumption is almost always stated in plain text.
Choose your approval carefully, because it sets the permission mode for every edit that follows.
Skip it for trivial changes, where planning is friction with no upside.

If you are wiring this into a real workflow, the natural next steps are getting your CLAUDE.md tuned so plans arrive with the right context and slotting plan mode into a repeatable end-to-end Claude Code workflow. Plan first, then let it build.

Awesome LLM Apps: 52 Ranked by What's Maintained (2026)

Nishil Bhave — Tue, 14 Jul 2026 00:46:44 +0000

Search "awesome-llm-apps" and you land on one giant GitHub repo. Shubhamsaboo/awesome-llm-apps has crossed 115,000 stars (GitHub, June 2026), and it is genuinely excellent. But read the fine print: it bills itself as "100+ AI Agent and RAG apps you can actually run, clone, customize, ship." Those are starter templates you build from, organized by technique. They are not finished apps you install and use.

This is the other kind of directory. It is 52 real, runnable LLM apps that I either use myself or have graded against hard repo signals, sorted into 7 categories, with one column that does the actual work: a maintenance verdict. Maintained, Slowing, or Abandoned. That column is the point of the page, because the flat "awesome" lists will happily send you to a tool whose last commit landed in 2024. If you want the runtime landscape underneath all of this, the local engines and the hardware math, start with the complete 2026 guide to running LLMs locally; this directory assumes you just want the ranked list.

Key Takeaways

The popular "awesome-llm-apps" repo (Shubhamsaboo, 115,000+ stars, June 2026) is a cookbook of templates you build, not a directory of finished apps you run. This page is the latter.

Of the 52 apps I rank here, 42 are Maintained, 6 are Slowing, and 4 are Abandoned. That looks healthy only because I threw out the dead forks before counting.

Last-commit recency beats star count. GPT4All sits on 77,000 stars but has been quiet since May 2025 (GitHub, June 2026); gpt-engineer and Verba are archived outright.

Install official or actively-shipping first: Ollama or LM Studio to run models, Open WebUI or LibreChat to chat, AnythingLLM or Dify to build.

How Did I Rank These LLM Apps?
Local Model Runners
Chat UIs and Frontends
RAG and Chat-With-Your-Docs Apps
Agent Frameworks and No-Code Builders
Coding Agents
AI Search and Research Apps
Voice, Speech, and Roleplay
Do GitHub Stars Tell You Which App to Pick?
What Does the Maintenance Split Tell You?
How Do I Pick and Run One of These?
Frequently Asked Questions
The Bottom Line

How Did I Rank These LLM Apps?

I graded all 52 apps on one axis the awesome lists ignore: is anyone still shipping it? Four of the 52 are already dead, including two archived repos and one whose parent company folded in late 2023 (Analytics India Magazine). "Does it exist" is the wrong question in a space moving this fast. "Was it touched this month" is the right one.

So every entry carries one of three statuses, and I want to be honest about how I assigned them. I run roughly 20 of these in real projects, from Ollama and Open WebUI on my own machine to Dify and Cline at work. The rest I graded on repo signals you can check yourself in five minutes: who backs it, when the last commit landed, whether releases are tagged on a cadence or just trail off. Star counts I treat with suspicion, for reasons the chart below makes obvious.

Here is the rubric, plainly:

Maintained. A first-party app from a company that has skin in the game, or a community project with commits in roughly the last six weeks, real releases, and a maintainer who answers issues. Production-considerable once you scope its credentials.
Slowing. It still works, and several are still widely deployed, but the commit cadence has dropped off (no meaningful push in two to seven months) or the project is mid-transition to something new. Fine to use; keep a fallback in mind.
Abandoned. Archived, orphaned by a shutdown, or quiet for nine months or more. Listed on purpose, so you recognize the dead fork before you copy a 2024 tutorial that points at it.

One caveat on the numbers. The star counts and last-commit dates here come straight from each project's GitHub page in June 2026, so they will drift after I publish; that drift is exactly why I lead with recency, not stars. Across the 52 apps, the split lands at 42 Maintained, 6 Slowing, and 4 Abandoned. Why does my list read 81% healthy when half of every "awesome" list is rot? Because this is a shortlist, not a census. The ratio you see is what survives the filter, which is the filter you wanted someone else to run for you.

Local Model Runners

If you want to run a model on your own hardware, this is where you start, and the category is dominated by one tool: Ollama has passed 175,000 GitHub stars (GitHub, June 2026), more than any other app in this directory except the automation platforms. These are the apps that pull weights, manage quantization, and expose a local API. Get this layer right and everything above it gets easier. For the deep dive on which runtime wins on your machine, the pillar covers llama.cpp versus Ollama versus vLLM in detail.

App	Maintainer	Status	Verdict
Ollama	Ollama (company)	Maintained	The default. One command to pull and run almost any open model, with a clean local API. If you run one tool locally, run this. Full walkthrough: the complete Ollama setup and model guide.
llama.cpp	ggml.org (community)	Maintained	The C++ engine half this ecosystem is built on, Ollama included. Run it raw only when you want to hand-tune quantization and squeeze a weak GPU.
LM Studio	LM Studio (company)	Maintained	The friendliest GUI for people who never touch a terminal. Closed source but free, with a model browser and a built-in server. Guide: downloading and running models in LM Studio.
Jan	Menlo Research	Maintained	Open-source LM Studio. A polished desktop app that runs models fully offline. The one I hand to people who distrust closed binaries.
text-generation-webui	oobabooga (community)	Maintained	The power user's cockpit. Every loader, every sampler, every extension. Overwhelming, but nothing else exposes this many knobs.
KoboldCpp	LostRuins (community)	Maintained	A single-file llama.cpp wrapper beloved by the local roleplay crowd. Tiny, fast to start, zero install ceremony.
vLLM	vLLM project	Maintained	Not a desktop app, a serving engine. When you outgrow Ollama and need real throughput across many users, this is the jump.
LocalAI	mudler (community)	Maintained	A drop-in OpenAI-compatible API you self-host. Best when you want existing apps to talk to local models with no code changes.
GPT4All	Nomic AI	Abandoned	Was the easiest on-ramp in 2023. The repo has been quiet since May 2025 (GitHub, June 2026) as Nomic moved on. Use Jan or LM Studio instead.

Chat UIs and Frontends

Once a model is running, you need something to talk to it, and this category is unusually healthy. Open WebUI leads it at over 143,000 GitHub stars (GitHub, June 2026), a full ChatGPT-style frontend that points at Ollama or any OpenAI-compatible endpoint. The rest split into self-hosted web apps and lightweight desktop clients. Pick by whether you want a server to run or a binary to download.

App	Maintainer	Status	Verdict
Open WebUI	Open WebUI (community)	Maintained	The category king. RAG, tools, multi-user, model management, all of it. The default UI for a local Ollama setup.
LibreChat	Danny Avila (community)	Maintained	The best multi-provider hub. One UI over OpenAI, Anthropic, Google, and local models, with agents and presets. My pick when I swap models all day.
Lobe Chat	LobeHub	Maintained	The prettiest of the bunch. Plugins, voice, vision, and a genuinely polished UX. A touch more opinionated than LibreChat.
Chatbox	Bin Huang (community)	Maintained	A cross-platform desktop client that just works. No server to run; point it at a key or a local endpoint and go.
Cherry Studio	Cherry HQ	Maintained	A desktop client that has quietly gotten excellent for knowledge work, with built-in agents and document chat.
big-AGI	Enrico Ros (community)	Maintained	Smaller and developer-flavored. Multi-model "beam" and persona features the bigger UIs still lack.

RAG and Chat-With-Your-Docs Apps

This is where most people actually want an LLM: pointed at their own documents. AnythingLLM has climbed past 62,000 GitHub stars (GitHub, June 2026) by being the most complete "chat with your files" app you can self-host. But this category also holds two of my four dead entries, so the maintenance column earns its keep here more than anywhere. RAG demos age fast.

App	Maintainer	Status	Verdict
AnythingLLM	Mintplex Labs	Maintained	The most complete chat-with-your-docs app. Workspaces, multiple vector DBs, desktop or Docker. The one I install for non-technical teams.
RAGFlow	InfiniFlow	Maintained	Deep-document RAG with serious parsing for tables, layouts, and OCR. Heavier to run, best results on messy PDFs.
Onyx	Onyx (company)	Maintained	Formerly Danswer. Enterprise-grade search and chat across your company's apps, with connectors for nearly everything.
Khoj	Khoj (company)	Maintained	Your second brain. Self-hostable, indexes your notes and files, and answers across them. Lovely for Obsidian users.
PrivateGPT	Zylon	Maintained	The name that launched the local-RAG wave. Still maintained by Zylon, still fully offline document Q&A.
Kotaemon	Cinnamon	Maintained	A clean open-source RAG UI with good defaults, inline citations, and an easy demo path.
Haystack	deepset	Maintained	deepset's production RAG framework, not an app. Reach for it when you are building a pipeline, not installing one.
Quivr	Quivr (company)	Slowing	Was a hot "second brain." The core repo has been quiet since mid-2025 (GitHub, June 2026) after the team pivoted to a RAG framework. Works, but watch it.
Verba	Weaviate	Abandoned	Weaviate's RAG showcase, now archived (GitHub, June 2026). A nice demo to read, not a thing to build on.

Agent Frameworks and No-Code Builders

If you want to build something rather than just chat, this is the deepest category in the directory, and the most volatile. The visual builders alone are enormous: Langflow sits above 150,000 GitHub stars and Dify above 146,000 (GitHub, June 2026). The split here is clean: code-first frameworks for developers, and drag-and-drop platforms for everyone else. Both halves are mostly Maintained, with two notable exceptions sliding toward Slowing. The model you wire into any of these matters as much as the framework, so see which open-source model to actually pick before you commit.

App	Maintainer	Status	Verdict
Dify	LangGenius	Maintained	The best open-source LLM app platform. Visual workflows, RAG, agents, and an API in one box, shipping constantly.
Langflow	Langflow (company)	Maintained	A polished node editor backed by a real company. Build agent flows visually, export an API.
n8n	n8n (company)	Maintained	Not LLM-specific, but at 194,000+ stars it has become the glue for production AI workflows. Self-hostable, endlessly useful.
LangChain	LangChain (company)	Maintained	The framework everyone complains about and still uses. 140,000+ stars. The default glue for LLM apps in Python and JS.
LlamaIndex	LlamaIndex (company)	Maintained	The data framework. If your app is mostly RAG, this is often a cleaner fit than LangChain.
CrewAI	CrewAI (company)	Maintained	The most popular multi-agent framework. Define roles, give them tools, let them collaborate. Pragmatic and well-documented.
AutoGPT	Significant Gravitas	Maintained	The 185,000-star project that started the autonomous-agent hype. Now a low-code platform; the original loop is mostly history.
Flowise	FlowiseAI	Maintained	Drag-and-drop LangChain. Build chatbots and agent flows visually, export an API. Great for prototypes and non-coders.
Letta	Letta (company)	Maintained	Formerly MemGPT. Treats long-term agent memory as a first-class concern. The interesting one to watch in stateful agents.
AutoGen	Microsoft	Slowing	Microsoft's multi-agent framework, now in maintenance mode. Microsoft directs new work to the Microsoft Agent Framework (Microsoft Learn, 2026); the community fork is AG2.
MetaGPT	DeepWisdom	Slowing	The "software company in a box" multi-agent demo. Impressive paper, but commits have thinned since early 2026 (GitHub, June 2026).

Coding Agents

Coding is the use case where open-source apps genuinely rival the paid tools, and the leader proves it: OpenHands has passed 78,000 GitHub stars (GitHub, June 2026) running as an autonomous agent that edits, tests, and iterates in a sandbox. This category lives or dies on the model behind it, so the freshness column matters less than which LLM you point it at. For that decision, I keep a separate scorecard.

App	Maintainer	Status	Verdict
OpenHands	All Hands AI	Maintained	Formerly OpenDevin. The leading open-source coding agent. Runs in a sandbox, plans, edits, tests, and iterates.
Cline	Cline (community)	Maintained	The best open-source coding agent inside VS Code. Plan and act modes, MCP support, bring your own key. My daily driver for autonomous edits.
Open Interpreter	Open Interpreter	Maintained	Lets a model run code on your machine to get things done. Powerful and a little terrifying, so sandbox it.
Goose	Block	Maintained	Block's open-source agent. Extensible via MCP, runs locally, and is genuinely good. The dark horse of this list.
Aider	Paul Gauthier (community)	Maintained	The terminal coding agent purists love. Git-aware, model-agnostic, no IDE required. Pairs beautifully with a strong model: the best LLM to drive a coding agent.
Continue	Continue (company)	Maintained	The open-source Copilot alternative for VS Code and JetBrains. Autocomplete plus chat, your model, your rules.
Tabby	TabbyML	Slowing	A self-hosted assistant with autocomplete and chat. Solid, but commits have thinned since March 2026 (GitHub, June 2026).
gpt-engineer	gpt-engineer org	Abandoned	The "describe an app, get a codebase" pioneer, now archived (GitHub, June 2026). Read it for history; use OpenHands or Aider to actually ship.

AI Search and Research Apps

This is the smallest category, but it is where open source quietly caught the commercial answer engines. These tools pair a model with a search backend to produce sourced answers or full reports instead of a wall of links. Most are Maintained, with one Stanford research project that is brilliant but should be treated as code, not a product. The model you choose drives the quality of the synthesis, which is its own rabbit hole.

App	Maintainer	Status	Verdict
GPT Researcher	Assaf Elovic (community)	Maintained	Point it at a question, get a sourced report. The most useful open research agent I have run.
Perplexica	ItzCrazyKns (community)	Maintained	An open-source Perplexity. Pairs a local model with SearXNG for private AI search. Very usable.
Morphic	Yuki Hattori (community)	Maintained	A clean generative answer-engine UI you can self-host or deploy on Vercel. Small but well-kept.
(https://github.com/stanford-oval/storm)	Stanford OVAL	Slowing	Stanford's research-to-article system. Brilliant as a paper and a demo; treat it as research code, quiet since fall 2025 (GitHub, June 2026).

Voice, Speech, and Roleplay

The last category is the most fragmented, which is why it has the lowest Maintained ratio in the directory. Speech and character apps are easy to start and hard to keep current. OpenAI's Whisper model alone has over 103,000 GitHub stars (GitHub, June 2026), but the interesting work happens in the wrappers around it, and one of the most beloved TTS projects here was orphaned when its company shut down.

App	Maintainer	Status	Verdict
whisper.cpp	ggml.org (community)	Maintained	Whisper transcription in portable C++. Runs on a laptop, a phone, a Pi. The speech-to-text backbone of countless local apps.
Whisper	OpenAI	Maintained	The open-weight STT model itself. The repo updates rarely because the model is finished, and the weights are everywhere.
SillyTavern	SillyTavern (community)	Maintained	The power-user frontend for AI roleplay and characters. Endless customization; pairs with KoboldCpp or any backend.
faster-whisper	SYSTRAN	Slowing	The fast CTranslate2 reimplementation everyone actually deploys for transcription. Still the workhorse, but pushes have slowed since late 2025 (GitHub, June 2026).
Coqui TTS	Coqui (defunct)	Abandoned	The open TTS standard, orphaned when Coqui the company shut down in late 2023 (Analytics India Magazine). Use the actively maintained Idiap community fork.

Do GitHub Stars Tell You Which App to Pick?

No, and the gap is wider than most directories admit. The top of the star chart is led by n8n at 194,000+ stars (GitHub, June 2026), a tool that is not even LLM-specific, followed by AutoGPT at 185,000, whose original autonomous loop is now mostly historical. Stars measure attention at the moment a project went viral. They do not measure whether anyone is still fixing bugs this quarter.

That mismatch is the single most useful thing to internalize before you install anything. A 50,000-star tool like Goose, shipping daily, will serve you better than a 185,000-star project coasting on a 2023 launch. The chart below ranks the eight most-starred apps in this directory. Read it as a popularity contest, not a quality ranking, and then cross-reference the maintenance column above before you commit.

What Does the Maintenance Split Tell You?

The clearest signal across all 52 apps is not which one is best. It is who stands behind it. Every Abandoned entry has the same backstory: a company that folded (Coqui), a vendor that archived its demo (Verba, from Weaviate), a pioneer that got superseded (gpt-engineer), or a single maintainer who moved on (GPT4All). Not one of them died because the idea was bad. They died because nobody had a standing reason to keep shipping.

That pattern repeats across the categories below. The deepest category, agent frameworks and builders, is also the one with the most company backing, which is exactly why it stays healthy. The thinnest categories, search and voice, carry the highest share of single-maintainer risk. Where would you rather place a production bet?

How Do I Pick and Run One of These?

Picking the app is half the job; the other half is matching it to a model and a runtime. The honest order of operations I follow: decide what you are building, pick the app from the category above, then choose the model that drives it. Most people skip the last step and wonder why a great app gives mediocre answers. The app is a shell. The model is the engine.

So if you are running anything locally, settle the runtime first. For most people that means Ollama for a clean command-line setup or LM Studio for a friendly GUI, both of which slot under the chat UIs and RAG apps above. Then pick the brain. If you are coding, the model choice swamps the app choice, so weigh it carefully in the best LLM for coding. If you are deciding between hosted frontier models to power an agent, the trade-offs in Claude Opus versus GPT-5 and DeepSeek R1 versus V3 will save you a few wrong turns. And if you want to stay fully open and self-hosted, start from the best open-source LLM and work back to the app.

Frequently Asked Questions

What is the awesome-llm-apps repo?

"awesome-llm-apps" usually means the GitHub repo Shubhamsaboo/awesome-llm-apps, a collection of 100-plus runnable AI agent and RAG app templates with full source code, now past 115,000 stars (GitHub, June 2026). It is a cookbook you build from. This directory ranks 52 finished apps you install instead.

What are the best open-source LLM apps in 2026?

For most people the best picks are the actively maintained leaders in each category: Ollama or LM Studio to run models, Open WebUI or LibreChat to chat, AnythingLLM or Dify to build, and OpenHands or Cline to code. All rank Maintained here, with Open WebUI alone above 143,000 GitHub stars (GitHub, June 2026).

How do I run these LLM apps locally?

Most of these apps need a model and a runtime underneath them. Install Ollama or LM Studio first, pull an open-weight model, then point a frontend like Open WebUI or AnythingLLM at the local endpoint. The pillar covers hardware requirements and runtime trade-offs in the guide to running LLMs locally.

Which LLM apps are abandoned or unsafe to rely on?

Four of the 52 here are dead: GPT4All (quiet since May 2025), Verba and gpt-engineer (both archived), and Coqui TTS (company shut down in late 2023, Analytics India Magazine). They still run, but nobody is patching them. For Coqui, use the Idiap community fork that picks up active maintenance.

Do GitHub stars mean an LLM app is good?

No. Stars measure attention at launch, not whether a project still ships. n8n leads this directory at 194,000+ stars yet is not LLM-specific, while AutoGPT's 185,000 stars sit on a loop that is now mostly historical (GitHub, June 2026). Check the last commit date before you trust the badge.

The Bottom Line

A useful LLM app directory is not the longest list. It is the one that already threw out the dead forks for you. The 52 apps here are the ones I would actually evaluate in 2026, and the most valuable column is the status: 42 Maintained, 6 Slowing, 4 Abandoned.

If you remember one thing, make it this: pick by who is still shipping, not by who went viral. Company-backed and actively-maintained apps cluster in the Maintained column for a reason, while the famous abandoned ones are famous precisely because they launched loud and then stopped. Start with a boring, well-kept app, add a riskier one only when it earns the slot, and check the last commit date either way. For the runtime and hardware layer underneath all of it, go back up to the complete guide to running LLMs locally.