Skip to content
Preview
Search the docs
Type to search the docs.

    How Clef works

    Guide

    Clef is the classifier that reads along while muxcode works. From muxcode 1.0.12, every built-in reading runs on Clef, Cloudflare’s 27B decision model on Workers AI (@cf/cloudflare/clef): the lane a change takes, intake, the contract screen, verification, gate checks, and the questions asked about a turn, command or tool result. mux runs Clef for every call unless a call names clef-flash, the smaller model muxcode used from 1.0.5. This page explains:

    • how Clef picks the lane each change takes;
    • where Clef reads a run;
    • what a sure answer changes;
    • what Clef no longer decides, from muxcode 1.0.12;
    • what happens when it is slow, unsure or off;
    • which plans include it, and how to use a key of your own;
    • how to steer it, or turn it off, from Settings → Classifier.

    Clef reads, muxcode decides

    Section titled “Clef reads, muxcode decides”

    Clef writes no code and holds no seat in a workflow. At fixed moments muxcode puts a typed question to it about text muxcode already has: a goal, a contract, a report, a command. Clef answers with a probability, a choice and its confidence, or a score. muxcode then compares that answer with a fixed bar.

    Only an answer over its bar acts. Each question has one fixed bar. The two dots are made-up answers to a 0.85 question: 0.91 acts, and 0.62 leaves things as they are.

    A sure answer changes one bounded thing: a stage, a failed gate, a line for the judge, a card on a bypassed command. An unsure, slow or missing answer changes nothing, and the run carries on as it would without Clef. Clef can never widen a permission. Scope checks, verification and the final judgement stay separate from classification.

    Where you can see it

    Section titled “Where you can see it”
    • Agents panel: each run’s routing line, for example “Plan first: fixed planner; intake read logic (0.91), hard 0.40 on …”. Each step’s receipt shows the model and the reasoning level its seat was set to.
    • Permission cards: a risky command’s card names what Clef read in it.
    • Settings → Classifier: every question Clef is asked, grouped by where it is asked, with calibration charts for each.

    Slow answers are skipped

    Section titled “Slow answers are skipped”

    A question asked about a turn, tool result or card waits 2.5 seconds for an answer. A question asked once per run, such as intake or the contract screen, waits 8 seconds. Each gets one retry. Past that, the question changes nothing and the run carries on as if Clef were off. The run never waits longer on Clef. Where a skipped answer leaves a mark, you see the default instead, such as a gate decided by its code checks alone.

    A slow answer is a skipped answer. Each question gets two tries at its wait, then the run moves on without it.

    Triage: the lane a change takes

    Section titled “Triage: the lane a change takes”

    Clef’s main job is triage. Once per change, at intake, it answers three narrow questions about your goal and your own words:

    Question What it asks Bar
    Check proves Would a check the project already has catch a wrong change? 0.60
    Confined Is there one place to edit? 0.85
    Subtle Would a wrong change still pass the tests? under 0.50 for solo; 0.80 for a second reviewer

    Code, not Clef, then picks one of three lanes:

    • Solo. One worker makes the change, with no plan, review or judge. The project’s own checks run on the untouched tree first and again after the change; they are the proof. A change takes this lane only when Clef is sure it is confined and provable, leans no on subtle, and reads no hard signal such as a migration or a change only a person can see. Solo runs on local tasks only, with project checks on.
    • Workflow. The Architect plans, the plan is reviewed, the worker builds, the gate checks, and a judge on another model decides. Every doubt lands here.
    • Workflow with a second reviewer. When Clef is sure a wrong change would pass the tests, or the change touches something whose mistakes are quiet (concurrency, a migration, auth, billing or infrastructure), a second reviewer on a model that neither wrote the change nor judged it reads the verified change without the judge’s verdict. Only its accept completes the run. A final gate that reads High risk adds the same review.

    A solo change goes to the full workflow, from the tree it left, when a check that passed before fails after, the gate flags a risk (a High reading, a manifest that defines checks, agent configuration or a dependency), the worker changed nothing, or the project has no checks. Only an answer Clef itself gave can choose solo: a stand-in model’s answer, or none, takes the workflow.

    The lane’s cuts were set on one labelled set and frozen before a separate holdout of 30 cases was written. On that holdout no change was sent solo by mistake, 9 of 10 true solo changes were, and 6 of 9 subtle changes got the second reviewer, none wrongly. The cases were written by the people who wrote the questions; real tasks are messier. On the benchmark tasks, a single agent and the default workflow both passed 24 of 24, and the workflow used about 30% more tokens.

    Why Clef, not Flash. With effort and worker choice gone, the readings left are few and high-stakes. On muxcode’s full calibration set, Clef met the bar on 16 of 19 question groups and Flash on 10. Clef’s three misses (a plain question’s intent, a weakened check and a drifting worker) catch too few true cases; every sure answer in them was right. Across the whole set Clef gave one wrong sure answer: it read a copy into the project’s own ./etc as touching files outside it, which draws a card you did not need. Clef also reads a 64K window, where Flash’s hosted window is 24K.

    One workflow run, where Clef looks

    Section titled “One workflow run, where Clef looks”

    A writing run meets Clef at each hand-off: intake, the contract screen, the worker’s progress, the gate, and the reading of its report. Each answer can move the run one bounded step. None of them skips the Architect’s plan, the scope gate or the judge, and none changes a seat’s model or reasoning level.

    Five hand-off readings, each with its own bar. No reading picks a model or a reasoning level. At the gate, scope, verification and secrets are code; Clef reads a check that fails in a new way, a weakened check and a test that only checks code ran.

    Intake. Before any model is paid, Clef reads your goal and your own messages:

    • the kind of change (logic, UI or terminal) and its risk;
    • whether you asked for a test;
    • whether the change can only be checked in the built app;
    • which paths you protected;
    • the constraints you stated.

    The constraints become a checklist the judge is handed. The same reading picks the lane; outside the solo lane, the Architect plans every change.

    Contract screen. Clef reads every contract before a worker runs, for four defects:

    • it cannot prove its goal;
    • it cannot reach a file the goal needs;
    • it leaves out the verification you asked for;
    • it contradicts a constraint.

    A sure defect sends the contract back to the Architect once. The roster muxcode ships has no separate critic: this screen, plus the Architect re-reading its own plan, does that job.

    Worker supervision. The worker runs at the model and reasoning level you set. Every 8 tool calls Clef reads whether it has drifted off its contract or is repeating itself with nothing new. At 0.85 or more the worker is steered once; read so again, it stops with a blocked report.

    Verify and caveats. After the checks run, Clef reads the worker’s summary against the verification log. Does it claim a check the log contradicts or never ran? Does it admit to skipping work? An answer over its bar reaches the judge as a line to read first, such as “read the log before the summary”. An accept that comes with caveats is read for how much they weigh. A worker that reports it is blocked is read for why: a missing tool or runtime pauses the run for you instead of spending the retry.

    The gate. The gate’s facts are code: an exit status, a check that passed before and fails now, a key in the change, a write to the tree. A fact always stands. Clef reads what code cannot settle, and a sure yes fails the change:

    • a check that still fails, but in a new way, at 0.6;
    • a rewritten check script or build file that checks less, at 0.65;
    • a changed test that only checks the code ran, at 0.75.

    A surviving mutant that matters to the change is read at 0.7 and shown to the judge; it never fails the gate. When Clef does not answer, code fallbacks decide, from names and counts.

    What Clef no longer decides

    Section titled “What Clef no longer decides”

    Until muxcode 1.0.12, Clef also set a seat’s reasoning effort before each model call, in leases of 1 to 10 calls up to an “Up to” ceiling, and could move a work package to a cheaper worker. A live comparison on 19 October 2026 found neither changed a decision: 164 effort readings left every level where it was, and 10 worker readings all stayed under their bar. Both arms passed 10 of 12 hidden checks; with Clef reading, runs used 1.3% more model tokens and took 27% longer at the median. muxcode 1.0.12 removed both.

    Every seat now runs at the model and reasoning level set for it on the Agents page, for the whole attempt. There is one Worker row, with no pool and no “Up to”. As shipped, the Default workflow runs:

    • the Architect, Claude Opus 5.5 at high, which plans, re-reads its own plan and replans;
    • the worker, Claude Opus 5.5 at medium;
    • the retry, Claude Fable 5.1 at xhigh, after a rejection or a failed check;
    • the judge, GPT-6.1 Sol at high.

    The judge is on a different model from the Architect, the worker and the retry, so the model that accepts the work did not write it. The default is the one workflow muxcode ships; Clef sizes each change inside it. If the roster’s judge is not available on your sign-ins, or a roster saved before 1.0.12 shares a writer’s model, muxcode seats another model that wrote nothing in the run; if none is available, the roster’s judge stands. A workflow started before 1.0.12 stops at its next step and needs a new run.

    Sure means a bar

    Section titled “Sure means a bar”

    Every question has a fixed bar. A bar is high where acting wrongly would be costly: sending a chat turn to a cheaper model, or reading a task as a change before any lane but the workflow, takes 0.9; a change only runs solo when it is confined at 0.85, and steering or stopping a worker takes 0.85 too. A second reviewer joins at 0.8 on subtle. Dropping a tool result from the context works the other way round: its probability of mattering must be under 0.1. In between, the bypass guard, a block kind and a tool result giving the model orders take 0.8; a contract defect, a stated constraint and a command’s risk take 0.7; a retry on the same seat, how a turn ended and whether a check proves the change take 0.6. For solo, subtle must read under 0.5, and a hard signal or a change only a person can see under 0.1.

    The gate’s readings and the bypass guard were recalibrated in muxcode 1.0.12. Their cuts were picked from a first live set and checked on a separate set of 84 cases with 144 labelled answers, both answered by Clef Flash before the switch to Clef. At each new cut every sure answer in that set was right, and each caught at least half of its true cases. The samples are small, so read these as measured starting points, not guarantees.

    Reading Bar Right when sure Caught
    A check fails in a new way 0.60 7 of 7 7 of 8
    A weakened check 0.65 4 of 4 4 of 8
    A test that only checks code ran 0.75 7 of 7 7 of 8
    A surviving mutant that matters 0.70 5 of 5 5 of 8
    A risky command under bypass 0.80 9 of 9 9 of 12

    The cuts have not yet been chosen again for Clef. On Clef’s answers to the full set, the weakened-check cut is still right every time it is sure, but catches only 2 of 8 true cases; the bypass guard is right on 12 of 13 sure answers and catches all 12.

    Under bypass, a command read at 0.6 or more but under 0.8 runs with a notice in the transcript; at 0.8 or more it draws an allow-once or deny card.

    The bar rises with the cost of a wrong move. Most questions act at or over their bar. The result filters act only under 0.1, when Clef is sure the text is not needed, and solo needs subtle, a hard signal and native UI to read under theirs.

    The interesting answers sit just under a bar. The Classifier page counts how many answers fall within 0.1 of each one: those are the answers that would flip if the bar moved.

    Outside workflows

    Section titled “Outside workflows”

    Chat tasks meet Clef too, in the same read-then-compare way:

    • how a turn ended, and whether more is needed;
    • whether a plain question can go to a cheaper model for one turn;
    • whether a tool result carries an instruction, which is flagged before the model reads it;
    • in long tasks, when to remind the model to checkpoint, what the handoff to a fresh window keeps, and which tool results can be left out;
    • the order of history search results;
    • the risk named on a permission card.

    From muxcode 1.0.6, Clef does not read a cloud task’s commands: muxcode makes no Clef call for them, refuses none on Clef’s word, and adds no notice. The sandbox holds the task in instead. Its container has none of your credentials, and its gateway forwards reads only, to a list of package registries, GitHub and the task’s own fork. It refuses an upload, a publish or a push the agent runs, and removes any sign-in header a request carries. On your Mac, the bypass guard is unchanged.

    In muxcode 1.0.5, while your Mac was attached, a cloud task’s command that Clef read as sending data out or touching credentials was refused instead of asked about.

    Steering Clef: Settings → Classifier

    Section titled “Steering Clef: Settings → Classifier”

    The page opens with what Clef is: something happens, Clef reads it, only a sure answer acts. It then lists every question Clef is asked. Below that, the switches sit on cards grouped by what they change. Read along, Reuse recent answers and Guard bypassed sessions start on; the cheaper model and the stand-in model start at None.

    Each switch and what it changes, with the state a new install starts in.

    Plans, keys and token windows

    Section titled “Plans, keys and token windows”

    muxcode picks who answers each call, checking in this order:

    1. Your own Cloudflare API token and Account ID, when you saved both. The call goes to Workers AI directly, for any project on any plan. It uses your own Cloudflare account and spends none of your included Clef tokens.
    2. A spent token window. Clef pauses until that window resets.
    3. mux, when the project’s workspace is signed in on Pro, Pro+ or the trial. In a team workspace, Clef comes from your own plan.
    4. A debug build, which muxcode’s developers run, uses a token built into it. The download never does.
    5. No one. muxcode makes no Clef call. The code’s own checks decide.

    The first yes decides. Your own token comes before any window or plan, so a spent window never stops it.

    Through mux, Clef counts the input tokens it reads, per person, across all your workspaces, teams included: 280,000 a UTC day and 100,000 per five-hour window on Pro and the 72-hour trial, ten times that on Pro+, and none on Hobby. Workflows run on every plan.

    Two limits, both in force. Each column has its own scale; Pro+ gets ten times Pro’s tokens in both.

    The day resets at midnight UTC. The five-hour windows are fixed, and run apart from the day. From muxcode 1.0.5, the plan sheet shows both reset times and any tokens held for pending calls. Once a window has less than 1% left and too little for your smallest call in it, Clef pauses until that window resets. muxcode then says “You’ve reached a Clef input-token limit”, with the time it comes back. Short of that, mux may turn away one call that is too large for what a window has left, or that has to wait for calls still pending. That question changes nothing, and Clef stays on. A spent window pauses Clef only: the sandbox, and a trial, keep running.

    Your coding models keep their own provider billing and limits.

    Under Advanced: endpoint, a custom or local endpoint changes which service answers; every reading still asks for clef. Recorded answers from a test endpoint do not prove live classifier availability or plan metering.

    Hobby, and Clef turned off

    Section titled “Hobby, and Clef turned off”

    On Hobby with no token of your own, muxcode makes no Clef call. The Classifier page says “Clef is part of Pro; the code fallbacks decide until you upgrade or add your own token”. Every reading falls back to code:

    • the Architect still plans and the judge still judges;
    • the mechanical contract screen still runs, without Clef’s;
    • every seat runs at its configured model and reasoning level, as it does with Clef on;
    • the gate’s code fallbacks decide what Clef would have read;
    • the third time a worker runs the same failing command with the same output, it is steered; the fifth time, it is stopped;
    • a run’s routing line adds “Clef is off for this project, so the host’s own checks run and its readings (contract screen, block triage, worker supervision, summary check) do not”.

    To turn Clef off on any plan, switch off Read along. No Clef call is made, and the page says “Clef is off”. A stand-in model you named still answers the low-stakes questions; set Stand-in model to none to stop those too. Run on your Mac only lists the other switches.

    Stakes and the stand-in model

    Section titled “Stakes and the stand-in model”

    Every question has stakes:

    Stakes Clef on and allowed Clef off, not allowed, or failing
    High the classifier nothing changes
    Low the classifier the stand-in model, if you named one

    The stand-in answers low-stakes questions, such as how a turn ended, the order of search results, or a reader’s wrap-up. Its answers are uncalibrated, logged separately, and never drawn on the charts. It never times the checkpoint reminder, and never wraps up or steers a reader.

    Reading the calibration charts

    Section titled “Reading the calibration charts”

    For each question the page draws a histogram of Clef’s answers in tenths, with the bar drawn over it. It counts how many answers acted and how many sit within 0.1 of the bar. Where the outcome is known, it adds a dot per tenth for how often the outcome came true, and a Brier score.

    On a calibrated question the dots climb the diagonal. A cluster of answers inside the band is where a moved bar would change the most. The counts are made up.

    An outcome is only what actually happened, for example whether you denied a card Clef drew. It is never a second model’s opinion. Use the charts to ask whether a bar sits in the right place. The bars themselves change only in new versions of muxcode.

    Next

    Section titled “Next”