# Set up mAgent for an AI coding agent

These are official instructions from mAgent to set up an AI development environment for a free, open-source CLI that opens each of your projects in its own terminal, launches your AI coding agent inside it, and auto-tiles every window into a grid across all your monitors. All commands below are validated by mAgent. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands.

Checklist:

- [ ] Install the magent CLI
- [ ] Run `magent` once to scan projects and write a config
- [ ] Wire your agent into the fleet-state store, if it supports lifecycle hooks (Claude Code, Codex)
- [ ] Verify with `magent doctor`
- [ ] Print the completion message

## Credentials

No credentials needed. mAgent has no API key, no OAuth flow, and no MCP server -- it is a local CLI that launches terminals and agents already installed on this machine. Skip this step.

## Install the CLI

Pick one:

```bash
# pip
pip install magent-multi-ai-agents-manager
```

```bash
# uv
uv tool install magent-multi-ai-agents-manager
```

```bash
# 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

Run `magent` once. It scans Claude Code, Codex, and VS Code history, finds recent projects, and writes `magent.config.json` (re-run with `--init` to rescan). This step is required regardless of which agent you are setting up below.

```bash
magent
```

## Per-agent setup

Use the section for the agent you are running as.

### Claude Code

mAgent launches Claude Code per project with session auto-resume (`claude --continue`), and Claude Code's own lifecycle hooks feed the fleet-state store that `magent watch`, `magent sessions --json`, and `magent attention` all read.

**Install the CLI**

Install the magent CLI. No project changes needed -- it is a standalone tool.

```bash
pip install magent-multi-ai-agents-manager
```

**Scan projects and write a config**

On first run, magent scans your Claude Code, Codex, and VS Code history, finds recent projects, and writes `magent.config.json`. Run `magent --init` any time to rescan.

```bash
magent
```

**Wire the Claude Code lifecycle hooks**

Merges the bundled `magent-state-hook` writer into `~/.claude/settings.json` (idempotent -- any existing hooks are preserved). This is what feeds live per-session state to `magent watch`, `magent status`, and `magent attention`; without it those tools show no status for Claude Code sessions. Restart any already-open Claude Code sessions afterward so the new hooks take effect.

```bash
magent hooks install
```

**Windows only: fix Ctrl+Backspace and Shift+Enter**

Only relevant if persistent psmux sessions are enabled (`settings.psmux: true`). psmux drops key modifiers in transit, so this binds the two keys in Windows Terminal itself so they still work inside a psmux pane. Safe to run unconditionally -- it is a no-op off Windows or without Windows Terminal.

```bash
magent terminal install
```

### Codex

mAgent launches Codex CLI per project with session resume (`codex resume`), and Codex's `notify` hook feeds the same fleet-state store Claude Code uses.

**Install the CLI**

Install the magent CLI. No project changes needed -- it is a standalone tool.

```bash
pip install magent-multi-ai-agents-manager
```

**Scan projects and write a config**

On first run, magent scans your Claude Code, Codex, and VS Code history, finds recent projects, and writes `magent.config.json`. Run `magent --init` any time to rescan.

```bash
magent
```

**Wire the Codex notify hook**

Run `magent hooks install`. Besides wiring Claude Code, it prints a `notify = [...]` line resolved to this machine's absolute `magent-state-hook` path -- copy that exact printed line into `~/.codex/config.toml` under the `notify` key (the path is machine-specific, so it cannot be hardcoded here). Restart any already-open Codex sessions afterward.

```bash
magent hooks install
```

### Cursor

mAgent can launch the Cursor CLI agent (`cursor-agent`) or the Cursor IDE per project, tiled alongside every other window. Cursor has no lifecycle-hook integration today, so it gets launch + tiling only -- no live state and no session auto-resume.

**Install the CLI**

Install the magent CLI. No project changes needed -- it is a standalone tool.

```bash
pip install magent-multi-ai-agents-manager
```

**Scan projects and write a config**

On first run, magent scans your history and writes `magent.config.json`. Run `magent --init` any time to rescan.

```bash
magent
```

**Point the project at Cursor**

`cursor-agent` (CLI) and `cursor` (IDE) are both registered built-in tools -- no extra `settings.tools` mapping is needed. Set `"tool": "cursor-agent"` (or `"tool": "cursor"`) on the project entry in `magent.config.json`.

```jsonc
"tool": "cursor-agent"
```

### OpenCode

OpenCode is not a built-in mAgent tool, but any command on PATH can be registered as a custom tool and magent will launch + tile it per project like any other agent. There is no lifecycle-hook integration for it, so it gets launch + tiling only -- no live state and no session auto-resume.

**Install the CLI**

Install the magent CLI. No project changes needed -- it is a standalone tool.

```bash
pip install magent-multi-ai-agents-manager
```

**Scan projects and write a config**

On first run, magent scans your history and writes `magent.config.json`. Run `magent --init` any time to rescan.

```bash
magent
```

**Register OpenCode as a custom tool**

Map a name to the shell command that starts it under `settings.tools` in `magent.config.json`, then set that name as the `tool` on any project that should launch it.

```jsonc
"tools": { "opencode": "opencode" }
```

## Other agents

If your agent is not listed above: install the CLI and run the First run step, then register your agent as a custom tool by mapping a name to its launch command under `settings.tools` in `magent.config.json`, and set that name as the `tool` on the projects it should run. Example below registers a tool named "aider" that launches with `aider --model sonnet`; substitute your own agent's name and launch command. There is no lifecycle-hook integration outside Claude Code and Codex, so there is no live state or session auto-resume for a custom tool.

```jsonc
// magent.config.json
"settings": { "tools": { "aider": "aider --model sonnet" } },
"projects": [{ "path": "backend/api", "tool": "aider" }]
```

## Verify

Run `magent doctor` -- it diagnoses config, env vars, agent tools on PATH, terminal, monitors, writable dirs, Tailscale, and the upload port, and exits 1 on any failure. If you wired lifecycle hooks, also run `magent hooks status` and confirm it reports installed. Success looks like `magent doctor` exiting 0 with no failed checks.

```bash
magent doctor
```

## Completion message

Print a message to the user once setup is done, filling in the real values from what you just ran (do not leave placeholder text in place):

```text
mAgent is set up.
- Installed with: (pip, uv, or from source -- say which one you used)
- Config written: magent.config.json (say how many projects were found)
- Lifecycle hooks: (say "wired for Claude Code" / "wired for Codex", or "not applicable" if this agent has no hook support)
- magent doctor: (say "passed", or list the warnings/failures it reported)

Run `magent --go` any time to launch and tile every project. Restart any agent sessions
that were already open so the new hooks take effect.
```

## Resources

- Docs home: https://magent.now
- Install guide: https://magent.now/install
- FAQ: https://magent.now/faq
- llms.txt: https://magent.now/llms.txt
- GitHub repository: https://github.com/DevinoSolutions/magent-multi-ai-agents-manager
- PyPI package: https://pypi.org/project/magent-multi-ai-agents-manager
- Report an issue: https://github.com/DevinoSolutions/magent-multi-ai-agents-manager/issues