Delegation & Devices

Codemux can move work off the chat you're in, in three ways:

All three live in the default Agent Chat GUI.

Delegate to another agent

A Claude or Codex chat in Full access can hand a task to another agent CLI installed on this computer when you ask for it — for example "have Codex implement this on high effort, then review it yourself." The agent calls a delegate_task tool; Codemux starts the target as an ordinary chat in a background tab beside yours (it doesn't steal focus) and posts that agent's final report back into your chat.

• Targets — Claude, Codex, OpenCode, Cursor, and Grok, when their CLI is on your PATH. Hermes isn't supported in either role.
• The child sees only the task. It gets the task text plus a short instruction to work on its own and finish with a report — nothing from your conversation. It runs in the same folder as your chat, in its provider's full-access mode.
• Model and effort are passed only when you ask for them; otherwise the target's defaults are used.

What you see

• A card at the hand-off with the provider's logo, the task title, model · effort, status, a live timer, one line of current activity, and Stop / Open. Several hand-offs in a row are grouped into one card.
• A line above the composer — "Continues when Codex finishes" (or "Continues when 2 agents finish") — with Open, Stop, and Stop all.
• When the round is done, one Delegated results divider in your chat. Expand it to see the exact text your agent received.
• Delegated chats also appear in the Subagents pane; clicking a row opens the child's tab.

Results are posted only while your chat is idle — never into a running turn, a rate-limited chat, or a chat without a session. A round's reports arrive together as one message; a failure is posted at once and tells your agent not to retry on its own.

Lifecycle

• Stop, closing the chat, or New Chat on the parent quietly stops its delegated tasks. Changing the parent's model, effort, or permission mode does not.
• A delegated chat that asks a question or hits a usage limit keeps its task open until it can continue.
• After an app restart, tasks that were still open are marked Stopped; nothing is restarted automatically.

Limits

• Full access only. The parent must be in Full access (checked on the live mode, so switching to Plan or Ask refuses). Claude chats in Supervised or Auto-accept-edits mode ask for approval and are then refused with a pointer to Full access. Codex chats only get the tool if they started in Full access, because Codex fixes its tool list when the thread starts.
• One level deep. A delegated chat can't delegate further.
• At most 3 running per chat and 6 per user message. No automatic retries and no time limits.
• OpenCode, Cursor, and Grok can receive tasks but can't delegate yet.

Delegation is on by default, because the tool only acts when you ask for another agent. Turn it off with Settings → Agent → Tools & runtime → Delegate to other agents — that hides the tool from Claude chats immediately and from new Codex chats.

Run a thread on a device

A device is another machine you can SSH into — a home server, a desktop, a cloud VM. Pick one under the new-thread composer and the whole thread runs there: the device checks out the project, creates the worktree, runs the terminals, and runs the agent. On this computer the thread is an attach-only workspace, and its sidebar card shows which device it runs on.

Adding a device

Open Settings → Devices. It lists This machine (by hostname) and your devices, each with a live status — Connected, Updating…, Needs setup, or Offline — and a ⋯ menu with Test connection, Set up again, Rename…, and Remove….

Add device takes an SSH host (user@host) or an alias from your ~/.ssh/config (aliases are suggested from your config). One Connect saves the device, checks SSH, and installs the Codemux helper (codemux-remote) on it, showing each step. Codemux uses your existing SSH config, agent, and keys — it stores no credentials.

To see and move the work that lives on each device — open a workspace on its device, pull it here, or sweep settled worktrees — use the Devices page.

Devices keep up with the desktop on their own: when a reachable device runs an older helper, it's upgraded in the background. It's never downgraded, running terminals are never killed, and the helper's service restarts only when idle. A missing helper is installed only when you click Connect or Set up again.

Starting a thread on a device

On a new thread, the Run on picker leads the strip under the composer. It shows this machine by default; its dropdown ("Where does this thread run?") lists your devices with their status, plus Add a device… (or Manage devices… once you have some). The project you're working in is shown in the headline ("What should we build in codemux?").

On first send:

1. The device finds its checkout of the project by git remote, cloning it into ~/.codemux/projects/ on first use. Nothing is copied from this computer.
2. It creates the thread's worktree under ~/.codemux/worktrees/.
3. The agent starts on the device over SSH, in that worktree.

Requirements and limits

• Supported agents: Claude, Codex, Cursor, and Grok. OpenCode, Hermes, and custom ACP agents refuse device threads with a clear message.
• The device needs the agent's CLI installed and signed in there, and git access to the repository. Each CLI is found through your login shell on the device, so nvm-style installs work. A project without a git remote can't be set up on a device.
• Claude runs through Codemux's bundled runtime, uploaded on first use (about 100 MB). It only runs on devices with the same OS and CPU type as this computer.
• Device threads get none of this computer's MCP tools, and skills and terminal presets don't run on devices yet.
• Running threads on a device isn't supported from the Windows desktop yet.

Run a task on a host

Where a device thread moves the whole conversation, a host task sends one self-contained task to an existing checkout on an SSH host and brings its result back into the chat you're in. Codex and Claude are supported on the host.

Starting one yourself

In the composer, open + → Run on host…. The dialog asks for:

• Host — one of your configured devices.
• Existing checkout — a workspace already registered on that host (for example, one a device thread created). Delegation never creates a checkout and never falls back to this computer.
• Provider, Model, Permission, and Reasoning effort — read from the host's installed runtime, not from this computer.
• Task — what to do and the result you need (up to 32,000 bytes). Only this text is forwarded — never your parent transcript or credentials.

The Explicit remote access box spells out what you're granting: the agent runs as the remote OS user and can reach that user's files and services under the selected permission mode, and may edit the checkout's working tree. This is not a sandbox. Ticking the box and pressing Run on host authorizes that host, checkout, provider, and permission mode for conversations in this workspace, then launches the task.

Authorized targets in this workspace (inside the dialog) lists every grant with a Revoke button. Revoking blocks future delegation to that target and requests a stop for its unfinished tasks.

Letting the agent delegate

Once a target is authorized, Claude and Codex chats in that workspace can delegate to it themselves through the delegation_targets and delegate_remote_task tools, and follow up with task_status and task_cancel. Agents can't create or widen grants.

A task's permission mode can never exceed the parent conversation's: a read-only or Plan-mode parent can only delegate read-only work, and unknown modes are refused.

Following a task

The task appears as a card in the transcript — Starting, Running, Approval needed, Completed, Failed, Stopped, or Interrupted — with View task and Stop task. The task view shows the host, checkout, the recorded events, and any questions or approval requests from the remote agent, which you answer there.

When the remote agent finishes, a concise result is delivered into the parent conversation once it's idle, and the full result stays available to the agent. Stopping a task while the host is offline stays pending until the host confirms it. After a restart or a lost connection, Codemux reports what actually happened — it doesn't re-run work whose outcome is uncertain.

Requirements and limits

• The host needs an up-to-date codemux-remote helper (update it from Settings → Devices), a registered checkout, and Codex or Claude installed and signed in on the host.
• The host must be Linux.
• The checkout is used as-is: Codemux doesn't sync git state, environment files, or credentials to it.
• SSH and the host's OS account are not a sandbox — authorize only hosts and checkouts you trust with the selected permission mode.

Related

• Agent Chat — the chat pane that hosts delegated tasks and their cards
• Workflow Orchestration — coordinate many tasks across providers
• Devices page — your devices and the work on them: open on a device, pull here, move to device
• Settings — the Agent and Devices sections
• MCP Server — the tool surface agents use