// install(1) — manual page

Get mAgent running.

Two minutes from an empty terminal to a tiled, resumed agent workspace. Follow the steps in order — 01 and 02 are all most people need.

Check the requirements

[+] Python 3.10 or newer

[+] Windows, macOS, or Linux — some power features are Windows-only, see the capability matrix

[+] a terminal — Windows Terminal · kitty · iTerm · alacritty · gnome-terminal

[+] your agents on PATH — claude · codex · cursor-agent · agy · code · cursor

Install it

Pick one. uv keeps it isolated from your project environments.

pip

pip install magent-multi-ai-agents-manager

uv tool install magent-multi-ai-agents-manager

from source

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

First run — it configures itself

The first run scans your Claude, Codex, and VS Code history, finds your recent projects, and writes a config. The second run launches everything.

$ magent
✓ found 8 recent projects across claude · codex · vscode
✓ config written — edit any time with: magent --edit
$ magent --go
✓ 2 monitors · launching 8 windows · resuming sessions…

Wire agent states (recommended)

The watch table and attention badges read state records written by your agents' lifecycle hooks. This merges the state writer into Claude Code's settings — your existing hooks are preserved — and prints the one-line Codex recipe. Restart your agents after.

magent hooks install

Optional extras

pip install magent-multi-ai-agents-manager[qr]

QR code for the phone uploader — install it as a home-screen app.

choco install psmux

Persistent sessions you can SSH into from anywhere. Windows.

npm install -g happy

E2e-encrypted phone/browser control of Claude & Codex sessions.

pip install magent-multi-ai-agents-manager[toast]

Desktop toast notifications on needs-input. Windows.

npx ai-agent-notifier setup

Companion package: phone and desktop alerts on the same hook events. Notifications only — agent states still come from step 04.

Something off? Run the doctor

Diagnoses config, env vars, agent tools on PATH, terminal, monitors, writable dirs, Tailscale, and the upload port. Exit 1 on any failure — pipe --json into a bug report.

magent doctor

config lives at:

windows %APPDATA%\magent\config.json

macos ~/Library/Application Support/magent/config.json

linux ~/.config/magent/config.json

← back to mAgent stuck? open an issue →or ask in our Discord →