{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/assets/hero.svg\" alt=\"magents shared session bus across Claude, Codex, Grok, and Cursor\" width=\"100%\" />\n</p>\n\nClaude Code, Codex, Copilot, Cursor, Gemini, Grok, and OpenCode already keep\ntranscripts on disk. **magents** is the shared API over those sessions - an MCP\nserver plus a small CLI - so one agent can pick up where another left off\nwithout you recapping, ping a *specific live chat* when you are not sitting in\nthe middle, or start an independent persisted chat for a complete task.\n\nIt is not a second copy of history and not a fire-and-forget council. Existing\nchats stay the default unit of work; new chats are for independent work that\nbenefits from its own session and working directory.\n\n[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)\n\n## Why\n\nYou already run more than one coding agent. The pain is not \"more models\" - it\nis **context trapped in another window**.\n\n| Pain | What magents does |\n| --- | --- |\n| You switched hosts mid-task | Read the live session and continue *here* |\n| Agent A hit a wall Agent B owns | Inject into that live chat without you as the messenger |\n| A subtask can run alone | Spawn a headless persisted session with a complete prompt + reply path |\n\n## What you can do\n\n**1. Handoff without a new thread**  \nYou were in Claude on the disaster-recovery branch. Now you are in Grok. Ask\nGrok what they were doing; it reads the live session and continues. No paste\nbuffer. No \"new chat, here's the context.\"\n\n**2. Send when you are not the messenger**  \nThree agents running. Claude hits a wall Codex owns. Claude injects into that\nCodex thread and keeps going - especially useful when the sender already has the\nfailing query, file, and constraint you would otherwise reconstruct.\n\n**3. Spawn independent work**  \nWhen a task can proceed alone, start a new headless persisted session with a\ncomplete prompt, an isolated working directory when files could collide, and a\nrequest to reply through magents. Spawned agents keep their host's native\napproval policy - spawning does not add an approval bypass.\n\n## Install\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew install abnegate/tap/magents\nmagents install --all\n```\n\n### APT (Debian / Ubuntu)\n\n```bash\ncurl -fsSL https://abnegate.github.io/apt-repo/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/abnegate.gpg\necho \"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\nsudo apt update && sudo apt install magents\nmagents install --all\n```\n\n### Binary\n\nFrom [Releases](https://github.com/abnegate/magents/releases):\n\n```bash\ncurl -LSsf -o magents \\\n  \"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/')\"\nchmod +x magents\n./magents install --all\n```\n\nAssets: `magents-x86_64-unknown-linux-musl`, `magents-aarch64-unknown-linux-musl`,\n`magents-aarch64-apple-darwin`, `magents-x86_64-apple-darwin`.\n\n### Container\n\n```bash\ndocker pull ghcr.io/abnegate/magents:latest\ndocker run --rm --user \"$(id -u):$(id -g)\" \\\n  -v \"$HOME:$HOME\" -e HOME \\\n  ghcr.io/abnegate/magents list --live\n```\n\n### From source\n\n```bash\ncargo install --path .\nmagents install --all\n```\n\n\n## Plugins\n\nHost plugins package the magents skill plus an MCP entry that runs `magents mcp`.\nInstall the CLI first (`brew install abnegate/tap/magents`), then load the matching\nfolder under [`plugins/`](plugins/).\n\n| Host | Path |\n| --- | --- |\n| Claude Code | [`plugins/claude`](plugins/claude) |\n| Codex | [`plugins/codex`](plugins/codex) |\n| Cursor | [`plugins/cursor`](plugins/cursor) |\n\nDetails and marketplace notes: [`plugins/README.md`](plugins/README.md).\n\n## Quick start\n\n`magents install --all` registers the stdio MCP server with each installed host,\nskipping hosts whose required binaries are unavailable:\n\n- Grok (`grok mcp add magents -- magents mcp`)\n- Claude Code (`claude mcp add --scope user magents -- magents mcp`)\n- Codex (`codex mcp add magents -- magents mcp`)\n- Cursor (`~/.cursor/mcp.json`)\n- OpenCode (`~/.config/opencode/opencode.json`)\n- Gemini CLI (`gemini mcp add -s user magents magents mcp`)\n- GitHub Copilot CLI (`copilot mcp add magents -- magents mcp`)\n\nIt also writes the `magents` and `learn` skills under supported hosts' skills\ndirectories (`~/.grok/skills/{magents,learn}`, `~/.claude/skills/{magents,learn}`,\n`~/.cursor/skills/{magents,learn}`, and the OpenCode / Gemini / Copilot\nequivalents). `/learn` reads every local agent's sessions, not only Grok.\n\nFor Grok and Codex only, point a host at the binary yourself:\n\n```toml\n[mcp_servers.magents]\ncommand = \"/path/to/magents\"\nargs = [\"mcp\"]\n```\n\nRestart the agent session (or refresh `/mcps`) so the tools appear.\n\nTry:\n\n```bash\nmagents list --live\nmagents digest grok:latest\nmagents handoff grok:latest --reason \"continuing in grok\"\n```\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `list_sessions` | Live and recent sessions; filter by `cwd` / `branch` |\n| `get_session` | Lookup by id, title, live name, pid, or `agent:ref` |\n| `read_transcript` | Compact inert handoff (last request, last action, recent turns) |\n| `search_transcripts` | Full-text search across those transcripts |\n| `search_memories` | Phrase search over Claude / Codex / Grok memory markdown |\n| `create_memory` | Write a note into Claude / Codex / Grok first-party memory |\n| `spawn_session` | Start a new headless persisted session for independent work |\n| `send_message` | Deliver a user turn to an existing chat |\n| `handoff` | Compact this session and inject it into another live chat |\n| `inbox` / `ack` / `await_reply` / `reply` | Mailbox for cross-session replies |\n| `session_digest` | Compact last request / action / cwd / branch / clipped turns |\n| `files_touched` | Paths another session edited |\n| `stop_session` | Stop a magents-supervised spawn or resume |\n| `read_memory` | Read one Claude / Codex / Grok memory markdown file |\n| `get_note` / `put_note` | Magents-owned shared scratch for a working directory |\n| `whoami` | Detect this connection; resolve session via env, socket, or unique cwd |\n| `learn_collect` | Collect compact records from every local agent's full history for `/learn`, or estimate a run |\n| `learn_state` | Read or update `/learn` state, decisions, and trash |\n\nRefs can be prefixed: `claude:disaster recovery`, `grok:latest`, `codex:<uuid>`,\n`cursor:latest`, `opencode:<id>`, `gemini:latest`, `copilot:<id>`.\n\n## CLI\n\n```bash\nmagents list --live\nmagents list --agent grok --query edge\nmagents get 'claude:disaster recovery'\nmagents read grok:latest -n 20\nmagents digest grok:latest\nmagents search \"dedicated databases\" --agent claude\nmagents spawn codex --prompt-file /path/to/task.md --cwd /path/to/isolated-worktree\nmagents send grok:latest \"handoff: the DR runbook is in docs/RUNBOOK.md\"\nmagents handoff grok:latest --reason \"continuing in grok\"\nmagents whoami\nmagents learn estimate\nmagents learn collect\nmagents learn plan\nmagents learn collect --since-last\nmagents learn state\n```\n\nPass `--output json` on any command for stable machine-readable stdout.\n\n`magents` with no args on a piped stdin starts the MCP server.\n\n`magents spawn` reads the complete task from stdin by default (`--prompt-file`\nsupported). Prompt text is never a process argument.\n\n## How sessions talk\n\n`list_sessions` / `read_transcript` / `search_transcripts` / `search_memories`\nare the handoff. `create_memory` writes into another harness's first-party\nmemory (Claude, Codex, or Grok).\n\nChoose the write path by where the work should happen:\n\n- **`spawn_session`** - new, headless, persisted, independent session. Complete\n  task, verification, reply-through-magents, isolated `cwd` when edits could\n  collide. Success means launch accepted (`accepted: true`, `status: \"starting\"`),\n  not that the task finished.\n- **`send_message`** - existing session. Always records mailbox mail; injects a\n  live user turn where the host supports one.\n- **`handoff`** - compact this session into an existing live session so that\n  session continues the same work.\n\n### Delivery routes (existing chats)\n\n`send_message` always appends to the mailbox, then prefers a native live path\nand otherwise starts a supervised headless resume:\n\n| Surface | Delivery route |\n| --- | --- |\n| Claude Desktop | UDS user turn (`/tmp/cc-socks/<pid>.sock`), then tmux or supervised `claude -p --verbose --resume <id>` |\n| Claude CLI | UDS when available, then tmux or supervised resume |\n| Grok | Supervised `grok --cwd <cwd> --resume <id> --output-format streaming-json --prompt-file /dev/stdin` |\n| Codex Desktop / VS Code | Length-prefixed JSON-RPC on `~/.codex/ipc/ipc.sock`, then supervised `codex exec ... resume` |\n| Codex CLI | Supervised `codex exec --json -C <cwd> resume <id> -` |\n| Cursor | Supervised `cursor-agent -p --output-format stream-json --resume <id> --workspace <cwd>` |\n| OpenCode | Supervised `opencode run --format json --dir <cwd> --session <id>` |\n| Gemini CLI | Supervised `gemini --resume <id> --output-format stream-json` |\n| GitHub Copilot CLI | Supervised `copilot --resume=<id> --output-format json` |\n\nSupervised routes pass the user turn through stdin and do not expose transcript\ntext, tokens, or raw host output in the response. Spawn never adds approval\nbypasses (`--dangerously-skip-permissions`, `--yolo`, `--full-auto`, etc.).\n\nSession discovery sources (unchanged): Claude `~/.claude/sessions`, Grok\n`~/.grok/active_sessions.json`, Codex sqlite + rollout JSONL, Cursor\n`agent-transcripts`, OpenCode DB, Gemini journals, Copilot `session-state`.\n\n## Tests\n\n```bash\ncargo test --locked --all-targets\ncargo llvm-cov --locked --all-targets --ignore-filename-regex 'src/main.rs|/rustlib/' --fail-under-lines 98\n```\n\nCI runs format, clippy (`-D warnings`), the full test suite, and a 98% line-coverage gate.\n\n## Requirements\n\n- Rust 1.88+\n- macOS or Linux (Claude UDS inject is Unix-only)\n\n## License\n\nMIT\n",
  "bytes": 10186,
  "sha": "9a8e774b9c0352dcf016d688bf26bc87c3d595e76cbf07cb99a6ba24de76ca59",
  "repo_slug": "abnegate/magents",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_abnegate_magents_619459a9/readme"
}