Muxie Get Muxie
Concepts Explanation

Agent awareness

How Muxie detects coding agents and tracks them as working, blocked, or done — through lifecycle hooks, transcript watching, and screen detection.

Coding agents are quiet until they aren’t. They run for minutes, then stop to ask a question or finish a task — and if you’re not watching that exact pane, you miss it. Muxie’s job is to tell you which agent needs you, without you having to stare.

Detecting agents

Muxie recognizes a set of known coding agents by the process running in a pane — either the binary name or a runtime signature. The recognized agents are Claude Code, Codex, Aider, Gemini, Cursor Agent, OpenCode, Amp, and Droid (see Supported agents). When one starts in a pane, that session is tracked as an agent.

The three states

Every tracked agent is labelled with one of three run states:

  • Working — the agent is actively running.
  • Blocked — the agent is waiting on you: a permission prompt, a plan to approve, a question to answer.
  • Done / idle — the agent finished, or the pane returned to a shell prompt.

These show as a chip on the session card in the rail and flyout, and drive the Agents hub and notifications.

How state is determined

Muxie uses the most reliable signal available, in roughly this order:

  1. Lifecycle hooks (best). If you install an agent’s hooks, the agent reports its own state transitions to Muxie directly — when it starts working, becomes blocked, or finishes. This is event-driven and accurate. Muxie can install Claude Code’s hooks for you; see Install agent hooks.
  2. Transcript watching. Some agents write a session transcript file. When a hook tells Muxie where that file is, Muxie watches it for changes as a precise activity signal.
  3. Screen detection. As a fallback with no hooks, Muxie reads the pane’s recent output and matches known patterns (an agent’s prompt, a “waiting” screen) to infer state.

Hooks are strongly preferred — screen detection is a best-effort guess, while hooks are the agent telling you the truth.

Recaps and telemetry

Beyond the state chip, an agent that reports through hooks can surface richer telemetry on its card and in the Agents hub: a short recap of the last action, a progress bar, and a status line. This is what lets you glance at a quiet pane and know where it left off, instead of scrolling its history.

Doing things with state

Agent state isn’t just visual. Plugins can react to the agent:state-changed event, and the muxie api wait.agentState CLI call blocks until an agent reaches a given state — useful for scripting multi-agent workflows. See the CLI reference and the hooks catalog.