How muxcode works
A tour of muxcode and mux, end to end: what runs on your Mac, the route one change takes, the gate, signing in, the code index, the sandbox, the plans, and how to turn each hosted part off.
At a glance
- muxcode runs pi, an open-source agent harness, on your Mac. The models you sign in to, and the one a paid plan includes, do the work; a gate in the app answers every tool call.
- mux, at usemux.com, adds a code index, agent memory, Clef, a cloud sandbox, an included model and Cowork. A local task needs none of it.
- Hobby is free. Pro is $12 a month and Pro+ $120, and a Mac's first sign-in can start a 72-hour Pro trial.
- Two switches and a sign-out stop every hosted part on a Mac, so a paid plan can still run as plain local pi.
muxcode splits the work in two. The models you sign in to do the thinking: they plan, write the code and judge the result. The app on your Mac does the deciding: which seat runs next, which checks must pass, and which tool calls may run without asking you. A model can ask for anything. Only the app can say yes.
This post is a tour of the whole system. It starts on your Mac, follows one change and one tool call, then goes out to mux: signing in, the code index, the sandbox, Cowork and memory. It ends with the plans and the switches that turn each hosted part off. The drawings you can click are interactive, and every rule in them is one the app enforces today.
What muxcode is
muxcode is a Mac app in two halves. A Rust host runs the sessions, the permission gate and every call to mux. A React window draws the composer, the transcript and Settings.
Inside the app ships pi, an open-source agent harness. muxcode builds it from source and bundles it, so nothing needs to be on your PATH. The host starts one pi process per task and drives it over RPC. pi owns the agent loop, the built-in tools and the model adapters. A muxcode extension gives it more tools and sends every tool call to the gate.
mux is the cloud side, at usemux.com, built on Cloudflare Workers. It adds the shared and paid parts. A local task needs none of them.
muxcode is a Mac app: a Rust host and a React window. It ships pi, an open-source agent harness, and starts one pi process per task, driven over RPC.
pi works with tools. The gate in the Rust host runs each call, refuses it or asks you. When a window fills, pi starts a fresh one with a short handoff.
mux is the cloud service at usemux.com. One router Worker sends /app, /api and /mcp to their Workers; cloud tasks have a host of their own.
mux mirrors the GitHub repositories you pick and indexes them in one container per workspace. get_context returns one ranked packet of code.
On a paid plan or trial, a task can run on mux. The agent runs in the task’s Durable Object on a sign-in your Mac lends it, and your Mac fetches the result.
Agent memory is two kinds of Git repo on mux: one shared per workspace, one private per member. Any connected plan can search it by words; meaning is paid.
The first two scenes need no mux connection; the last four are mux. Blue is muxcode, teal is pi, purple is mux, amber is the gate.
One change, start to finish
Select a step to read what runs there, or use the arrow keys to walk it in order. The seats name the roster muxcode ships with; you can change any of them in Settings.
Select a step to see what runs there.
Your prompt
A task in plain words. Every seat is given your own words, so nothing is lost to a paraphrase. Clef reads it once and picks the lane: a confined change your checks can prove runs solo, straight to the worker with your checks before and after; everything else takes this route.
- Starts on your Mac, in a worktree of its own
- A solo change that fails a check or touches a risky file comes back to the plan
Plan
The Architect reads the code it needs and writes a contract: the change, what it must not touch, and the verification that proves it.
- Its brief carries the checks your repository's manifests define
- Every change but a solo one starts here
Contract screen
Before a worker starts, the contract is read for gaps: a check you named that nothing runs, or verification that cannot fail. The host lints the plan first.
- No model re-reads the plan: the shipped roster has no critic, and the Architect stopped re-reading its own in muxcode 1.0.27
Baseline
Your project's typecheck, lint and tests run once on the untouched tree, with the tree watched for writes. What passes here is what the change may not break.
- Checks that would download their tool are never run
- Frozen for the run before the first worker
Seats
Every seat runs at the model and reasoning level you set, for the whole attempt. No reading picks a worker or moves an effort level. As shipped, every seat but the root is Claude Opus 5.5.
- From muxcode 1.0.12, Clef no longer routes workers or sets effort
- If the judge's model is not signed in, another that wrote nothing stands in
- A judge may share the worker's model; the second reviewer never does
Implement
The worker edits inside the contract at its set level. Every 8 tool calls Clef reads whether it has drifted or is stuck; a sure reading steers it once, a second stops it.
- The contract's post-edit checks run after every edit
- Every tool call still goes through the permission gate
Paused for you
A worker that needs what only you can give, an answer or a tool to install, pauses instead of failing. Resume puts the configured worker back.
- A pause is not a failure: no retry is spent
Gate
Code settles what code can: real exit codes, a check that passed at baseline and now fails twice, a secret the change added, a write to the tree. Where reading is needed, Clef answers at 0.6 to 0.75 or the code's fallback decides.
- Coverage and mutation testing inform the judge, never gate
- A gate reads only what this route changed
Judge
A judge reads the result against the goal through four lenses, in a session of its own that never saw the work happen. An accept that fails any lens is a reject, and nothing the gate found can be argued away.
- A fact from the gate always stands
- A change whose mistakes would pass the tests, or a High gate, also gets a second reviewer on another model
Retry seat
A failed check or a judged reject goes to the retry seat, the worker's model one reasoning level up, with the gap named. Its change goes back through the gate.
- A fresh attempt with more thinking, not the same one again
- You can put the retry on another model
Ready to land
An accepted change is yours: commit and push from the app, or fetch the branch a sandbox task left. Nothing lands on its own.
- The run keeps its record: seats, time, tokens and every command it asked to run
Three things decide the shape of that route.
Every change starts with a plan. The Architect writes a contract before any code is written: the change, what it must not touch, and the checks that prove it. Every step after it is checked against that contract.
Code settles what code can. The gate trusts exit codes, not descriptions of them. A check that passed on the untouched tree and fails after the change fails the change, and nothing the judge says can argue it away. Coverage and mutation testing are shown to the judge, but they never block a change on their own.
A retry is a fresh attempt. A rejected change goes to the retry seat with the judge’s points named: as shipped, the worker’s model at a higher reasoning level, or another model if you set one. Its work goes back through the same gate.
A workflow runs on every plan, with your own sign-ins. Read how the plan comes first for the whole route.
Where Clef fits
Clef is a small, fast classifier that reads along: Cloudflare’s 27B decision model, run as @cf/cloudflare/clef on Workers AI. Its main job is triage. Once per change it asks whether a project check would catch a wrong change, whether there is one place to edit, and whether a wrong change would pass the tests; a change it is sure of runs solo, proved by your checks before and after, and the rest take the workflow, with a second reviewer where mistakes would be quiet. It also answers typed yes-or-no questions along the way: is this contract missing a check, is this worker stuck, does this still-failing test fail in a new way. muxcode only acts on an answer that clears a fixed bar. When Clef is unsure, or not available, the configured choice stands.
Clef comes with Pro, Pro+ and the Pro trial, in token windows: Pro and the trial get 280,000 input tokens a day and 100,000 in each five-hour window; Pro+ gets ten times both. On any plan, Clef also runs with your own Cloudflare API token and account ID, on your own Cloudflare bill.
Clef is never a seat. It cannot widen a permission, move the judge’s model, or replace your Architect. It helps choose; the app decides.
Every tool call goes through the gate
The agent asks, and the gate on your Mac answers. Pick a permission mode and a call to see the questions the gate asks, in the order it asks them, and where it stops.
Asks you
It changes the project, and no rule of yours covers it.
The agent wants to run pnpm add zod.
A few of these answers surprise people.
- Plan mode refuses without a card. Plan mode is for research and proposals, so anything that changes a file or runs a changing command is refused, and the agent is told why.
- A
.gitfolder asks, except in Bypass mode. What is written there decides which programs git runs, so no rule lets an edit through unasked. Bypass runs it, and Plan mode never writes. - Bypass has one narrowing. A command the classifier is very sure would delete files outside the project, send data out, touch credentials or change the machine is put to you first. Everything else runs. From muxcode 1.0.6, a sandbox task skips this reading, because its gateway already refuses the agent’s uploads, publishes and pushes. In muxcode 1.0.5, a sure reading that a sandbox task’s command sends data out or touches credentials refuses it instead.
When the gate asks, the card names the exact call and offers four answers: allow once, allow for this session, always allow, or deny. An always answer becomes a rule you keep, so the same call is not asked about again.
When a context window fills, muxcode’s extension does not let pi summarise it. At the line, the window less pi’s reserve of 16,384 tokens by default, it starts a fresh window with a handoff of at most 20,000 characters, and the full transcript stays on disk. This is on for every plan and needs no mux; the Fresh context windows switch brings pi’s own summaries back. That is why we left compaction out; How Context works is the guide.
The models are yours
mux serves one hosted model. On Pro and Pro+, your own plan in a team workspace, it includes DeepSeek V4.1 Flash, listed in the model picker under AI Gateway, and the shipped workflow’s root runs on it. The other seats are filled from the sign-ins you already have; on a paid plan, a seat you have not signed in for runs on DeepSeek until you do. The work around them belongs to you, not to whichever model ran it.
- Tasks and worktrees
- Session history
- Notes and decisions
- Permission rules
- Your workspace's code index
Swap the Worker from Opus to anything else your sign-ins offer and the task, its worktree, its history and your permission rules stay exactly where they were.
Connecting to mux
One router Worker serves usemux.com. It sends /app to the web app, /api to the JSON API and /mcp to the MCP server other agents use. Cloud tasks have a host of their own, sandbox.usemux.com.
You need a mux account only to connect a workspace. muxcode signs in with a device code, so the Mac never sees your password.
- start sign-in
- a short code, good for 10 minutes
- open the code page
- you approve: Connect this Mac
- poll every 3 seconds
- once approved: one key, and the plan
- the key: credentials.json, mode 0600 a first sign-in can start a 72-hour Pro trial
The key leaves mux only once, on the first poll after you approve. muxcode keeps it in a file only your user can read, not in the keychain.
muxcode stops waiting after ten minutes. A Mac’s first sign-in can start a 72-hour Pro trial, once per Mac and per person. Sign out on this Mac revokes that Mac’s key; other Macs keep their own.
From muxcode 1.0.19, Create workspace opens mux’s workspaces page, where mux makes it, and Connect workspace signs this Mac in to the one you pick. A workspace other than Personal can also leave this Mac, from its × in the switcher or Remove from this Mac in Workspace Settings: its repositories move to Personal and muxcode clears its keys on this Mac, while the workspace stays on mux. Running tasks have to stop first.
The code index
Pick GitHub repositories on the web app, and mux indexes them for the workspace. A container mirrors each one into Cloudflare Artifacts and builds the search data. There is one container per workspace, and it sleeps after three idle minutes. Your own checkout is never uploaded.
An agent, local or cloud, calls get_context and gets back one ranked packet of code: keyword matches and the code graph on every plan, and matches by meaning on a paid one. The scene above draws it.
| Tool or part | Hobby | Pro, Pro+ and the trial |
|---|---|---|
grep_code, get_context, trace_code |
yes | yes |
search_code, ask_code |
no | yes |
| Repositories | 1, refreshed by hand | 20 or 50, refreshed on push |
Memory and code search goes deeper.
Where the sandbox fits
On Pro, Pro+ or a Pro trial, a task can run in a sandbox on Cloudflare instead of on your Mac; in a team workspace, your own plan counts. There the agent runs on mux, beside the task’s container, and keeps the conversation. Your Mac attaches to it and lends it a sign-in: a short-lived access token, or an API key for 12 hours, never a refresh token. The loan stays with the agent, never in the container.
The task runs without permission cards, cannot run commands on your Mac, is offered none of your MCP servers, and belongs to you: teammates see only its status. On Hobby, or with Sandbox by default off in Settings → Models, every task runs on your Mac.
and gate replies
over a socket
reads, and its fork
- MethodRequestAnswerRule
- GET registry.npmjs.org/zod forwarded download-read
- GET static.crates.io/crates/serde forwarded download-read
- POST github.com/acme/ledger.git forwarded git-fetch
- POST github.com/acme/ledger.git refused read-only-methods
- PUT registry.npmjs.org/zod refused read-only-methods
- GET paste.example.com/raw refused host-allowlist
The container reaches the internet through one gateway. It can download packages and fetch from GitHub; it cannot push anywhere but its own fork, or publish, or reach a host that is not on the list, and every decision is logged with the rule that made it. The task works on its own fork of the project and checkpoints to a branch, so nothing reaches your repository until you fetch it and choose to land it. A Cowork task works differently: when its run completes, the mux GitHub App opens a draft pull request, as the next section says.
Pro runs five sandboxes at once with 40 hours a month, Pro+ 12 with 300 hours, and the trial one, for 3 hours in all. How the sandbox is held in has the rest.
Cowork
Cowork, in muxcode’s sidebar, works a project’s GitHub issues. One box starts it. Paste an issue, as its link, #123 or owner/repo#123, and Start works it at once. Or describe the bug or the feature in your own words, and Write it up files a GitHub issue with you first: it reads what you typed, asks only what is missing, and takes the specs, PDFs and images you attach, drop or paste. Bug or Feature decides what the first test does: show something broken, or specify something new. Type / to pick a skill the repository’s cloud tasks carry, and it goes with the task.
Each task runs in the cloud on its own branch, on mux’s included model. The run’s first step writes a test that fails on today’s code; then a change makes it pass, and the run’s last gate runs that test again. When the run completes, mux writes the work as one commit with your git name and email, pushes it to a branch of its own on origin and opens a draft pull request as the mux GitHub App, for you to review. Your Mac takes no part after Start: you can close the lid or quit muxcode. Nothing merges on its own. A pushed branch runs your CI with the repository’s secrets, so Cowork holds back a change to what CI runs, such as CI and build files, manifests, lockfiles, agent guides or anything in a hidden folder, for you to push.
A task you start stays on the page as Cowork’s session until you press Back to start, across trips into other sessions and relaunches; the task keeps running in the cloud either way. History, the clock beside Refresh, lists every repository’s tasks in the workspace, grouped as Needs you, In progress and Done, and picking one resumes it. Where the workspace’s mux serves them, the Coworkers tab lists coworkers: standing teammates on mux, each with a job, rules for what it may do alone and what it must ask about first, routines, check-ins, webhooks, secrets and a model of its own.
Cowork needs a project whose workspace is connected to mux, with Pro or Pro+ behind it: the workspace’s own plan, or in a team workspace your own. Hobby and the trial do not include the model. The repository must be on GitHub, with origin naming it, and the mux GitHub App must be installed on it. The task starts from the default branch on GitHub, so what your checkout holds stays on your Mac. Only writing up a new issue uses gh, to file it.
Memory and MCP
Agent memory lives in private Git repos on mux, not on GitHub: one shared repo per workspace and one personal repo per member, each opening at MEMORY.md. A task on your Mac reaches it through the workspace_memory tool, and a cloud task with a ticket of its own. Memory needs a mux connection on any plan; search by words is free, and search by meaning is paid. How Memory works has the rest.
MCP has two sides. muxcode runs your own MCP servers, from ~/.muxcode/mcp.json, in local tasks on every plan, and asks before each call unless a rule of yours covers it. mux’s own MCP server at usemux.com/mcp gives other agents the code index and memory, with a workspace key.
Plans at a glance
The gate, fresh context windows, workflows and your own MCP servers come with every plan, Hobby included; on Hobby, pick the workflow’s root from your own sign-ins. The plans differ in the hosted parts. Prices are flat, per organization.
| Hobby | Pro | Pro+ | Pro trial | |
|---|---|---|---|---|
| Price | free | $12 a month | $120 a month | free, 72 hours |
| Indexed repositories | 1, by hand | 20, on push | 50, on push | 20, on push |
| Clef tokens a day | own key only | 280,000 | 2,800,000 | 280,000 |
| Clef tokens per 5 hours | own key only | 100,000 | 1,000,000 | 100,000 |
| Sandboxes at once | none | 5 | 12 | 1 |
| Sandbox hours | none | 40 a month | 300 a month | 3 in all |
| DeepSeek V4.1 Flash included | none | $2.50 of use a month | $35 of use a month | none |
| Cowork | no | yes | yes | no |
| Memory search | words | words, meaning | words, meaning | words, meaning |
Turning each part off
You can keep your plan and still run plain local pi. Two switches stop the hosted parts: Sandbox by default and Clef’s Read along. Memory has no switch of its own; signing the Mac out stops it, with the hosted index. Three more switches turn off muxcode’s local extras, if you want pi closer to stock.
- Sandbox by default Settings → Models → Cloud sandbox New tasks start on your Mac.
- Read along · Clef Settings → Classifier · and set Stand-in model to None
- sign out Sign out on this Mac · memory and the hosted index Settings, Workspace scope → Overview · memory has no switch of its own To keep code search, pick On this Mac under Repositories & index.
- The workflow’s switch Settings → Agents
- Each MCP server’s switch Settings → Integrations → MCP servers
- Fresh context windows · optional Settings → Models → Context windows pi’s own summaries return; restart open tasks.
The first three rows stop everything this Mac sends to mux. The last three need no mux at all; they are muxcode’s own, and turning them off is optional.
What this adds up to
You can hand muxcode a task and walk away. The change comes back planned, checked against your own tests, judged, and waiting on a branch. In a task on your Mac, anything that needed your say was asked, with the reason on the card; in a sandbox, such a call is refused.
Download muxcode for macOS or read how the sandbox is held in.
The working where each number comes from
- The app and pi: muxcode
src-tauri/src/harness/pi/pi.rs(onepi --mode rpcchild per session) andsrc-tauri/pi.json(the bundled pi), read 6 October 2026 at muxcode 1.0.6. - Router and hosts: mux’s
apps/router/src/routing.tsandalchemy.run.ts(the sandbox Worker’s own host), as of 6 October 2026. - Sign-in: muxcode’s connect code (poll every 3 seconds, give up after 10 minutes) and
src-tauri/src/workspaces.rs(credentials.json, mode 0600); mux’sapps/api/src/routes/connect.ts(one key, minted once). - Trial, prices and plan figures:
TRIAL_DURATION_MS(72 hours),PLAN_PRICES($12 and $120),PLAN_LIMITS(repositories, sandboxes, sandbox hours, search by meaning),TRIAL_LIMITS(1 sandbox, 3 hours) andPLAN_METERS(Clef tokens, and the included model’s $2.50 and $35 a month) inpackages/types/src/index.ts, anddocs/markdown/billing.md, on 7 October 2026; the sandbox and model figures read again on 28 October 2026. - Index container sleep:
sleepAfter = '3m'in mux’sapps/index/src/index.ts. - Fresh windows: the line at the window less pi’s 16,384-token reserve, and a handoff of at most 20,000 characters, from muxcode
src-tauri/src/harness/pi/context.ts. - Tools by plan: mux’s
apps/api/src/routes/workspace-corpus.tsrefusessearch_codeandask_codeon Hobby. - Switches: the labels in muxcode
src/components/settings/(CloudSandboxSettings,ClassifierSettings,ContextWindowSettings, the account card andWorkspaceSettings). - Included model: muxcode’s
CHANGELOG/1.077.mdand1.078.md(1.0.13 and 1.0.14) and 1.0.17’s release notes,default_model.rsand the shipped roster inorchestration.rs, read on 28 October 2026 at muxcode 1.0.19. Who pays: mux’sapps/api/src/billing/allowances.ts(accountAllowances: in a team, each member’s own plan) androutes/default-model.ts(a 402 where that plan’s model allowance is 0, as on Hobby and the trial), read the same day. - Cowork: muxcode 1.0.19’s
CHANGELOG/1.094.mdand1.096.md, andsrc-tauri/src/sandbox/issue.rs(what it holds back), read on 28 October 2026; muxcode 1.0.21’s release notes (no Mac after Start, the pull request from the mux GitHub App, the start from the default branch on GitHub), read on 2 November 2026. Back to start:CoworkSession.tsxat muxcode commite8e813b2(1.0.22), read on 4 November 2026. - Sandbox loans: never a refresh token, per
apps/sandbox/PROTOCOL.md, “The agent socket”; an API key’s 12-hour term isKEY_TERM_MSin muxcodesrc-tauri/src/harness/pi/login.ts.