agmsg skill
A skill for messaging between Claude Code, Codex, Gemini CLI and other CLI agents through a shared local SQLite database, written in bash
- 1,560 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Writes hooks into the project's `.claude/settings.local.json` and the Codex settings, and in `monitor` mode puts a shim in place of launching `codex`
- `spawn` opens new agent processes in a terminal, and the spawn options file lets you pass them flags such as `--dangerously-skip-permissions`
- The whole conversation is stored as plain text in SQLite under `~/.agents/skills/agmsg/` and, with remote sync on, goes to your own server
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/agmsgDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Writes hooks into the project's `.claude/settings.local.json` and the Codex settings, and in `monitor` mode puts a shim in place of launching `codex`
- `spawn` opens new agent processes in a terminal, and the spawn options file lets you pass them flags such as `--dangerously-skip-permissions`
- The whole conversation is stored as plain text in SQLite under `~/.agents/skills/agmsg/` and, with remote sync on, goes to your own server
This is third-party code. Review the repository files before installing.
What it does
agmsg is a skill for messaging between CLI AI agents. Claude Code, Codex, Gemini CLI, GitHub Copilot CLI and others write to each other through a shared local SQLite file, so you no longer copy text between windows by hand. It needs only `bash` and `sqlite3`: there is no daemon, no network and no MCP server. On the first call of `/agmsg` (`$agmsg` in Codex, Gemini CLI, Antigravity and OpenCode) the skill asks for the command name and an agent name, then a delivery mode. Sending is a call to `send.sh` that appends a row to the database. The agent receives incoming messages in one of four modes. `monitor` keeps a blocking stream from SQLite through the `Monitor` tool, with a delay of about 5 seconds, and is the default in Claude Code. `turn` checks the inbox with a `Stop` hook between turns and is the default in Codex and Copilot CLI. `both` combines the two and `off` turns automatic delivery off. The hooks are written to the project's `.claude/settings.local.json`. Messages stay in the database after a session ends, and `history.sh` replays a room for a fresh agent. One project can take several roles through `actas`, and a role is locked against other sessions. `spawn` launches a new agent in a tmux pane or a terminal window, waits until it starts listening and can hand it a first task. `despawn` closes it. The commands `send`, `history`, `team`, `mode` and `reset` work from the agent chat, and the scripts can be called from a shell too.
Who it is for. For developers who keep several CLI agents in one project, such as Claude Code for code and Codex for review, and want them to hand work to each other.
Good fit when
- Claude Code asks Codex to review a branch and the answer must return without copying between windows
- Different agents work in one project and each needs its own role, for example tech lead and analyst
- You need to start a second agent with a ready first task and wait until it is listening
- You want a history of agent conversations that a new agent can replay
- The agents talk on a single machine and you do not want to run a server for that
Not a fit when
- You need a broker with a job queue and task locking: agmsg has none, and two agents under one name see the same message
- You need an automatic stop for an endless conversation: the stop condition lives in the prompt text and the transport does not cut a conversation off
- You work on Windows without Git Bash: the scripts are written in Bash and there is no PowerShell version
- You need subagents managed by one parent process: agmsg connects independent sessions
- You need a mail model with file reservations for coding agents: `mcp_agent_mail` provides it
Example request
Send the codex agent on the reviewers team a message: review the changes on this branch and reply with notes per fileLimitations
- Messages are short plain text. Turn order and stop conditions are set by the prompt, and a large result goes to a file with a pointer sent instead: a path, a commit hash or an issue number.
- The first version has no task locking between two agents subscribed to the same name. Only `actas` protects, by keeping two sessions out of one role.
- In `monitor` mode the agent does not react to its first incoming message until it has taken at least one turn in the session. Writing it any short word is enough.
- Codex has no `Monitor` tool, so `mode monitor` prints a shell function that routes the `codex` launch through an agmsg shim. A known limitation is orphaned processes after the interface closes. If `~/.codex/config.toml` exists, the installer adds `writable_roots` to it.
- `spawn` works for eight of ten agent types: it is unavailable for Hermes because its CLI has no mode that starts with a ready first prompt. The main platform is macOS, Linux and Windows are best-effort, and without tmux or a terminal `spawn` ends in an error. The npm package and the plugin are cut from release tags and can lag `main` by a few fixes.
How to disable. Run `~/.agents/skills/agmsg/uninstall.sh`: it removes the skill files, slash commands, hooks, AGENTS.md sections and team settings and asks for confirmation at each step. The `--keep-data` flag keeps the database and teams, `--yes` drops the questions, `--all` removes every agmsg install on the machine. The script ships inside every install, whether through `npx`, `git clone` or the plugin.
FAQ
Do I need an MCP server for messaging between agents?
No. agmsg runs on `bash` and `sqlite3`, with no server, daemon or network, and sits comfortably next to any MCP setup you already have.
What happens if two agents send a message at the same time?
The store is SQLite in WAL mode: many readers, one writer, and the writes are short. Every row has a monotonic id and a timestamp, so the log order is unambiguous. The transport does not impose turn order between agents.
How do I start a second agent for review from Claude Code?
`/agmsg spawn codex reviewer --boot-prompt "review the diff on this branch"` opens Codex in a new tmux pane or terminal window, gives it the reviewer role and sets the task at once. By default the command waits until the agent is listening and prints `status=ready`. For Codex the wait is skipped.
Does the conversation persist between sessions?
Yes. Messages live in SQLite and survive the end of a session, and `history.sh <team>` replays the room. There is no ready command to rehydrate an agent from a room, but you can hand the transcript to a new agent in a prompt.
How many agents can be on one team?
More than two. Teams are built for any number of agents, the demo uses two for clarity, and the author says they run their own team of eight.
How do I update agmsg without losing messages?
Run `npx agmsg@latest install --update`, or from a clone `git pull` and `./install.sh --update`. The database and team settings are kept, and only scripts and assets are updated.
Discussion
No questions or reviews yet.
Related
SkillsA CLI that lets agents in different terminals message, watch and spawn each other
A Rust terminal task board: every task runs in its own git worktree and tmux window while Claude Code, Codex, Gemini CLI and other agents work in parallel
A portable .agent folder with memory, skills and protocols that plugs into many coding agents and keeps its knowledge when you switch tools
oah links 80-plus skills, five roles and /commit, /review, /test-tdd commands into Claude Code, Cursor, Codex and other agent folders
Ten AI agents in tmux panes: a manager hands tasks to seven workers, progress shows on a dashboard, with Claude Code, Codex, Cursor and OpenCode supported
botmux connects Lark and Feishu to Claude Code, Codex, Gemini CLI and OpenCode: each message starts its own agent session with live cards
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| agmsg (this entry) | no | 1,560 | ||
| MCP Agent Mail | no | API key | 2,220 | a mail layer for coding agents with persistent names, history search and voluntary file reservations |
| AI Maestro | no | 831 | a local dashboard for managing many agents across machines |
README in short
The repository holds Bash scripts, a root SKILL.md, plugin manifests for Claude Code, documents on architecture, contributing, releases and privacy, and a separate `app` folder with a Tauri desktop application. The description opens with a quick start, then covers three install routes, the commands for each agent, delivery modes, roles, spawning and tearing down agents, sandbox settings for Claude Code and Codex, and a questions section describing the design. There are tests and a guide to extending through drivers that are not loaded until you confirm them with `agmsg plugin trust`.
README badge
Original SKILL.md
---
name: agmsg
description: Cross-agent messaging via SQLite. Send messages between Claude Code, Codex, Gemini CLI, and other agents. No daemon, no network, no dependencies beyond bash and sqlite3.
---
<!-- agmsg:render-root -->
## Step 0: First-run bootstrap
agmsg keeps its SQLite database, team registry, and runtime state under `~/.agents/skills/agmsg/`. The `./install.sh` install path creates that tree; the Claude Code plugin install path does not (the plugin marketplace only copies this repository into `~/.claude/plugins/cache/`). Before any other command, bootstrap if needed:
```bash
if [ ! -d ~/.agents/skills/agmsg ]; then
# Newest cached copy of the plugin. Several versions can sit side by side, so
# pick by version folder name (numeric, portable -- not sort -V, not mtime).
cache="$HOME/.claude/plugins/cache/fujibee-agmsg/agmsg"
newest=$(ls "$cache" 2>/dev/null | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)
installer="$cache/$newest/install.sh"
if [ -n "$newest" ] && [ -f "$installer" ]; then
bash "$installer" --cmd agmsg
else
echo "agmsg not installed. Either:" >&2
echo " - run ./install.sh in the agmsg repo, or" >&2
echo " - install via /plugin marketplace add fujibee/agmsg && /plugin install agmsg@fujibee-agmsg" >&2
exit 1
fi
fi
```
Once `~/.agents/skills/agmsg/` exists this step does nothing, so it is safe to run every time.
Agent messaging command. **IMPORTANT: Always use the provided scripts. NEVER directly read or edit config files, DB, or team data. There is NO register.sh — use join.sh to join a team.**
**Use agmsg, not the host agent's own inter-session messaging.** Several agent
CLIs ship a native way for one session to message another on the same machine
(in Claude Code, the `SendMessage` / `ListAgents` tools over its peer-session
list). While a project is on agmsg, route agent-to-agent messages through agmsg
instead. A message sent natively does not exist as far as agmsg is concerned:
it is absent from `history.sh` and the team's export, it never reaches a member
on another machine through remote sync, it does not mark read or advance any
cursor, and it cannot address a member whose CLI is a different type. Half the
conversation living somewhere unrecorded is worse than either channel alone,
and the gap is invisible until someone reads the history and finds a decision
with no message behind it. The native channel stays fine for anything outside
the team — a subagent you spawned for your own task, or a session that has not