Claude Code Agent Teams: How to Run Them on a Schedule

Most Claude Code sessions are one conversation, one agent, one thread of work at a time. Claude Code Agent Teams changes that: it's Anthropic's experimental feature for running up to ten Claude instances in parallel against a shared task list. Kick it off and you've got ten agents working different parts of the same problem at once, instead of one agent working through them in sequence.

It's early, it's opt-in, and most developers haven't touched it yet. That's exactly why it's worth understanding now, before the guides and the gotchas are common knowledge.

Key Takeaways

• Agent Teams runs up to ten Claude Code instances concurrently against one shared task list, gated behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• It suits genuinely independent work, bulk fixes, test triage, parallel exploration, and performs badly on anything with tight sequential dependencies or shared files.
• Token spend scales roughly linearly with instance count: ten agents for the same wall-clock window means roughly ten times the cost of one.
• There's no native way to schedule a team run, it's manually triggered every time, which is where a scheduler like OpenHelm fits in.
• Anthropic's own experimental features documentation is the authoritative source on flag behaviour, and it's worth rereading each time you update Claude Code, experimental interfaces shift.

What Is Claude Code Agent Teams?

Agent Teams is an experimental Claude Code capability that lets multiple Claude instances work concurrently against one shared task list rather than one agent working alone. Instead of Claude Code picking up task one, finishing it, then moving to task two, an agent team splits the list across several instances that run at the same time.

It's gated behind an environment variable, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, which is Anthropic's usual signal that a feature is real but not yet considered stable enough for default-on behaviour. Expect the interface and limits to shift as it matures.

How Agent Teams Works

Set the environment variable, and Claude Code exposes the ability to spin up a team, up to ten instances, against a task list you define. Each instance in the team can see the shared list, pick up unclaimed work, and mark items complete as it finishes them. The coordination lives in that shared list rather than in the instances talking to each other directly.

Practically, that means the tasks you hand to a team need to be genuinely independent, or close to it. "Fix these fourteen failing tests across fourteen different files" parallelises cleanly, each instance can grab a test, fix it, move on. "Refactor this one file's architecture" doesn't, ten agents editing the same file at once is a recipe for conflicting changes, not speed.

Why This Matters Now

Feature launches like this tend to follow a pattern: an experimental flag ships quietly, a handful of developers try it, and six months later it's a stable, documented, widely-used part of the toolchain with a crowded field of guides. Right now, Agent Teams is still in the first phase. Search interest is climbing, but genuinely in-depth guides are thin on the ground, which is a narrow, real window for anyone building workflows around it early.

The bigger shift underneath the specific feature is what it signals about where agentic coding tools are heading: away from one long conversation with one model, and towards small coordinated groups of instances working a shared backlog. Whether Agent Teams itself becomes the standard mechanism or gets superseded by something else, that direction looks set to stick.

Real-World Use Cases for Parallel Agent Runs

A few patterns fit an agent team well:

Bulk, independent fixes. A dependency upgrade that breaks a dozen unrelated files. A lint rule change that needs fixing across the codebase. Anything where the task list is naturally a set of separate, non-overlapping items.

Test suite triage. Fourteen failing tests after a refactor, each in a different file, each needing its own diagnosis. One agent per failure, working simultaneously, gets you through the list in a fraction of the wall-clock time.

Parallel exploration. Trying three different implementation approaches to the same problem at once and comparing the results, rather than trying one, discarding it, and starting again.

What doesn't fit well: anything with tight sequential dependencies, or anything touching the same files repeatedly. Ten agents contending for the same three files will spend more time on merge conflicts than on the actual work, the same class of problem Git's own documentation on merge conflicts describes for human contributors working the same lines at once.

Does Your Task Fit an Agent Team?

A quick way to sanity-check a task list before you burn tokens on it:

The Manual Problem: Kicking Off Agent Teams by Hand

Here's the friction point once you've used Agent Teams a few times: someone has to start it. Right now that means sitting down, defining the task list, setting the environment variable, and launching the run, every single time you want the team to work.

For a one-off refactor, that's fine. For anything recurring, a nightly dependency check, a weekly lint sweep across the codebase, it's the same problem cron jobs solved for regular scripts twenty years ago, just not yet solved for agent teams specifically.

Scheduling Agent Team Runs with OpenHelm

This is where scheduling infrastructure earns its keep. OpenHelm was built for exactly this shape of problem: define a job once, set when it should run, and let it fire without you needing to be at your keyboard to start it.

Practically, that means you can define an agent team task list as an OpenHelm job, point it at your project, and let it run on whatever cadence makes sense, nightly, weekly, or after a specific trigger. OpenHelm's run history then gives you a record of what the team actually did across the run, rather than you scrolling back through a terminal buffer trying to reconstruct which instance did what.

It's also where OpenHelm's silence detection matters more than usual. A single hung Claude Code session is a wasted run. A hung instance inside a ten-agent team can be harder to spot, the other nine may keep working while one sits stuck, quietly burning nothing while looking, from a distance, like everything's fine. Ten minutes of no output from any individual instance triggers the same detection either way.

Best Practices for Multi-Agent Reliability

Keep the task list genuinely independent. This is the single biggest factor in whether an agent team run goes smoothly. If two tasks touch the same file, expect friction.

Watch your token spend closely. Ten parallel instances can mean roughly ten times the token consumption of a single agent, for the same wall-clock window. That's the trade you're making for speed, and it's worth budgeting for explicitly rather than discovering it on the bill. Our guide to controlling AI coding agent costs covers the budgeting side of this in more detail.

Start smaller than the ten-instance ceiling. Two or three agents against a genuinely parallel task list is a much easier thing to reason about and debug than ten. Scale up once you trust the pattern.

Treat it as experimental in your own planning, not just Anthropic's. The flag name is a fair warning. Build workflows around it, but don't build anything business-critical on the assumption the interface won't change.

"The first time I tried Agent Teams I gave it a task list that looked independent but wasn't, three of the ten agents ended up touching the same config file. Once I split the list properly it was genuinely the fastest I'd ever cleared a backlog of failing tests."

>, Developer in the OpenHelm community Slack, July 2026

FAQ

How do I enable Claude Code Agent Teams?

Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 before starting Claude Code. It's an opt-in experimental feature, not on by default.

How many agents can run in a team?

Up to ten Claude instances working concurrently against a shared task list, at the time of writing. Anthropic may adjust this limit as the feature develops.

Does Agent Teams cost more than a single Claude Code session?

Broadly, yes, proportional to how many instances you run. Ten agents working in parallel for the same duration consume roughly ten times the tokens of one. It gets more done in less wall-clock time, but the total spend reflects the work done, not the time saved.

Can I schedule Agent Teams runs automatically?

Not natively within Claude Code itself, it's a manually-triggered feature. Pairing it with a scheduler like OpenHelm is how you turn a one-off team run into a recurring job.

Is Agent Teams stable enough for production use?

It's labelled experimental for a reason. It's genuinely useful today for the right kind of parallelisable task, but treat the interface as subject to change and keep a human reviewing the output, the same discipline that applies to any agentic coding workflow.

Agent Teams is one of those features that's more interesting for where it's pointing than for what it does today. If you're already running Claude Code unattended, see how OpenHelm's scheduling works to get a sense of how a recurring agent-team job would actually be structured, or start with the free local app and try a small parallel task list yourself.