Agent Chat (Beta)

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, and OpenCode.

It is opt-in Beta. The legacy terminal-only experience is preserved when the toggle is off.

Enabling Beta Features

Open Settings (Ctrl+,) → Beta Features → flip "Enable Agent Chat".

Toggling Beta Features quits and restarts Codemux to keep your data intact across the legacy/Beta UI swap. The two underlying feature flags (enable_agent_chat and enable_lazy_workspace_creation) flip together — there is one user-facing switch.

When Beta is off:

• The sidebar + button 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.

When Beta is on:

• The sidebar + button opens a chat draft surface (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.

Single-Bar Chrome

For a real (non-draft, non-OpenFlow) workspace with Beta on, Codemux collapses the four stacked chrome rows — title bar, tab strip, preset bar, and pane header — into a single title bar, so the chat gets more vertical room and the toolbar clutter goes away.

• 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 (with a "Restore checkpoint" footer when a checkpoint exists), 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.
• Rehomed controls — the right-panel toggle, the Run button, resource monitor, and editor launcher all move into the title bar's right cluster.

With Beta off, the chrome is byte-for-byte the legacy multi-row layout. Live chat drafts and OpenFlow workspaces also keep the legacy chrome. Splitting a chat pane restores its per-pane header.

Providers

Three providers ship behind one picker:

Each provider authenticates through its own CLI (claude auth status, codex auth status, opencode auth login). Codemux never reads or writes upstream API keys.

The Composer

The chat composer lives at the bottom of the pane:

• Textarea — your prompt. Multi-line with auto-resize.
• + popup — file, folder, GitHub issue, GitHub PR, and image attachments. Drag-drop and clipboard paste both work; the + icon is the explicit picker. See Attachments.
• @ 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 /default to return to normal build mode), Workflows (/workflow), Settings (/model pops the model picker), 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/commands or the project's .claude/commands. Provider commands are inserted as literal text and forwarded verbatim for the agent to interpret — Codemux never runs them locally.
• Mode pill — Ask / Allow always / Plan / Debug. Click to cycle, or press Shift+Tab. Switching modes mid-session restarts the underlying provider with the new permission mode.
• Model picker — opens the unified provider rail + model list (see below).
• Send button — paired with Cmd/Ctrl+Enter. Optimistically guarded to prevent double-send.

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 they run plus a short description (e.g. Opus 4.8 with 1M context · Best for everyday, complex tasks) instead of a bare alias, matching the terminal /model picker so you always know what an alias actually selects.
• 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 · Anthropic for 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."

Mid-conversation provider/model swaps are supported: pick a new model, the session restarts with the new selection, the transcript is preserved.

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.).
• Permission request blocks — when the agent wants to run a tool that needs approval, a block appears with Allow / Deny / Allow always buttons. "Allow always" persists a rule (see Settings → Permissions).
• Plan proposals — Claude's ExitPlanMode tool 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.
• Activity block — a contiguous run of the agent's thinking and tool calls folds into a single Activity row so the transcript stays readable (see The Activity Stream below). Tools awaiting approval, TodoWrite checklists, 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 / Write render as a red/green diff card with ± line stats, so you see exactly what the agent changed inline.
• Task checklist cards — the agent's TodoWrite plan renders as a live checklist that updates as items complete.
• 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.

Queuing Follow-ups

You don't have to wait for the agent to finish before typing your next instruction. Send a message while a turn is still streaming and Codemux queues it — the message shows greyed-out with a "Queued" pill, and dispatches automatically as the next turn the moment the current one completes, is interrupted, or aborts. Queue several and they run in order (FIFO).

• Cancel a queued message — hover it and click the ✕; the text drops back into the composer so you can edit or discard it.
• The composer tells you — while the agent is working, the send hint reads "Enter to queue" so it's clear the message won't interrupt the live turn.

Queueing is backed by Claude and Codex. OpenCode doesn't queue (the message waits until the turn ends). Injecting into a live turn ("send now" mid-stream) and keeping the queue across an app restart aren't supported yet.

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.

The Activity Stream

Rather than printing every tool call and thought as its own "Thought… Ran… Thought…" row, Agent Chat folds each contiguous run of the agent's work into one compact Activity block.

• While the agent is working, the block is a single amber-spinner "Working" row with a live action line (Reading src/app.rs, Running cargo test) and a 3 done · 1 running counter, so a long tool run doesn't flood the transcript.
• When the run settles, it rolls up to a green-check summary sentence with a 12 steps · 1m 12s meta line and a Details toggle.
• Expand Details to see each step as a compact verb/target row; click any step to expand its full output inline — the same tool card or red/green diff you'd see standalone.
• Errors stay visible — a failed step folds in but shows a red marker, and the block header calls out · 1 failed, so nothing silently disappears.

Anything you need to act on, or that stands on its own, always breaks the run and renders outside the Activity block: tool approvals, TodoWrite task lists, plan proposals, AskUserQuestion panels, and the agent's prose replies.

Subagents

When an agent delegates work to subagents (Claude's Task / Agent tool, Codex collaborators, OpenCode task tools), Agent Chat shows a live Subagents card in the transcript instead of blending their work into the main thread — across all three providers.

• One row per subagent — status (spinner while running, check when done, red on failure), the subagent's name and model, a live activity line of what it's doing right now, and its elapsed time + tool count.
• Parallel-aware header — the card aggregates "N tasks · running in parallel" with an "X done · Y active" counter, so you can see fan-out at a glance.
• Inline peek — click a row to preview its recent activity (the last few tool calls) without leaving the conversation.
• Enter a subagent — open a read-only drill-in that shows 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.

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, the cards and their drill-in transcripts survive an app restart.

The live activity bar

While any subagent is running, a compact bar docks just above the composer so you never lose track of background work — even if you've scrolled far away from the card that spawned it.

• It rolls up the whole thread. If one reply spawned two subagents and an earlier reply spawned another, the bar counts all three, tagging each with the task it came from.
• One subagent running — the bar is a single View button that jumps to its card.
• Several running — click Show all to expand a list (name, what each is doing right now, elapsed time); click any row to jump to it.
• When the last one finishes, the bar flashes green — "Subagents finished · all tasks complete · results are in the thread" — and then disappears.

The bar only exists while work is in flight: there's no idle state, and it hides while you're drilled into a subagent's transcript.

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 — it's part of the Beta chat pane.

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 --resume with the captured session ID; Codex uses thread/resume with thread/start fallback).
• 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. Click again to restart the session so the next turn works.

Run Checkpoints

An opt-in rollback point taken when a chat session starts, so you can undo everything an agent run changed with one click.

Enable it in Settings → Agent → "Checkpoint before agent runs" (the toggle appears once Agent Chat is on; it's a synced setting, off by default).

• Zero startup cost — the snapshot runs in the background after the session is already up. It never delays the agent's first token.
• Non-destructive — the snapshot captures tracked and untracked files (.gitignore respected) without touching your index, working tree, stash, or running any git hooks. It's anchored under refs/codemux/checkpoints/ so git gc can't reap it.
• Restore from the pane header — a history icon appears in the chat pane header when a checkpoint exists (hidden otherwise, disabled mid-turn). Restoring undoes the run's commits, deletes files the run created (ignored files are spared), and brings your pre-run uncommitted changes back as unstaged edits.
• Safety first — restore refuses if you've since switched branches, and it snapshots the current state to refs/codemux/pre-restore/ before touching anything, so even a restore can be recovered from.
• Self-pruning — only the 20 newest checkpoints are kept per namespace.

One known trade-off: a pre-run staged/unstaged split comes back flattened to unstaged after a restore.

Thread Scope

Before you send the first message of a new thread, a row of controls sits below the composer telling you exactly where the agent will run — and letting you change it. It appears on a fresh chat draft and on an existing workspace's empty new-thread state. Once the conversation starts, the controls hand off to the Context Row in the same spot.

There are 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 — run in the project's current checkout, or create a new worktree for this thread.
• 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. Choose "New worktree" and nothing happens yet. The worktree is created when you send the first message, 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.

Context Row

Once a thread has messages, the scope controls give way to a read-only Context Row in the same place, just under the composer. 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

Because this row carries the same detail, the workspace context bar at the bottom of the window hides itself while an Agent Chat pane is active — the numbers show once, next to the conversation they belong to, rather than twice.

Lazy Workspace Creation

When Enable Agent Chat is on, the sidebar + 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.

Skills

Agent Chat exposes a cross-provider skills system. Skills are markdown files under ~/.claude/skills/, ~/.codex/skills/, ~/.opencode/skills/, or ~/.codemux/skills/ that get auto-injected as context when their compatibility filters match. Codemux watches these directories, handles conflicts, and surfaces enable/disable per skill in Settings → Skills.

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 when Agent Chat is on. 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 via an in-process facade.

See MCP Servers for the full picture.

Keyboard Shortcuts (in the chat pane)

Known Limitations

• Beta-gated. Off by default. Opt in via Settings → Beta Features.
• 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.
• No keyboard shortcuts on the picker for jumping to a specific provider. Ctrl+1..9 collides with workspace switching; a non-colliding namespace is being figured out.
• OpenCode credential management lives in OpenCode itself. Run opencode auth login to add upstream providers; Codemux only reads connection state.
• No favorites sync across devices. Favorites live in localStorage only — they don't roam with your account.

Related

• Workflow Orchestration — Claude Workflow runs as an approval, progress, and drill-in surface
• 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 — Beta Features, Permissions, Skills, MCP, Sync sections
• OpenFlow — the older multi-agent orchestration surface (separate from Agent Chat)