How do I install Magents?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Magents need an API key?

No required environment variable is listed on this record.

What transport does Magents use?

Magents runs locally over stdio.

When was Magents last checked?

Last checked 2026-11-09. Shared session bus for Claude, Codex, Copilot, Cursor, Gemini, AGY, Grok, and OpenCode.

Magents MCP server

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 · Plugins · What you can do · Quick start · Tools · CLI · 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)

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

APT (Debian / Ubuntu)

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:

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

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

cargo install magents --locked
magents install --all

From source

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/.

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

Gemini CLI installs the extension straight from this repository:

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

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

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

Details and marketplace notes: 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 user magents -- magents mcp)
Codex (codex mcp add magents -- magents mcp)
Cursor (~/.cursor/mcp.json)
OpenCode ($XDG_CONFIG_HOME/opencode/opencode.json, default ~/.config/opencode)
Gemini CLI (gemini mcp add -s user magents magents mcp)
GitHub Copilot CLI (copilot mcp add magents -- magents mcp)
AGY CLI (agy mcp add magents magents mcp)

It also writes the magents and learn skills under supported hosts' skills directories (~/.grok/skills/{magents,learn}, ~/.claude/skills/{magents,learn}, ~/.cursor/skills/{magents,learn}, and the OpenCode / Gemini / AGY / Copilot equivalents). /learn reads every local agent's sessions, not only Grok.

For Grok and Codex only, point a host at the binary yourself:

[mcp_servers.magents]
command = "/path/to/magents"
args = ["mcp"]

For Cline, open MCP Servers → Configure MCP Servers and add this to cline_mcp_settings.json:

{
  "mcpServers": {
    "magents": {
      "command": "magents",
      "args": ["mcp"]
    }
  }
}

Restart the agent session (or refresh /mcps) so the tools appear.

Try:

magents list --live
magents digest grok:latest
magents handoff grok:latest --reason "continuing in grok"

Tools

Tool	Purpose
`list_sessions`	Live and recent sessions; filter by `cwd` / `branch`
`get_session`	Lookup by id, title, live name, pid, or `agent:ref`
`read_transcript`	Compact inert handoff (last request, last action, recent turns)
`search_transcripts`	Full-text search across those transcripts
`search_memories`	Phrase search over Claude / Codex / Grok memory markdown
`create_memory`	Write a note into Claude / Codex / Grok first-party memory
`spawn_session`	Start a new headless persisted session for independent work
`send_message`	Deliver a user turn to an existing chat
`handoff`	Compact this session and inject it into another live chat
`inbox` / `ack` / `await_reply` / `reply`	Mailbox for cross-session replies
`session_digest`	Compact last request / action / cwd / branch / clipped turns
`files_touched`	Paths another session edited
`stop_session`	Stop a magents-supervised spawn or resume
`read_memory`	Read one Claude / Codex / Grok memory markdown file
`get_note` / `put_note`	Magents-owned shared scratch for a working directory
`whoami`	Detect this connection; resolve session via env, socket, or unique cwd
`learn_collect`	Collect compact records from every local agent's full history for `/learn`, or estimate a run
`learn_state`	Read or update `/learn` state, decisions, and trash

Refs can be prefixed: claude:disaster recovery, grok:latest, codex:<uuid>, cursor:latest, opencode:<id>, gemini:latest, agy:<id>, copilot:<id>.

CLI

magents list --live
magents list --agent grok --query edge
magents get 'claude:disaster recovery'
magents read grok:latest -n 20
magents digest grok:latest
magents search "dedicated databases" --agent claude
magents spawn codex --prompt-file /path/to/task.md --cwd /path/to/isolated-worktree
magents send grok:latest "handoff: the DR runbook is in docs/RUNBOOK.md"
magents handoff grok:latest --reason "continuing in grok"
magents whoami
magents learn estimate
magents learn collect
magents learn plan
magents learn collect --since-last
magents learn state

Pass --output json on any command for stable machine-readable stdout.

magents with no args on a piped stdin starts the MCP server.

magents spawn reads the complete task from stdin by default (--prompt-file supported). Prompt text is never a process argument.

How sessions talk

list_sessions / read_transcript / search_transcripts / search_memories are the handoff. create_memory writes into another harness's first-party memory (Claude, Codex, or Grok).

Choose the write path by where the work should happen:

spawn_session - new, headless, persisted, independent session. Complete task, verification, reply-through-magents, isolated cwd when edits could collide. Success means launch accepted (accepted: true, status: "starting"), not that the task finished.
send_message - existing session. Always records mailbox mail; injects a live user turn where the host supports one.
handoff - compact this session into an existing live session so that session continues the same work.

Delivery routes (existing chats)

send_message always appends to the mailbox, then prefers a native live path and otherwise starts a supervised headless resume:

Surface	Delivery route
Claude Desktop	UDS user turn (`/tmp/cc-socks/<pid>.sock`), then tmux or supervised `claude -p --verbose --resume <id>`
Claude CLI	UDS when available, then tmux or supervised resume
Grok	Supervised `grok --cwd <cwd> --resume <id> --output-format streaming-json --prompt-file /dev/stdin`
Codex Desktop / VS Code	Length-prefixed JSON-RPC on `~/.codex/ipc/ipc.sock`, then supervised `codex exec ... resume`
Codex CLI	Supervised `codex exec --json -C <cwd> resume <id> -`
Cursor	Supervised `cursor-agent -p --output-format stream-json --resume <id> --workspace <cwd>`
OpenCode	Supervised `opencode run --format json --session <id>`, started in the session `cwd` (with `PWD` set)
Gemini CLI	Supervised `gemini --resume <id> --output-format stream-json`
AGY CLI / Antigravity	Supervised `agy --input-format stream-json --output-format stream-json --conversation <id>`
GitHub Copilot CLI	Supervised `copilot --resume=<id> --output-format json`

Supervised routes pass the user turn through stdin and do not expose transcript text, tokens, or raw host output in the response. Spawn never adds approval bypasses (--dangerously-skip-permissions, --yolo, --full-auto, etc.).

Session discovery sources: Claude ~/.claude and ~/.claude-* (plus Desktop Claude / Claude-* session dirs), Grok ~/.grok/active_sessions.json, Codex sqlite + rollout JSONL, Cursor agent-transcripts, OpenCode SQLite (opencode.db and channel databases, v1 session and v2 session_v2 / session_message tables), Gemini journals, AGY CLI conversations / brain plus Antigravity desktop conversation_summaries, Copilot session-state. Claude sessions include a profile field when they come from a named home (work for ~/.claude-work). Resume and live inject use that home's CLAUDE_CONFIG_DIR.

Tests

cargo test --locked --all-targets
cargo llvm-cov --locked --all-targets --ignore-filename-regex 'src/main.rs|/rustlib/' --fail-under-lines 98

CI runs format, clippy (-D warnings), the full test suite, and a 98% line-coverage gate.

Requirements

Rust 1.97+
macOS or Linux (Claude UDS inject is Unix-only)

License

MIT

Magents

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Magents?

Does Magents need an API key?

What transport does Magents use?

When was Magents last checked?

Documentation

Why

What you can do

Install

Homebrew (macOS / Linux)

APT (Debian / Ubuntu)

Binary

Container

Cargo

From source

Plugins

Quick start

Tools

CLI

How sessions talk

Delivery routes (existing chats)

Tests

Requirements

License