magent

Open every project in its own terminal, launch your AI agent, and auto-tile all windows across your screens.
One command. Every tool. Every monitor.

magent.io

      Monitor 1  (4K @ 250%)         Monitor 2  (4K @ 250%)        Monitor 3 (1080p @ 175%)
   +------------+------------+    +------------+------------+    +---------+---------+
   |   api      |   web      |    |   infra    |   docs     |    |  ops    |   ...   |
   |  [claude]  |  [claude]  |    |  [codex]   |  [vscode]  |    | [claude]|         |
   +------------+------------+    +------------+------------+    +---------+---------+
                     columns x rows per screen -- true physical pixels on every monitor

Quick Start

Available once v1.0.0 is published to PyPI. Until then, install from source.

pip install magent-multi-ai-agents-manager          # or: uv tool install magent-multi-ai-agents-manager
magent

On first run, magent scans your Claude, Codex, and VS Code history, finds your recent projects, and generates a config. Run it again to launch everything.

Supported Tools

Add any tool by mapping a name to a shell command in settings.tools. CLI agents open in a terminal; IDE tools open via their native CLI (code, cursor).

Happy (mobile/web access)

Enable Happy to monitor and control all your AI sessions from your phone or browser with end-to-end encryption:

"settings": { "happy": true }

Requires npm install -g happy. Supported agents: Claude, Codex. Per-project override with "happy": true/false.

psmux (persistent sessions for SSH access)

Enable psmux (native Windows terminal multiplexer) so each project runs in a named session you can attach to from anywhere — SSH from your phone, another PC, or a second terminal:

"settings": { "psmux": true }

Requires psmux installed (choco install psmux or download from GitHub). When enabled, magent creates a detached psmux session per project and opens Windows Terminal attached to it. From any SSH client: psmux attach -t project-name.

Each magent session brands its psmux status bar — magent on the left, its window hotkeys on the right (F1 Proj. Picker F2 </> VS Code, each key name badged in bold cyan). The F2 </> VS Code half only appears when VS Code (code) is installed on the session host; without it the bar advertises F1 Proj. Picker alone rather than a key that would do nothing:

F2 needs code on your PATH; magent up refreshes the branding and hints on sessions that were already running. magent sets both halves per session, so they win over a personal ~/.tmux.conf.

Attach windows reconnect themselves

magent attach <host> opens one window per remote session, and each one runs a small supervisor (magent-attach-client) instead of a bare ssh. When the connection dies — laptop sleep, wi-fi change, VPN flap, host reboot — the pane no longer freezes on client_loop: send disconnect and then sits there dead as [process exited with code 255]. It waits (2s, doubling to a 30s ceiling) and dials again, forever, until the host answers.

A whole outage costs one line, rewritten in place — not a scroll of retries. The counters tick down where they are, and ssh's own connect to host ... timed out noise is folded into the last: clause instead of filling the pane:

  ~ reconnecting to me@desk (attempt 4, retry in 16s, last: Connection timed out) -- Ctrl+C to stop

That line lives on the bottom row of the pane, and nowhere else. When the connection dies your agent's screen is left exactly as it was — mid-answer, and with whatever you had typed into the prompt box and not yet sent still sitting there, readable, on the row it was always on. The reconnect warning never draws over it. (It used to: it painted wherever the cursor happened to be, which in an agent pane is the end of your half-written sentence.)

Narrow panes drop the hint, then the host name, then the reason — the attempt and the countdown are the last things to go. Redirected panes (magent attach ... > log) get one plain line per attempt instead, with no cursor tricks. When a reconnected session eventually ends, the pane leaves one permanent record of the outage it survived (+ reconnected to me@desk after 4 attempt(s); stayed up 1h04m).

Nothing is lost while it waits: the psmux session lives on the host, so the reattached pane comes back to the same running agent, the same scrollback, and the same unsent prompt text — the agent is holding it, not your terminal. You can even keep typing during the outage: what you type is buffered by your terminal and delivered to the agent as soon as the connection is back. You do not have to close a wall of dead terminals and re-run magent attach any more.

Only a deliberate detach closes a pane. When a connection ends, the supervisor asks the host — over a separate, one-shot SSH check — whether your session is still alive. If it is, you left on purpose (F1, or psmux detach), the pane says detached from <session> and exits. If the session is not there (host rebooting, a bring-up still in progress), the pane keeps dialling for a few more tries and only then stops and tells you to run magent attach — so it never hammers a healthy SSH server over a session that is gone for good. Ctrl+C stops the supervisor immediately at any point.

That check exists because an exit code alone cannot be trusted: Windows OpenSSH doesn't report a remote command's exit status back over an interactive session, so a session that died on the host looked exactly like a clean detach. Panes used to close on that — one wi-fi flap, forty windows gone, each announcing a "detach" you never asked for. The separate check drops the interactive pseudo-terminal, which is what makes the host's answer truthful on every OS.

magent attach --no-reconnect restores the old one-shot behavior (one connection, no check). --no-mux panes are never supervised — without a multiplexer the agent dies with the connection, so there is nothing to reattach to.

Your sessions survive your connection

A dropped connection must never kill work on the host. That is not automatic on Windows: OpenSSH runs everything an SSH session starts inside a job object that it destroys when the connection closes, and every child inherits it — so a psmux session created by a remote magent up (which is exactly what magent attach does) used to be owned by your laptop's wi-fi. One flap and the host's psmux servers, and the agents inside them, were killed. magent now creates sessions with an explicit break-out from that job, so a session's lifetime is tied to the host, not to the connection that asked for it.

Note that magent down --all is the deliberate way to stop everything: it kills every psmux session on the machine along with the agent running in each, not just the daemons. Name sessions explicitly (magent down api web) or use -g/--group to stop a subset.

The host brings itself up on its own desktop

magent attach asks the host to run magent up for you, over SSH. On Windows that is a problem nobody sees coming: OpenSSH is a service, so every process an SSH login starts lives in logon Session 0 — a session with no desktop attached to any monitor. Sessions created there are real and running, and completely useless: the host's own magent status reports them stopped, nothing can tile or attach to them, and because psmux's session registry is shared they hold their names, so every later bring-up on the real desktop fails with "session never came up". (Measured once: 82 psmux servers and 42 agents, plus an upload server squatting the loopback port the desktop's Alt+V needed. Clearing it took an elevated kill of 1172 processes.)

So a bring-up that finds itself in Session 0 does not run there. It hands the same command to the logged-on desktop through Task Scheduler, waits for it, and relays its output back down the SSH pipe — you see the host's normal up output on your laptop, prefixed by one hand-off: ... line. No password, no elevation, no scheduled task left behind. The same applies to the upload server attach ensures on the host. A plain foreground magent serve is left alone.

MAGENT_SESSION0_POLICY controls it: handoff (default), allow for a headless Windows host that is only ever reached over SSH and has no desktop to hand off to, or refuse to make the situation loud instead. If nobody is logged on at the host's console there is nowhere to hand off to, so the bring-up refuses and says exactly that rather than waiting out a scheduled task Windows is never going to start. Nothing changes on macOS or Linux, where there is no session isolation and tmux over SSH is simply how people work. If servers from an older magent are still stranded, magent doctor and magent status count them for you.

Your typing outranks your fleet

On Windows, magent keeps every psmux process at above-normal priority. Your keystrokes reach an agent through a chain of psmux processes, none of which owns a window — so Windows never gives them the boost it gives a foreground app, and under load they queue behind the very builds and language servers they are hosting. That is the difference between typing that feels instant and typing that lags while a normal text box on the same machine stays snappy. The processes are waiting on a pipe rather than burning CPU, so the boost costs your agents nothing.

It needs no administrator rights, it only ever raises a process (anything you or another tool put at high/realtime priority is left alone), and it re-runs periodically so sessions created later are covered too. Set MAGENT_PSMUX_BOOST=0 to leave every process's priority exactly as it is.

Mobile image upload (over Tailscale)

Send screenshots from your phone straight into a project's agent session:

"settings": { "psmux": true, "uploadServer": true, "uploadPort": 8033 }

magent serve (or uploadServer: true during launch) starts a small HTTP server on this config's uploadPort — the same port magent status, up and doctor watch, so a bare magent serve and the rest of the tool can't disagree about where the server is (-p still overrides it; with no readable config the port falls back to 8033). magent mobile prints the phone URL + a QR code you can install as a home-screen app (the QR code needs the optional qr extra: pip install magent-multi-ai-agents-manager[qr]). Pick a project on the phone, upload an image, and its path is pasted into that project's session. On a desktop browser you can also Ctrl+V an image from the clipboard: the page stages it with a preview showing which project it will go to, waits for you to confirm with Send, and shows live upload progress until the "pasted into …" confirmation. The Alt+V hotkey (Windows) does the same for whatever magent: session is focused. Setting MAGENT_ALTV_NATIVE=1 makes a local press skip the pipeline and deliver one native Ctrl+V to the pane instead -- opt-in, because the pane's agent must support pasting on an injected Ctrl+V (Claude Code on Windows reacts only to the physical chord, so for it the default upload path is the one that works). Remote-wired listeners (magent attach) always keep the upload path.

This works over Tailscale: the server binds only the loopback and your machine's Tailscale IP — never the LAN wildcard — and attach/mobile/termius shell out to the tailscale CLI to resolve hosts. Devices must be on your tailnet; there is deliberately no auth token, since the bind set is the access control. To bind something else (e.g. LAN-wide), use the escape hatch: magent serve --host 0.0.0.0.

The Alt+V listener stays alive by itself

The upload server owns the Alt+V listener: while magent serve runs it makes sure a listener exists, restarts one that died or is running older code after an upgrade, and leaves alone one that magent attach pointed at another machine. So Alt+V survives reboots, crashes and upgrades — start the server (directly, or via magent --go / magent attach) and the hotkey follows.

If it isn't working you will be told, rather than left guessing:

• magent status prints Alt+V listener DEAD (upload server is up but no listener — Alt+V does nothing) in red and exits 3, with the repair command underneath. magent doctor fails the hotkey check with the same hint. A listener that is simply not expected yet (no server running) still reads as a quiet off.
• Every press narrates itself in that project's status line, starting the instant the chord is detected: Alt+V: capturing... (before the clipboard is even read) → Alt+V: uploading... → Alt+V: image sent (a local native press is shorter: Alt+V: pasting... → Alt+V: pasted from clipboard). A press that can't complete ends in a specific reason rather than a generic failure — clipboard has no image - copy one first, cannot reach magent serve (connection refused), serve said HTTP 400: Unknown project, saved, but psmux would not paste it. The narration never delays the press: it is queued and delivered on its own thread, and a dead server costs a paste nothing.
• Every press is also recorded in ~/.magent/logs/hotkey.log as one ALTV outcome=… project=… line — so grep ALTV ~/.magent/logs/hotkey.log is the whole history of the chord — and magent serve logs each status-line message it served (flash project=… msg=… in ~/.magent/logs/upload.log), so "the status didn't show" is answerable after the fact.

To own the listener's lifetime yourself, set MAGENT_HOTKEY_SUPERVISOR=0; status still reports whether one is running.

Usage

Run magent with no arguments for the interactive menu:

                         _
 _ __  __ _ __ _ ___ _ _| |_
| '  \/ _` / _` / -_) ' \  _|
|_|_|_\__,_\__, \___|_||_\__|
           |___/
  v3.1.1  auto-tile your AI workspace

  ----------------------------------------

   1   Launch & tile new windows  (default)
   2   Re-tile all open windows
   3   Launch a group  AUTOMATIONS | INTERNAL | LEAD-GEN
   e   Edit config
   q   Quit

Just start typing. In a real terminal every list magent shows you — the menu above, its group submenu, and the magent sessions switcher — filters as you type, with the closest match marked >:

  attach to web

 > 2   beta-web                   still going... 4m
   3   gamma-web-docs             needs input

Up/Down move the mark, Enter takes it, Esc clears the query (and, on an empty query, backs out). Nothing else changed: the row numbers still work, q is still Quit even if you have a project called queue-worker, and pressing Enter on an untouched menu still takes the default it always did. Piped or scripted input keeps the plain line-based prompt.

Or skip the menu with flags:

Typing through psmux

Two keys stop working the moment your agent runs inside a psmux pane:

• Ctrl+Backspace arrives as a plain Backspace — one character, no word-delete.
• Shift+Enter arrives as a plain Enter — which submits in Claude Code instead of inserting a newline.

Neither is your terminal's fault. psmux drops the key modifier in transit; the child only ever sees the bare key. The real fix upstream is win32-input-mode (psmux#159), which died unmerged — we filed psmux#610 and #611 to revive it.

Until then the mitigation is to resolve the chord before psmux sees it, in Windows Terminal itself, with a sendInput binding that writes the resulting bytes straight into the pty — a byte has no modifier left to lose:

magent terminal install     # writes the bindings (backup first, never clobbers)
magent terminal status      # installed / missing / conflicting, per key

• ctrl+backspace → 0x17, the Ctrl+W word-erase byte every readline already honors. The same trick VS Code ships. Works through psmux today.
• shift+enter → 0x1b 0x0d (ESC CR), exactly what Claude Code's /terminal-setup installs. Works outside psmux now, and inside it once upstream fixes its ESC+CR decode — installing it is right either way.

magent ships this itself because /terminal-setup refuses to run inside a tmux/psmux pane, which is precisely where magent users live.

The install is idempotent and never clobbers: a key you have already bound to something else is reported and left alone (the other key still installs), and a timestamped backup lands beside settings.json before any write. If your settings.json uses JSONC (comments, trailing commas) magent refuses to rewrite it and prints the exact snippet to paste by hand instead. magent doctor reports the same per-key state under wt-keys — as a warning, never a failure.

When every psmux command hangs (the wedge)

Rare, and worth knowing before it happens: psmux's control plane can wedge machine-wide. Every command — has-session, list-sessions, new-session — hangs forever, from any console, and the whole fleet looks dead.

It isn't. magent doctor probes the control plane once (bounded, 5 s) and fails the psmux wedge check with the repair:

• your sessions are frozen, not dead — do not restart them, and do not reboot;
• find the conhost.exe processes whose parent chain reaches a dead pid or a psmux.exe, and kill only those (it was 14 of 874 conhosts in the incident this check comes from);
• psmux answers again immediately afterwards, and every session comes back intact.

Platform support

Launching, tiling, and the mobile/notification plumbing run on all three OSes. A few power-user features are Windows-only because they lean on Win32 primitives with no cross-platform equivalent wired up yet. This table is the honest contract — every cell is derived from the capability probes in src/magent/platform/, not from aspiration.

Notes:

• Badges, flash, and toast are gated on Platform.supports_attention_signals(), which returns True only in platform/windows.py. On macOS/Linux the daemon prints window badges/flash aren't supported on this OS and those renderers stay off. Toast additionally uses the Windows-only winotify ([toast] extra). ntfy push is cross-platform — it is stdlib urllib over HTTP — so phone notifications work on every OS.
• The magent: title prefix can be turned off with settings.windowTitlePrefix: false — window titles then become the bare project name (e.g. api instead of magent:api). Launch-path tiling still places windows (it matches the exact title it set), but the features that read the magent: grammar degrade to a safe no-op while the prefix is off: the attention daemon's title badges, the Alt+V clipboard hotkey (which only fires in magent:-titled windows), and magent-name title matching all stop recognizing your windows. One deliberate exception: magent attach windows always keep the prefix — there the title carries the psmux session id that the hotkey chain resolves, so it is load-bearing rather than cosmetic. Leave the setting on unless you specifically want prefix-free titles.
• Persistent psmux sessions and the Alt+V hotkey are gated on supports_psmux() / supports_hotkey() (also Windows-only). Off Windows the psmux entry points raise NotImplementedError and importing hotkey raises ImportError.
• magent terminal install is gated on supports_wt_keybindings() — it edits Windows Terminal's own settings.json, which no other OS has. Elsewhere it says so and does nothing (see Typing through psmux).
• The mobile upload server itself (serving the PWA over loopback + Tailscale and receiving images) runs everywhere; auto-pasting the uploaded path into a live agent session uses psmux, so that last hop is Windows-only. Likewise, watch's table renders on every OS but its press-a-number-to-focus action uses the same Windows-only window primitives.

Where agent states come from

magent sessions, magent watch, magent attention, and magent status --json do not poll your agents directly. They read per-session state records — working, needs-input, done, error, idle — that your coding agent writes through its lifecycle hooks. Until those hooks are wired, the state store stays empty and the pickers show no status. Wire them once with:

magent hooks install

This merges the bundled magent-state-hook writer into Claude Code's ~/.claude/settings.json (idempotent — your existing hooks are preserved) and prints the one-line notify recipe for Codex's ~/.codex/config.toml. Restart open agent sessions to activate. After that the session picker shows live still going... 3m / done / needs input labels — the hook refreshes the record on every tool call, so still going... means the agent really is moving, and a session reads done only when its turn ends with no background tasks (subagents, background shells) still running — and magent watch / magent attention -d light up as your agents change state. magent hooks status shows what is wired and how fresh the store is.

The companion ai-agent-notifier package (same authors) adds phone/desktop notifications on top of the same hook events (it is a pure notifier — it does not write state records):

npx ai-agent-notifier setup

Configuration

Config is stored at a platform-standard location:

• Windows: %APPDATA%\magent\config.json
• macOS: ~/Library/Application Support/magent/config.json
• Linux: ~/.config/magent/config.json

Or place magent.config.json in your working directory (it is gitignored — your personal config never gets committed).

Start from the committed sample, magent.config.example.json — it is generated from the config factory and exercises every surface (groups, remote host/remotePath, ssh, the full settings block):

{
  "version": 1,
  "baseDir": "C:/Users/you/projects",
  "layout": { "columns": 2, "rows": 1 },
  "settings": { "defaultTool": "claude", "...": "see the example file / magent docs" },
  "projects": [
    { "path": "backend/api", "group": "backend", "tool": "claude", "color": "#3b82f6" },
    { "path": "gpu-worker", "group": "infra", "host": "gpu-box.example.com", "remotePath": "/home/dev/worker", "tool": "codex" }
  ]
}

Configs are versioned ("version": 1). A config without a current version still loads but prints a warning until you run magent config migrate — loading never rewrites your file; migrate is the only writer (it also persists auto-assigned project colors; those are derived deterministically from each project's title/path, so they stay the same every run even before you migrate).

Project fields

Multi-window sessions

Open the same project in multiple windows. windows is a list of window objects, each with optional per-window tool/command overrides:

{
  "path": "api",
  "windows": [
    { "name": "api" },
    { "name": "api-2" },
    { "name": "api-codex", "tool": "codex" }
  ]
}

name sets the window title; tool/command override the project's defaults for that window only. Windows without an override each resume the Nth most recent Claude/Codex session.

The legacy "windows": 3 and "windows": ["api", "api-2"] forms still parse and are normalized to window objects by magent config migrate.

Remote projects

{ "host": "deploy@server", "path": "/srv/api", "tool": "claude" }

CLI agents run over SSH. VS Code/Cursor projects open via Remote-SSH.

Custom tools

"tools": {
  "claude": "claude --continue",
  "codex": "codex",
  "cursor-agent": "cursor-agent",
  "agy": "agy",
  "aider": "aider --model sonnet",
  "shell": "bash"
}

Testing

Job	Live status	Platforms	What it verifies
Unit		Windows / macOS / Linux Python 3.10 -- 3.14	Config parsing, grid computation, title generation, session resume, discovery, grouping (15 matrix jobs)
Platform		Windows / macOS / Linux	Real monitor detection (ctypes/Swift/xrandr), real window find+move, real terminal launch, DPI scaling
E2E		Windows / macOS / Linux	Full CLI dry-run, config loading, group filtering, SSH project handling, vscode/cursor tool alias, multi-window
Packaging		Windows / macOS / Linux	Build wheel, install into a pristine no-extras venv, drive the real installed magent entry point: version/help, dev-dep import sweep, virgin first-run, socket-real serve, optional-extra degradation, and a real window spawn (win32)

Run it yourself

pip install -e ".[dev]"
pytest tests/unit/ -q                        # fast, safe anywhere
pytest tests/e2e/ -m "e2e and not needs_ssh" # subprocess dry-runs; no SSH server needed
pytest tests/platform/ -v -m platform        # real monitors/terminals — CI-grade env only
pip install build && pytest tests/dist/ -m dist  # wheel -> pristine venv -> real installed entry point
python scripts/check.py                      # the quality gate: ruff + custom lint + ty + compileall + vulture + pytest w/ coverage

A bare pytest collects all tiers, including tests that enumerate real monitors, launch real terminals, and expect an SSH server — run those only in an environment set up like CI (.github/workflows/ci.yml). scripts/check.py is the repo's commit gate; it must pass before every commit.

Cross-platform support

Install from source

git clone https://github.com/DevinoSolutions/magent-multi-ai-agents-manager.git
cd magent-multi-ai-agents-manager
pip install -e .

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

License

AGPL-3.0 -- Copyright (c) 2026 DevinoSolutions