Claude Code Workflows: How to Set-Up The New Hidden Multi-Agent Feature

Deterministic multi-agent orchestration via JavaScript, hidden inside the Claude Code binary — a step-by-step setup guide from hands-on testing with a feature Anthropic has not officially documented yet

I had four Claude Code instances running in parallel last month. Manual orchestration. Four terminal windows. Each agent doing its part of a video conversion pipeline — inspecting, converting, validating, reporting.

It worked. But every run was slightly different. The inspector agent would chase rabbit holes.

Hidden Feature in Claude Code /Workflow | Image: GPT Pro © Alireza Rezvani

Note: AI assisted with the feature structure and flow. The experiments, observations, and analysis are from my own practice.

The converter would re-read files the inspector had already analyzed. Context bled between steps in ways I could not predict, and I spent more time babysitting the agents than actually building.

Then I found something buried in the Claude Code binary. Not agent teams. Not subagents.

A tool called Workflow — hidden behind a single environment variable, absent from every page of the official documentation, and built to solve the exact problem I had been hacking around for weeks:

repeatable multi-agent orchestration controlled by plain JavaScript.

Nobody at Anthropic has announced it. The docs at code.claude.com do not mention it. But it ships inside the binary, it is actively receiving bug fixes and UI polish in the changelog, and a community skill has already sprung up around it. This is the practical guide that does not exist yet.

What the Workflow Tool Actually Is

A workflow is a JavaScript file. Not a prompt. Not a YAML configuration. A .js file with ordinary control flow — loops, conditionals, fan-out — that you write and own.

The key mechanic: only leaf agent() calls spend model tokens, and each one runs in its own clean context window. Everything between those calls is your deterministic JavaScript. The model never decides whether to loop or branch. You decide. The model only does what you explicitly delegate through agent().

That means multi-agent work that behaves the same way every run. If it stops partway through, it can resume. If an agent call fails, your JavaScript handles the retry, not a probabilistic prompt hoping to pick up where it left off.

So where does this sit relative to what already exists in Claude Code?

Subagents are ad hoc. You type “use a subagent to investigate X” mid-session, Claude spawns one, and you get a summary back. Useful. But there is no script behind it. Run the same prompt tomorrow and you will probably get different behavior.

Agent teams are heavier. Multiple Claude instances coordinate through git. A lead agent breaks down tasks, teammates claim work, merge changes, resolve conflicts.

Three orchestration layers, three different jobs | Image: GPT Pro © Alireza Rezvani

Great for collaborative coding. But the coordination itself is nondeterministic.

The lead decides how to split work based on its reasoning at that moment, and that reasoning shifts between runs.

Workflows are the scripted layer. You write the orchestration. The agents execute within the boundaries you define. Deterministic structure, probabilistic execution only at the leaves.

I keep thinking of it like this: subagents are asking a colleague for help. Agent teams are spinning up a project team. Workflows are writing a runbook that a team follows exactly, every time.

Claude Code Workflows: How to Enable the Feature

The whole setup takes about 60 seconds. The Workflow tool ships inside the binary but stays gated behind an environment variable.

Step 1: Open your settings file.

nano ~/.claude/settings.json

If the file does not exist yet, create it with an empty JSON object.

Step 2: Add the environment variable to the env block.

{
  "env": {
    "CLAUDE_CODE_WORKFLOWS": "1"
  }
}

If you already have other entries in env, merge this in. Do not overwrite existing keys.

Step 3: Validate the JSON.

Do not skip this. A broken settings.json silently disables all your settings — every hook, every permission, every environment variable. No error message. Things just stop working, and you will spend 20 minutes wondering why your hooks disappeared before you think to check the JSON.

jq -e '.env.CLAUDE_CODE_WORKFLOWS' ~/.claude/settings.json

Should print "1". If it prints an error, your JSON is malformed. Fix it before moving on.

Step 4: Restart Claude Code.

Environment changes apply only at session start. Close your current session and open a new one.

Step 5: Confirm activation.

Ask Claude to create a workflow, or check whether a Workflow tool appears in the available tools. If nothing shows up, your Claude Code version may gate the feature differently. This is a research preview, and the enablement mechanism could shift between releases.

To disable later: Remove the CLAUDE_CODE_WORKFLOWS line from your settings and restart. There is also an internal kill-switch: CLAUDE_CODE_DISABLE_WORKFLOWS=1.

Anatomy of a Workflow File

A workflow file is plain JavaScript. Here is what one looks like:

// workflow: parallel-review.js

// Fan-out: three agents work in parallel, each in its own context window
const [security, performance, style] = await Promise.all([
  agent("Review this codebase for security vulnerabilities. Focus on injection, auth bypass, and data exposure."),
  agent("Analyze performance bottlenecks. Check database queries, memory allocation, and API response paths."),
  agent("Review code style and consistency. Flag naming violations, dead code, and missing documentation.")
]);
// Your JavaScript aggregates the results - deterministic, not probabilistic
const report = `
## Code Review Summary
### Security
${security}
### Performance
${performance}
### Style
${style}
`;
agent(`Write a final summary combining these three reviews into a unified recommendation:\n${report}`);

A few things worth noticing. The fan-out is Promise.all — standard JavaScript. You control which agents run in parallel and which run sequentially. The model has no say in that decision.

Each agent() call gets its own clean context window. The security reviewer does not see what the performance reviewer found. No context bleed. That alone makes this worth exploring, because context bleed was the thing that kept ruining my manual multi-agent setups.

And the aggregation between agent calls is your code. String concatenation, filtering, conditional logic. All deterministic. The final agent() call gets exactly the input you constructed, not whatever the model decided to remember from three prompts ago.

The Three Core Shapes

Every workflow maps to one of three patterns, or a combination.

3 Core Shapes in Workflow | Image: GPT Pro © Alireza Rezvani

Fan-out. Multiple agents work in parallel, results merge. The code review example above is a fan-out. Use it when tasks are independent.

Pipeline. Sequential chain. Agent A’s output feeds Agent B, which feeds Agent C. Use it when each step depends on the previous one: analysis, then implementation, then testing.

Loop. An agent runs repeatedly until a condition is met. Generate, evaluate, regenerate until quality passes a threshold or a token budget runs out.

Orchestration Patterns That Actually Work

The community has already started cataloging patterns beyond the three core shapes. The claude-code-workflow-creator skill by ray-amjad documents several worth knowing:

Loop-until-budget is the one I reach for most. Run an agent in a loop, track cumulative iterations, stop when you hit a ceiling and return the best result so far. Without this, a loop pattern can quietly burn through your entire token allocation.

let result = "";
let iterations = 0;
const maxIterations = 5;

while (iterations < maxIterations) {
  result = await agent(`Improve this code based on the previous review:\n${result || initialCode}`);
  const evaluation = await agent(`Rate this code 1-10 for production readiness. Reply with just the number.`);

  if (parseInt(evaluation) >= 8) break;
  iterations++;
}

Judge panel is the interesting one for subjective work. Three agents independently evaluate something — a PR, a doc, an architecture decision. A fourth agent reads all three evaluations and produces a consensus. You are averaging out individual model biases instead of trusting a single roll of the dice.

Pipeline with conditional branching is a classifier up front that routes to specialist agents. A triage agent reads the input, decides whether it is a bug, a feature request, or a refactor, and your if/else sends it to the right handler. Standard JavaScript branching, informed by one cheap model call.

If tasks are independent, fan out. If they depend on each other, pipeline. If quality needs iteration, loop. If judgment needs diversity, judge panel. Most real workflows combine two or three of these.

The Workflow Creator Skill: Authoring Without Guesswork

Anthropic has not published an official authoring guide. The community filled the gap.

The claude-code-workflow-creator skill by ray-amjad is the most complete resource I have found for writing correct workflow files. It includes a full reference manual covering every global and constant the Workflow tool exposes, copy-paste patterns for all the orchestration shapes, starter template files, six runnable example workflows, and a linter that validates your file against the parser's hard rules before you run it.

Installation:

git clone https://github.com/ray-amjad/claude-code-workflow-creator.git
mkdir -p ~/.claude/skills
cp -R claude-code-workflow-creator ~/.claude/skills/workflow-creator

After that, ask Claude to “create a workflow for X” and the skill guides the authoring end to end: format constraints, judgment calls, the whole procedure.

I recommend the linter especially. The Workflow tool’s parser has hard rules, and when you get the format wrong it either fails silently or throws errors that tell you nothing about what actually went wrong. The linter catches those mistakes before you waste a run.

What Breaks: The Honest Assessment

This is a research preview. That label is not decoration.

The env-vars reference page at code.claude.com lists dozens of variables. CLAUDE_CODE_WORKFLOWS is not among them. When you hit a problem — and you will — there is no support page. The community skill and the GitHub changelog are your best bet.

The enablement mechanism could change. When Anthropic officially ships this, the variable name, the file format, or the activation flow might all shift. I would not build anything production-critical on the current interface.

Token costs caught me off guard at first. Each agent() call opens a fresh context window and runs a full model invocation. Fan out to five agents and you are paying roughly five times what a single call costs. The loop-until-budget pattern exists for a reason. Without it, an iterative workflow can eat through tokens before you notice.

Debugging is rough. When a workflow fails, the error could be in your JavaScript or inside the model’s response from an agent() call. The Workflow tool does show live agent counts in a status row, which helps. But stack traces that cross the JS-to-model boundary are still hard to read.

Resumability works, but with limits. If an agent call was mid-stream when the process stopped, that call reruns from scratch. Completed calls are preserved. So resume works, but expect a few reruns when you pick back up.

None of this stops me from experimenting with it. All of it stops me from putting workflow files in a CI pipeline right now.

Where This Fits in the Multi-Agent Landscape

The Claude Code orchestration stack has three layers now:

Claude Code Orchestration Stack | Image by Alireza Rezvani

The Workflow tool is not a replacement for subagents or agent teams. It is a different primitive entirely. I still use subagents for quick delegation mid-conversation. Agent teams still make more sense when multiple agents need to coordinate on a shared codebase with merge conflict resolution.

Workflows are for when you need the same multi-agent process to run identically every time: code reviews, migration audits, test generation pipelines, documentation sweeps.

Outside Claude Code, there are third-party orchestrators like OpenClaw, Multiclaude, and Gas Town. I use OpenClaw in production for openLEO.ai, and it solves problems the Workflow tool does not: team collaboration, cloud execution, multi-provider support. The Workflow tool’s advantage is that it runs inside the Claude Code binary with zero external dependencies. The tradeoff is that it is preview-grade and flying without docs.

Quick Reference: Claude Code Workflows FAQ

What is the Claude Code Workflow tool?

A hidden feature inside the Claude Code binary that enables deterministic multi-agent orchestration through JavaScript files. Each agent call runs in its own clean context window. The orchestration logic — loops, conditionals, fan-out — is plain JavaScript that you control. It ships with the binary but requires an environment variable to activate.

How do you enable Claude Code Workflows?

Add "CLAUDE_CODE_WORKFLOWS": "1" to the env block in ~/.claude/settings.json, validate the JSON with jq, and restart Claude Code. The feature is a research preview and does not appear in the official documentation. Disable it by removing the variable or setting CLAUDE_CODE_DISABLE_WORKFLOWS=1.

What is the difference between Claude Code Workflows and subagents?

Subagents are ad hoc — you spawn them mid-session with a prompt, and each run may behave differently. Workflows are scripted JavaScript files where you define the orchestration logic. Agent calls in workflows get clean context windows with no bleed between them. Workflows are deterministic, repeatable, and resumable. Subagents are flexible and spontaneous.

Anthropic is building deterministic orchestration directly into the Claude Code binary before officially documenting it.

The changelog shows active polish: inline progress displays, status rows, bug fixes for workflow subagent errors. This is not something someone started and forgot about.

The question I keep sitting with: will the community shape how this feature ships, or will most developers wait for the official docs and miss the window where early feedback actually influences the design?

The workflow-creator skill is already writing that feedback in code. The workflow files are already running. The docs are the part that has not caught up yet.

About Me:

I write about Claude Code, agentic workflows, and building real products with AI every week. More at alirezarezvani.substack.com.