imux is a terminal-first AI command center for macOS — built for multi-agent execution in the agent era, not a full VS Code/Cursor IDE clone. Claude, Codex, and your agents are the workers; imux is the workshop. Use this guide as the baseline operating manual: pick a default path and keep execution, verification, remote ops, and Git-visible work in one native workbench.
Download the current macOS build and install imux as your daily workbench.
Open a workspace from a local repo or a configured SSH host — one goal per workspace.
Pick one default path: terminal agent CLI (most power users), Agent Chat (in-app LLM), or Mission Control (goal → fleet → verify).
Verify with explorers, in-app edit, browser surfaces, Git sidebar, and Mission Control predicates without leaving imux.
Do not open every surface at once. Choose one primary path for the session. imux is the daily driver — multi-agent execution, files, SCM, browser, and remotes in one command center.
Run Claude Code, Codex, Aider, Cursor Agent CLI, or your own tools as real terminal processes — side by side. imux is the host workbench; the agents are the workers.
Use Agent Chat when you want streaming chat, @file/@symbol context, slash commands, and reviewable diffs inside imux.
Open Supervisor → Mission Control after you have a concrete goal. Set done-when predicates, Start Mission to dispatch ready fleet panes, and Verify without relying on LLM self-grade alone.
Treat imux as the terminal-first command center beside (or instead of) Electron IDEs for agent-era work on macOS. Move agent runs, file inspect, SCM, remote, and browser verification into one native workbench.
Treat each SSH host as a first-class workspace with the same discipline as local work.
imux is optimized around a workspace model. The workspace should represent one concrete project or one concrete remote host so the terminal, files, browser tasks, and supervisor all reference the same operating context.
The explorer is not decorative. It is the fastest way to inspect project shape, open files, confirm paths, and stay oriented while the terminal conversation is active.
imux can open and edit files so inspect, small fixes, and agent-diff review stay on the same deck as terminals and Git. Keep the loop inside imux for daily work.
The supervisor works best when you give it a concrete target, enough repo context, and a bounded objective. It should reduce ambiguity and compress the next move into a plan that can actually be executed.
imux is most useful when Git state stays visible during execution rather than becoming an afterthought at the end of the task.
Do not treat upgrades as a blind overwrite. imux should be updated with the same discipline you apply to any other developer tool that controls project context, remote access, or model settings.
A few habits change imux from a promising shell wrapper into a much more reliable command center.
Most slow starts come from vague goals, not from missing features. A short, concrete brief usually gets imux into execution mode fast.
When imux feels slow, noisy, or unreliable, the fix is usually operational rather than magical. These are the first checks worth making.
Most remote failures are caused by incomplete authentication, mismatched SSH config, or trying to browse files before the connection has fully settled.
This usually means the workspace goal is too broad or too many unrelated paths and tasks are sharing the same surface.
That usually means it is missing a bounded objective, fresh file evidence, or a clear signal about what counts as done.
