agmsg: The SQLite Message Bus for CLI Agents
A no-daemon messaging layer that lets local AI agents talk, watch, and coordinate through one file, with locks and prompts designed for models, not humans.
- agmsg is interesting because it turns one local SQLite file into a practical message bus for CLI agents without a daemon or broker.
- Its real trick is not storage, but coordination, combining WAL mode, watcher loops, PID files, and role locks into a simple local protocol.
- The prompt layer is part of the system design, because the scripts are written to produce behavior that LLM agents can actually follow and recover from.
- The project trades distributed reach and raw throughput for portability, transparency, and a much lower setup threshold.
One SQLite file, many agents
The memorable move in agmsg is almost absurdly small. It uses one local SQLite database as a shared inbox for CLI agents, then wraps that file in just enough shell tooling to make the whole thing feel live.
That choice matters because it keeps the system invisible until it is needed. No daemon, no Redis, no hosted broker, no always-on service sitting in the process tree when nothing is happening.
Claude CodeやCodexなどのCLI AIエージェント同士がメッセージをやり取りできるツールらしい 複数のエージェントを連携させて作業を効率化するのに使えそう yug1224 starred fujibee/agmsg https://t.co/9V5oDNBHg3
Why this is not just a database trick
If this were only about persistence, it would be boring. The real problem is coordination: several agents need a shared place to leave messages, observe progress, and avoid stepping on the same role at the same time.
That is why the local-first approach is the point. The design lowers the adoption threshold for the exact case it targets, which is a single machine running multiple CLI agents that need to cooperate without becoming an infrastructure project.
| Approach | Setup overhead | Local-first | Concurrency handling | Agent-friendly UX | Network dependency |
|---|---|---|---|---|---|
| agmsg with SQLite | Low | Yes | WAL plus file locks | High | No |
| Redis or NATS broker | Medium to high | Sometimes | Strong, but external | Medium | Usually yes |
| Daemon-based orchestration | High | Sometimes | Depends on service | Medium | Often yes |
| Ad hoc shell polling | Low | Yes | Weak | Low | No |
How watch.sh turns polling into a live feed
The most interesting mechanism in the repo is the watcher loop. It polls the database on an interval, remembers a high-water mark, and only surfaces rows beyond that mark, which gives the feel of push without a permanent server.
Two other pieces make that believable. WAL mode keeps reads and writes from fighting each other as much as a plain SQLite setup would, and PID-file control prevents duplicate watchers for the same session from lingering forever.
Locks, roles, and the actas problem
`actas-lock.sh` solves a subtle but important problem. In a multi-agent setup, two sessions should not pretend to be the same inbox owner, because that creates confusion about who is responsible for reading, responding, and cleaning up.
The lock is not glamorous, but it is what keeps the protocol honest. It turns identity from a suggestion into an enforced constraint, which is exactly what you want when agents are sharing a local workspace.
| Without role lock | With actas lock |
|---|---|
| Two sessions can consume the same inbox at once. | Only one session can own the role at a time. |
| Messages may be duplicated or missed in practice. | Visibility is gated before delivery. |
| Cleanup becomes ambiguous. | Ownership is explicit and recoverable. |
The prompt layer is part of the protocol
The templates are not decorative documentation. They are the bridge between shell scripts and model behavior, teaching the agent which command to run and how to react when the environment changes.
That makes `SKILL.md` style instructions part of the system itself. The repo is not just storing messages, it is shaping how an LLM interprets failure, retries, and role boundaries.
# The protocol is simple, but the behavior is model-aware.
# Scripts do the work.
# Templates teach the agent when to call them.
if [ "$AGMSG_ROLE" = "reviewer" ]; then
./scripts/watch.sh --session "$SESSION_ID"
fi
# If the lock is held elsewhere, surface a message the model can act on.
# Then retry or ask the owning session to release it.
What agmsg chooses not to be
The obvious comparison is with Redis, NATS, or a custom daemon. Those tools buy you stronger distributed semantics and a broader deployment story, but they also ask for more setup, more surface area, and more moving parts.
agmsg makes a different trade. It is not trying to win as a general-purpose message broker. It is optimized for local, ephemeral, CLI-native coordination, where the simplest working thing is often the best thing.
| System | Best at | Tradeoff |
|---|---|---|
| agmsg | Local agent coordination | Not built for networked scale |
| Redis or NATS | High-throughput messaging | Requires a separate service |
| Traditional agent frameworks | Workflow orchestration | More opinionated and heavier |
| Shell polling alone | Tiny scripts | Weak coordination and locking |
Why this matters beyond the repo
The broader idea is more interesting than the implementation detail. agmsg suggests that some agent coordination problems may belong in the filesystem, not in a platform.
That is a useful reset. It points toward software that is designed around agent failure modes, local control loops, and human-debuggable state, instead of only around human-authored APIs.





