magents

<p align="center">
  <img src="docs/assets/hero.svg" alt="magents shared session bus across Claude, Codex, Grok, and Cursor" width="100%" />
</p>

<p align="center">
  <a href="https://hol.org/registry/plugins/abnegate%2Fmagents"><img alt="HOL Trust" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fhol.org%2Fapi%2Fregistry%2Fbadges%2Fplugin%3Fslug%3Dabnegate%252Fmagents%26metric%3Dtrust%26style%3Dflat"></a>
</p>

Claude Code, Codex, Copilot, Cursor, Gemini, AGY, Grok, and OpenCode already keep
transcripts on disk. **magents** is the shared API over those sessions - an MCP
server plus a small CLI - so one agent can pick up where another left off
without you recapping, ping a *specific live chat* when you are not sitting in
the middle, or start an independent persisted chat for a complete task.

It is not a second copy of history and not a fire-and-forget council. Existing
chats stay the default unit of work; new chats are for independent work that
benefits from its own session and working directory.

[Install](#install) · [Plugins](#plugins) · [What you can do](#what-you-can-do) · [Quick start](#quick-start) · [Tools](#tools) · [CLI](#cli) · [Releases](https://github.com/abnegate/magents/releases)

## Why

You already run more than one coding agent. The pain is not "more models" - it
is **context trapped in another window**.

| Pain | What magents does |
| --- | --- |
| You switched hosts mid-task | Read the live session and continue *here* |
| Agent A hit a wall Agent B owns | Inject into that live chat without you as the messenger |
| A subtask can run alone | Spawn a headless persisted session with a complete prompt + reply path |

## What you can do

**1. Handoff without a new thread**  
You were in Claude on the disaster-recovery branch. Now you are in Grok. Ask
Grok what they were doing; it reads the live session and continues. No paste
buffer. No "new chat, here's the context."

**2. Send when you are not the messenger**  
Three agents running. Claude hits a wall Codex owns. Claude injects into that
Codex thread and keeps going - especially useful when the sender already has the
failing query, file, and constraint you would otherwise reconstruct.

**3. Spawn independent work**  
When a task can proceed alone, start a new headless persisted session with a
complete prompt, an isolated working directory when files could collide, and a
request to reply through magents. Spawned agents keep their host's native
approval policy - spawning does not add an approval bypass.

## Install

### Homebrew (macOS / Linux)

```bash
brew install abnegate/tap/magents
magents install --all
```

### APT (Debian / Ubuntu)

```bash
curl -fsSL https://abnegate.github.io/apt-repo/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/abnegate.gpg
echo "deb [signed-by=/usr/share/keyrings/abnegate.gpg] https://abnegate.github.io/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/abnegate.list
sudo apt update && sudo apt install magents
magents install --all
```

### Binary

From [Releases](https://github.com/abnegate/magents/releases):

```bash
curl -LSsf -o magents \
  "https://github.com/abnegate/magents/releases/latest/download/magents-$(uname -m | sed 's/arm64/aarch64/')-$(uname -s | tr 'A-Z' 'a-z' | sed 's/darwin/apple-darwin/;s/linux/unknown-linux-musl/')"
chmod +x magents
./magents install --all
```

Assets: `magents-x86_64-unknown-linux-musl`, `magents-aarch64-unknown-linux-musl`,
`magents-aarch64-apple-darwin`, `magents-x86_64-apple-darwin`.

### Container

```bash
docker pull ghcr.io/abnegate/magents:latest
docker run --rm --user "$(id -u):$(id -g)" \
  -v "$HOME:$HOME" -e HOME \
  ghcr.io/abnegate/magents list --live
```

### Cargo

```bash
cargo install magents --locked
magents install --all
```

### From source

```bash
cargo install --path .
magents install --all
```


## Plugins

Host plugins package the magents skill plus an MCP entry that runs `magents mcp`.
Install the CLI first (`brew install abnegate/tap/magents`), then load the matching
folder under [`plugins/`](plugins/).

| Host | Path |
| --- | --- |
| Claude Code | [`plugins/claude`](plugins/claude) |
| Codex | [`plugins/codex`](plugins/codex) |
| Cursor | [`plugins/cursor`](plugins/cursor) |
| Gemini CLI | repo root ([`gemini-extension.json`](gemini-extension.json)) |
| AGY CLI / Antigravity | [`plugins/agy`](plugins/agy) |

Gemini CLI installs the extension straight from this repository:

```bash
gemini extensions install https://github.com/abnegate/magents
```

AGY CLI installs the plugin from [`plugins/agy`](plugins/agy) (manifest, MCP, and skills):

```bash
agy plugin install https://github.com/abnegate/magents/plugins/agy
```

Details and marketplace notes: [`plugins/README.md`](plugins/README.md).

## Quick start

`magents install --all` registers the stdio MCP server with each installed host,
skipping hosts whose required binaries are unavailable:

- Grok (`grok mcp add magents -- magents mcp`)
- Claude Code (`claude mcp add --scope us

... (truncated)