Claude Code Ultracode Architecture Blueprint for Cursor and Custom Agents

TL;DR

• Claude Code Ultracode is not a new model or an API effort level. It is a session setting that combines xhigh model effort with automatic Dynamic Workflow orchestration for substantive tasks.
• The important behavior is not the word ultracode. It is the loop: decide whether orchestration is warranted, plan a task graph, fan work out, verify independently, converge, and return one result.
• As of July 15, 2026, Cursor documents model effort parameters, automatic and custom subagents, Agent Skills, hooks, worktrees, and an SDK. My assessment is that these primitives cover most of the functional loop, but not Claude Code’s workflow runtime.
• Cursor does not currently document a direct equivalent to Claude Code’s generated JavaScript workflow runtime, where orchestration and intermediate state live outside the conversation and a run can be inspected and replayed as code.
• The closest Cursor-native approximation is a high-effort coordinator with focused planner and verifier subagents plus a skill that defines when to fan out.
• For teams that require explicit replay, budgets, checkpoints, or scheduling, the more controllable architecture is an orchestrator built with the Cursor SDK or another agent SDK.
• Do not enable this pattern for every edit. Parallel agents multiply context, tokens, possible conflicts, and review work. Use it for audits, migrations, broad investigations, and changes with genuinely independent work streams.

What You Will Learn Here

• What Anthropic’s Ultracode setting actually does
• Which parts are model behavior and which parts belong to the agent harness
• How close Cursor’s native subagents can get
• How to create an Ultracode-like policy with Cursor agents and skills
• How to build a provider-neutral orchestration loop
• Where worktrees, hooks, checkpoints, and independent verification fit
• How to evaluate whether orchestration beats a normal single-agent run

Ultracode Is a Harness Feature, Not a Magic Model

Anthropic’s May 28, 2026 announcement now states that Dynamic Workflows are generally available. Its workflow documentation defines Ultracode precisely:

Ultracode combines xhigh reasoning effort with automatic workflow orchestration.

That definition has two layers:

1. Model layer: send a supported Claude model an xhigh effort setting.
2. Harness layer: let Claude Code decide when a request is substantive enough to become a Dynamic Workflow.

The second layer is the interesting one.

A Dynamic Workflow is a JavaScript orchestration script written for the task. Claude Code runs that script outside the main conversation. The script can spawn workers, run a pipeline over a list of items, retain intermediate results in variables, and send only the coordinated result back to the conversation.

Anthropic’s current workflow documentation says the runtime allows up to 16 concurrent agents and 1,000 agents in one run, subject to local resources. It can pause and resume inside the same Claude Code session, reusing completed results.

You can invoke the behavior in two different ways:

• Include ultracode in one prompt, or ask for a workflow in natural language, to create a workflow for that task.
• Run /effort ultracode to let Claude Code make that decision for substantive tasks throughout the current session.

Starting Claude Code with claude --effort ultracode requires Claude Code v2.1.203 or later. The Dynamic Workflow feature itself requires v2.1.154 or later.

The session distinction matters. Ultracode is session-only and resets when a new Claude Code session starts. Anthropic warns that each request can use more tokens and take longer, and recommends returning to /effort high for routine work.

Workflows must also be available and enabled. On Pro, enable Dynamic Workflows in /config; Anthropic documents them as enabled by default on Max, Team, Enterprise, and API access. When workflows are unavailable, the model-configuration docs say --effort ultracode falls back to xhigh effort without the orchestration layer.

The Portable Architecture

If you remove the product names, an Ultracode-like system has seven parts:

User task
   |
   v
[1. Trigger gate]
   | routine ----------------------> single agent
   |
   | substantive
   v
[2. High-effort planner]
   |
   v
[3. Task graph + success criteria]
   |
   +----> [4a. Worker A in isolation] ----+
   +----> [4b. Worker B in isolation] ----+--> [5. Reducer]
   +----> [4c. Worker C in isolation] ----+         |
                                                    v
                                        [6. Verifier / refuter]
                                                    |
                                  failed <----------+----------> passed
                                     |                            |
                                     v                            v
                              bounded repair loop          [7. Final result]

Here, the reducer combines worker outputs into one candidate result. The refuter starts independently and tries to disprove that result instead of merely polishing it.

The roles and owners should be explicit:

Keep three controls separate:

• Model effort controls how deeply one model invocation reasons.
• Worker count controls breadth and parallelism.
• Runtime budget controls total tokens, time, retries, and tool usage.

Increasing one does not replace the others.

The key engineering decisions are:

1. Triggering: When is one agent insufficient?
2. Planning: Can the coordinator produce a dependency-aware task graph?
3. Isolation: Can workers avoid editing the same files?
4. State: Where do plans and intermediate results live?
5. Verification: Does a fresh agent challenge the result?
6. Convergence: What causes another iteration, and what stops the loop?
7. Budget: How many agents, tokens, retries, and minutes are allowed?

This is why copying a system prompt alone does not reproduce Ultracode. A prompt can encourage delegation. It cannot by itself provide durable workflow state, concurrency controls, isolated workspaces, or resumability.

How Close Can Cursor Get Today?

As of July 15, 2026, Cursor documents these relevant primitives for a behavioral approximation:

• Cursor 2.4, released on January 22, 2026, introduced the current subagent and Agent Skill foundation.
• Cursor Agent can automatically delegate complex work to subagents when it considers delegation appropriate.
• Custom subagents live in .cursor/agents/ and can have their own prompts, models, read-only status, and background behavior.
• Subagents use isolated context windows and can run in parallel.
• Model configuration supports per-model parameters such as reasoning effort. Cursor recommends discovering valid parameter IDs and values with Cursor.models.list() because they vary by model.
• Agent Skills in .cursor/skills/ can encode a reusable orchestration procedure and a description that helps Agent decide when to load it.
• Hooks can observe or control subagent start and stop events, trigger bounded follow-ups, and enforce tool policies.
• Worktrees isolate changes when agents need to write in parallel.
• The Cursor SDK exposes durable agents, per-prompt runs, streaming, cancellation, token usage, named subagents, custom tools, local sandboxes, and cloud VMs.

That is a useful foundation, but it is not exact feature parity. The following mapping is my assessment, not a vendor benchmark:

My judgment: Cursor configuration can create a model-directed behavioral approximation within a run, but it cannot reproduce Claude Code’s workflow runtime through configuration alone.

Choose the smallest path that gives you the controls you need:

Decide Whether to Orchestrate Before Choosing a Path

The trigger gate should run before the planner or any worker. Useful positive signals are:

• At least two independent work lanes
• Discovery across many modules, services, documents, or repositories
• A migration partitionable by file, package, endpoint, or customer
• A result that warrants independent challenge or evidence cross-checking
• Work likely to exceed one context window

Negative signals matter just as much:

• One small file or one obvious change
• A sequential task with heavy shared state
• Several workers would edit the same core abstraction
• Human review capacity is already the bottleneck

A useful gate returns structured evidence rather than confidence alone:

{
  "substantive": true,
  "reasons": [
    "three independent audit surfaces",
    "findings require adversarial verification"
  ],
  "estimatedWorkers": 4,
  "writeConflictRisk": "low",
  "budgetClass": "medium"
}

Enforce maximum workers, token ceilings, wall-clock limits, allowed tools, and repair iterations outside the prompt. Skill descriptions can improve triggering, but skills do not guarantee invocation or better outcomes.

Non-Negotiable Invariants

1. Start read-only. Prefer parallel discovery before editing to reduce write-conflict exposure.
2. Isolate every writer. A declared write scope is planning metadata, not enforcement. Use separate worktrees or cloud branches and validate actual writes.
3. Stop on missing dependencies. Never schedule a dependent wave after an upstream worker fails.
4. Verify from fresh context. This reduces shared-context coupling; it is a design rationale, not a guarantee of correctness.
5. Bound every loop. Set worker, token, time, retry, and repair limits before launch.
6. Preserve a human gate. Require approval for destructive migrations, production changes, security decisions, or broad automated merges.

A conservative starting policy might be:

max concurrent workers: 4
max total workers: 12
max repair iterations: 2
max wall time: 30 minutes
max token budget: team-defined

Those are example limits, not universal defaults. Anthropic’s 16-concurrent and 1,000-total figures are product ceilings, not targets. For larger fleets, see How to Run 300+ Subagents.

Runtime isolation

Security-sensitive Cursor hooks should use failClosed: true; command hooks otherwise fail open by default. Local SDK runs are unsandboxed by default. For local SDK runs, enabling the sandbox denies outbound network access from shell commands and shell-spawned processes unless hosts are allowlisted. Control Fetch and MCP access separately through hooks and tool policy.

Untrusted input and credentials

Auto-review is not a security boundary. Treat repository text, tickets, and fetched content as untrusted; scope credentials per worker; and enforce write paths outside model prompts. See Secure Agentic Code Generation for the broader threat model.

Option 1: A Prompt-Only Approximation

The fastest version is a reusable instruction:

For each request, first classify it as routine or substantive.

A substantive task has at least one of these properties:
- broad discovery across many files or services
- two or more independent work streams
- a migration or repetitive transformation
- a high-consequence result that needs an independent challenge
- evidence that must be cross-checked

For routine work, use the main agent.

For substantive work:
1. Define measurable success criteria.
2. Produce a dependency-aware plan.
3. Delegate independent discovery tasks in parallel.
4. Isolate any overlapping write tasks.
5. Use a fresh verifier to challenge the combined result.
6. Repair only verified failures, with at most two iterations.
7. Report tests, unresolved risks, and total delegated work.

This steers the agent toward the desired behavior, but it has weak guarantees. The model still decides how literally to follow the procedure, intermediate results still flow through conversation context, and there is no hard concurrency or budget controller.

Use this to test the idea, not as the final platform design. For the boundary between a one-off instruction and a reusable system, see When a Prompt Is Enough.

Option 2: Reproduce the Policy with Cursor Subagents and Skills

Cursor custom subagents are Markdown files. A planner can use a high-effort model while remaining read-only:

---
name: workflow-planner
description: Use proactively for broad, multi-stage, high-risk, or parallelizable engineering tasks.
model: claude-opus-4-8[effort=high]
readonly: true
---

Turn the request into a dependency-aware task graph.

Return:
- success criteria
- independent read-only discovery tasks
- write tasks and their expected file ownership
- dependencies between tasks
- verification commands
- stop conditions and unresolved risks

Then add a verifier:

---
name: workflow-verifier
description: Use after substantive changes to independently inspect and challenge the result.
model: inherit
readonly: true
---

Start from the task and success criteria, not from trust in the implementation.
Inspect the diff and supplied test output, look for missing cases, and try to
refute the claimed result. Report PASS, FAIL, or UNVERIFIED with concrete
evidence. List any commands that a separate test runner still needs to execute.

Finally, add an Agent Skill whose description identifies the trigger:

---
name: substantive-task-orchestrator
description: Use for broad, multi-stage, parallelizable, migration, audit, or high-consequence engineering tasks that need independent verification.
---

1. Decide whether normal single-agent work is sufficient.
2. If it is, continue normally and do not delegate.
3. Otherwise invoke workflow-planner.
4. Run independent read-only tasks in parallel.
5. Never run overlapping writers in one checkout. Start isolated worktrees or
   cloud branches first; otherwise execute write tasks sequentially.
6. Combine results against the original success criteria.
7. Invoke workflow-verifier with fresh context.
8. Run at most two repair-and-verify iterations.
9. Stop on budget exhaustion and report incomplete work honestly.

This configuration gives Cursor’s parent agent a similar general policy. It also keeps roles versioned with the repository. The example pins high because that value is documented for this Cursor model shape; discover the model’s available parameters before selecting xhigh.

The implementation owner must also be explicit. In the simplest Cursor-native setup, the parent agent is the only writer and executes write tasks sequentially. If you want concurrent writers, an operator or external scheduler must launch each task in a separate Cursor worktree or cloud branch before editing. Agent and skill configuration alone does not create that filesystem isolation.

There are three caveats:

1. A strong description encourages automatic invocation but does not create a deterministic session switch.
2. A subagent plan is still model-directed orchestration, not a generated program with explicit runtime state.
3. The read-only verifier inspects evidence; a separate runner must execute checks that write caches, build artifacts, or snapshots.

This path may be sufficient when model-directed scheduling, conversation-held state, and one sequential writer are acceptable. If you need application-managed replay, hard budgets, checkpoints, or auditable scheduling, move the policy into code.

The completion gate should be:

parent writer finishes in isolated worktree
  -> test runner executes required checks and stores raw output
  -> read-only verifier inspects task, diff, and test evidence
  -> human or policy approver accepts or rejects
  -> merge only after PASS + approval

Option 3: Build the Orchestrator with the Cursor SDK

Cursor released its SDK in public beta on April 29, 2026. It exposes the same broad agent runtime across local and cloud execution, so it is a practical foundation for building a more explicit orchestrator.

Start by discovering a model that supports an xhigh-like parameter instead of hard-coding provider-specific names:

import { Agent, Cursor } from "@cursor/sdk";

const models = await Cursor.models.list();
const approvedModelIds = new Set(
  (process.env.APPROVED_DEEP_MODELS ?? "")
    .split(",")
    .map((id) => id.trim())
    .filter(Boolean),
);

if (approvedModelIds.size === 0) {
  throw new Error("Set APPROVED_DEEP_MODELS to an approved model allowlist.");
}

const deepCandidate = models
  .filter((model) => approvedModelIds.has(model.id))
  .map((model) => ({
    model,
    effort: model.parameters?.find((parameter) =>
      parameter.values.some((value) => value.value === "xhigh"),
    ),
  }))
  .find((candidate) => candidate.effort);

if (!deepCandidate) {
  throw new Error("No approved model exposes an xhigh effort parameter.");
}

const deepModel = {
  id: deepCandidate.model.id,
  params: [{ id: deepCandidate.effort!.id, value: "xhigh" }],
};

const coordinator = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: deepModel,
  mode: "plan",
  local: {
    cwd: process.cwd(),
    sandboxOptions: { enabled: true },
    autoReview: true,
  },
  agents: {
    explorer: {
      description: "Read-only repository exploration. Use for independent discovery lanes.",
      prompt: "Gather evidence and return concise file-and-line findings. Do not edit.",
    },
    verifier: {
      description: "Independent verifier. Use after substantive work is complete.",
      prompt: "Try to falsify the result against its success criteria. Do not trust prior claims.",
      model: "inherit",
    },
  },
});

try {
  const run = await coordinator.send(`
  Classify this request as routine or substantive: ${process.argv.slice(2).join(" ")}

  For a routine request, return a concise answer without delegation.
  For a substantive request, define success criteria, delegate independent
  read-only discovery lanes, combine their evidence, and invoke the verifier.
  Do not let multiple agents edit the same checkout in parallel.
  `);

  const result = await run.wait();

  if (result.status !== "finished") {
    throw new Error(result.error?.message ?? `Run ended with ${result.status}`);
  }

  console.log(result.result);
} finally {
  await coordinator[Symbol.asyncDispose]();
}

This coordinator is intended to remain read-only, but prompts do not enforce that boundary. Deny Write and write-capable shell calls with a preToolUse hook, mount a read-only workspace, or run against a disposable snapshot. The pattern also requires Node.js 22.13 or later, @cursor/sdk, CURSOR_API_KEY, an APPROVED_DEEP_MODELS allowlist, a command-line task, and explicit agent disposal. See the Cursor SDK requirements. It is still model-directed and does not implement the full seven-stage workflow.

For deterministic scheduling, move the task graph and state machine into your application. The following is architecture pseudocode, not a drop-in SDK sample:

type Step = {
  id: string;
  prompt: string;
  dependsOn: string[];
  writes: string[];
};

type WorkflowPlan = {
  substantive: boolean;
  successCriteria: string[];
  steps: Step[];
};

async function runWorkflow(task: string) {
  const plan = await planTask(task); // Parse and validate structured output.

  if (!plan.substantive) {
    return runSingleAgent(task);
  }

  const state = await checkpointStore.create({ task, plan });

  for (const wave of topologicalWaves(plan.steps)) {
    assertDeclaredWriteScopesDoNotOverlap(wave);

    const settled = await Promise.allSettled(
      wave.map((step) =>
        runWorker(step, {
          workspace: createIsolatedWorkspace(step.id),
          readOnly: step.writes.length === 0,
          writeAllowlist: step.writes,
          budget: budget.forWorker(step.id),
        }),
      ),
    );

    await checkpointStore.recordEach(state.id, wave, settled);

    const failedStepIds = wave
      .filter((_, index) => settled[index].status === "rejected")
      .map((step) => step.id);

    if (failedStepIds.length > 0) {
      await checkpointStore.markBlocked(state.id, failedStepIds);
      await cleanupWaveWorkspaces(wave);
      throw new Error(
        `Workflow blocked; dependent waves were not scheduled: ${failedStepIds.join(", ")}`,
      );
    }
  }

  const candidate = await reduceResults(state.id);
  const testResults = await runTestRunner(candidate, {
    workspace: createIsolatedWorkspace("verification"),
  });

  const [verification, refutation] = await Promise.all([
    verify(candidate, plan.successCriteria, testResults),
    refute(candidate, plan.successCriteria, testResults),
  ]);

  if (verification.passed && !refutation.foundBlockingIssue) {
    const approval = await requestApproval({
      task,
      candidate,
      testResults,
      verification,
      refutation,
    });

    if (!approval.approved) {
      throw new Error(`Merge rejected: ${approval.reason}`);
    }

    return mergeAcceptedChanges(candidate, approval);
  }

  return boundedRepairLoop({
    task,
    plan,
    candidate,
    verification,
    refutation,
    maxIterations: 2,
  });
}

The omitted helpers are where production quality lives:

• planTask must return schema-validated output.
• topologicalWaves groups dependency-independent steps that can run together.
• assertDeclaredWriteScopesDoNotOverlap checks the plan, while post-run policy must also reject undeclared writes.
• createIsolatedWorkspace gives every worker its own snapshot or worktree and enforces read-only mode or a write allowlist.
• checkpointStore keeps state outside model context.
• runWorker must enforce application budgets and cancel the SDK run when a limit is exceeded.
• verify and refute should start with fresh contexts.
• boundedRepairLoop must stop, rerun tests and verification, and require approval before merging any repaired candidate.
• The workspace manager must merge accepted changes and handle conflicts, cleanup, and abandoned worktrees.

For an operational deployment, assign these responsibilities:

The state store should checkpoint after every worker, not only after a whole wave. A resumed run must use idempotency keys so completed work is not applied twice.

When the runtime reports token usage, read cumulative totals from run.usage or result.usage; the SDK documents that either may be undefined. Keep hooks focused on policy, lifecycle telemetry, formatting, and bounded follow-ups rather than hiding the scheduler inside hook scripts.

You can implement the same shape with another provider’s agent SDK, a queue plus CLI agents, or a minimal harness such as Pi. The invariants matter more than the vendor. For the broader planner-worker-verifier pattern, see The Senior-Engineer Agent.

Cost: Parallelism Is Not Free Intelligence

Cursor’s subagent documentation makes the tradeoff explicit: each subagent consumes its own context and token budget. Five subagents can use roughly five times the tokens of one agent.

A practical cost model is:

workflow cost =
  trigger decision
  + planner
  + sum(all worker contexts)
  + reducer
  + verifier and refuter
  + repair retries
  + human review

Parallel execution may reduce wall-clock time while increasing total token use. It can also increase human review load if workers generate overlapping or low-confidence findings.

A useful decision metric is cost per accepted result, not the number of agents launched.

How to Evaluate Your Clone

Compare four modes on the same task set:

1. Normal single agent
2. Prompt-only orchestration
3. Cursor subagents plus skills
4. SDK-controlled workflow

Include routine tasks as negative controls. A good trigger should avoid orchestration when it adds no value.

Pin the repository commit, model and effort settings, worker limits, tool policy, and acceptance criteria. Repeat each condition enough times to expose nondeterminism rather than comparing one favorable run from each mode. For more detail on delegation tradeoffs, see When to Use Subagents vs. the Main Chat Thread.

Track:

Record every run in a consistent shape:

type WorkflowEval = {
  taskId: string;
  repeatIndex: number;
  mode: "single" | "prompt" | "cursor-native" | "sdk";
  orchestrated: boolean;
  accepted: boolean;
  triggerWasCorrect: boolean;
  workerCount: number;
  failedWorkers: number;
  retryCount: number;
  writeConflicts: number;
  undeclaredWrites: number;
  policyViolations: number;
  findingsReported?: number;
  truePositiveFindings?: number;
  expectedFindings?: number;
  verifierOpportunities: number;
  verifierCaughtDefects: number;
  totalTokens?: number;
  wallTimeMs: number;
  humanReviewMinutes: number;
};

Start with at least 10 representative tasks plus routine negative controls, and repeat each task/mode combination five times. Report the median cost and latency, the range across repeats, and aggregate rates rather than choosing one favorable run. Set adoption thresholds before running the evaluation. For example:

no high-severity policy violations
zero undeclared writes
trigger precision >= 80%
accepted-task rate > single-agent baseline
cost per accepted result <= team ceiling
human review time does not increase

These are example gates, not universal targets. Finding precision is truePositiveFindings / findingsReported; coverage requires a labeled expectedFindings set; verifier catch rate is verifierCaughtDefects / verifierOpportunities. Keep the workflow only if it clears your predefined gates often enough to justify the extra cost and operational complexity.

What You Cannot Faithfully Copy

There are three boundaries to be honest about.

First, Anthropic documents the behavior of Dynamic Workflows, but not every internal decision behind how Claude Code recognizes a “substantive” task or writes an optimal workflow. A clone will use your own trigger and planner.

Second, selecting the same model and effort does not recreate the same harness. Tool design, context assembly, permissions, compaction, runtime state, and worker prompts all affect outcomes.

Third, the sources cited here do not include independent head-to-head evaluations showing that Ultracode outperforms simpler approaches across large coding tasks. Anthropic presents strong product examples, but teams should still run local evaluations.

The goal should not be pixel-perfect product imitation. It should be a transparent system that preserves the useful invariants:

deep reasoning when justified
+ explicit decomposition
+ safe parallelism
+ state outside chat
+ independent verification
+ bounded convergence
= an Ultracode-like engineering loop

Final Recommendation

If you want the behavior inside Cursor today:

1. Start with two custom subagents: a read-only planner and a skeptical verifier.
2. Add one narrow orchestration skill with clear substantive-task triggers.
3. Use model effort parameters only after discovering what the selected model supports.
4. Run discovery in parallel, but isolate writing agents in worktrees.
5. Add hooks for policy, telemetry, and bounded follow-ups.
6. Build an SDK-based orchestrator when you need application-managed replay, budgets, checkpoints, or deterministic scheduling.

If you are building a platform, skip the fiction that one large prompt is an orchestration system. Build a small state machine with a task graph, worker isolation, independent verification, and hard stop conditions.

Ultracode’s most transferable lesson is not “use more agents.”

It is:

Move coordination out of a fragile conversation and into an inspectable, bounded workflow.

That is the part worth reproducing in Cursor, another agentic IDE, or a harness of your own.

Related Reading

• Build an Ultracode-Like Coding Workflow with Agno and AgentOS
• Build an Ultracode-Like Coding Workflow with LangGraph
• Cursor Subagents and Claude Code /simplify: A Practical Workflow
• The Senior-Engineer Agent: Orchestrating Subagents and Loop Engineering
• Skills vs Default Agents: Do Coding Skills Really Improve Claude Code and Cursor?
• When to Use Subagents vs. the Main Chat Thread

Sources

• Anthropic, “Introducing dynamic workflows in Claude Code”, May 28, 2026.
• Claude Code Docs, “Orchestrate subagents at scale with dynamic workflows”, accessed July 15, 2026.
• Claude Code Docs, “Model configuration”, accessed July 15, 2026.
• Cursor Docs, “Subagents”, accessed July 15, 2026.
• Cursor Docs, “Agent Skills”, accessed July 15, 2026.
• Cursor Docs, “Hooks”, accessed July 15, 2026.
• Cursor Docs, “Worktrees”, accessed July 15, 2026.
• Cursor Docs, “Cursor TypeScript SDK”, accessed July 15, 2026.
• Cursor, “Subagents, Skills, and Image Generation”, January 22, 2026.
• Cursor, “Build programmatic agents with the Cursor SDK”, April 29, 2026.