Workflow Orchestration

Run dynamic workflows that coordinate many tasks across your providers, and watch Claude Workflow runs as a first-class approval, progress, and drill-in surface.

Codemux has two kinds of workflow, both part of the default Agent Chat GUI:

Dynamic workflows — Codemux itself runs a workflow script that adds, routes, and coordinates tasks across Claude, Codex, Cursor, OpenCode, and Hermes, keeps file changes isolated until you apply them, and records everything durably. You start these from the Workflows pane.
Claude Workflows — when a Claude agent runs its own Workflow tool (a script that spawns many subagents across named phases), Agent Chat surfaces it as an approval card, a live progress card, and an Orchestration panel instead of a raw tool call.

Dynamic Workflows

A dynamic workflow is a run that Codemux owns: a short JavaScript program adds tasks as results arrive, picks which provider and model handles each one, and can replace, message, cancel, or retire work along the way. Codemux schedules the tasks, enforces the run's limits, and keeps a durable record of every task and attempt.

Opening the Workflows pane

Click the Dynamic workflows button (network icon) in the composer footer, or open the Workflows tab in the right panel. The pane is available in local workspaces only — not in device or attach-only workspaces, and not from a Web Remote Access browser.

The picker at the top lists New workflow and your previous runs with their status.

Setting up a run

Run name and Goal — what you want done.
Providers — tick the providers that may work on it. Each shows Live or Dry run only for this machine.
Models and routes — optionally pin a model or effort per provider, or Add route to use more than one model from the same provider. Scripts pick a route by ID; an omitted ID uses the first route. OpenCode needs an explicit provider/model; Cursor uses its default effort, so leave effort empty.
Limits — worker ceiling (Auto (bounded) or 1–256), task budget, attempt budget, nesting depth, output limit, token budget, and time limit. Auto uses a bounded host ceiling; retries share the attempt budget. The token budget controls admission — it's not a hard dollar cap.
Allow file changes — off by default. Write tasks keep their changes isolated until you review and apply them.
Workflow script — the built-in read-only starter reviews three areas of the workspace in parallel, then asks for a summary. Edit it, Save script for reuse, or Load a saved script…. Script reference summarizes the API.

Then choose:

Dry run — exercises the scheduler and your script without calling any model. No tokens are used.
Run with agents — enabled only when every selected provider reports live support and its required settings are filled in.

The script API

Scripts are async function bodies — top-level await and return work. They read goal, routes, and args:

await workflow.phase("Inspect");
const areas = ["architecture", "tests", "integration"];
const findings = await parallel(areas, (area, index) =>
  agent(goal + "\nInspect " + area + ". Return concrete findings.", {
    id: "inspect-" + index,
    title: "Inspect " + area,
    route_id: routes[index % routes.length].id,
    access: "read_only"
  })
);
await workflow.phase("Synthesize");
return await agent("Summarize findings and propose the next steps: " +
  JSON.stringify(findings), {
    id: "synthesis",
    title: "Synthesize findings",
    route_id: routes[0].id,
    access: "read_only"
  });

agent(prompt, options) creates a task and awaits its outcome; parallel(items, fn) fans out.
workflow.addTask(spec) and workflow.wait(id) express dependencies.
workflow.replace, workflow.cancelTask, workflow.message, and workflow.retire adapt the plan as results come in.

Scripts have no imports, network, files, or timers, and must await every workflow operation. A script can't grant write access — custom write tasks also need Allow file changes.

Watching and steering a run

A running workflow shows its phases, a compact worker-capacity readout, and task lists grouped into checkpoints. Select a task to see its prompt, attempt history, messages, and result; from there you can Send message, Cancel task, Retry task, or Remove from run. At the run level:

Pause stops new work from starting; already-running workers finish. Resume continues.
Cancel run stops everything. A worker's slot is held until its stop is confirmed; if that can't be verified, the task shows Needs confirmation rather than being retried automatically.
Edit as a new workflow copies a run's settings and script into a fresh draft.

Managed workers use a restricted set of workflow tools — they can't run shell commands, builds, or project tests. Ordinary chat sessions keep their normal tools.

Reviewing and applying file changes

File changes from write tasks stay in isolated snapshots. Review file changes shows each changed file before and after; Apply writes every file in the change set to your workspace — including files you haven't previewed — and stops if the workspace has changed since the run started. Changes from an earlier attempt of a task are review-only, and a cancelled run's results stay viewable but can't be applied or retried.

Requirements and configuration

Live runs require Linux and a local git workspace. On other platforms, providers report Dry run only.
Claude and Codex use their existing sign-in. Cursor uses its SDK login or CURSOR_API_KEY, which is separate from the Cursor CLI login. OpenCode needs an explicit provider/model and an API key in the environment. Hermes needs a prepared source checkout and Python environment. Grok is dry-run only for now.
A workspace can narrow its own limits with .codemux/workflows.json — for example {"concurrency": 2, "max_tasks": 100, "token_budget": 100000, "deny_writes": true}. Project caps can only narrow limits, never grant permissions. Host-wide ceilings live in ~/.config/codemux/workflows.json (restart the app after editing).

Claude Workflows

When a Claude agent runs a Workflow — a script that spawns and coordinates many subagents across named phases — Agent Chat surfaces it as a first-class run instead of a raw tool-use block. You get an in-thread approval card, a live progress card, and a dedicated Orchestration panel where you can drill into each phase and each subagent.

This is a Claude-only feature. Other providers don't emit Claude Workflow runs, and the /workflow command is visible-but-disabled ("Only available with Claude models") for them. To coordinate work across providers, use dynamic workflows.

Starting a Workflow

Type /workflow in the composer (it's in both the / command menu and the + menu, under Workflows) and describe the task you want orchestrated — for example "review this diff across correctness, security, and performance." Selecting the command just inserts /workflow into your draft; you write the rest and send it like any other message.

Claude decides whether the task warrants a Workflow and, if so, writes and runs the orchestration script itself. You don't author the script — you describe the goal.

The Approval Card

Because a Workflow can spawn dozens of subagents and use a lot of tokens, it asks for approval before running. The approval card shows:

Planned phases — the named stages the Workflow will run (e.g. Find → Verify → Synthesize).
A token-use caution — a reminder that orchestration fans out across many agents.
Run once — approve this single run.
Always for this project — persist a permission rule so future Workflow runs in this project skip the prompt (written to the project's .claude/settings.local.json).
View script — inspect the exact orchestration script before you approve.
Deny — reject the run.

Live Progress

Once approved, the card becomes a compact progress line — "phase 2 of 4," a running-agent count, and a progress bar. Click it to open the Orchestration panel.

When the run finishes it collapses to a summary row (completed / failed / stopped) that you can still click to reopen the panel, plus the agent's own written report in the transcript.

The Orchestration Panel

The Orchestration panel is a right panel tab that appears only while a workspace has an active or recent Workflow run. It gives you the full picture:

Run header — name, status, and live ticking stats (agents, tokens, elapsed). While the run is waiting for approval, the header also has Run once and Deny.
Phase cards — one per phase, each expandable, with per-phase agent / token / elapsed rollups and status-filter chips (all / running / issues).
Agent rows — every subagent in a phase, with a finding badge when it reports structured findings or issues.
Agent drill-in — click a subagent to see its prompt, recent tool calls, and result. When its activity points at a file, an Open action jumps you straight to it in the editor. Press Esc to back out.

Stopping a Run

While a run is going, the panel header has a Stop workflow button. Stop currently interrupts the whole turn rather than the workflow alone.

Current Limitations

Claude only. Other providers never produce Claude Workflow runs; the progress card and Orchestration panel never appear for them.
No pause. A Claude Workflow can only be stopped, not paused.
Per-agent Restart isn't supported yet — the drill-in's Restart agent button is disabled.
Stop interrupts the whole turn, not just the workflow — there's no "stop this workflow only" control yet.
Phase and token attribution are approximate. Subagents are attributed to the running workflow heuristically, and token / agent totals are rolled up from multiple sources rather than one authoritative counter.
Long results are truncated before they reach the panel.

Agent Chat — the chat pane that hosts workflow runs, including the Subagents card the panel builds on
Delegation & Devices — hand a single task to another installed agent or machine
Right Panel — where the Workflows and Orchestration tabs live
Settings — Interface and per-project Permissions

On this page