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.

6 to 8 min read • View on GitHub • More from fujibee

A single SQLite file sits at the center of a desk like a tiny post office. Several CLI terminal windows surround it and pass messages into and out of the file as if it were a shared inbox. The image explains how agmsg turns one local database into a coordination hub for multiple agents.
agmsg makes the database itself feel like the bus, not just the storage.
Key Takeaways

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

ぷーじ, yug1224 · @yug1224 on X

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.

ApproachSetup overheadLocal-firstConcurrency handlingAgent-friendly UXNetwork dependency
agmsg with SQLiteLowYesWAL plus file locksHighNo
Redis or NATS brokerMedium to highSometimesStrong, but externalMediumUsually yes
Daemon-based orchestrationHighSometimesDepends on serviceMediumOften yes
Ad hoc shell pollingLowYesWeakLowNo

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.

The watcher is doing the work that a daemon would normally do, but it stays local, finite, and easy to reason about.

A close-up technical scene shows a moving high-water mark on a gauge, with new message rows appearing only beyond the line. A small lock gate blocks one inbox lane while another lane stays open. The image explains how polling, state tracking, and role exclusivity combine into a push-like experience.
The watcher loop only delivers what is new, and the lock gate decides who gets to see it.

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

SystemBest atTradeoff
agmsgLocal agent coordinationNot built for networked scale
Redis or NATSHigh-throughput messagingRequires a separate service
Traditional agent frameworksWorkflow orchestrationMore opinionated and heavier
Shell polling aloneTiny scriptsWeak 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.