Chat Modes: Code, Ask, and Architect

Most AI coding agents are one-size-fits-all. You ask a question, the agent responds. You want code written, the agent writes it. You want a plan, the agent... writes code anyway because that is what it does.

That works until it does not. Sometimes you just want to understand a function without the agent trying to refactor it. Sometimes you want a detailed implementation plan before committing to changes. Sometimes you want the agent to actually ship features.

muxd solves this with chat modes: three distinct interaction modes that change what the agent can do and how it behaves.

The Three Modes

Code Mode (Default)

Full access. The agent can read files, edit code, run shell commands, and make changes to your project. This is the default and what you expect from a coding agent.

Use code mode when:

  • You want the agent to implement a feature
  • You need bugs fixed or code refactored
  • You are comfortable with the agent modifying your codebase

Ask Mode

Read-only. The agent can read files, search your codebase, and answer questions, but it cannot write files or run commands. Perfect for exploration without risk.

Use ask mode when:

  • You want to understand how a module works
  • You are exploring an unfamiliar codebase
  • You need a quick answer without side effects

Architect Mode

Plan only. The agent analyzes your codebase and outputs a detailed implementation plan with step-by-step instructions. It does not make any changes, but gives you a clear roadmap.

Use architect mode when:

  • You are planning a significant refactor
  • You want to understand the scope of a change before starting
  • You prefer to implement the plan yourself

How to Switch

Switching is instant with the /mode command:

/mode code       # full access, make changes
/mode ask        # read-only, answer questions
/mode architect  # plan only, no changes

The mode indicator in the TUI footer shows your current mode: a sparkle icon for code, a magnifying glass for ask, a brain for architect.

Real World Example

Imagine you inherit a legacy codebase and need to add a new API endpoint. Here is how the modes work together:

Step 1: Ask mode — Understand the existing patterns

How does authentication work in this codebase? Show me an example endpoint.

The agent reads files, finds patterns, and explains without touching anything.

Step 2: Architect mode — Plan the implementation

I need to add a /users/profile endpoint. Plan the implementation.

The agent outputs a detailed plan: files to modify, functions to add, tests to write. No changes made yet.

Step 3: Code mode — Implement it

Go ahead and implement that plan.

The agent executes the plan, making the actual changes to your codebase.

Why Modes Matter

Without modes, every conversation is high stakes. The agent might misinterpret a question as a change request, or start refactoring when you just wanted an explanation.

Modes give you control:

  • Safety: Ask mode lets you explore without risk of accidental changes
  • Clarity: Architect mode forces planning before implementation
  • Efficiency: Code mode does not waste time asking permission for every edit

The agent respects your intent instead of assuming everything is a change request.

Getting Started

muxd starts in code mode by default. Type /mode ask to switch to read-only, or /mode architect to start planning. Switch back with /mode code when you are ready to make changes.

Your agent should match your workflow, not force you into its defaults. Now it does.