Cowork: from an issue to a draft pull request

Guide

Cowork is the page in muxcode’s sidebar, under New Chat, that works your project’s GitHub issues. Press ⌘I to open it. Give it an issue, or say in your own words what is broken or what you want built, and mux works it in the cloud, with no Mac after you press Start: you can close the lid or quit muxcode. A task goes through three steps:

1. Starting. mux claims the issue and starts a task from your default branch on GitHub.
2. Working. A test that fails on today’s code shows the problem, then the change that makes it pass.
3. Pull request. The mux GitHub App opens a draft pull request for you to review. Nothing merges on its own.

Every step, the write-up included, runs on DeepSeek V4.1 Flash, the model mux includes with Pro and Pro+, so a Cowork task needs no OpenAI or Anthropic sign-in of your own. Its second tab, Coworkers, holds standing teammates on mux that work on your repositories while you are away, on a model whose sign-in this Mac lends them.

This guide describes muxcode 1.0.21. Settings shows which version you run.

What Cowork needs

Cowork asks mux for all of this before a start, says what is missing, and files and spends nothing until it can start.

• Pro or Pro+. The project’s workspace must be connected to mux, and mux bills the model to a Pro or Pro+ plan: the workspace’s own, or in a team workspace your own. Hobby and the trial include no model allowance.
• The mux GitHub App on the repository. It reads the issue and the default branch, and it opens the pull request. An owner installs it from mux in the browser; Install the GitHub App sits beside Check again while it is missing.
• Access to the repository. The workspace’s owner can start a task, and so can a member whose GitHub account is linked to mux and who can push to the repository.
• origin on GitHub. origin must name the repository on github.com. To file a write-up, gh must be signed in and file in that same repository.
• A repository a cloud run can finish. Up to about 4,000 tracked files; no submodules, since a task does not fetch them; and no .gitattributes line that makes a checkout differ from what git stores: filter, ident, working-tree-encoding, or eol=crlf on anything but Windows’ own scripts (.bat, .cmd, .ps1).

Your checkout’s own state only informs: what you have here stays on this Mac, and the task starts from the default branch on GitHub. Each task runs within your plan’s sandbox hours and awake sandboxes, and its model and Clef are charged to whoever started it.

Start from an issue

1. Open Cowork in the sidebar, or press ⌘I, and pick the project at the top. Cowork and Pull requests share that choice.
2. Cowork opens on What should we work on? and one box. Paste the issue: its link, #123, 123, owner/repo#123 or host/owner/repo#123. Only the whole box counts as an issue, so “fix #12 crash” is words, not issue 12.
3. Under the box, choose Bug or Feature; the arrow keys move between them. A bug’s first test shows what is broken. A feature’s first test describes what is new.
4. Read the line under the box, which says what the button will do, then press Start.

The issue must belong to the project’s own repository, since the pull request goes there, and it must have a description: Cowork works from what the issue says, not from its title. The agent gets up to 12,000 characters of the issue’s text, with its link for the rest, and muxcode tells it the text is a report to work from, not instructions. An issue that another Cowork task is already working does not start twice.

Add skills

Type / in the box, or press the skill button, to pick a skill this repository’s cloud tasks carry. Each pick shows as a chip, and the task names it to the agent after the issue’s text. A task takes at most eight. Choose which skills a repository’s cloud tasks carry in Repo Settings → Skills for cloud tasks.

Write up a bug or a feature

With no issue yet, type what is wrong or what you want in the box and press Write it up. Cowork writes the issue with you, files it on GitHub, then works it.

• It reads what you typed at once. The first line becomes the title and the rest answers the first question. It then asks only what mux’s model still needs, one to three questions at a time, in the kind’s own terms: “One thing to pin the bug down”, or “2 things to settle about the feature”.
• Three rounds at most. Answer, then press Send answers. Leave a question blank to let the agents decide. By the third round the model stops asking, writes the brief from what it has, and marks the gaps.
• The form folds away under The bug in detail or The feature in detail, with a count of the fields you have answered. Open it to fill any field in yourself.

	A bug	A feature
The form asks	What happens? What should happen instead? How do you make it happen?	What should it do? Who is it for? How will you know it’s done? What’s out of scope?
The issue’s sections	What happens, What should happen, Steps to reproduce, Fixed when	Behaviour, Who it is for, Done when, Out of scope

Both also take Constraints. Where you attached files or links, the brief has a Material section: what each file or image shows, and each link as you gave it.

Attach a spec, a screenshot or a log

• Press + beside Bug and Feature to pick Markdown, text, PDF or image files. You can also drop a file anywhere on the Cowork page, or paste an image. Each file shows as a chip with a remove button.
• A bug asks you to show what happens: a screenshot, a log or the error itself. A feature takes a spec or a design, and keeps a design link as a link.
• Text and PDF files are read whole, up to 40,000 characters each. The model looks at an image of up to 4 MB, and the brief describes it. Cowork marks a file it cannot read, such as a .docx or a PDF with no text, and the line under the box says why.
• Images never reach the issue: GitHub’s API has no way to upload them. What the brief says of an image, and any link you add, is what the issue carries.
• Files go with a write-up only. With an issue and files both in the box, the button is off until you remove the files.

File it

Next to the questions, Cowork shows the brief as the issue will read. Edit anything before you file it: the issue carries exactly that text. When the brief is ready, File the issue and start turns blue. muxcode files the issue with gh in the project’s repository, adds a line saying Cowork filed it, and starts it as if you had pasted it.

The model only suggests. Its questions are yours to answer, its brief is yours to edit, and Cowork files nothing until you press the button.

Cowork asks mux first, so a project that cannot start files nothing. A start mux refuses after that, such as a repository with too many files, leaves the issue on GitHub. Fix what Cowork names, then paste that issue’s number into the box and press Start. Pressing File the issue and start again would file a second issue.

Back drops the write-up and returns to an empty box. A write-up you leave for a session or another repository waits for you, one per repository, until you quit muxcode.

What happens next

The task runs on mux, as far along the next time you open Cowork as it got. Its first step writes a test that must fail on the code as it is, and its last must make that test pass. The run’s own checks decide whether the bug was shown and fixed, not the agent’s word. If the test cannot show the bug, the task stops as Not reproduced.

When every check passes, mux:

1. makes one commit of the task’s work, on the commit the task started from, with your git name and email as its author;
2. pushes it to a branch named muxcode/issue-<number>-… on GitHub;
3. opens a draft pull request as the mux GitHub App (<app>[bot]), naming you in its description.

None of this touches your working tree, your index or the branch you have checked out. The pull request carries exactly the files the run’s final check read, and nothing else. A file over 4 MiB, more than 2,000 changed paths or 48 MiB in all is not something Cowork pushes from the cloud.

A pushed branch runs your repository’s CI with its secrets, as any pushed branch does. So Cowork does not push a change to what CI or the repository’s tools read: hidden folders such as .github, dotfiles, CI files, build and task files, tool settings, manifests, lockfiles and agent guides. The task says which files it held back. Review the change in the task’s session and open the pull request yourself from its Git menu.

Nothing merges on its own. Review the draft on GitHub as you would a teammate’s.

A run that reaches your plan’s sandbox hours, or the included model’s allowance, pauses with its work kept and says when they return. Resume, on the Cowork page or the Agents tab, carries on from there; mux keeps the task for two weeks past that return. A Resume while the allowance is still spent says so and wakes nothing, so it costs no hours.

Where a task stands

Label	What it means
Starting, Working	The task is under way.
Paused, Blocked, Not reproduced, Interrupted	The run needs you; the reason shows under it.
Not started	mux let the start go, for the reason shown. Start again starts the issue afresh.
Cancelled	The run was cancelled.
Opening PR	mux has made the branch and is asking GitHub for the pull request.
Draft PR #12	GitHub lists the draft. Press the label to open it.
PR unconfirmed	GitHub’s answer was lost, and the task still holds the issue. Check again asks GitHub about the branch before it asks for a pull request, so you never get two.
No PR	Nothing was opened, for the reason shown. Where a retry can help, Open PR tries again.

The session and Back to start

A task you start becomes Cowork’s session. The page shows its title, its issue, its kind and day, where it stands on the three steps, and a sentence that says what that means. Open session opens the task’s own cloud session once mux has made it, so you can follow along. It has no message box, since nothing typed there would reach the run: it says so, and offers Stop run and Open Cowork. Beside it are the pull request, and Check again or Open PR where a retry can help.

The session stays on the page through visits to other sessions, a switch of repository and back, and a relaunch, until you press Back to start. Each repository keeps its own. Going back only takes the task off the page: it goes on as it was on mux, its pull request stays where it is, and History brings it back. A run that is paused or interrupted waits for you, and you answer it on this page, or in the session’s Agents tab.

History

The clock icon beside Refresh opens History. It lists every Cowork task in every repository of the workspace, grouped as Needs you, In progress and Done, then Earlier runs: runs made before Cowork had tasks, which open as they did. With more than one repository, each row names its own.

Pick a task to make it Cowork’s session again. If it belongs to another repository, the project picker switches to it. The start page also counts this repository’s earlier sessions under the three steps, and that line opens History.

Coworkers

A coworker is a standing teammate on mux, with a name, a job and a model of its own. It works on one of your repositories while you are away, within rules you set, and asks before anything those rules say to ask about. The Coworkers tab shows wherever any repository’s workspace offers them on mux. It lists every coworker in the workspace, grouped by repository.

New coworker asks for the repository, a name and a job, for example “Keep main green: when CI fails, find why, fix it in a task, and tell me.” The repository must be on GitHub. Each coworker has these sections:

• Activity. Its messages and work, and a box to message it. When it needs you, an approval card says what it wants to do, with Allow and Deny. A card nobody answers within a day counts as refused.
• Tasks. Cloud tasks it asked for on the repository’s code. muxcode starts them while the app is open, under an ordinary cloud task’s checkout rules, and each shows in the sidebar as a cloud task you can open. A task it asked for after reading text from outside, such as a webhook, an email or a web page, waits for you: Review and start shows what it will run first.
• Routines. Work it does on a schedule, as five cron fields in UTC, or once at a set time. A routine can also watch a web page and run only when the page changes. Its play button runs it at once.
• Open items. What it is keeping track of, each with Resolve.
• Rules. One per kind of action: edit files, run commands, read the web, drive its browser, use connected apps, message other coworkers, schedule routines and start tasks. Each is Allow, Ask or Block. Ask waits for you; while it works with you away, ask means no. Below the rules, Check in on its own lets it wake every 1 to 24 hours, look at its open items and routines, and speak only when something is worth saying, up to a daily limit and outside the quiet hours you choose.
• Secrets. Keys it may send to one https origin, as a bearer token, basic auth or a header you name. A secret’s value goes to mux once and is never shown again.
• Settings. Its model: mux’s included model is not offered to coworkers yet, so pick one you are signed in to on this Mac, which lends it the sign-in while the app is open. Its name and job. Make a webhook address: a POST to it wakes the coworker with the body as material, and a new address turns the old one off. Delete coworker, once you confirm, removes it with its routines, secrets and memory.

Pause stops a coworker until you press Resume. Duplicate makes it again on another repository in the workspace, with its name, job, rules, check-ins, routines and model. Its secrets stay with the original, and the line under its header says so.

When a start is refused

Cowork says why in a sentence under the box, on the task’s row, or in the session. These are the ones you are most likely to see.

Cowork says	What to do
Cowork runs on mux’s included model, and your plan does not include it	Connect the project’s workspace to mux on Pro or Pro+, or move the repository to a workspace on one of them; in a team workspace, your own plan must be Pro or Pro+. The write-up says the same.
You’ve used the allowance of mux’s included model	It says when it comes back. Start the issue then.
You’ve used this month’s sandbox-hours	It says when they come back, or what has more.
The mux GitHub App is not installed for this workspace	An owner installs it from mux in the browser: Install the GitHub App opens the page.
The mux GitHub App cannot see the repository	Add it to the App’s repositories on GitHub, then try again.
The mux GitHub App has not been given the access Cowork needs	An owner of that account accepts the App’s new permissions on GitHub.
You need write access to the repository on GitHub	Link a GitHub account that can push there to mux, or ask the workspace’s owner to start it.
origin names no github.com repository	Set origin to the repository’s https or ssh clone URL.
gh would file in another repository (for a write-up)	Make them the same. gh repo view in the checkout names the one gh uses; gh repo set-default changes it.
GitHub names no default branch	Push one and make it the default on GitHub.
The issue is in another repository	Open the project for that repository, or file the issue in this one.
The issue has no description to work from	Add what happens and what should happen to the issue, then start it again.
The issue is already being worked in another Cowork task	Open that task, or wait for it to end. It may be another member’s, which only they can open.
The repository has too many tracked files for a Cowork run	Work this change in an ordinary cloud task.
The repository has submodules	Work this change in an ordinary cloud task, or take them out on the default branch.
A .gitattributes line sets filter, or makes git check a file out differently from how it stores it	Drop it on the default branch, or work this change in an ordinary cloud task.
Any of these, after File the issue and start	The issue is on GitHub already. Fix what Cowork names, then paste the issue’s number into the box and press Start, rather than filing it again.

And when a run ends without a pull request:

Cowork says	What to do
The change touches what CI or the repository’s automation runs	Review it in the task’s session and open the pull request from its Git menu.
The commit this task started from is no longer on the default branch	Its pull request would carry more than the run checked. Start the issue again.
A branch named muxcode/issue-… already holds something else	Delete it, then press Open PR.
GitHub would not make the branch	GitHub’s own words follow, such as a ruleset on the name or a branch called muxcode. Clear it, then press Open PR.
GitHub does not offer draft pull requests on this repository	The branch holds the change: open a pull request from it on GitHub. Cowork opens only drafts.
GitHub lists the pull request as closed	Someone closed the draft, so Cowork opened no other. Reopen it on GitHub if it should go on.
The run finished with no change to the code	There is nothing to open. Open the session to read what the agent found.

For coworkers, “Coworkers are not on this workspace’s mux yet” means the tab has nothing to show, and “mux’s included model is not offered to coworkers yet” means you should choose a model you are signed in to on this Mac. A coworker’s task that could not start says why beside its status, starting with “Not started on this Mac”.

Next

• Cowork’s page: what it does, at a glance.
• muxcode: advanced guide: the other kinds of task, cloud tasks, and landing the work.
• How Clef works: the classifier that reads along in a run.
• Getting started: the workspace, its code index, and what each plan includes.