Usage Guide

How to use imux from first launch to daily execution.

imux is designed to get you from intent to verified change fast, without scattering the workflow across multiple apps. Use this guide as the baseline operating manual for local projects, remote hosts, file editing, source control, GitHub links, and supervisor-driven work.

Download for macOS View changelog

Quick start

01
Download the current macOS build from the imux website and install the app.
02
Open imux and create a workspace from a local folder, or start from a configured SSH target.
03
Set your LLM provider and model in Settings, then use readiness indicators as the checklist before handing a task to the supervisor.
04
Use the right-side explorer and editor to keep files, paths, and task context visible while the terminal remains primary.
05
When a task repeats, turn the steps into a reusable workflow instead of rebuilding the same prompt and command sequence each time.

Recommended operating methods

Most teams do better when imux is used as a repeatable operating surface rather than a one-off prompt box. These patterns keep the terminal primary while reducing drift.

1. Local coding loop

Use one workspace per repo, keep Git visible, and let the terminal drive the task while files stay open beside it for verification.

Open the target repo as its own workspace.
Inspect the file tree before changing anything substantial.
Keep edits small, verify them in the editor, then return to the active thread.

2. Remote operations loop

Treat each SSH host like a first-class workspace with the same discipline you would apply locally. Remote work gets safer when path awareness and authentication state are visible.

Connect only after confirming the correct SSH target.
Wait for authentication and directory discovery before browsing files.
Use a separate workspace per host so logs, paths, and objectives do not mix.

3. Review and verification loop

Do not rely on generated output alone. imux works best when the operator quickly checks files, paths, Git state, and command results before the next step is approved.

Open changed files immediately after each meaningful step.
Confirm the exact path and branch before packaging or publishing.
Use the right-side surfaces for evidence, not just for navigation.

4. Multi-task supervisor loop

When several tasks are moving at once, the supervisor should be used to keep goals bounded and progress interpretable rather than to produce abstract commentary.

Give every workspace a short, concrete objective.
Revisit the supervisor only when context has materially changed.
Prefer several clean workspaces over one overloaded universal session.

5. Readiness and workflow-library loop

From v1.11.6 onward, diagnostics, telemetry, and crash reporting are first-party and locally visible: no third-party SDK runs on your machine, and uploads only happen while "Send anonymous telemetry" is on. Treat readiness as the entry gate and workflow evidence as the operating record.

Check provider, CLI, hook, and workspace readiness before launching a long agent task.
Keep reusable workflows small: one command path, one agent prompt path, or one verification path.
Store project-specific workflows with the project so future sessions inherit the same operating recipe.

1. Start with a workspace, not a loose terminal

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.

Create a local workspace from the repo or folder you actually want to work on.
Use a dedicated remote workspace for each SSH target instead of mixing unrelated hosts together.
Keep one goal per workspace when possible. That keeps supervisor plans and file context cleaner.

2. Use the local and remote explorers as your control plane

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.

Use the local explorer to inspect repo structure before editing or delegating work.
Use the remote explorer only after the SSH session is actually connected and authenticated.
Drag file paths into the active terminal conversation when you want the path to become part of the task context.

3. Read, edit, and save files without breaking flow

imux includes in-workspace file viewing and editing so you do not have to keep bouncing out to a second editor for every small change or inspection pass.

Click a file to preview or edit it directly inside the workspace.
Save edits in place and return to the active terminal thread without losing context.
Use the file view for verification too: confirm the exact contents before you ask the supervisor or terminal to continue.

4. Treat the supervisor as an execution layer, not a chat toy

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.

Give each workspace a clear objective before asking the supervisor to take over.
Review the proposed next steps instead of accepting vague plans blindly.
Use the supervisor to frame work, track progress, and keep multiple active tasks from drifting.

5. Keep source control visible while changes are happening

imux is most useful when Git state stays visible during execution rather than becoming an afterthought at the end of the task.

Check branch and working tree state before you start editing.
Use visible file paths and repo context to avoid accidental edits in the wrong place.
Review current changes before packaging or publishing any result.

6. Use readiness before automation

Readiness indicators are not just decoration. They help you decide whether imux has enough configuration to launch agents, route notifications, use saved provider profiles, and keep automation predictable.

Resolve missing CLI or provider setup before a task becomes urgent.
Treat optional notification hooks as quality-of-life setup, not as a blocker for every launch.
If a readiness item looks wrong, verify the underlying CLI, saved profile, or hook file before debugging the whole workspace.

7. Upgrade with a release-first habit

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.

Read the changelog before replacing the app build.
Reconfirm model settings, SSH behavior, and any saved connection preferences after updating.
Use one clean workspace to validate the new build before you move all active work onto it.

Best practices that improve the experience fast

A few habits change imux from a promising shell wrapper into a much more reliable command center.

Keep one repo or one remote host per workspace whenever possible.

Set the workspace objective before handing control to the supervisor.

Drag precise file paths into the active thread instead of describing files vaguely.

Check Git state early, not only at the end of the task.

Use the editor for confirmation after every non-trivial generated change.

Promote repeated command and agent patterns into reusable workflows instead of relying on memory.

Validate one clean local path and one clean remote path after every upgrade.

How to brief imux so execution starts in 2 to 3 turns

Most slow starts come from vague goals, not from missing features. A short, concrete brief usually gets imux into execution mode fast.

Name the exact repo, folder, or SSH target first.

State one outcome you need now instead of bundling several unrelated goals together.

Mention the most relevant files, commands, or URLs if you already know them.

Define what done looks like in one measurable sentence.

Use the next reply to tighten scope or priorities instead of rewriting the full request.

Troubleshooting and recovery

When imux feels slow, noisy, or unreliable, the fix is usually operational rather than magical. These are the first checks worth making.

SSH connection looks stuck

Most remote failures are caused by incomplete authentication, mismatched SSH config, or trying to browse files before the connection has fully settled.

Reconfirm the target in your SSH config and reconnect cleanly.
Wait for the terminal to show the connected shell state before using the remote explorer.
Test the target in a normal SSH session if the explorer still cannot populate.

The workspace feels noisy or unfocused

This usually means the workspace goal is too broad or too many unrelated paths and tasks are sharing the same surface.

Split unrelated efforts into separate workspaces.
Narrow the active objective to one concrete outcome.
Close files and panes that are no longer part of the current decision path.

Setup readiness looks incomplete

A readiness warning usually means one layer is not configured yet: provider profile, CLI install, notification hook, workspace context, or remote connection state.

Check the specific missing item before changing unrelated settings.
Confirm the matching CLI works in a normal terminal and in an imux terminal.
If the task can still launch, treat the warning as setup debt and fix it before the next high-stakes workflow.

The supervisor is suggesting vague next steps

That usually means it is missing a bounded objective, fresh file evidence, or a clear signal about what counts as done.

Restate the objective in one sentence with a measurable end condition.
Open the most relevant files before asking it to continue.
Point it at the current repo state instead of relying on old chat context.

Safe update checklist

Download the latest DMG from the imux website download endpoint.

Quit the current app cleanly so open writes or active sessions are not interrupted mid-task.

Install the new build, reopen imux, and verify LLM settings plus SSH connections before resuming important work.

For v1.13.1, confirm the app reports build 162, then disconnect / reconnect a remote SSH workspace (yank the network or use the sidebar reconnect) and verify the terminal scrollback is preserved instead of being cleared. v1.13.1 also demotes the daemon-only handshake timeout from a red `SSH error` banner to the orange `Remote service unavailable` warning.

Check the changelog for behavior changes in explorers, supervisor flow, file editing, routing, workflow loading, or release packaging.