muxcode: advanced guide

Guide

For people who already run tasks in muxcode, the desktop app, and want more from it. It covers:

• which kind of task to start;
• how to work with context that is never summarised away;
• how to use your workspace’s code index from a task;
• how skills teach every task at once;
• how finished work reaches your repository.

How Jev works covers the classifier that reads along.

Pick the shape of the task

The composer starts four kinds of work, and Triage starts a fifth from its own page. Choosing the right one matters more than the prompt.

Shape	Use it for	Start it with
Chat	a question, a small edit, a look around	type in the composer
Workflow	a change you want planned, checked and judged	the workflow’s root model, or /muxcode-workflow
Analysis	a broad, read-only investigation	ask for one in your own words
Sandbox	isolation, long runs, Linux	Switch mode → Sandbox
Triage	a GitHub issue, from report to fix	⌘I, then the issue

Chat is one model under your permission mode, with no plan. A workflow runs a change through these steps:

1. An Architect plans it.
2. A worker writes it inside a contract.
3. A gate checks that the worker stayed in scope.
4. Your checks run.
5. A judge accepts or rejects the result.

An analysis sends readers out in parallel and brings their findings back as one answer. A sandbox runs any of these in a cloud container instead of on your Mac, and comes with paid plans.

Start a workflow

There are three ways in, and all three go to the same place:

• Pick the root model. Choose the workflow’s root model in the composer. For the roster muxcode ships, that is GPT-6 Luna. The workflow’s skill tells that model to send every change through the workflow.
• Use the command. Type /muxcode-workflow <name> <goal>, for example /muxcode-workflow luna-opus add a summary() to the ledger. The Agents panel lists each workflow’s name.
• Ask for it. Say so in plain words: “run this through the workflow: …”.

The shipped roster runs on two sign-ins, both under Settings → Sign in:

• OpenAI Codex (ChatGPT) for GPT-6 Luna at the root.
• Anthropic for the rest. Claude Opus 5.5 is the Architect, fixed at high, and the worker, from medium up to xhigh. Claude Fable 5.1 takes the retry, from high up to xhigh.

Every seat can be changed on the Agents page, including how far Jev may raise it (“Up to”). If a sign-in is missing, the run stops before its first step and names the one it needs.

Every seat is handed your own messages word for word, beside the root’s summary: up to 12 of them, 2,000 characters each and 8,000 in all. A constraint you typed reaches the planner and the judge even if the summary leaves it out.

Pause, don’t Stop, to keep a run

A workflow’s controls are in the Agents panel.

Control	Where	What happens to the run
Pause	Agents panel	It waits; the attempt in flight finishes.
Resume	Agents panel	It carries on with the same run and contract.
Cancel	Agents panel	It ends; partial changes stay in your tree.
Stop	composer	It is cancelled along with the chat turn.

Asking again after Stop starts a new run from the plan. The planner reads the tree as the stopped run left it and works from there. A run that muxcode pauses by itself also waits for you in the Agents panel; that happens when a file changes outside the contract, or a tool the run needs is missing.

Sandbox or your Mac

A sandboxed task runs the same agent on your Mac. Only its file and shell tools reach the cloud container. You keep the same prompts and the same permission cards, and the files live in the cloud.

• Stop sandbox · retain files parks it, and your next message starts it again with the files intact. By default it stops by itself after 10 idle minutes (Settings → Sandbox).
• A task starts from your checkout as it stands, uncommitted edits included. A clean checkout starts from your last commit.
• Tools may call the tree /workspace, as the sandbox does. It is the same set of files.

Keyboard

⌘ is Cmd on a Mac; muxcode also accepts Ctrl.

Keys	Does
⌘N	new task
⌘K	search every chat
⌘I	Triage
⌘E	open or close the right pane
⌘J	the task’s terminal
⌘2	Changes
⌘R	refresh what the pane shows
⌘⇧[ / ⌘⇧]	step through the pane’s tabs
⌘B	sidebar
⌘,	settings

Work with fresh windows

When a conversation fills up, muxcode does not summarise it. It opens a fresh context window: the system prompt, the tools, a short handoff, then new messages. Nothing is thrown away. The whole conversation stays on your Mac, and the agent reads back what it needs with its notes and history tools.

Layer	What it holds
What the model sees	the system prompt and tools, the handoff, this window’s messages
Written as you go	task notes, project notes
Searchable for good	this line of the conversation, the whole task, the project

So write down what matters as you go, and expect the agent to look things up rather than remember them.

Checkpoint with notes

Ask for a note before a long step, for example “write a task note with the plan and what you’ve ruled out”. A note outlives every window, and the handoff lists the task’s notes so the next window finds them.

• Task notes belong to the task, and writing one needs no approval.
• Project notes are shared by every task in the project. muxcode asks before one is written, and plan mode refuses to write one.
• A note is replaced only against its current revision, so two writers cannot silently overwrite each other. Older revisions stay readable.

Find what scrolled out

history searches the stored conversation for a phrase and reads an entry back by id. It has three scopes:

• branch: this line of the conversation.
• task: everything in the task, including edited-away branches and the work of subagents and workflow seats.
• project: up to 200 earlier sessions in the project.

A stopped subagent’s card says where its work went, for example “Use history search with scope task”. Ask the agent to do just that.

Roll over on purpose

Between phases, ask the agent to start a fresh window: “finish this step, note the result, then start a new context”. The agent writes its own handoff, up to 20,000 characters. The new window starts only if every tool call in that step succeeded.

A new window is not an undo. Changed files and commands you ran stay changed: it clears the conversation, not the tree.

The meter under the composer shows how full the window is, and whether that figure comes from the provider or is an estimate.

When to switch it off

Settings → Models → Context windows. Fresh windows are on by default. Turning them off restores summary compaction. Keep them on unless a model misbehaves after a rollover: with summaries, a long task loses detail at each one, and nothing brings it back.

Ask the workspace, read the tree

A task sees two things:

• The live tree is the checkout it works in, including your uncommitted changes. The agent reads it with read, grep and find.
• Your workspace’s code index holds every repository the workspace indexes, as of each one’s last indexed commit. The agent reads it with the workspace_corpus tool.

muxcode ships a workspace-index skill that teaches the agent this order:

1. Call get_context for the task.
2. Read the freshness of each repository.
3. Search, grep or trace.
4. Open the files.
5. Record what was checked.

Mention the index in a prompt, for example “check how the other services consume this event”, and the agent follows it.

Start with get_context

get_context answers a task, not a query. One call returns the evidence from across the workspace:

• passages bound to the commit they were read at;
• the files two hops out on the code graph: imports, tests, and the routes one repository calls in another;
• any finding an owner has approved.

When the checkout is an indexed repository, muxcode adds the files your branch changed.

Freshness is part of the answer

Read the freshness before the evidence. A repository that is behind was read at an older commit, and the agent should say so beside anything it takes from there. Pro and Pro+ refresh on every push. On Hobby, press Refresh index. Hobby matches words rather than meaning, and refuses search_code and ask_code; that is the plan, not a fault.

Which search for which question

Ask one question per search. A broad query answers none of them well.

Tool	Use it for	Note
search_code	concepts, flows, similar code	by meaning; Pro and Pro+
grep_code	structure, such as every call shaped like foo(…)	\NAME stands for one node
ask_code	a conceptual question	returns passages, not a written answer
trace_code	one file’s graph	needs both repository and path
list_repositories	names for the repository filter	owner/name

Keep what you checked

record_context_outcome proposes a finding for the workspace to keep. It takes a one- or two-sentence statement, the packet’s receiptId, the repository and revision, and the paths it rests on.

Always name paths, and only the files the statement depends on. A push carries the finding forward while those files are unchanged, and a change to any of them marks it outdated. Without paths, a finding depends on every file the packet read, so almost any push outdates it. A proposal is not trusted until an owner approves it; only then does get_context hand it out.

A snippet is not evidence

Every hit is a pointer. Open the file, read the tests beside it, and cite path:line from what you actually read. Your uncommitted edits exist only in the live tree; the index has never seen them. And “no results” does not mean “no integration”: dotfiles, .github/, generated files and unsupported formats may be missing from the index, so check them directly.

The same index from other agents

Claude Code, Codex and GitHub Copilot CLI can read the same index, with the same tools, over MCP. The MCP guide has the key, the endpoint and each client’s setup. muxcode needs none of this: it signs itself in, and you never paste a key into it.

Skills teach every task at once

A skill is a folder with a SKILL.md file in ~/.agents/skills, the one folder muxcode shares with other agents on your Mac. The skill’s description says when it applies. The agent loads the body when a task matches, or when you name it with /skill:<name>.

The Agents page lists skills under the workflows: muxcode’s own first, then yours, grouped by any prefix that three or more share.

Kind	Examples
Yours	team conventions, deploy steps, review checklists
Workflows	muxcode-<name>, written when you save a workflow
Shipped	workspace-index

Write a good one.

• Make the description specific: name the situations, files and words that should call it up. A vague description never gets chosen.
• In the body, put what the agent cannot work out from the code: the order of steps, the checks that prove a change, the traps you have already hit.
• Keep secrets out of shared skills. Every agent on your Mac reads the same folder.

Workflow skills are generated. Edit a workflow’s roster on the Agents page, not its files; the next save or launch rewrites them. A roster you edited keeps every seat you set, including ones the page has no row for.

Land the work

Work reaches your repository as commits, never as files copied in. The commit menu under the composer has seven actions:

• Commit
• Commit & Push
• Push
• Create Branch
• Create Branch & Commit
• Create Branch, Commit & Push
• Commit & Create PR

Local tasks, cloud tasks and triage runs all use the same menu.

From a cloud task:

• The work lands on a branch that grows from where the task started, so anything you committed in the meantime is not mixed in.
• Commit & Create PR asks for the branch name, then pushes and opens the pull request. The first line of the message becomes the title.
• An action that squashes the work refuses to run while your checkout has uncommitted changes of its own, rather than burying them.

Triage an issue. Press ⌘I, pick the project, and name the issue as a URL, as owner/repo#123, or as #123 for the project’s own repository. The run reads the issue, works in the cloud, and ends with the same commit menu. The Triage and Pull requests pages share the same project choice.

Next

• How Jev works: what the classifier reads, and what a sure answer changes.
• MCP guide: the index from Claude Code, Codex and Copilot.
• Getting started: pattern search, search by meaning, and plan limits.