There’s a question I’ve been avoiding for about two years.
What happens to all of this if something happens to me?
Not in a morbid way. Just practically. I run 27 client sites. I have an AI stack with dozens of moving parts — Cloud Run services, scheduled jobs, Notion databases, Workers that fire on their own while I sleep. I’ve built systems that work exactly the way I want them to work, in exactly the ways I understand, documented in exactly the language that makes sense to me.
The bus factor for this entire operation is one. It’s me. If I’m not here, none of it survives in any meaningful way.
I’ve been sitting with that long enough that I think it’s time to say it out loud.
The bus factor is an old software engineering concept. It asks: how many people would need to get hit by a bus before this project fails? One is the worst possible number. It means everything lives in a single person’s head — their habits, their passwords, their way of naming things, their unwritten rules about how the system works.
Most solo operators are a bus factor of one. They know this and they don’t talk about it because it sounds like a personal failing. Like you should have hired more people, or documented better, or not let yourself become the single point of failure for something people depend on.
But I think the honest version is more complicated than that. A lot of what makes a solo operation valuable is exactly the thing that makes it fragile: it’s shaped entirely around one person’s judgment. The reason the system works is because I know when to break the rules I wrote. I know what the edge cases are before they happen. I know which automations to trust and which ones to watch. That’s not something you write in a runbook.
So the question isn’t just “how do I document this better.” It’s “how do I make the judgment portable without turning it into something that loses the judgment in the process.”
I’ve been building toward an answer, in pieces, over the last several months.
The first piece was Notion as the control plane. Everything that matters about how this operation runs lives in Notion — specs, work orders, site credentials, content pipelines, system standards, the doctrine documents that explain why things are built the way they are. If I disappeared tomorrow, someone with the right access could open that workspace and read their way into understanding the shape of the operation, even if they couldn’t run it yet.
The second piece was the two-plane architecture — Notion for thinking and storage, GCP for compute. Every Cloud Run service, every scheduled job, every Worker is defined somewhere in Notion before it runs somewhere on GCP. The compute is durable. The logic is documented. Those are two different things, and keeping them separate means neither one is a black box.
The third piece is the hardest and I’m the least done with it: making the judgment readable.
I write doctrine pages. Long ones, sometimes. They explain not just what the system does but why it works that way — what the original problem was, what I tried that didn’t work, what the rule is now and what would have to be true for the rule to change. I write them mostly for myself, because I forget things. But they’re also written for the hypothetical person who has to pick this up without me.
That hypothetical person might be a future employee. It might be a contractor. It might be an AI agent working from a context window that needs to understand the operation well enough to continue it.
It might be my partner, trying to figure out what to do with the business side of things if I’m not around.
That’s the version that focuses the mind.
I don’t have this solved. I want to be clear about that.
What I have is a direction. The direction is: every decision should live somewhere outside my head. Every system should be explainable by someone who didn’t build it. Every credential should be in the registry, every automation should have a spec, every rule should have a reason written next to it.
It’s slow work. It runs against the instinct to just build the thing and move on. There’s always something more urgent than documentation, and “I’ll remember how this works” is almost always true right up until it isn’t.
But I’ve started treating the documentation as part of the product. Not the boring part — the part that makes the product real. A system that only works because I’m here isn’t really a system. It’s a performance.
The goal is to build something that could survive me. Not because I’m planning to leave, but because the work of making it survivable is also the work of making it understandable, and a system I can’t fully explain is a system I don’t fully own.
If you’re running something like this — solo or nearly so, more complexity than your headcount would suggest — I’d ask you the same question I’ve been sitting with.
If something happened to you tomorrow, what would survive?
Not what you hope would survive. What actually would.
I’ve hired developers. Good ones. For specific things — infrastructure, custom integrations, work that genuinely required someone to sit down and write production code from scratch — it was the right call.
But if I’m honest about the full list of things I’ve brought developers in for over the years, a meaningful chunk of it wasn’t really developer work. It was workflow work. It was “I need this thing to happen automatically when that other thing happens” work. It was “why does this still require a human to touch it” work.
That category of problem has a different answer now.
Here’s the pattern I kept running into:
I’d have a clear picture of what I wanted. Data from one tool synced into Notion. A webhook that logged events automatically. A scheduled job that pulled information from an external API every morning and wrote the results somewhere I could see them. Nothing exotic. Stuff that, described out loud, sounds almost embarrassingly simple.
But turning that description into something that actually ran required code. And writing code required a developer. And hiring a developer for something this small felt like bringing a contractor in to change a lightbulb — technically the right tool, but something about the ratio felt off.
So a lot of it didn’t get built. The workflow stayed manual. The friction stayed.
Last night I built ten of those things in three hours.
Notion Workers — their new hosted serverless platform, shipping in beta as of May 13, 2026 — lets you deploy real code inside Notion’s infrastructure without managing a server. Combined with Claude Code, which writes the TypeScript while you describe what you want in plain English, the gap between “I know what I want” and “it exists and is running” is smaller than it has ever been.
I’m not a developer. I operated the process. I described each Worker, reviewed what Claude Code wrote, ran the deploy commands, checked that it worked. When something broke, I read the error and passed it back. The loop was fast enough that two failures in ten attempts felt like a normal part of the session, not a crisis.
By midnight I had a live webhook endpoint receiving authenticated traffic from the internet and writing verified events to a Notion log page. Automatically. While I slept.
That’s workflow work. It just didn’t require a developer to get there.
I want to be careful about what I’m claiming here.
There are things that genuinely need a developer. Complex systems. Production APIs with serious security requirements. Anything where a bug has real consequences for real people. I’m not suggesting you staff down your engineering team based on a three-hour session with a CLI tool.
What I’m suggesting is narrower: there is a category of work that has always felt like it needed a developer but actually needed something else. It needed clarity about what you wanted. It needed a good description. It needed someone willing to read an error message and try again.
That work is yours now, if you want it.
The practical question is where to start.
Start with the thing that’s most manual in your current workflow. The task someone does by hand because no one ever got around to automating it. The data that lives in one tool but should live in another. The notification that goes out because someone remembered to send it, not because the system sent it automatically.
Describe it out loud. If you can explain it to another person in two or three sentences, you can build it. Open Claude Code. Tell it what you want. Run the commands it gives you.
You might be surprised how far that gets you before you need to call anyone.
Notion Workers beta is free through August 11, 2026. The ntn CLI installs in one line on macOS or Linux. Business or Enterprise plan required to deploy Workers.
There’s a word that’s been sitting in my head lately and I think it’s the right one.
Not developer. Not user. Not prompt engineer — please, not that.
Operator.
The developer builds the system. The user benefits from it. The operator runs it.
Operators have always existed. They’re the people who know a tool well enough to get unusual things out of it — who understand what’s possible, who can configure and connect and troubleshoot, who treat software as infrastructure rather than a product to consume. In a restaurant, the chef is the operator. In a warehouse, it’s the floor manager who actually knows where everything is and why the inventory system does what it does.
In most software companies, the operator was assumed to be technical. You needed to code, or at least to read code, to run anything at a real level of depth. Everyone else was a user — handed a finished product, expected to stay in the designated lanes.
That line is moving.
Last night I deployed ten Notion Workers in three hours. Workers are Notion’s new hosted serverless platform — real code, running inside Notion’s infrastructure, no server to manage. I built a webhook endpoint that receives authenticated HTTP traffic from the internet and logs it to a Notion database. I built data sync Workers. I built scheduled jobs.
I am not a developer.
What I am is an operator. I know what I want the system to do. I can describe it precisely. I understand how the pieces connect even when I can’t write the connection myself. And I have Claude Code, which handles the TypeScript while I handle the architecture.
The stack looks like this:
Claude Code — the reasoning layer. Describe what the Worker should do in plain English. Claude Code writes the code, catches errors when you paste them back, and tells you exactly what commands to run.
ntn CLI — the deployment layer. Four commands: scaffold, write, push secrets, deploy. Single-command deploys. You run what Claude Code tells you to run.
Notion Workers — the execution layer. Serverless functions running on Notion’s infrastructure. They connect to external APIs, respond to webhooks, sync data, run on schedules. They do the work while you do something else.
That’s it. Three layers. None of them require you to be a developer to operate.
The operator’s job in this stack is not to write code. It’s to know what should exist.
That sounds simple. It isn’t. Knowing what should exist means understanding your own operations well enough to identify where the friction is, what’s being done by hand that shouldn’t be, what would run better automatically. It means being able to describe a system clearly enough that an AI coding agent can build it. It means reviewing what gets built and knowing whether it’s right.
That’s real skill. It’s just not the skill most people thought they needed.
For years the implicit message was: if you can’t build it, you can’t have it. The work of describing exactly what you want, of thinking through the logic, of understanding how systems connect — that work was treated as a prerequisite for coding, not a valuable thing in its own right.
Now it’s the job.
I’m not going to tell you the technical barrier is gone. It isn’t. You still hit errors. You still have to read them and understand them well enough to know if Claude Code’s fix makes sense. You still have to think before you build.
But the barrier has moved. The question is no longer “can you write TypeScript” — it’s “can you think clearly about what you want and describe it precisely.”
Most people reading this can do that. They’ve been able to do that. They were just told, implicitly or explicitly, that it wasn’t enough.
It’s enough now.
The Notion Workers beta is free through August 11, 2026. The ntn CLI installs in one line on macOS or Linux. Deploying Workers requires a Business or Enterprise plan. If you’ve been running your operations in Notion and watching things like Workers from the sidelines because you figured it was for developers: it’s for operators too. You might already be one.
It was late. I had Claude Code open on my laptop and a fresh cup of coffee going cold next to it.
Notion had shipped Workers eight days earlier — their new hosted serverless platform, basically “run real code inside Notion without managing a server.” I’d been meaning to dig in. Last night I finally did.
I want to tell you what that actually looked like. Not a tutorial. Not a polished case study. Just what happened, in order, including the parts that didn’t work.
By midnight I had ten Workers deployed and a live webhook endpoint logging authenticated traffic from the internet into a Notion page. The whole thing took about three hours.
I did not write TypeScript.
Here’s the honest version of how it went.
The first Worker took the longest — maybe 35 minutes — because I was figuring out the CLI at the same time as building the thing. The ntn tool is straightforward once you understand it: scaffold, write the code, push your secrets, deploy. Four steps. But the first time through any new tool you’re reading error messages and second-guessing yourself.
Claude Code handled the TypeScript. I described what I wanted — a Worker that receives a POST request, verifies an HMAC signature, and appends a line to a Notion log page. Claude Code wrote it. I ran the commands it told me to run. The Worker deployed.
I tested it. It worked.
The second one took 22 minutes. The third took 15. By Worker five I was moving fast enough that I stopped tracking individual times and just kept going.
Two of them didn’t work on the first try. One had a secret I’d named wrong in the environment — my fault, five minutes to fix. The other had a logic error in how it was handling the Notion API response. Claude Code caught it when I pasted the error back in, rewrote the relevant section, and I redeployed. Eight minutes total for that dead-end.
Neither failure felt like a crisis. That’s the part I want to underline. When something broke, the path forward was obvious: read the error, paste it back to Claude Code, get a fix, redeploy. The loop was tight enough that failure was just a speed bump, not a wall.
At 02:54 in the morning, I sent a test ping to Worker #8.
The webhook logger received it, verified the HMAC signature, and wrote this to a Notion page in real time:
🔔 2026-05-21T02:54:44.452Z [claude-test:test] {"event":"test","message":"Hello from Worker #8 self-test","sender":"claude-code"}
I sat there for a second looking at that.
There’s something specific about seeing a system you built actually receive traffic. It’s not the same as a script running on your laptop. This was a deployed endpoint, on Notion’s infrastructure, receiving an authenticated HTTP request from the open internet and writing the result to a database. Automatically. Without me doing anything after the initial deploy.
That’s a different category of thing than what I had before.
I want to be honest about what I am, technically. I’m not a developer. I’ve picked up enough over the years to be dangerous — I can read code, I understand how APIs work, I’ve shipped things — but I’m not someone who sits down and writes TypeScript from scratch.
Last night didn’t require that. What it required was knowing what I wanted, being able to describe it clearly, and being willing to run commands and read errors.
That’s it.
The question I keep hearing from people who run operations like mine — agencies, small teams, people who live in tools like Notion and have always hired out the code work — is whether any of this AI coding stuff is actually for them or if it’s still fundamentally a developer story with a better interface.
Last night felt like an answer. Ten Workers. Three hours. No TypeScript.
If you can describe what you want clearly enough to explain it to another person, you can build this. The friction that used to live between “I know what I want” and “it exists in the world” is genuinely smaller now.
Not gone. Smaller.
You still have to show up. You still have to read the errors. You still have to think through what you’re building before you build it.
But if you’ve been waiting for some invisible threshold of technical credibility before you try — you’re past it. You were probably past it a while ago.
The Notion Workers beta is free through August 11, 2026. The ntn CLI installs in one line. Business or Enterprise plan required to deploy.
Notion shipped Workers on May 13, 2026. By last night I had ten of them running in production, including a live HMAC-verified webhook endpoint that’s actively logging events. Total build time: about three hours.
I didn’t write TypeScript by hand. Claude Code did most of the typing.
Here’s what that actually looked like — and what it means for the non-developer Notion power user who’s been watching the Workers announcement and wondering if it’s for them.
What are Notion Workers? Notion Workers are hosted serverless functions that run inside Notion’s infrastructure. You write code, deploy it through the ntn CLI, and Notion runs it in a secure sandbox — no server to manage. They’re free through August 11, 2026, then run on Notion credits. Deploying Workers requires a Business or Enterprise plan.
What Notion Workers Actually Are (The One-Paragraph Version)
If you’ve used Notion’s built-in database automations — the lightning bolt icon — Workers are that concept extended to real code. They can call any external API, respond to webhooks, sync data from Stripe or Zendesk or GitHub, and write results back to Notion databases. The CLI (ntn) is available on all plans. Deploying Workers requires Business or Enterprise.
Do You Need to Know TypeScript to Build Notion Workers?
Technically, Workers are written in TypeScript. Practically, if you have Claude Code, the answer is no.
Claude Code (currently at v2.1.144 as of May 19, 2026) scaffolds Workers from plain-English descriptions. You describe what the Worker should do. Claude Code writes the src/index.ts, handles the ntn workers env push for secrets, and tells you exactly what commands to run. You copy the command. The Worker deploys.
The workflow looks like this:
ntn workers new my-worker-name — scaffold the project
ntn workers deploy --name my-worker-name — ship it
That’s it. The only thing you actually type is the deploy commands. Claude Code fills in the gap between them.
What We Built in 3 Hours
Ten Workers, averaging about 18 minutes each, including two dead-ends that took 5–8 minutes to diagnose and abandon.
The most useful one is Worker #8: an HMAC-verified webhook logger. Any external service — GitHub, Stripe, a cron trigger, another Claude Code session — can POST to the Worker’s endpoint with a shared secret, and it auto-appends a timestamped line to a Notion log page. The webhook log shows its first self-test ping from Claude Code at 02:54 UTC:
🔔 2026-05-21T02:54:44.452Z [claude-test:test] {"event":"test","message":"Hello from Worker #8 self-test","sender":"claude-code"}
That’s a live, verifiable event log. Not a draft. Not a mock. A deployed Worker receiving authenticated HTTP traffic and writing to Notion.
The ntn workers env push command works cleanly for both NOTION_API_TOKEN and non-Notion secrets like TYGART_WP_USER and WEBHOOK_SECRET — one of the key things we needed to confirm before trusting the stack at scale.
The Design Principle That Makes This Actually Work
The best insight from Notion’s Workers documentation: use code for deterministic work, use AI for judgment calls.
A Worker that pulls invoice status from Stripe and updates a Notion database doesn’t need AI. It needs reliable, cheap code execution. That’s what Workers give you. A Claude Sonnet 4.6 (claude-sonnet-4-6) or Opus 4.7 (claude-opus-4-7) agent that reads those Notion rows and drafts follow-up emails is handling the judgment call. Those are two different tools for two different jobs.
When you collapse that distinction — letting AI do everything — you pay AI prices for work that shouldn’t require AI reasoning. Workers run at a fraction of the cost of AI credits. Notion’s own example calculations put a daily sync job at roughly one cent per month. The AI layer sits on top for the parts that actually need it.
This is the architecture: Workers handle the plumbing. Claude handles the reasoning. You stop paying Opus rates for jobs a ten-line TypeScript function can do.
The Part Nobody Else Is Writing About
Every guide covering Notion Workers frames it as a solo-developer workflow. You sit down, you know TypeScript, you build a Worker over an afternoon.
That’s not how this went.
Claude Code is listed in Notion’s own documentation as a first-class deployment partner for Workers. The ntn CLI was explicitly designed to work with coding agents — same interface for humans and agents. When you treat Claude Code as the author and yourself as the operator running the commands it outputs, you get through ten Workers in a session that most developers would take a week to plan.
The non-developer angle is real. If you run Notion as your operating system — databases, automations, dashboards — and you’ve been watching the Workers announcement wondering whether it requires a CS degree, the answer in May 2026 is: not if you have Claude Code. The scaffolding is a one-line command. The deployment is a one-line command. Claude Code fills in the gap between them.
Three Things to Know Before You Start
Business or Enterprise plan required to deploy. The CLI (ntn) installs on any plan and runs free. Deploying Workers needs Business or Enterprise. Check your plan before you spend an afternoon scaffolding.
macOS and Linux only as of May 2026. Windows users need WSL2. Native Windows support is listed as coming soon. If you’re on Windows without WSL2, that’s your first step.
Free through August 11, 2026. After that, Workers run on Notion credits. Build and optimize now while the cost is zero. The free period gives you enough runway to understand your actual usage patterns before you’re paying for them.
Frequently Asked Questions
What is the Notion Workers free period?
Notion Workers are free to try during the beta period, which runs through August 11, 2026. After that date, Workers will run on Notion credits. The free period is a good window to build, test, and optimize your Workers before metered usage begins.
Can non-developers build Notion Workers?
Yes, if you have an AI coding agent like Claude Code. Workers are written in TypeScript, but Claude Code can generate the Worker code from a plain-English description. You run the scaffold and deploy commands; Claude Code writes the code. No prior TypeScript knowledge required.
What Notion plan do you need for Workers?
The ntn CLI is available on all Notion plans. Deploying and managing Workers requires a Business or Enterprise plan.
How does Claude Code work with Notion Workers?
Claude Code (v2.1.144 as of May 2026) integrates directly with the ntn CLI. Notion designed the CLI as a tool for both humans and coding agents — same interface, same commands. Claude Code scaffolds the Worker TypeScript, sets environment variables, and outputs the exact deploy commands to run.
What can Notion Workers do?
Workers can call any external API, respond to incoming webhooks (with HMAC verification), sync data between external services and Notion databases, run scheduled tasks, and execute custom business logic. Common use cases include syncing Stripe payments, Zendesk tickets, GitHub issues, or any service with an API into Notion.
Is the ntn CLI available on Windows?
As of May 2026, the ntn CLI is available on macOS and Linux. Windows support is listed as coming soon. Windows users can use WSL2 in the meantime.
The Bottom Line
Ten Workers. Three hours. A verified webhook endpoint logging live traffic. Claude Code did the TypeScript. The ntn CLI did the deployment. Notion’s infrastructure handled everything else.
The question isn’t whether Notion Workers are for developers. The question is whether you have a coding agent. If you do, the friction is gone.
Last week I wrote about the three-file split every team should set up in their repo: CLAUDE.md, .claude/settings.json, and .claude/settings.local.json. That gets a team to a sane shared baseline. It does not stop a single engineer with admin rights on their laptop from disabling every guardrail you wrote.
If you are deploying Claude Code to more than a handful of engineers — anyone past Series B, anyone regulated, anyone whose CISO has asked a single pointed question about AI tooling — repo-level settings are insufficient. The control you want is managed-settings.json, and most teams I talk to either do not know it exists or have not deployed it.
Where managed-settings.json Actually Lives
Claude Code reads settings in a strict precedence order. Managed settings sit at the top and cannot be overridden by anything a user does in their repo, their home directory, or their environment. The file location depends on the OS:
You push the file via whatever you already use to manage developer machines. On macOS that is MDM — Jamf, Kandji, Mosyle. On Windows it is Group Policy Preferences. On Linux fleets, your config management tool of choice — Ansible, Chef, whatever survived your last platform team rewrite. The file does not need to be created by Claude Code itself. It just needs to be present at the path above, owned and writable only by an admin account, and readable by the user running claude.
The One Rule That Earns Its Keep: permissions.deny
Of every field in managed-settings.json, the one that pays for the entire deployment effort is permissions.deny. Deny rules at the managed-settings tier take effect regardless of any allow or ask rules at lower scopes. A user cannot grant themselves permission to do something an admin has denied — not in their project settings, not in their personal settings, not via a one-time CLI flag.
Concretely, here is a minimum-viable managed file for a team that wants to stop the obvious foot-guns:
That blocks Claude from curl-ing arbitrary URLs (the most common vector for accidental data exfiltration in agentic loops), reading anything in an .env file, and deleting filesystem roots in a Bash one-liner gone wrong. It does not stop legitimate work. It stops the long tail of “I didn’t realize it would do that.”
The Drop-In Directory Is the Underrated Piece
The single-file model breaks the moment you have more than one team contributing policy. Security wants curl blocked, platform wants kubectl delete blocked, the data team wants reads against the /data/prod/ mount blocked. Funneling all three through a single admin-owned file becomes a coordination tax.
Claude Code supports a drop-in directory at managed-settings.d/ in the same parent directory as managed-settings.json. Files in that directory are merged alphabetically — same convention as systemd and sudoers.d. Layout looks like this:
/Library/Application Support/ClaudeCode/
├── managed-settings.json # base policy
└── managed-settings.d/
├── 10-security.json # security team owns
├── 20-platform.json # platform team owns
└── 30-data.json # data team owns
Each team owns one file. They push their fragment through their own MDM channel without touching the others. Merge order is alphabetical, so the number prefix matters — later files override earlier ones for any overlapping keys, but permissions.deny rules always accumulate. Nothing a later file does can unblock something an earlier file denied.
What Belongs in Managed Settings — and What Does Not
Managed settings is a heavy hammer. Use it for things that must not be overridable. Everything else belongs in the repo’s .claude/settings.json, where engineers can iterate without filing a ticket.
Belongs in managed:
Deny rules for credentials, network egress, destructive shell operations
Telemetry / opt-out flags if your contract with Anthropic requires training data opt-out
Default model if you have a real reason to pin — most teams should let repos choose
Audit log paths if you are forwarding to a SIEM
Does not belong in managed:
Project-specific subagents or hooks (these live in the repo)
CLAUDE.md content (repo)
Allow rules — these are better as defaults at the repo scope, where engineers can adjust per-task
Verifying the Policy Is Actually Active
Pushing a config file is not the same as enforcing one. After deployment, run claude config list on a test machine and confirm the managed entries show up. Then attempt something the deny rule blocks — try a curl command, ask Claude to read an .env. The denial should be immediate and unambiguous, not a quiet skip. If a user can override it from their repo settings, the file is not at the right path or not readable by the user account running claude.
Model Selection at the Org Level
If you do pin a default model in managed settings — and I would argue most teams should not — read the model docs at docs.anthropic.com/en/docs/about-claude/models before writing the version string. Model identifiers change. As of this writing the workhorse is claude-sonnet-4-6, the flagship is claude-opus-4-7, and the fast option is claude-haiku-4-5-20251001. Hardcoding a model string in a managed file that nobody touches for six months is how you end up running last year’s model in production.
Where This Approach Loses
Managed settings cover the local Claude Code process. They do not cover the Anthropic Console, the Claude web app, or any MCP server an engineer connects to manually. If your threat model includes data leaving via the web app, managed settings on developer laptops are not the answer — the Enterprise plan’s org-level controls and SSO are. The two layers compose. Neither replaces the other.
Managed settings also do nothing about an engineer who runs Claude Code on a personal machine outside MDM scope. That is a device management problem, not a Claude Code problem, and the fix is the same as it has always been: do not let unmanaged machines touch production code.
The 30-Minute Rollout
Pick one platform — start with whichever fleet is largest, usually macOS
Write the minimum-viable managed-settings.json above
Push it to one test machine via MDM, verify with claude config list
Try three things the deny rules should block; confirm all three are blocked
Roll to the rest of the fleet
Set up the managed-settings.d/ directory so other teams can layer their own fragments without coordination
The whole exercise is half a day of work for a platform engineer who already knows your MDM. The alternative is hoping every engineer reads the same Notion page about which commands not to run. Hope is not a security control.
Most “Claude Code changed my life” posts are vibes. The interesting case studies are the ones with a number attached — a PR count, a token spend, a defect rate, a codebase size. After spending the week reading every concrete writeup I could find and cross-referencing them against Anthropic’s own internal usage report, three patterns hold up. Everything else is marketing.
Here is what the credible Claude Code case studies actually say, what they share in common, and where the wheels come off when teams try to repeat them.
Case 1: The 350k-line solo codebase
The most cited solo-developer case study right now is a maintainer of a 350,000+ line codebase spanning PHP, TypeScript/React, React Native, Terraform, and Python. Since August 2025, 80%+ of all code changes in that codebase have been written by Claude Code — generated, then corrected by Claude Code after review, with only minimal manual refactoring. The author has been working in commercial software for 10+ years, so this is not a beginner overstating things.
The two operational constraints they call out are the ones that matter:
Context selection is the job. A 200k token context window is less than 5% of a codebase this size. Include the files that show your patterns, exclude anything irrelevant, and accept that “too much context” degrades output as badly as “too little.”
Speed parity is the gate. If an LLM implementation isn’t at least as fast as doing it yourself, you’ve added a tool and lost time. They keep working documents to 50–100 lines and start every task with the bare minimum context.
This is the case study to send to anyone asking “does Claude Code work on legacy code.” The answer is yes, but only after you treat context curation as a first-class engineering activity.
Case 2: Anthropic’s own internal teams
Anthropic published a usage report covering ten internal teams. It is the highest-signal document in the ecosystem because every example is from a team that has unlimited access and zero incentive to oversell it. The patterns worth stealing:
Data Infrastructure lets Claude Code use OCR to read error screenshots, diagnose Kubernetes IP exhaustion, and emit fix commands. The team is not writing prompts about Kubernetes — they’re handing Claude a screenshot and a goal.
Growth Marketing built an agentic workflow that processes CSVs of hundreds of existing ads with performance metrics, identifies underperformers, and uses two specialized sub-agents to generate replacement variations under strict character limits. Sub-agents matter here — a single agent loses the constraint discipline.
Legal built a prototype “phone tree” to route team members to the right Anthropic lawyer. Non-engineering team, real internal tool, shipped.
Finance staff describe requirements in natural language; Claude Code generates the query and outputs Excel. No SQL skill required from the requester.
The Claude Code product team itself uses auto-accept mode for rapid prototyping but explicitly limits that pattern to the product’s edges, not core business logic. The RL Engineering team reports auto-accept succeeds on the first attempt about one-third of the time. That’s the honest number to hold onto when someone tells you their agent “just works.”
Case 3: The Sanity staff engineer’s six-week journey
The single most useful sentence in any Claude Code case study this year came from a staff engineer’s six-week writeup at Sanity: “First attempt will be 95% garbage.” That’s not a complaint — it’s an operating manual. The engineer’s workflow runs three or four parallel agents, treats every first pass as a draft to be re-prompted, and reserves human attention for architecture and steering rather than typing.
This is also the case study that matches the Pragmatic Engineer’s February 2026 survey of 15,000 developers, which ranked Claude Code as the most-used AI coding tool on the market. The teams who report the biggest gains are not the ones treating it like autocomplete. They’re the ones running multiple threads, accepting that most first drafts are throwaway, and putting their senior judgment on review rather than authorship.
What every credible case study has in common
Cross-reference the three above with the dozen other writeups that include real numbers and the same five operational habits show up every time:
A written context doc. Every successful team has something Claude reads first — a CLAUDE.md, a .clauderules file, a project README that defines patterns and conventions. Teams without one get inconsistent output.
Sub-agents for constraints. One agent that has to remember the character limit, the style guide, the schema, and the deadline will drop one of them. Two agents — generator and constraint-checker — won’t.
Real review on the way in. The 80% figure from the 350k-LOC case includes “corrected by Claude Code after review.” Nobody is shipping unreviewed agent output to production and reporting wins.
A measurement loop. Faros and Jellyfish reports both show teams using Claude Code analytics to track PRs and lines shipped with AI assist. The teams that measure ship more; the teams that don’t, drift.
Honest scoping. Auto-accept on edges, synchronous prompting on core business logic. Every team that ignores this distinction generates the “tech debt nightmare” posts.
Where the case studies break down
Two warnings from the data. First, Jellyfish’s AI Engineering Trends report shows a 4.5x increase in companies running agentic coding workflows, but most engineering teams using these tools spend $200–$600 per engineer per month and report a 1.6x productivity multiplier — not the 10x that vendor marketing implies. The case studies you read are the wins; the median outcome is more modest.
Second, the model version you run matters more than any workflow trick. As of this week the flagship is claude-opus-4-7, the workhorse is claude-sonnet-4-6, and the fast option is claude-haiku-4-5-20251001. Opus 4.7 lifted resolution on a 93-task coding benchmark by 13% over Opus 4.6 — including four tasks that neither Opus 4.6 nor Sonnet 4.6 could solve. Teams running on stale model strings are leaving real capability on the table.
The takeaway
If you only steal one thing from the credible case studies, steal the context discipline. The 350k-LOC maintainer keeps documents to 50–100 lines. Anthropic’s own teams use sub-agents to enforce constraints. The Sanity engineer runs parallel agents and treats first drafts as garbage by default. None of these patterns require a special prompt or a hidden flag. They require deciding, before you start a task, what Claude is allowed to see and what it isn’t.
That’s the whole game. The teams shipping 80% of their code with Claude Code aren’t using a better model — they’re feeding it a better context.
Once you stop asking what Claude is and start asking how to use it at scale, the limits become the conversation.
Once you stop asking “what is Claude” and start asking “how do I use Claude at scale,” you run into a different category of question. How big is the context window, actually, in this specific situation? What’s the file upload limit? What happens when one teammate burns through the Team plan? Where does the 1M context window apply and where doesn’t it? When does extra usage kick in and what does it cost?
The answers exist — they’re just spread across a dozen Anthropic Help Center articles, and the wrong combination of guesses can make you think you’ve hit a hard limit when you’ve actually just hit the wrong setting. This article is the consolidated map. Triple-sourced against Anthropic’s official documentation, verified May 15, 2026.
The four limits that matter most
If you’re running Claude in any sustained capacity, four limits will define your experience. Get these right and you have headroom. Get them wrong and you’ll think Claude is broken when it’s actually working as designed.
1. Context window — how much Claude can read in a single conversation. Varies by model and surface. The 1M window is real but only available in specific places.
2. File upload size — how big a single file can be. 30 MB cap per file across the board, with workarounds for larger files.
3. Usage limits — how much Claude work you can do per session/week. Per-user, not pooled. Different limits for chat vs Claude Code vs Agent SDK.
4. Extra usage / overage — what happens when you hit the cap. Either you’ve enabled it and you keep going at API rates, or you’re stopped until the limit resets.
Context window: where 1M tokens actually applies
Per Anthropic’s Help Center documentation (verified May 15, 2026), context window size depends on the model AND on the surface you’re using Claude through. This is the single most-misunderstood limit because the same model can have a different context window in chat than it does in Claude Code or the API.
Web and desktop chat (claude.ai):
Opus 4.7, Opus 4.6, Sonnet 4.6 — 500K tokens on all paid plans
All other models — 200K tokens on paid plans
Claude Code:
Opus 4.7 — 1M tokens on Pro, Max, Team, and Enterprise
Sonnet 4.6 — 1M tokens on all paid plans, but extra usage must be enabled to access it (except on usage-based Enterprise plans)
Claude API:
Opus 4.7, Opus 4.6, Sonnet 4.6 — 1M tokens at standard pricing (no long-context premium)
All other models — 200K tokens
The practical translation: if you need the full 1M token window, use Claude Code or the API with one of the supported models. The web chat tops out at 500K even on the most capable models. That difference matters when you’re trying to feed Claude an entire codebase, a long video transcript, or a multi-document research bundle.
File upload size: 30 MB per file, with workarounds
Per Anthropic’s Help Center, the maximum file size for both uploads and downloads is 30 MB per file. This applies whether you’re uploading a PDF, a CSV, an image, or any other supported file type.
For PDFs larger than 30 MB, Anthropic’s documentation notes that Claude can process them through its computing environment without loading them into the context window. That’s a real workaround for big PDFs but it doesn’t help you for other large file types.
If you regularly hit the 30 MB cap, the practical patterns are:
Split before upload — break the file into chunks under 30 MB, upload each, work with them as separate sources
Convert format — a 35 MB Word doc with embedded images may compress to under 30 MB as a PDF; CSVs can often be reduced by removing unused columns
Upload to GCS or S3 and let Claude read via tools — for the Agent SDK / API path, you can put the file in cloud storage and have Claude read it via web fetch or a custom tool, bypassing the upload cap entirely
Usage limits: per-user, not pooled
This is the limit that confuses teams the most. Per Anthropic’s Help Center documentation on the Team plan (verified May 15, 2026): each team member has their own set of usage limits. They are not shared across the team.
If one teammate burns through their session limit, the rest of the team is unaffected. There is no pooled team allowance that one user can drain on behalf of others. The math is per-seat, always.
The usage limits themselves vary by seat type:
Standard Team seats — 1.25x more usage per session than Pro plan. One weekly usage limit applies across all models. Resets seven days after the session starts.
Premium Team seats — 6.25x more usage per session than Pro plan. Two weekly limits: one across all models, plus a separate one for Sonnet models specifically. Both reset seven days after session start.
For the actual numeric token-per-session limits, Anthropic does not publish exact numbers — they describe relative multipliers vs Pro. This is intentional; the underlying math is calibrated against typical workloads rather than a hard token ceiling.
Extra usage: what happens when you hit the cap
When a user hits their weekly limit, two things can happen depending on whether the organization has enabled extra usage:
If extra usage is enabled: additional Claude requests continue to flow at standard API rates (the same per-token pricing published on Anthropic’s pricing docs — $5/$25 MTok for Opus 4.7, $3/$15 for Sonnet 4.6, $1/$5 for Haiku 4.5). Extra usage is billed separately from the subscription. Team and Enterprise admins can enable, cap, and monitor extra usage at the organization level.
If extra usage is not enabled: the user’s Claude requests stop until their limit resets at the start of the next session window (seven days from when the current session started, not a fixed weekly day).
The right setting depends on your team’s tolerance for surprise bills versus interrupted workflows. Most production teams enable extra usage with a hard organizational cap so individual users have continuity but the org has predictable spend ceiling.
Claude Code limits: a separate model
Claude Code has its own usage limit accounting that exists alongside chat usage limits. Per Anthropic’s Help Center on Claude Code models, usage, and limits (verified May 15, 2026):
Interactive Claude Code (typing in terminal/IDE) draws from your subscription’s usage limits, the same pool as web chat
Non-interactive claude -p mode currently also draws from subscription usage limits — until June 15, 2026
Starting June 15, 2026, non-interactive mode and Agent SDK usage move to a separate per-user monthly Agent SDK credit pool
The June 15 change is important enough that it gets its own breakdown in our Agent SDK Dual-Bucket Billing article. The short version: if you’re running unattended Claude Code work in cron jobs or CI, your billing model is changing. Plan capacity against the new credit pool.
The limits that aren’t really limits
Three things that get reported as limits but are actually configuration choices:
“My context window keeps filling up.” This is usually caused by long-running conversations accumulating history rather than the model’s actual context window being too small. Starting a new conversation (or running /clear in Claude Code) resets the working context. Long sessions are not a hard limit; they are a working-memory pressure that compounds over turns.
“Claude won’t read my whole repository.” Repository size is rarely the actual limit; the limit is how much you can load into the context window at once. Tools like Claude Code’s file reading and search work around this by loading files on demand rather than upfront. The 1M context window helps but is not a substitute for selective loading.
“My team keeps hitting limits even though we’re on Team.” Almost always one of two things: (a) people are mistakenly assuming the seat allowance is shared, when it’s strictly per-user; (b) someone is running heavy automation through a subscription seat instead of a Claude Developer Platform API key (which is the recommended path for sustained team-wide automation, especially after June 15).
Decision matrix: which limits affect which use case
Map your use case to the limits that actually apply:
Solo chat user on Pro — 500K context on Opus 4.7/4.6/Sonnet 4.6 in chat, weekly session limit, 30 MB upload cap. Hit your limit and you wait or pay extra usage.
Solo developer using Claude Code — 1M context on Opus 4.7 (1M on Sonnet 4.6 with extra usage on). Same weekly session limit. June 15 billing change applies if you use claude -p.
Small team on Team Standard — Per-seat limits at 1.25x Pro session capacity, not pooled. 30 MB upload cap. June 15 billing change applies per-seat.
Team running Claude Code in CI — All of the above plus separate Agent SDK credit pool starting June 15. Strongly consider a Developer Platform API key for the CI workload to get true pay-as-you-go billing.
Enterprise running large-scale automation — Subscription limits are the wrong tool. Move to a Developer Platform API key, monitor usage at the org level, set spend caps in the Console.
What to actually do this week
Identify which surface you’re using Claude through (web, Claude Code, API). Different surfaces have different context windows even for the same model.
If you’re hitting “limit” errors, check whether extra usage is enabled at the organization level before assuming it’s a hard cap.
If you’re a Team admin and your team is reporting hitting limits, audit per-seat usage rather than assuming you need to upgrade the plan — the issue is often one heavy user, not the plan tier.
If anyone on your team is running unattended Claude work, read the Agent SDK billing change before June 15.
If you need the full 1M context window, switch to Claude Code or the API. Web chat tops out at 500K.
For uploads larger than 30 MB, split, compress, or move the file to cloud storage and have Claude read it via tools.
Frequently Asked Questions
Is the Claude Team plan usage limit shared across team members?
No. Per Anthropic’s Help Center documentation, each team member has their own set of usage limits. If one team member reaches their seat’s included limit, other team members are unaffected and can keep working.
What is Claude’s file upload size limit?
30 MB per file for both uploads and downloads, per Anthropic’s official documentation. For PDFs larger than 30 MB, Claude can process them through its computing environment without loading them into the context window.
Where does the 1M token context window actually apply?
1M context is available on Claude Code with Opus 4.7 (Pro/Max/Team/Enterprise) and on the API with Opus 4.7, Opus 4.6, and Sonnet 4.6. Web chat tops out at 500K tokens even on the most capable models. Sonnet 4.6 in Claude Code requires extra usage to be enabled to access the 1M window (except on usage-based Enterprise plans).
What’s the difference between Standard and Premium Team seats?
Standard seats offer 1.25x Pro plan usage per session with one weekly limit across all models. Premium seats offer 6.25x Pro session usage with two weekly limits (one across all models, one Sonnet-specific). Both reset seven days after the session starts.
What happens when I hit my Claude usage limit?
If extra usage is enabled at your organization, you continue at standard API rates billed separately. If extra usage is not enabled, your requests stop until your limit resets at the next session window (seven days from session start, not a fixed weekly day).
Should I use a Team plan or the API for production automation?
For sustained shared automation (CI pipelines, cron jobs, background services), Anthropic recommends the Claude Developer Platform with an API key over subscription seats. Subscription seats are sized for individual interactive use; API keys give you predictable pay-as-you-go billing, no per-seat caps, and don’t compete with team members’ interactive usage.
Anthropic Help Center: Understanding usage and length limits, What is the Team plan?, How is my Team plan bill calculated?, Manage extra usage for Team and seat-based Enterprise plans, Models, usage, and limits in Claude Code, How large is the context window on paid Claude plans?, How large is the Claude API’s context window?, Upload files to Claude (primary sources for all limit specifics)
Anthropic platform documentation: Context windows at docs.claude.com (primary source for API context window behavior)
Anthropic Help Center: Use the Claude Agent SDK with your Claude plan (primary source for the June 15, 2026 billing change)
All limit numbers and policies are accurate as of May 15, 2026. Anthropic adjusts subscription mechanics regularly; if you’re making procurement decisions on this article more than 60 days from the date stamp, re-verify the per-seat multipliers and context window availability against the current Help Center.
Installing Claude Code is the easy part. Deploying it across a team in production is the part most guides skip.
Most of the published guidance on installing Claude Code stops at “run npm install -g and you’re done.” That’s enough for a developer playing on a laptop. It is not enough for a team that wants to run Claude Code in production — in CI, in shared infrastructure, behind a firewall, with cost controls, and with the new Agent SDK billing model that takes effect June 15, 2026.
This article is the production deployment guide. Triple-sourced against Anthropic’s own Claude Code documentation, the github.com/anthropics/claude-code-action repo, and Anthropic’s announced June 15 billing model. Verified May 15, 2026.
The three install paths and which to pick
Per Anthropic’s official Claude Code docs, there are three supported ways to install Claude Code. They produce the same underlying binary but make sense in different operational contexts.
1. Standalone installer. A native installer for macOS, Windows, and Linux that drops the Claude Code binary in a system path. This is the cleanest install for individual developers — no Node.js required, no npm dependency, predictable upgrade behavior. Use this on workstations where the operator owns the machine.
2. npm global package.npm install -g @anthropic-ai/claude-code. Requires Node.js 18 or later. Pulls the same native binary as the standalone installer through a per-platform optional dependency, then a postinstall step links it into place. Use this when you already manage developer tools through npm and want one less install path to track. Supported platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64.
3. Desktop app. A desktop-class application distributed via .dmg on macOS and MSIX/.exe on Windows. This is the path most teams will deploy to non-developer staff, and it integrates with enterprise device management tools like Jamf, Kandji, and standard Windows MSIX deployment.
If you are deploying across a team larger than a handful of developers, mix-and-match: standalone or npm for engineering workstations, desktop for everyone else.
The npm install gotchas worth knowing before you ship
Two things in Anthropic’s official docs are worth flagging because they will save you from a whole class of bug reports later:
Don’t use sudo. Anthropic’s setup documentation explicitly warns against sudo npm install -g @anthropic-ai/claude-code. It can lead to permission issues and security risks. If you need a global install on a machine where your user can’t write to the npm prefix, fix the npm prefix first (point it at a user-writable directory) rather than escalating with sudo.
Don’t use npm update for upgrades. The right command per Anthropic’s docs is npm install -g @anthropic-ai/claude-code@latest. npm update -g respects the original semver range and may not move you to the newest release. This trips up CI pipelines that try to keep Claude Code current via update; they will sit on a stale version forever.
Production deployment considerations
The single most important piece of context for a production Claude Code deployment in 2026: the billing model changes on June 15, 2026.
Before June 15, Claude Code interactive sessions and claude -p non-interactive runs both draw from your normal subscription usage limits. Starting June 15, interactive Claude Code keeps using subscription limits as before, but claude -p and direct Agent SDK usage move to a separate per-user monthly Agent SDK credit pool ($20 Pro, $100 Max 5x, $200 Max 20x, $20-$100 Team, up to $200 Enterprise).
For teams running Claude Code in CI, in cron jobs, in shell scripts, in GitHub Actions workflows — anywhere the trigger is automated rather than a human — this changes the economics. Plan capacity against the new credit pool, not the legacy shared subscription pool. Full breakdown in our Agent SDK Dual-Bucket Billing article.
Three other production considerations:
Network configuration. Behind a corporate firewall, you’ll need to allowlist Anthropic’s API endpoints, configure proxy settings, and potentially route through an LLM gateway. Anthropic’s network configuration documentation covers the specifics.
Enterprise device deployment. Per Anthropic’s official docs, the desktop app distributes through standard enterprise tools — Jamf and Kandji on macOS via the .dmg installer, MSIX or .exe on Windows. If your IT team already has a deployment workflow for similar developer tools, Claude Code drops into it without anything special.
API key management. If your team uses Claude Developer Platform API keys instead of (or alongside) subscription auth, manage them like any other production secret — vault them, rotate them, scope them per environment, never check them into source control. This becomes more important after June 15 because API key usage is the recommended path for sustained shared automation, and unintended sprawl gets expensive.
Claude Code GitHub Actions: the team multiplier
The fastest way to get team-level value from Claude Code is the official GitHub Actions integration. From Anthropic’s documentation and the public github.com/anthropics/claude-code-action repository:
The setup command. The cleanest install is to run /install-github-app from inside Claude Code in your terminal. It walks you through installing the GitHub App, configuring the required secrets, and wiring the workflow file. Manual setup also works — copy the workflow YAML from Anthropic’s docs and add the ANTHROPIC_API_KEY secret to your repository settings — but the install command saves the assembly time.
The interaction model. Once installed, mentioning @claude in a pull request comment or an issue triggers Claude Code to act on the context. Claude can analyze the diff, create new PRs, implement features described in an issue, fix reported bugs, and respond to follow-up comments — all while adhering to whatever conventions you’ve documented in your repository’s CLAUDE.md file.
Three use cases worth separating clearly.
Automated code review. Claude Code reads the diff on every pull request and posts inline comments flagging potential issues, suggesting improvements, or checking for convention violations. Highest signal-to-noise when path-filtered to relevant code only.
Issue-to-PR automation. Tag @claude on a well-described issue and Claude Code opens a PR implementing it. Best for small, well-scoped changes; less useful for architectural work.
On-demand assistance. Reviewers tag @claude mid-PR to ask questions, request explanations, or get a second opinion before merging. The most defensible use case because it keeps a human in the decision loop.
Pick the use case that matches your team’s actual bottleneck. Running all three at once on every PR is the fastest way to burn through your usage budget without proportionate value.
Cost expectations at team scale
Independent reports as of May 2026 put Claude Code GitHub Actions PR-review costs at roughly $15-25 per month for a team of 3-5 developers doing 10-15 PRs per week, billed against a Claude Developer Platform API key at Sonnet rates. That figure should be treated as directional — your actual cost depends on PR size, how many tools you’ve configured, model selection, and how aggressive your path-filtering is.
Two cost controls that materially change the math:
Path filters. Trigger Claude Code only on file changes that actually need review. Skipping documentation, generated files, and lockfile-only PRs cuts the bill substantially.
Concurrency limits. GitHub Actions concurrency settings prevent Claude Code from running multiple instances against the same branch at once. Without this, force-pushes and rapid-fire updates can stack runs.
If you are running Claude Code on every PR across an active team, you will hit Anthropic API rate limits. The mitigation is path filters, concurrency limits, and batching — none of which are speculative; they are documented patterns.
The CLAUDE.md file is not optional
Whatever your install path and whatever your use case, the single piece of project context that has the largest effect on Claude Code’s output is the CLAUDE.md file at the root of your repository. This is where you tell Claude Code what your project is, what conventions to follow, what tools are available, what to avoid, and what success looks like.
If you skip it, Claude Code is reasoning from the files alone — useful but generic. If you write it, Claude Code is reasoning with your team’s context and your specific codebase rules. The difference shows up in the first ten minutes of use.
A practical CLAUDE.md for a production team usually includes: the project’s purpose and stack, naming conventions and folder structure, testing requirements, lint and format rules, deployment considerations, what kinds of changes need human review, and explicit prohibitions (“never commit migrations directly to main”, “always update X when you change Y”). Keep it concise — verbose CLAUDE.md files inflate every per-turn token cost across the team.
What to actually do this week
Pick your install path per role (standalone or npm for developers, desktop for everyone else).
Install Claude Code on one workstation and run through the quickstart end-to-end before rolling to the team.
Write a real CLAUDE.md for your primary repository before anyone uses Claude Code on it. Even a 100-line version is far better than nothing.
If you want team-level value, install the GitHub Actions integration — but pick one use case (code review, issue-to-PR, or on-demand help), not all three at once.
Set path filters and concurrency limits in your workflow before you put Claude Code on every PR.
Frequently Asked Questions
What’s the difference between the npm install and the standalone installer?
None functionally — both install the same native binary. The npm path is convenient if you already manage developer tools through npm. The standalone installer is cleaner if you don’t want a Node.js dependency. Both upgrade through their own mechanism.
Why does Anthropic say not to use sudo with npm install?
Per Anthropic’s official setup documentation, sudo with global npm installs can create permission issues and security risks. The recommended fix is to configure your npm prefix to a user-writable directory, then install without elevated privileges.
How do I upgrade Claude Code installed via npm?
Run npm install -g @anthropic-ai/claude-code@latest. Don’t use npm update -g — it respects the original semver range and may not move you to the latest release. This is documented in Anthropic’s setup guide.
Does Claude Code work in CI/CD pipelines?
Yes. The official GitHub Actions integration is the recommended path for GitHub-based workflows. For other CI systems (GitLab, CircleCI, Jenkins), the underlying tool is the Claude Agent SDK plus claude -p. Both move to the new Agent SDK monthly credit pool on June 15, 2026.
How much does Claude Code GitHub Actions cost for a team?
Independent reports as of May 2026 estimate $15-25/month for a 3-5 developer team running PR review on 10-15 PRs/week at Sonnet rates with a Claude Developer Platform API key. Actual cost varies with PR size, tool configuration, model selection, and path filtering aggressiveness.
What’s the single biggest mistake teams make installing Claude Code?
Skipping the CLAUDE.md file. Without it, Claude Code reasons generically against your codebase. With even a basic CLAUDE.md describing your conventions and constraints, output quality improves substantially across every interaction. It is the highest-leverage 30-minute setup task.
Anthropic Claude Code documentation: Set up Claude Code and Advanced setup at code.claude.com (primary source for install paths, npm gotchas, enterprise deployment patterns)
Anthropic Claude Code GitHub Actions documentation at code.claude.com/docs/en/github-actions (primary source for the GitHub Actions integration setup and use cases)
github.com/anthropics/claude-code-action public repository (primary source for the action’s interaction model)
Anthropic Help Center: Use the Claude Agent SDK with your Claude plan (primary source for the June 15, 2026 billing change)
Independent cost analyses (KissAPI, OpenHelm, Steve Kinney) for the team-scale cost estimates — Tier 2 confirming sources
Cost figures and version specifics in this article are accurate as of May 15, 2026. Anthropic ships Claude Code updates frequently; the install paths and CLI commands are stable, but pricing and rate limits are the most likely figures to need re-verification.
The three-legged stack — Notion, Claude, Google Cloud — is what’s actually holding up the operation.
I run a portfolio of businesses — restoration companies, content properties, creative ventures, a software platform, a comedy site, a few things I haven’t decided what to do with yet — on three legs. Notion. Claude. Google Cloud. That’s it. Everything else either fits inside that triangle or it doesn’t last in my stack.
This article is the doctrine. Not “here’s a list of tools I like.” The actual operating philosophy of why this specific three-piece architecture is what holds the work up, where each leg’s job ends, and what I learned the hard way about which tools belong on the floor instead of the table.
If you’re trying to decide what your own AI-driven operating stack should look like, what follows is what I’d tell you over coffee.
Why three legs and not two, four, or twelve
I tried twelve. I tried four. I lived for a while with two. Three is what’s left after everything else either failed in production, got absorbed into one of the three legs, or became overhead that didn’t pay for itself.
The reason it’s not two is that you need a place where state lives, a place where reasoning happens, and a place where heavy compute runs. If you collapse two of those into one tool, the tool has to be excellent at both jobs and almost nothing is. If you keep them separate, each tool gets to be excellent at its actual job.
The reason it’s not four is that every additional leg multiplies the surface area of what can break, what needs to be monitored, what needs to be paid for, what needs to be learned by every new person you bring in. Four legs sounds like it would be more stable but it isn’t. It’s more rigid. Three legs sit flat on uneven ground.
The reason it’s not twelve is that I tried that and the cognitive cost of remembering which tool did which job was higher than the work the tools were supposed to be saving.
Notion is the system of record
State lives in Notion. That’s the rule. If a piece of information needs to exist tomorrow, it goes in Notion first.
That includes the things you’d expect — clients, projects, content pipelines, scheduled tasks, the Promotion Ledger that governs which autonomous behaviors are running at what tier — and a lot of things you might not. Meeting notes go in Notion. Random ideas at 11pm go in Notion. The reasons I made a particular architectural decision six months ago go in Notion. Anything I might want Claude to read later goes in Notion.
The reason this leg has to be Notion specifically — and not, say, a folder of markdown files, or a Google Doc, or Airtable — is structured queryability paired with human-readable rendering. Notion databases let me describe my business in shapes (a content piece is a row, a project is a row, a contact is a row) while keeping every row a real document I can read and write to like a normal page. That dual nature is rare. Most systems force you to pick between structured and prose. Notion lets the same object be both.
The May 13, 2026 Notion Developer Platform launch made this leg even stronger. Workers, database sync, and the External Agents API mean the system of record can now do active things on its own and host outside agents (including Claude) as native collaborators. Notion stopped being a passive document store and started being a programmable control plane. That’s a big deal for this architecture and I wrote about it in my piece on the platform launch.
Claude is the reasoning layer
Claude does the thinking. That’s the rule on the second leg.
Anywhere I would otherwise have to write something from scratch, decide between options, summarize a long document, generate code, audit content, or do any task that requires a brain rather than just a database query, Claude is the first thing I reach for. The work happens in Claude. The result lands in Notion.
I want to be specific about why Claude and not “an LLM” generically. I have used the others. I have used GPT in production. I have used Gemini in production. They all work. Claude is what I picked, and the reasons aren’t religious.
First, the writing is recognizable. Claude’s voice has a calibration to it that the others don’t quite have for the kind of work I’m doing — long-form content, operator-voice editorial, technical explainers. I can edit a Claude draft to feel like me much faster than I can edit the others.
Second, the agentic behavior is the most stable across long sessions. Claude Managed Agents and Claude Code in particular are willing to think for a long time without losing the plot. For multi-step work that involves reading a lot of context, holding it, and acting on it across many turns, the difference is real.
Third, the tooling around Claude — Claude Code, Cowork, the Agent SDK, MCP — is the most operator-friendly of the bunch right now. The other models will catch up. As of May 2026, Claude is the best fit for how I actually work.
Fourth, and this matters more than people give it credit for: I am willing to bet on Anthropic the company. I am betting my operations on the leg that bears my reasoning load. Whose roadmap I’m comfortable with, whose values I find legible, whose engineering culture I trust to keep shipping the thing without breaking it underneath me — that’s a real input to the decision, not a soft preference.
Google Cloud is the substrate
The third leg is the heavy one. Google Cloud is where the things live that have to be reliable in a way that Notion can’t be and Claude isn’t supposed to be.
The 27 WordPress sites I manage all live on GCP infrastructure. The knowledge-cluster-vm hosts five interconnected sites. The proxy that lets Claude talk safely to WordPress sites runs on Cloud Run. The cron jobs that fire scheduled work, the Python services that handle image pipelines, the AI Media Architect that runs autonomously — all on GCP. Anything that involves real compute, regulated data, behind-a-firewall execution, or sustained reliability lives on the third leg.
The reason this leg has to be a real cloud and not just a laptop or a Hetzner box is that I run autonomous behaviors. Tier C autonomous behaviors run unattended, which means the substrate they run on has to be more reliable than I am. GCP gives me that. It’s also where Anthropic’s Claude is available through Vertex AI, which means there’s a path where the entire stack can run inside one cloud’s perimeter when that becomes operationally necessary.
I picked GCP specifically over AWS or Azure for a few reasons. Vertex AI’s first-party Claude access matters to me. The GCP control surface is the one I’m fastest in. Cost-wise it’s been competitive for the workloads I run. None of those are universal — your third leg might be AWS, or Azure, or a hybrid with on-premise hardware. The doctrine isn’t “use GCP.” The doctrine is “have a real substrate that can carry the heavy work.”
How the three legs hold each other up
The thing that makes this an actual stack and not just three tools is the load each leg puts on the others.
Notion holds Claude’s memory. Claude doesn’t have persistent memory across sessions in any deep way — what it remembers is what’s in the prompt and what it’s allowed to look up. Notion is where I put the things I want Claude to know tomorrow. Project briefs, brand voice docs, the Promotion Ledger, client context, my preferences. When Claude starts a session it looks at Notion. When the session is done, what mattered gets written back to Notion. The memory leg is Notion. Without it, Claude is amnesiac and has to be re-briefed every time.
Claude does the work that Notion can’t and that GCP isn’t shaped for. Notion can hold structured data and run light automation through Workers and database sync. Notion can’t write a 2,000-word article in your voice. GCP can run a reliable cron job and host whatever you want on Cloud Run. GCP isn’t going to read your existing client notes and propose a follow-up email. The reasoning leg is Claude. Without it, you have a database and a server and no one to think.
GCP holds the things that have to keep running when nobody is watching. Notion can’t host a WordPress site. Claude can’t run a cron job by itself. The compute leg is GCP. Without it, the autonomous behaviors that make this a system instead of a tool collection have nowhere to live.
Each leg fails gracefully into the others. If Notion is down, GCP keeps the live workloads running and Claude can still do work in a session. If Claude is down, Notion still holds state and GCP still runs the autonomous infrastructure. If GCP is down, the websites are unreachable but the planning surface (Notion) and the reasoning surface (Claude) still let me figure out what to do about it. No single failure takes the whole operation down.
What I tried that didn’t make the cut
For honesty’s sake, here’s what I had in earlier versions of the stack that’s no longer there:
Zapier and Make for orchestration. They worked. They cost real money at the volumes I was running. The May 13 Notion Developer Platform launch absorbed most of what I was using them for into native Notion functionality. What’s left I do with Cloud Run jobs.
Multiple LLMs for “best tool for the job.” I went through a phase of routing different work to different models. The cognitive overhead of “which one for this task” was higher than any quality gain from the routing. I picked Claude and stayed.
Custom CRMs and project management tools. Tried several. None of them did the job better than a well-structured set of Notion databases with the right templates and views. The CRM is in Notion now. The project management is in Notion. The pipeline tracking is in Notion.
A second cloud “for redundancy.” Sounded smart, was actually overhead. If GCP goes down catastrophically I have bigger problems than my stack. Single-cloud is fine for a small operator portfolio.
Local AI models for cost savings. The math didn’t work for me. I have a powerful workstation that can run open models, but the time cost of running them, debugging them, and maintaining them outweighed the API savings. Claude through the subscription and through Vertex when I need it is what I pay for now.
Why this matters beyond my own operation
I write about this not because anyone is required to copy it but because the shape of the answer — three legs, one for state, one for reasoning, one for compute — generalizes.
If you’re a solo operator, a small agency, a content business, a service business with operational complexity, this shape works. Your specific tool choices for each leg will be different. Maybe your state lives in Airtable instead of Notion. Maybe your reasoning leg is GPT or Gemini. Maybe your substrate is AWS or Vercel or your own bare metal. The three-leg architecture survives the substitutions.
What doesn’t survive substitutions is collapsing the legs. Putting state and reasoning in the same tool (anyone who has tried to use ChatGPT as their CRM knows what I mean) doesn’t work. Putting reasoning and compute in the same tool means you’re either compromising on reasoning to keep compute simple or compromising on compute to keep reasoning fluid. The separation is where the strength is.
Where the stack is going next
Three things I’m watching:
Notion’s platform maturation. The May 13 launch is version 1 of what Notion as a programmable platform looks like. If Workers and database sync continue to grow into real automation surface, more of what I do on GCP could move to Notion. I don’t expect the heavy stuff to migrate, but the lightweight glue is moving in that direction.
Claude’s agentic capabilities. Claude Managed Agents and the Agent SDK are getting better fast. Some of what I currently script in Python on Cloud Run will move into Claude-native agentic loops as the agents become more capable of long-running, reliable work without supervision.
The fortress pattern on GCP. The ability to run Claude inside a private GCP perimeter via Vertex AI is becoming more important as I take on regulated industry work. The substrate leg is staying GCP precisely because of this — the perimeter matters.
The stack will evolve. The three-leg shape probably won’t.
Frequently Asked Questions
Why Notion and not Airtable, Coda, or Obsidian?
Notion’s combination of structured databases and human-readable page rendering is what makes it work as both a database and a knowledge base for Claude. Airtable is more powerful as a database but worse as a document. Coda is similar in spirit but smaller community and tooling around it. Obsidian is excellent for personal knowledge but doesn’t have the multi-user, structured-database surface I need to run businesses on.
Why Claude and not GPT or Gemini?
Voice quality for the kind of writing I do, agentic stability across long sessions, operator-friendly tooling (Claude Code, Cowork, MCP), and Anthropic’s roadmap and culture being legible to me. The other models work; Claude is what I picked.
Why Google Cloud and not AWS?
Vertex AI’s first-party Claude access, GCP’s control surface fitting how I work, competitive cost on my specific workloads. AWS would also work. The doctrine is “have a real substrate,” not “use GCP specifically.”
Can a small operator afford this stack?
Yes. Notion is $10/seat. Claude Pro is $20/month, Max is $100-$200. GCP costs scale with what you actually run — my 27-site infrastructure runs in the low three figures monthly. Total monthly stack cost for a solo operator running this architecture is well under what most people pay for a single SaaS tool that does only one of these jobs.
What if one of the legs goes away or pivots badly?
Each leg is replaceable. The shape of the stack matters more than the specific brands. If Notion pivots away from being useful, the state leg moves somewhere else. If Anthropic pivots, the reasoning leg moves. If I leave GCP, the substrate leg moves. The architecture is durable; the specific tool choices are not load-bearing in the way the architecture is.
How long did it take to settle on this shape?
Roughly two years of trying things. I write the doctrine now because I want my own next iteration to start from this shape rather than rebuilding it from scratch. If you want to skip those two years, this is the shortcut.
