magents

[magents shared session bus across Claude, Codex, Grok, and Cursor]

[HOL Trust]

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/magentsmagents install --all

APT (Debian / Ubuntu)

curl -fsSL https://abnegate.github.io/apt-repo/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/abnegate.gpgecho "deb [signed-by=/usr/share/keyrings/abnegate.gpg] https://abnegate.github.io/apt-repo stable main" | sudo tee /etc/apt/sources.list.d/abnegate.listsudo apt update && sudo apt install magentsmagents 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:latestdocker run --rm --user "$(id -u):$(id -g)" \  -v "$HOME:$HOME" -e HOME \  ghcr.io/abnegate/magents list --live

Cargo

cargo install magents --lockedmagents 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 --livemagents digest grok:latestmagents handoff grok:latest --reason "continuing in grok"

Tools

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

CLI

magents list --livemagents list --agent grok --query edgemagents get 'claude:disaster recovery'magents read grok:latest -n 20magents digest grok:latestmagents search "dedicated databases" --agent claudemagents spawn codex --prompt-file /path/to/task.md --cwd /path/to/isolated-worktreemagents send grok:latest "handoff: the DR runbook is in docs/RUNBOOK.md"magents handoff grok:latest --reason "continuing in grok"magents whoamimagents learn estimatemagents learn collectmagents learn planmagents learn collect --since-lastmagents 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-targetscargo 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