magents

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.

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

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

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

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:

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