Agent Chat
A native chat pane for Claude, Codex, Cursor, Grok, OpenCode, Hermes, and your own ACP agents — streaming, attachments, mode pills, and a unified model picker.
Agent Chat is an in-app conversational surface for AI coding agents. Instead of running claude in a terminal and watching ANSI scroll by, you get a real chat pane: streaming messages, tool approvals you can click, image attachments, slash commands, and one model picker that spans Claude, Codex, Cursor, Grok, OpenCode, (experimentally) Hermes, and any custom ACP agents you add.
Agent Chat is on by default. The classic terminal-first interface remains available as a per-device opt-out.
Choosing the Interface
Open Settings (Ctrl+,) → Agents → Interface to switch the Agent Chat GUI off or back on.
Changing the interface updates the two underlying feature flags (enable_agent_chat and enable_lazy_workspace_creation) together, then closes Codemux. Reopen the app to apply it. Existing installations were promoted to the GUI once; Codemux remembers a deliberate opt-out and does not turn it back on later.
With the Agent Chat GUI off:
- The sidebar New agent button opens the New Workspace dialog, which creates a traditional workspace with a terminal pane.
- The empty-state splash shows "Open Terminal / New Project."
- Chat panes are hidden; the provider registry is not initialised.
With the Agent Chat GUI on (the default):
- The sidebar New agent button (
Ctrl+N) opens a chat draft in your home directory (Shift+click it for the New Workspace dialog). No workspace is created until you send your first message — see Lazy Workspace Creation). - The empty-state Home shows a centered chat composer.
- The
+tab dropdown gains an Agent Chat option.
Frameless Chrome
For a real (non-draft) workspace in the default GUI, Codemux collapses the four stacked chrome rows — title bar, tab strip, preset bar, and pane header — into a single band, so the chat gets more vertical room and the toolbar clutter goes away.
That band is no longer a bar. There is no full-width surface and no divider: the sidebar, workspace, and right panel all reach the physical top edge of the window, and the chrome is two transparent floating islands over the content. They stay transparent even while you scroll: when a chat fills the workspace, its transcript runs up under the band but text dissolves before it reaches the controls — fully clear behind the control row, then fading in just below it — so the controls never need a backing surface of their own.
Terminal pane chrome went transparent along with it: a terminal that is a pane's sole occupant drops the redundant "Terminal" label and shows only a compact working-directory chip when the live directory differs from the workspace root. That treatment is identical in both interfaces — it is not tied to Agent Chat being on.
- Inline tabs — your workspace tabs render as compact pills with a per-tab status dot. The active chat tab grows a chevron that opens the session history dropdown, and shows the live "N subagents running" pill inline. Drag a pill to reorder tabs.
+launcher — a single popover replaces the preset bar: start a GUI chat, launch a CLI agent (Shift to split), open a Terminal or Browser pane, or jump to Manage presets. Pin a preset to the bar for one-click access. CLI agents whose binary isn't on your PATH are dimmed and labelled not installed; they stay selectable, so the launch error still says what's missing.- Rehomed controls — the Run button, resource monitor, and editor launcher move into the title bar's right cluster, with the right-panel toggle docked beside the window controls.
With the Agent Chat GUI off, the chrome returns to the classic multi-row layout. Live chat drafts use the same compact GUI-styled title bar with an Agent Chat pill and launcher, but suppress workspace-only actions such as Run, editor launch, and the right-panel toggle until the first message creates the workspace. Splitting a chat pane restores its per-pane header.
Providers
Six built-in providers ship behind one picker, plus any custom ACP agents you add:
| Provider | Backed by | What it adds |
|---|---|---|
| Claude | Claude Agent SDK via a Bun-compiled sidecar | Full Claude Code feature set — plan mode, AskUserQuestion, tool approvals, permission modes |
| Codex | codex app-server JSON-RPC binary | OpenAI's Codex CLI with sandbox-policy permission modes and per-turn effort control. Can run on your ChatGPT plan |
| Cursor | cursor-agent acp over the Agent Client Protocol | Cursor's agent, with its model list read live from the CLI |
| Grok | grok agent stdio over the Agent Client Protocol | xAI's Grok agent, with its model and reasoning-effort list read live from the CLI |
| OpenCode | Rust-direct HTTP against a managed opencode serve child | Federates 100+ upstream providers (OpenAI / Anthropic / OpenRouter / Google / …) behind one rail entry. Works with OpenCode 1.x and 2.x |
| Hermes (experimental) | Official hermes acp over the Agent Client Protocol, bound to an existing Hermes profile | Runs your Hermes profiles — their own models, memory, skills, and tools — inside a Codemux chat |
| Custom agents | Any local ACP v1 harness you configure | Your own coding harness, with the models and options it advertises |
Each provider signs in through its own CLI — claude auth login, codex login, cursor-agent login, grok login --device-auth, opencode auth login. Hermes credentials live in Hermes itself, and custom agents sign in through the harness. Codemux never reads or writes upstream API keys. The one exception is opt-in: connecting your ChatGPT plan to Codex, whose sign-in Codemux keeps on this device.
On Windows, Codemux also finds Claude Code installed by its native installer in %USERPROFILE%\.local\bin even when the installer didn't add that folder to your PATH, and finds OpenCode installed through npm (current and legacy npm layouts).
Codex and your ChatGPT plan
Codex can run on your ChatGPT plan instead of an API key. Click Continue with ChatGPT — on the sign-in screen, in the model picker when Codex isn't signed in, or in Settings → Agent → Use your ChatGPT plan — and approve Codemux in your browser (the request expires after five minutes; Cancel sign-in stops it).
- It's separate from your Codemux account. GitHub or email sign-in connects Codemux's own cloud account and sync; the ChatGPT connection only feeds Codex. One doesn't sign you into the other.
- Once connected, eligible Codex requests use your plan, the Codex composer shows Using ChatGPT plan with a Manage usage link, and new chats default to Codex (unless you've picked a default model yourself). Chats that already exist keep their provider.
- Settings lists saved connections, offers Use a different ChatGPT account, and Disconnect.
- The Codex CLI still has to be installed — the connection shows an installation link if it isn't. You can keep using your existing CLI account (
codex login) instead. - Desktop only — the connection isn't offered in the web client.
Cursor
Cursor is fully dynamic — Codemux keeps no catalog of Cursor models. It asks cursor-agent what it can run and projects each model's own options onto the reasoning, context, fast-mode, and thinking controls. The answer is cached for five minutes.
- Sign in with
cursor-agent loginin a terminal. Codemux's probe is read-only (cursor-agent --version, thencursor-agent models) and never opens an interactive flow behind your back. - Permission modes are Cursor's own two: Ask first ("Ask before commands or edits that need approval") and Full access (the default). Both can change mid-session.
- Supported: mid-session model and permission changes, tool approvals, interrupt, session resume, images.
- Not supported: conversation rollback — so per-turn revert is unavailable on Cursor.
- No Codemux-hosted MCP servers. Cursor reads its own
~/.cursor/mcp.jsonnatively; Codemux does not inject its registry into a Cursor session. See MCP Servers. - Cursor is also not used for background jobs — commit messages, merge-conflict resolution, and the utility agent, because
cursor-agenthas no one-shot mode.
Grok
Grok is fully dynamic too — Codemux keeps no catalog of Grok models. It reads the model list, each model's reasoning-effort levels, and its context size from the Grok CLI's own handshake, so a new Grok release needs no Codemux update. The answer is cached for five minutes.
- Sign in with
grok login --device-authin a terminal, or setXAI_API_KEY. ThegrokCLI must be on your PATH. Codemux's probe is headless and never opens a browser login behind your back. - Permission modes are Ask first ("Ask before commands or edits that need approval.") and Full access (the default). Grok fixes the mode when a session starts.
- Codemux's Plan and Ask pills aren't available — "Grok does not expose a client-controlled read-only mode." When Grok proposes a plan or asks a question itself, it still appears as a plan card or question panel, and its plans feed the Tasks panel.
- Switching models applies live, except between model families Grok can't switch inside one session; then Codemux starts a fresh Grok session and keeps your transcript.
- Supported: live model list, per-turn reasoning effort, tool approvals, interrupt, queued follow-ups, session resume, the context meter, and images when the CLI advertises them.
- Not supported: Fast mode, a context-window picker, steering, subagent groups, and conversation rollback — so per-turn revert is unavailable.
- No Codemux-hosted MCP servers are passed to a Grok session, and Grok is not used for background jobs (commit messages, merge-conflict resolution, the utility agent).
Hermes (experimental)
Hermes is a bounded, experimental integration with your existing Hermes profiles. Codemux never creates profiles, installs dependencies, or touches credentials — do that in Hermes.
- Set up in Settings → Agent → Hermes · experimental ACP integration. Set Hermes executable (default
hermeson your PATH) and Hermes root (default$HERMES_HOME, else~/.hermes), click Save and refresh, then Check runtime on a profile. The executable needs Hermes's optional ACP support (hermes --profile <id> acp --check). Both settings stay on this device. - Pick a profile, then a model. The Hermes rail shows a Profile selector, then Use profile default and the profile's own models. A started chat keeps its profile.
- New chats pick a profile for you, in this order: the profile you last picked by hand in this project, then Settings → Agent → Default Hermes profile, then — on Automatic, the default — the only installed profile. With several profiles and no default, the picker asks. A default that no longer exists in Hermes is skipped and shows as not found in Settings.
- Disconnect on a profile in the Hermes setup stops Codemux's Hermes session for it; background learning may not finish, and worktrees are kept.
- File edit policy comes from Hermes itself and is not a terminal sandbox.
- Supported: mid-session model and edit-policy changes, Hermes's own approval options, interrupt, resume, queued follow-ups (queued per profile, so two chats on one profile take turns), and Hermes's native slash commands. Memory and skill results show Memory saved, Skill created, or Skill updated once Hermes confirms them; otherwise Outcome unconfirmed.
- Not supported: reasoning effort, Fast mode, context window, image attachments, Codemux skills (Hermes uses its own), Codemux-hosted MCP servers (Hermes uses its own MCP config), per-turn revert, SSH workspaces, and background jobs (commit messages, conflict resolution, utility agent).
- Use one interface per profile. Codemux can't coordinate with Hermes Desktop or other processes using the same profile, and there's no hand-off to Hermes Desktop.
- Workspace cleanup is conservative. Hermes can't confirm when its background work has finished, so deleting a worktree it worked in is refused; close or archive the workspace instead, which keeps the files.
Custom agents (ACP)
Any coding harness that speaks the Agent Client Protocol (ACP v1) can run in a Codemux chat without a built-in adapter. Add it under Settings → Agent → Custom agents with Add custom agent:
- Agent name and Executable — a command on your PATH or an absolute path.
- Arguments — one literal argument per row. Codemux runs the executable directly, without a shell, so spaces, quotes, and
$are not interpreted. - Environment — extra variables for the harness. Values are stored encrypted on this device and never shown again; leave a saved row untouched to keep it, remove the row to delete it.
- Authentication method (optional) — only if the harness requires one of the auth IDs it advertises. Otherwise sign in with the harness itself.
- Enabled — a disabled agent stays saved but can't start.
Saving doesn't launch anything. Probe starts a temporary session without a coding prompt and reports what the harness advertises — N models advertised, whether Resume is supported, and Images supported or Text only. The harness runs with your OS account's access.
In a chat, pick Custom agents on the model picker rail, choose the agent, then a model or Use agent default. Once the chat starts, the agent is fixed for that chat, and any select or on/off options the harness advertises (a mode, an effort level) appear in the same panel; Refresh session controls re-reads them.
- Approvals stay supervised. Codemux's Plan / Ask / Debug modes and access picker don't apply; the harness's own modes are not a sandbox.
- Images only when the harness advertises them; otherwise the chat is text only.
- Resume only when the harness supports it. Codemux won't silently start a fresh conversation if a resume fails.
- Not available: Codemux-hosted MCP servers, delegation, and Codemux-managed skills.
- Local only — custom agents don't run in SSH-host or attach-only workspaces.
- Editing an agent affects future starts; running sessions keep their launch configuration. Deleting one disconnects its active sessions; the chat history stays, but those chats can't resume.
The Composer
The chat composer lives at the bottom of the pane:
- Textarea — your prompt. Multi-line with auto-resize.
+popup — the modes (Plan, Debug, Ask) and/workflow; file, folder, image, chat, issue, and pull request attachments (see Attachments); MCP Servers… to toggle integrations for this chat; and Run on host… to hand a task to another machine. Images can also be pasted or dropped onto the composer.@mentions — start typing@to attach a file or folder by fuzzy-search instead of clicking through the picker.- Slash commands — start with
/to open the slash command popup, grouped into Modes (/plan,/ask,/debug, and/defaultto return to normal build mode), Workflows (/workflow), Settings (/modelpops the model picker), Chat controls (/helpbrowses every command and skill for the current provider;/skills,/settings, and/usageopen those Settings pages;/permissionsopens the access picker;/mcpthe connected-tools menu;/refreshreloads the provider's commands and skills; and, on Codex,/hooks), Skills, and Commands — your agent's own native slash commands, discovered live rather than hardcoded. For Claude that's the deployed CLI's built-ins (/compact,/clear,/init,/review,/context, …) plus any custom commands in~/.claude/commandsor the project's.claude/commands. Codex/compactand/review [uncommitted | branch <name> | commit <sha> | instructions]and OpenCode's commands run through the provider's native API rather than as prompt text; other providers' commands are sent for the agent to interpret. Each row shows its source's logo. Filtering matches command names and, from three characters on, each item's description too — so a skill can be found by what it does — with name matches ranked first. $skills — type$for a skills-only menu. If a skill shares a name with a native command, the command keeps/nameand the skill stays reachable as$name.- Codex hooks — on Codex,
/hooksopens a Codex hooks manager where you can review lifecycle hooks, Trust this hook, and enable or disable them. Managed hooks are read-only. - Mode pill — Plan, Ask, or Debug, picked from the
+menu or with/plan,/ask,/debug.Shift+Tabcycles Default → Plan → Ask → Debug (providers without Plan or Ask skip them). - Access picker — how much the agent may do without asking. For Claude: Supervised (ask before commands and file changes), Auto-accept edits, or Full access (the default). Other providers list their own levels.
- Model picker — opens the unified provider rail + model list (see below).
- Send button — or press
Enter. On a new chat draft,Ctrl+Enter(or Ctrl-click Send) sends in the background. Optimistically guarded to prevent double-send. The composer has a single action button: while the agent works and the message box is empty it's Stop; once you type, it becomes a send button whose icon matches the delivery mode. Clearing the text brings Stop back.
New chats start with Full access, so a note above a new chat's composer explains that agents run commands and edit files without asking first, and points to the access menu. Got it dismisses it for good.
Narrow panes. When a sidebar or split makes the chat narrow, the composer gives up labels one step at a time instead of truncating them: a long model name shortens, then the access, tasks, and send-mode controls become icons, then effort, then the model shows only its provider logo, and finally effort and access move into the + menu. Hovering an icon still shows the full value. Widening the pane brings the labels back. The row below the composer hides the branch, then the project, before its status items.
The Model Picker
One popover, two columns:
- Provider rail (left, 48px) — icon-only buttons, one per driver. Active provider has a 2px indicator bar.
- Searchable model list (right) — cmdk-driven flat list. Typing in the search input collapses provider grouping and returns cross-provider results.
Features:
- Resolved version + blurb — Claude model rows show the concrete version the installed Claude CLI reports for each alias, plus a short description, instead of a bare alias — matching the terminal
/modelpicker so you always know what an alias actually selects, and following the CLI as soon as an alias moves to a new model. The CLI's Default row is named after the model it currently recommends (e.g. Claude Opus 5.5) and merged with its alias twin, and a new Claude chat drafted before the model list loads starts on that CLI default rather than a hard-coded model id. - New-chat default — a fresh draft starts on Settings → Agent → New chats → Default model. Automatic prefers Codex on your connected ChatGPT plan, otherwise Claude's default model; Custom fixes the provider, model, and reasoning level. Changing it also updates any open draft you haven't typed in or attached to yet. See Settings.
- Favorites — click the star on any model row to pin it. Favorites bubble to the top of the visible list (rail view AND search results) and persist across sessions.
- OpenCode federation — a single rail entry whose model list shows entries like
OpenCode · OpenAI/OpenCode · Anthropicfor each upstream provider you've authenticated. Disconnected upstreams are filtered out so the list stays usable. - FREE badge on free-tier OpenCode Zen models, with a sort boost.
- Empty states — separate copy for "OpenCode not installed", "OpenCode installed but no connected upstreams", and "no match for your query."
- Row-jump shortcuts — while the popover is open,
Ctrl+1–Ctrl+9(⌘1–⌘9on macOS) activate the first nine rows of the current list, respecting your search filter and favorites order. Each row shows its own shortcut chip. The listener is scoped to the open popover, so it does not disturb the globalCtrl+1..9terminal-tab bindings.
Service tier (Standard / Fast / Ultrafast)
Some models expose faster speed tiers. When the selected model advertises one, the reasoning pill's popover gains a Service tier section (on a model with no effort setting, the pill itself shows the tier):
- Standard — normal speed and usage rate, always available
- Fast — faster output at a premium usage rate
- Ultrafast — on Codex, only when the installed Codex model catalog advertises it for the selected model and your account. The row carries Codex's own description of its usage rate.
Because this affects billing, it is an explicit menu rather than a one-click toggle, and the choice is saved per thread — it survives drafts, session restores, and restarts. The new tier takes effect only once the provider accepts it — a rejected change leaves the tier as it was, shows a "Failed to set service tier" error, and isn't saved. On Codex the tier applies from the next turn without replacing the conversation. If a saved tier is no longer offered for that model or account, the chat falls back to Standard and says so with an inline notice.
It appears on Codex models, and on Cursor models that advertise a fast option.
Codex reads its tiers from its own model catalog, so which ones you see depends on the model and account. For Claude, Codemux deliberately forces fast mode off: the Claude
SDK advertises supportsFastMode as a capability, not an entitlement, so on
accounts without Extra Usage the request silently falls back to standard speed
while the UI would still claim Fast. Until there's a reliable entitlement signal,
the control stays hidden for Claude.
Switching provider mid-thread
Picking a model under a different provider rail moves the live thread to that provider. The old session stops, the new one starts on the same thread, and your transcript is preserved.
What does not carry is the provider's own context: native session cursors aren't portable, so the new adapter starts with clean provider-side context and reads the conversation as history. Fast mode, permission mode, reasoning effort, and context window all reset to the new model's defaults. If the switch fails, the previous provider is rebuilt and you're told why.
To hand a past conversation to another agent rather than move a live one, use conversation handoffs.
Reasoning Effort
A reasoning pill in the composer footer sets how hard the model thinks, and (for Claude) which context window it runs in. The pill reads Effort · Context — for example Ultracode · 1M. The same picker appears in the New Workspace dialog and in the preset editor, where it applies at launch.
Which levels you see comes from the selected model, so the list changes as you switch:
| Provider | Levels |
|---|---|
| Claude | Low, Medium, High, Extra High, Max, Ultracode, plus Ultrathink |
| Codex | Minimal, Low, Medium, High, Extra High, Max, Ultra — whichever the live model catalog advertises |
| Grok | Whichever levels the live model advertises |
| OpenCode / Gemini | No reasoning control |
| Hermes | No reasoning control |
Each row carries a one-line description, and the model's own default is marked (default). Leaving the pill on Default emits no flags at all.
Ultracode
Ultracode is the top rung on Claude: extra-thorough reasoning plus standing multi-agent workflow orchestration. Where the other levels only turn the thinking dial, Ultracode also leaves workflow orchestration switched on by default, so the agent reaches for fan-out and adversarial verification without being asked.
- Claude only, and only on models that offer Extra High — pick a model without it and the level isn't listed.
- Switching to a model that can't do Ultracode quietly drops back to that model's default.
- Codex's own top rung is Ultra, which enables its provider-side proactive multi-agent mode. It's a separate thing with a similar shape.
Ultrathink is different again: rather than changing an effort setting, it prepends Ultrathink: to your prompt.
How the choice persists
- In chat, effort is remembered per thread and comes back after a restart. Changing it on Claude restarts the session silently (Claude's effort is fixed per session); on Codex it applies from the next turn with no restart.
- At launch, your last model + reasoning + context pick is remembered per agent family, and can be baked permanently into an agent preset.
Streaming, Tool Approvals, and Mode Pills
A live conversation in Agent Chat surfaces several block types beyond plain text:
- Tool call cards — every tool the agent invokes shows up as a card with the tool name, status, and a body rendered per-tool (file paths for read/write/edit, search terms for grep, command for bash, etc.). Click anywhere on the header to open or close it. Trimmed Bash, Read, and Grep output ends in a Show all N lines / Show N more matches button that expands it in place, and hovering a Bash command or its output shows a copy button.
- Inline visualizations — when you ask for a chart, dashboard, table, or diagram, Claude and Codex can answer with a rendered HTML page through Codemux's
html_rendertool. It appears inline above the agent's final reply, picks up your theme's colors (and repaints if you switch themes), and grows to fit its content. The page runs in a sandboxed frame with no access to Codemux or your files; links you click open in your browser. Pages are capped at 512 KB and only render in Agent Chat, not in a terminal session. - Tool-result images — screenshots and other image blocks returned by tools render as clickable thumbnails inside the tool card, with a full-size lightbox and broken-image fallback. Text and structured output stay alongside them.
- Local screenshot links — an absolute image path in the agent's prose renders as a labelled inline preview card instead of a dead underlined filesystem link, and clicks through to a near-fullscreen lightbox. Both forms agents actually emit are upgraded: a normal Markdown link (
[Terminal screenshot](/abs/path.png)) and image syntax. PNG, JPEG, GIF, and WebP, on POSIX paths, Windows drive paths, and localfile://URLs. Relative paths stay ordinary Markdown — a chat message has no durable document directory — and non-image local links are left alone. A missing or already-reaped temp file degrades to a stable "Image unavailable" card rather than a broken-image glyph. This works in web-remote and browser clients too, through an absolute-path-only reader capped at the same 25 MB ceiling as chat attachments. - Permission request blocks — when the agent wants to run a tool that needs approval, the card gets an amber ring and Allow / Allow always / Deny buttons. See Approvals below.
- File chips — file paths in the agent's replies render as clickable chips that open in the right panel. Codemux checks the file exists first; a bare filename like
signal.gifis also looked up in folders the same message or turn mentioned. If nothing is found you get "File not found" instead of an empty viewer. - Plan proposals — Claude's
ExitPlanModetool surfaces as a plan card with Accept / Reject buttons. - AskUserQuestion panel — Claude's structured-question tool gets its own answer form so you don't free-text answers into the composer. A blocking question has Skip · answer in chat (or
Esc), which declines it with a note to the agent and puts your cursor in the composer; the transcript then reads Skipped, while a question the run abandoned reads Not answered. Its keyboard shortcuts only apply when nothing else has focus, so they never steal keys from other panes. A dismissed non-blocking question moves into the transcript with a Reopen action. - Work log — a contiguous run of the agent's thinking and tool calls folds into a single work-log line so the transcript stays readable (see The Activity Stream below). Tools awaiting approval,
TodoWritechecklists, plan proposals, and prose break the run and render on their own, so nothing you need to act on is ever hidden. - Diff cards —
Edit/MultiEdit/Writerender as a red/green diff card with ± line stats, so you see exactly what the agent changed inline. - Task receipts — task-tool calls leave a compact “Task list created/updated” receipt in the transcript and open the live Agent Tasks panel.
- Code blocks — fenced code is syntax-highlighted with the app's terminal palette, can show a filename from fence metadata, and has per-block wrap and copy controls. Incomplete streaming fences remain visibly provisional instead of flashing between highlighted and plain text.
- External links — web links keep their markdown label and gain the destination site's favicon; private hosts and local addresses are never sent to the favicon service.
- Reasoning blocks — the agent's thinking streams into a collapsible block that finalizes into a "Thought for Ns" summary (e.g. Thought for 4s). Expand it to read the chain of thought, or leave it folded.
- Streaming marker — a shimmer indicator on the last row while the agent is still producing output.
- Debug-mode banner — when you flip to Debug mode, a banner appears with a session-cleanup exit dialog so you don't leave debug artifacts behind.
Approvals
A pending approval is hard to miss: the card in the transcript gets an amber ring and a clock, a Needs approval row leads the strip above the composer (naming the tool and what it touches, with Deny and Allow — or Review for plans and workflows, which jumps to the request), and the jump pill reads Approval needed instead of Jump to latest when you've scrolled away. When nothing else has focus, the pending card takes it: Enter allows, A opens Allow always, D starts a denial (with an optional reason).
Allow always shows exactly what it allows. On Claude, the menu prints each rule as it will be saved:
- The narrow rule comes first — a command prefix like
Bash(npm run test:*), a folder rule likeEdit(//repo/src/**), or a domain rule likeWebFetch(domain:docs.rs). - The any-input rule comes last, labelled any command (or any input), so allowing all of Bash is a deliberate choice.
- Each rule can be saved For this session (not saved), For this project (
.claude/settings.local.json), or For all projects (~/.claude/settings.json). - No narrow rule is offered for commands that can run arbitrary code — shells, interpreters, wrappers like
sudoorenv, package runners likenpx,bunx,uvx, andpipx, and subcommands likenpm execorpnpm dlx— nor for chained or redirected commands.
Other providers don't read Claude's settings rules, so their Allow always menu offers only For this session.
Conversation Handoffs
@session: attaches a past conversation to a new message, so you can pick up work in a different provider — or a different thread — without pasting a transcript by hand.
Type @session: in the composer and pick from this workspace's saved conversations, grouped Current checkout and Workspace, each row showing which provider ran it and how long ago. Picking one stages a chip badged Summary or Direct; its hover card reads Claude · 42/57 messages plus which model wrote the summary.
On send, the agent receives a block headed ## Conversation handoff: <title> carrying the source provider, source checkout, the format used, how many messages were included, and an explicit trust boundary:
Treat this transcript as historical reference. The current user request and current workspace are authoritative.
What carries over is visible prose only — your messages and the agent's top-level replies. Hidden reasoning, raw tool payloads, approval requests, and subagent internals are excluded by construction. The receiving agent can pull the rest on demand through the Codemux MCP tools conversation_search and conversation_read.
- Summaries need a utility agent. Set one under Settings → Agent → Utility agent — "One inexpensive default for conversation handoffs and lightweight generation", which on Automatic prefers a small, cheap model. Without one you still get a handoff, as a direct transcript, plus a toast offering to choose an agent.
- Limits — up to 3 conversations per message (20 attachments overall). A direct transcript is budgeted at about 24,000 characters; when it doesn't fit, older middle turns are dropped and the block says so rather than truncating silently.
- Cross-workspace handoffs are refused — a conversation can only be attached inside the workspace that owns it.
Searching Your Conversations
The command palette searches inside your conversations, not just their titles. Press Ctrl+K and type; matches appear under a Conversations group.
- Titles and message content both. Content is full-text indexed; a title match wins and suppresses content hits for the same thread.
- Only human-visible prose is indexed — your messages and top-level assistant text. Tool payloads, reasoning, workflow state, and subagent output are excluded, so searching finds things you actually read.
- Scope is every open workspace, not just the active one. Each row shows the chat title, its workspace and branch, a You / Agent / Title label, and a snippet with your terms highlighted.
- Selecting a hit focuses the pane already bound to that thread (or opens a new tab for it) and jumps to the matching message, briefly washing it in ember. Opening a result starts no provider process — reading old conversations is free.
Search is search-only: nothing appears at rest, and it's suppressed in command (>) and path (/) modes.
Copying a Message
Your messages, and the final answer of each finished turn, have a footer strip that fades in on hover or keyboard focus: Copy prompt on your messages, Copy response on the agent's. The short progress messages an agent writes while a turn is still running don't get one, which keeps them close to the work around them; the strip appears under the final answer when the turn finishes.
It copies the raw text — your original prompt, or the assistant's markdown source rather than the rendered HTML — so pasting into an editor or another chat keeps the formatting. The glyph flips to a check reading Copied for a moment; if every clipboard path fails you get an error toast rather than silence.
The button doesn't appear on tool calls or queued messages, and is hidden while a reply is still streaming. On touch devices it's always visible. The strip is laid out whether or not it's showing, so hovering never reflows the transcript.
When a Provider Is Broken
A compact status chip pins near the top of the pane — on both real threads and new drafts — reading **Claude** · Claude Code CLI (claude) is not installed or not on PATH. It's red when the provider genuinely can't run a session and amber when a probe was merely inconclusive ("Could not verify Codex authentication status."). Nothing shows while a provider is healthy. "Not installed" means the binary really is missing; a CLI that times out or errors is reported as not responding instead.
- The banner floats: it never shifts the transcript.
- Sign in (when the CLI is signed out) opens a Sign in terminal tab running the provider's login command, such as
claude auth login, in the draft's workspace or in Home. Re-check probes again right away. - Dismiss hides that specific failure. A different failure banners again, and recovery clears the dismissal.
- An unhealthy provider is re-probed every five minutes, and again when the chat mounts or the window regains focus (at most every 10 seconds), so fixing it in another terminal (
cursor-agent login) clears the banner on its own.
Nothing is created for an agent that can't run. When you send a new chat's first message, Codemux first checks the agent ("Checking the agent…"). If its CLI is missing or signed out, the send is blocked before any worktree or workspace exists, your text stays in the composer, and the composer shows the reason. An inconclusive check doesn't block the send.
Before your first workspace, the empty Home shows an Agents row with a Ready, Needs setup, or Not installed chip per provider; clicking an installed one switches the composer to it.
Session errors land in the transcript, not in a toast that scrolls away: a red-bordered Session error: claude-agent sidecar exited unexpectedly notice, persisted so it's still there after a restart. A turn that fails because the CLI is signed out shows one "Claude Code isn't signed in." line with Sign in and Re-check. When a Claude API call fails (signed out, invalid key, no credit, overloaded), the turn ends as failed with the API's error rather than showing the error text as if it were the reply. Recoverable advisories are amber — see Usage limits.
The model picker shows the same health per rail — Not installed, Not signed in, Unavailable — with empty states that name the fix, e.g. "Codex is not signed in — Run codex login in a terminal and try again."
Provider Updates
When a chat pane or draft opens, Codemux checks whether the selected provider's CLI has a newer release (then hourly while the pane is visible). If it does, a small card floats at the top right — e.g. "Codex update available" with installed → latest:
- When Codemux recognises how the CLI was installed (mise, npm, pnpm, Bun, Homebrew, or the CLI's own updater), the card says "Updates through npm" (or whichever manager it found) and offers an Update button.
- Otherwise — for example a CLI installed by your system package manager — it links to an Update guide instead of running anything.
- After an update the card reads "Codex updated". Running chats aren't restarted; restart Codemux when you're ready to use the new version.
- Dismissing the card hides that version pair until the next app restart. Checks stay silent on network failures, and don't run for SSH-host workspaces or in the web client.
Sending While the Agent Works
You don't have to wait for the agent to finish. While a turn is running, a delivery picker appears beside Send — Send while the agent is working — with three choices. You can also type the choice as a leading command:
| Choice | Command | What it does |
|---|---|---|
| Queue (default) | /queue | Send after the current turn finishes |
| Steer | /steer | Guide this task without stopping its tools |
| Interrupt and send | /interrupt | Stop current work, then send this message |
Only a command at the very start of the message counts; it's stripped before sending, and paths or quoted commands elsewhere stay literal. The send hint reads "Enter to queue", "Enter to steer", or "Enter to interrupt" to match.
- Queued messages show greyed-out with a Queued footer and run in order (FIFO) as soon as the current turn completes, is interrupted, or aborts. Each one has Steer (where supported), Interrupt, and Cancel — Cancel drops the text back into the composer.
- Steering hands guidance to the running turn at its next safe point without stopping its tools; the message is marked Steered and you get a "Guidance accepted" toast. It's available on Codex and OpenCode only. Elsewhere Steer is greyed out — "Safe steering is unavailable for this provider. Choose Queue or Interrupt and send." — and it never silently turns into an interrupt.
- Interrupt and send stops the current turn (the session, transcript, and on-disk work are kept), then runs your message next.
Queue and Interrupt and send work on Claude, Codex, Cursor, Grok, and OpenCode. Hermes queues per profile, so a message can wait behind another chat on the same profile. Queued messages aren't kept across an app restart.
If a Claude or Codex approval or question outlives the provider process that created it, Codemux marks it expired and asks you to continue so the agent can repeat the request. It does not start a replacement session that cannot answer the old callback. OpenCode's server-backed requests can survive a pane remount.
A quiet run gets a nudge. If a running turn produces nothing for 10 minutes, a notice reads "No activity for 10m — the agent may have stopped." with Stop and Keep waiting (which hides it until another 10 minutes pass without activity).
Usage Limits
When a provider stops a run because you hit a usage limit, the transcript records it — e.g. Usage limit reached · 5-hour limit · resets 23:40 — and a Usage limit row sits above the composer.
- Automatic resume. When the provider reports when the limit resets (or how long to wait), Codemux continues the interrupted run then. The row counts down — resuming automatically in 1h 12m — with Cancel and Try now. If several quota windows are exhausted (say an hourly and a weekly one), it waits for the last one. This works for Claude, Codex, OpenCode, Cursor, and Grok.
- Manual resume. Otherwise the row offers Resume and says why the agent won't continue on its own — no reset time was reported, the reset is more than 26 hours away, two automatic resumes were already used, or you cancelled it. Resume shows Resuming… while it starts and can't be sent twice.
- Turn it off with Settings → Agent → Resume automatically after usage limits reset (on by default). At most two automatic attempts are made before it waits for you.
- Hermes can't resume automatically: it doesn't report a structured limit or reset time, so its chats show a notice to continue manually once your provider limit resets.
Workflow Orchestration
When a Claude agent runs a Workflow — a script that coordinates many subagents across named phases — Agent Chat promotes it to a first-class run: an in-thread approval card, a live progress card, and a dedicated Orchestration panel with per-phase and per-agent drill-in. Trigger one with the /workflow command.
This is Claude-only. See Workflow Orchestration for the full walkthrough.
Agent Tasks Panel
When a provider publishes a plan, a compact Tasks N/M control appears in the composer and a Tasks pane appears in the right panel. The panel is read-only agent state — you can inspect and copy the plan, but not reorder or edit its steps.
- Claude maps both
TodoWriteand its current task tools; Codex and OpenCode map their native plan/todo updates into the same view. - Pending, active, and completed steps have distinct states, with a progress bar, last-update time, and Queued / Working / Complete badge.
- The control follows the focused chat pane, so split panes never show another thread's plan.
- Plans persist with the conversation and return after a restart. Transcript task calls collapse to a short receipt; the panel is the live source of truth.
Activity Orbs
Wherever an agent's activity has context, Codemux shows a small orb: the in-flight turn in a thread, running subagent rows, the strip above the composer, and workflow run headers. One orb per live thing. Sidebar workspace cards use a static working icon instead (see Agent Status).
The orb's motion reflects what the agent is doing right now — searching the repo, writing files, running a build or test, talking to GitHub, resolving a merge conflict, retrying after a failure, waiting on you, or queued. Shell commands are read for intent, so git push looks like network work and cargo test looks like a build.
- It is always monochrome — white ink on dark themes, black on light. There is no color to interpret. Red stays reserved for "needs a human", which the sidebar shows as a red dot.
- Aggregate rows stay neutral. A row that summarises several agents shows the plain working orb; each individual running row shows its own.
- Turn it off in Settings → Appearance → Agents with Match the orb to the activity, and every orb becomes the same neutral working orb.
Tabs in the right panel deliberately don't animate — liveness there is a plain count badge.
The Activity Stream
Rather than printing every tool call and thought as its own "Thought… Ran… Thought…" row, Agent Chat folds each uninterrupted stretch of the agent's work into one compact work log line.
- While the agent is working, the line shows an activity orb, the newest action (Reading
src/app.rs, Runningcargo test), and stretch totals like12 tools · 2 subagents, so a long tool run doesn't flood the transcript. - Click the line to open the chronological history (the latest ten entries, with Show earlier for the rest); click any step to expand its full output inline — the same tool card or red/green diff you'd see standalone.
- Timing — a running step shows a live elapsed time, and a finished step shows how long it took when that was a second or more, e.g.
ok · 3s. - Errors stay visible — a failed step keeps a red marker, and the totals call out
· 1 failed, so nothing silently disappears.
When the turn settles, everything except the agent's final answer collapses into one quiet Worked for 1m 12s row; click it to expand the turn's work again. A work log you opened while the turn was running stays open when it ends, so you aren't cut off mid-read; one click on the fold collapses it. While a thread's history is still loading, the pane shows a transcript placeholder rather than the new-chat landing.
Anything you need to act on, or that stands on its own, always renders outside the work log: tool approvals, TodoWrite task lists, plan proposals, AskUserQuestion panels, inline visualizations, and the agent's prose replies.
What a turn changed
A settled turn that edited files shows a chip on its fold row — 3 files changed +42 −7. Hover it to list each file with its own line counts; click it to open the workspace's Changes pane. It counts the turn's own Edit / MultiEdit / Write / NotebookEdit calls and Codex file changes, not edits made by subagents, and it doesn't appear while the turn is still running.
Subagents
When an agent delegates work to subagents (Claude's Task / Agent tool, Codex collaborators, OpenCode task tools), Agent Chat keeps their work out of the main thread's prose. Subagents appear for Claude, Codex, and OpenCode; Cursor, Grok, Hermes, and custom agents don't report subagents.
Handing a task to a different installed agent ("have Codex implement X, then review it") or to another machine is delegation, not subagents — see Delegation & Devices.
- It is one line, always. In the transcript, subagent work joins the turn's work log as a single agents row — a preview of up to three subagent names,
1 done · 2 activewhile they run, then a9 tools · 1m 14srollup — with a View › chip that opens the right panel's Subagents pane. One subagent and forty cost the same single line. - Enter a subagent — Open thread in the Subagents pane opens a read-only drill-in showing that subagent's own transcript through the normal renderers, with a breadcrumb back to the orchestrator and a live tail while it's still running.
- Model badges — each subagent row carries a small mono pill naming the model it ran on, spelled exactly as the provider spells it. A subagent routed to a different model than its parent shows correctly; no badge appears when the provider didn't report one.
Steering stays with the orchestrator: the composer always messages the main agent, and subagents report their results back into the thread when they finish. Because subagent activity is stored on the parent conversation, it and the drill-in transcripts survive an app restart.
The Subagents pane
The right panel has a Subagents pane, so you can keep delegated work in sight while you read something else in the transcript. The tab appears on its own the first time a thread spawns subagents and badges the running count.
It's live-first: what is running now sits at the top, one row per subagent with an orb, its name and model, a live activity line, and elapsed time. A subagent that finishes while you watch turns into a green check with the first line of its report and lingers for a few seconds (longer while you hover it). Failed or stopped subagents are pinned above the list until you Dismiss them. When nothing is running, the pane shows the last wave as a receipt; History holds everything the thread spawned.
The live activity bar
While any subagent is running, a compact strip appears welded into the top edge of the composer, so you never lose track of background work even if you've scrolled far away from the group that spawned it.
- It rolls up the whole thread. If one reply spawned two subagents and an earlier reply spawned another, the strip counts all three, tagging each with the task it came from.
- Running —
N subagents runningwith what they're doing now and a Jump button back to their row in the transcript. Expand the strip to list each subagent (name, current activity, elapsed time), each with its own Jump. - When the last one finishes, the strip flashes green — "Subagents finished · all tasks complete · results are in the thread" — and then disappears.
The strip only exists while work is in flight and the subagents' row is off screen: there's no idle state, and it steps aside while their row is visible in the transcript.
A watch loop — an agent tailing CI or polling a PR — deliberately does not appear in this bar. It gets its own bar instead; see below.
The monitoring bar
When the agent finishes its deliverable but keeps watching something in the background, a bar appears between the transcript and the composer carrying the reason it gave and a Stop button. The workspace shows the calm cyan Monitoring status rather than staying pinned at "Working".
Stop clears the monitoring state and makes a best-effort attempt to interrupt the session. One honest limitation: the interrupt is a turn interrupt, and by the time the badge appears the turn has usually already settled — at that point there is no way to interrupt an idle session, so a genuinely detached background process can outlive Stop. Codemux clears its own state anyway, rather than leave you a status you cannot dismiss.
Any agent with a shell can declare this itself with codemux monitor start, so it works with Codex and OpenCode too. See Agent Status → Monitoring.
How the transcript scrolls
Sending a message is treated as a navigation intent, not a data update. Your prompt is parked near the top of the transcript and the reply streams into the space reserved beneath it — instead of the prompt being yanked to the bottom edge the moment you hit send.
While the turn is anchored this way, the transcript advances only as much as it takes to reveal the growing tail, so your prompt stays put while the reply fits on screen.
Follow is released only by a deliberate gesture — mouse wheel, touch-move, a scrollbar drag, or subagent-jump navigation. Clicks on rows do not count, so accepting a plan, answering an approval, expanding a tool card, or selecting text all leave follow intact. Scrolling back to the bottom re-claims it.
The anchor survives the turn settling: nothing on screen moves when the reply finishes, at the deliberate price of blank space persisting below a completed reply until your next send. The positioning is animated, unless you have prefers-reduced-motion set, in which case it is instant.
The same contract covers text sends, image sends, Continue run, and Send now on a queued turn. Jump to latest appears on a short delay and hides immediately, so it no longer flashes during load or sticks on during programmatic scrolling. A failed send or a thread switch clears the anchor, and clearing it never yanks the viewport away from a reader already browsing history.
Navigation Trail
Long conversations get a slim navigation trail down the left edge of the transcript — one tick mark per turn you sent — so you can scan and jump a long thread without dragging the scrollbar.
- Hover a tick to preview that turn (your prompt plus the start of the reply).
- Click a tick to jump straight to that turn.
- The tick for the turn currently in view is highlighted, so the rail doubles as a position indicator.
- Very long threads down-sample the ticks so the rail never overflows the gutter.
It appears automatically once a thread passes a few turns (short chats show nothing) and needs no setting.
Sessions and History
Each chat pane is bound to one session. The pane header has a session selector that lists your recent sessions for the active provider. Transcripts persist locally and replay on session resume.
- New session — opens a fresh transcript.
- Resume — picks up where you left off (Claude uses
--resumewith the captured session ID; Codex usesthread/resumewiththread/startfallback). - Auto-resume after an app restart — reopening Codemux revives an existing chat pane on your next message (the session is rebuilt behind the scenes from your saved transcript), and your per-thread model, effort, context-window, and permission-mode picks come back with it instead of resetting to the provider default.
- Stop — interrupts the current turn (or press
Escin the composer). Click again to restart the session so the next turn works.
Importing Claude Code and Codex Chats
Already have history in Claude Code or Codex? Settings → Archive → Import recent chats, or Import recent chats… in the command palette (Ctrl+K), copies recent conversations from this computer into Codemux as read-only chats. Before your first workspace, the empty Home offers the same thing — "Already working with Claude Code or Codex?"
- Opt-in. Nothing is scanned until you click Find recent chats. Pick conversations (or Select all available chats), then Import selected. Chats you've already imported are marked Already imported.
- What's read — Claude Code's
~/.claude/projects(or$CLAUDE_CONFIG_DIR/projects) and Codex's~/.codex/sessions(or$CODEX_HOME/sessions). Only conversations active in the last 30 days are listed. Subagent transcripts and symlinked files are skipped, and very large histories hit safety caps (8 MB per file, 128 MB per scan) with a warning that some sessions weren't scanned. - What carries over — your messages and the agent's visible replies, nothing else. Tool output, system prompts, images, and hidden reasoning stay behind. The text may still contain secrets you pasted. Your original files are never modified, and importing uploads nothing and starts no agent.
- Where they land — in the workspace already open on that folder, or a new import-only workspace for it, each as its own tab titled from the first prompt. Imported chats are searchable from
Ctrl+Kand can be attached with@session. - Read-only. The pane shows "Imported conversation · Read-only copy" instead of a composer. It's a copy, not a resumable provider session; to keep going, start a new chat and attach it with
@session. - Desktop only — not available in the web client or the mobile layout.
Per-Turn Revert Checkpoints
Per-turn checkpoints undo a turn — rewinding your files, the provider's conversation, and the transcript together, so the agent genuinely doesn't remember the turn you took back.
Enable it in Settings → Agent → "Per-turn revert checkpoints". It's off by default.
Codex only, today. It needs the provider to support rewinding its own durable conversation history, and Codex is the only one that does. Claude, Cursor, Grok, OpenCode, Hermes, and custom agents show no Revert button.
Hover any of your messages and click Revert ("Revert to before this turn"). The confirmation says how much goes — "Revert this turn?" or "Revert this turn and 2 later turns?" — and what happens: the workspace files go back to how they were before the turn, the agent's conversation is rewound, and those turns leave the transcript.
Your prompt comes back. After the revert, the reverted prompt (and its images) is put back into the composer with the cursor at the end, ready to rephrase. If you'd already typed something there, the prompt is added to it.
The files can be brought back; the conversation can't. The Turn reverted toast offers Restore files for 15 seconds, which returns the workspace to how it was just before the revert. The conversation stays rewound. Restore files is refused if a turn has started since or the checkpoints changed.
It really does touch your files. Codemux snapshots your current state first, restores the tree as it was before the turn, removes files the turn created, and leaves the restored content as unstaged changes against your pre-turn commit. Ignored files — node_modules and friends — are left alone. If the provider's rollback then fails, the workspace is put back and the error names the safety ref.
Snapshots are taken when a turn is dispatched, not while you type, and live in hidden refs so git gc can't reap them.
Limits worth knowing:
- Needs a git repository with at least one commit. Elsewhere, checkpoints are silently skipped.
- Switching branches blocks a restore — "Cannot restore: the workspace is now on branch 'X' but the checkpoint was taken on 'Y'. Switch back to that branch first."
- You can't revert during a live turn; finish or interrupt it first.
- The newest 500 checkpoints per thread are kept.
- One unprotected turn invalidates the timeline before it. If a turn runs without a checkpoint — the setting was off, the provider was Claude, the directory wasn't a repo — every Revert button in that thread disappears, rather than offering a rewind that would land you somewhere Codemux can't describe.
Thread Scope
On a new chat draft — the sidebar New agent button (Ctrl+N), Ctrl+Shift+N, or the empty-state Home — a row of controls sits below the composer telling you exactly where the agent will run, and letting you change it before you send.
Inside an existing workspace, that spot is always the read-only Context Row instead, from the pane's very first render. A workspace owns exactly one project root and one checkout, shared by every tab and pane in it, so there is nothing per-thread to pick. Create a worktree from a new chat draft or from the sidebar; switch project or workspace from the sidebar.
The draft surface has three controls:
- Location — which project the thread runs in, or your home directory. Picking home hides the agent preset bar, since presets are project-scoped.
- Checkout — create a new worktree for this thread, or run in the project's current checkout. Which one new chats start on comes from Settings → Agent → New chats → Workspace (New worktree by default). Non-git folders have no checkout control and always run in place.
- Branch — the branch to work from (or, in worktree mode, the base branch to branch off).
Two behaviours worth knowing:
- Worktrees are created on send, not on click. Even on New worktree, nothing is created yet. The worktree is created when you send the first message — after Codemux has checked the agent can run — and if you left the name field blank Codemux auto-names the branch from what you typed (falling back to a random name). Change your mind before sending and nothing was created.
- Picking a different branch never repoints your real checkout. If you're on "current checkout" and select another branch, Codemux silently flips you into worktree mode with that branch as the base. Your working tree is left alone.
Picking a project
The Location control opens a searchable, keyboard-first Run in list.
- Fuzzy search by name. Typing ranks by project name — a prefix beats a substring beats scattered letters, initials work (
hapfindshermes-agent-personal), and shorter names win ties. - Type
/to search paths instead. This is how you tell two checkouts of the same repo apart. - Active / Settled sections. Projects with at least one unparked workspace list under Active, most recently active first. Projects whose workspaces are all parked — settled or snoozed — list under Settled · still open, most recently parked first, collapsed to the first four behind a Show N more row. Parking never closes anything, so they stay reachable, just below the fold. The headings appear only when something is parked; otherwise it's a flat list. Searching spans both sections and reveals the whole settled tail.
- Picking a parked project does not un-park it — sending the first message is what resurfaces it.
- "Home directory (~)" is a normal filtered row, and "Open another project…" sits below the list and is never filtered out, so it stays reachable when nothing matches. The query resets each time the popover opens.
Every chat popover with a search field — this one, the model picker, and the mode / reasoning / speed pickers — puts your cursor in that field the moment it opens, so you can open, type to filter, and press Enter without touching the mouse.
Context Row
In a workspace chat pane, a read-only Context Row sits just under the composer — present from the pane's first render, including on an empty thread, so the strip never changes shape across your first send. It shows the project and branch the thread is running in, plus a status cluster on the right:
- a behind chip when your branch has fallen behind its base
- a pull request chip, colored by state
- a Browser chip when the agent has a background browser session open — click it to peek
- a Workspace details popover with branch, base, behind, ahead, uncommitted count, pull request, and location, and quick actions to View PR or Sync the commits you're behind
This row is where that detail lives. The full-width status bar that used to run along the bottom of the window was removed, so the numbers appear once — next to the conversation they belong to — and panes keep the full window height.
Context Window Meter
After the provider reports usage, a donut beside the Send/Stop button shows how full the current model window is. Click it for the exact percentage, live used/max token count, a progress bar, and — when available — lifetime Total processed tokens plus an automatic-compaction note.
The ring follows live occupancy, so it can drop after compaction while Total processed keeps rising. Above 90% it changes to the danger color. Drafts and providers that have not reported usage reserve no empty space; when a provider knows usage but not the model maximum, the popover shows a token count without inventing a percentage. The latest snapshot persists with the thread and returns after restart.
Lazy Workspace Creation
With the default Agent Chat GUI, the sidebar New agent button and the empty-state Home both open a chat draft instead of eagerly creating a workspace. The draft is a real composer — pick a provider, pick a model, attach files, type your prompt — but no git worktree exists yet.
The draft is promoted to a real workspace on first message send. The promotion creates the worktree, materialises the pane, and pipes your prompt straight into the new session.
Why: starting a workspace per "I want to ask Claude something" gets old fast. Lazy creation lets the chat pane double as a scratch space, and only commits when you actually want to do work.
Send in the background
Press Ctrl+Enter (or Ctrl-click Send) on a new chat draft to create the workspace and start the agent without leaving where you are. The composer hints "Ctrl+Enter to send in background". A fresh draft opens with the cursor ready, and the sidebar shows a Creating card until the new workspace lands. If the send fails, your text is restored and an error toast offers Review draft to reopen it.
This uses the Ctrl key on every platform, and only applies to a draft's first send — inside an existing workspace, Ctrl+Enter is a normal send.
Skills
Agent Chat exposes a cross-provider skills system. Skills are markdown files under the supported user roots (~/.codemux/skills/, ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/, ~/.opencode/skills/, and ~/.config/opencode/skills/) or the matching project-level roots. Codemux canonicalizes aliases, handles name conflicts, and surfaces enable/disable per skill in Settings → Skills.
Discovery merges readable skill files with the provider's own catalog, scoped to the thread's working directory — a provider binary that isn't installed is a normal empty catalog, not an error. Every skill carries a per-provider verdict (native, portable, or unavailable, with a reason), so compatibility is judged against the provider you are actually talking to rather than computed once and reused.
In the / popup, a portable skill is offered only when the active provider can use it. Unique names keep /name; a collision is resolved by scoping rather than rebinding — each colliding skill gets an exact qualified token and each row shows which one it is. Selections carry exact ids through to the backend and are revalidated there against the thread's working directory.
A portable skill sent to a different provider carries its base directory with it, so relative scripts/, references/, and assets/ paths still resolve. The transcript shows your unexpanded command, not the injected skill body.
The Settings switch means "available in Codemux" and nothing more. Disabling a skill removes it from the Codemux popup and resolver; it does not rewrite any provider's configuration, and it does not hide that skill from the provider's own native discovery. A skill with an invalid legacy name stays visible in Settings as an unavailable row with the validation reason, rather than silently disappearing.
Home chats run in your home directory, so built-in and plugin skills reported by Codex and OpenCode appear there too.
Skills also sync server-side across every device you sign into Codemux on. See Skills Sync.
MCP Servers
User-installed MCP servers are hosted by Codemux itself while the Agent Chat GUI is enabled. Codemux discovers configs across Codemux / Claude / Cursor paths, spawns each server once (deduped if the same config appears in multiple places), and exposes the resulting tools to the agent.
Claude, Codex, and OpenCode all reach the same registry. Cursor does not — it reads its own ~/.cursor/mcp.json natively instead. Grok, Hermes, and custom ACP agents aren't given Codemux-hosted servers either; Hermes uses its own MCP configuration.
See MCP Servers for the full picture.
Keyboard Shortcuts (in the chat pane)
| Shortcut | Action |
|---|---|
Enter | Send the current message |
Ctrl+Enter | On a new chat draft: send in the background and open a fresh draft |
Shift+Enter | Newline in the composer |
Shift+Tab | Cycle the mode pill (Default → Plan → Ask → Debug) |
@ | Open the mention popup for files/folders |
/ | Open the slash command popup |
$ | Open the skills-only menu |
Esc | Dismiss any open composer popup; otherwise, while the agent works, stop it |
Ctrl+C | In an empty composer while the agent works: stop it |
Enter / A / D | On a focused pending approval: Allow / open Allow always / start Deny |
Ctrl/Cmd+1–9 | With the model picker open, jump to the Nth model row |
Selecting and Copying Text
Codemux behaves like a desktop app rather than a web page: UI chrome isn't selectable, so dragging across the sidebar, tab labels, buttons, or panel edges no longer rubber-band-selects them.
Everything you'd actually want to copy still is — user and assistant messages, reasoning text, code blocks, tool output, diffs, file paths, error and notice text, review comments, issue bodies, and your account details in Settings. Terminal and editor panes keep their own selection behaviour unchanged.
Known Limitations
- One instance per provider. A user with multiple Codex accounts or multiple OpenCode connections sees them collapsed under one rail entry. Multi-instance lifting is planned.
- Per-turn revert is Codex-only, and Cursor, Grok, Hermes, and custom agents have no Codemux-hosted MCP servers — see the notes above.
- Provider rail has no jump shortcut. Model rows do (
Ctrl/Cmd+1..9while the picker is open); the rail itself must be clicked. - OpenCode credential management lives in OpenCode itself. Run
opencode auth loginto add upstream providers; Codemux only reads connection state. - No favorites sync across devices. Favorites live in
localStorageonly — they don't roam with your account.
Related
- Workflow Orchestration — Claude Workflow runs as an approval, progress, and drill-in surface
- Delegation & Devices — hand tasks to other agents, devices, and hosts
- Skills Sync — server-side cross-device skill sync
- MCP Servers — host user-installed MCP servers in chat sessions
- Attachments — files, folders, issues, PRs, images in the composer
- Settings — Interface, Permissions, Skills, MCP, and Sync sections