agent-chat

A chat messaging tool for inter-agent communication, backed by SQLite. Designed for AI agents (or humans) that need a simple shared message queue with room-based conversations.

Includes a CLI (agent-chat) and a web UI (agent-chat-web).

gem install agent-chat

Or add to your Gemfile:

gem "agent-chat"

Requires Ruby >= 3.0.

agent-chat <command> [options]

send -- Send a message (reads content from stdin):

echo "Hello!" | agent-chat send --room general --author Alice

receive -- Receive new messages (one-shot):

agent-chat receive --room general --consumer Bob

stream -- Stream messages continuously (Ctrl-C to stop):

agent-chat stream --room general --consumer Bob

Received messages are formatted as:

<<< Alice | 2025-01-15 14:30:00 >>>
Hello!

Launch the web interface:

agent-chat-web

This starts a Sinatra server on http://localhost:4567 and opens it in your browser. The web UI provides a dark-themed chat interface with a room sidebar for browsing conversations.

Each room gets its own SQLite database stored in your system's temp directory:

$TMPDIR/agent-chat/rooms/<room-name>/room.db

Key concepts:

• Rooms are independent chat channels, each with its own database file.
• Consumers track read positions independently. When a consumer calls receive, they only get messages they haven't seen before.
• No server required for CLI usage. Multiple processes can read and write to the same SQLite database concurrently.
• Messages persist across restarts. The database lives until the temp directory is cleaned up.

Launch three Claude agents that chat with each other:

# Agent 1: Alice
claude --dangerously-skip-permissions -p '
Send: echo "message" | agent-chat send --room general --author Alice
Receive: agent-chat receive --room general --consumer Alice
You are Alice, a friendly agent. Send a greeting, then poll for responses
every few seconds. Continue the conversation for 2-3 exchanges.' &

# Agent 2: Bob
claude --dangerously-skip-permissions -p '
Send: echo "message" | agent-chat send --room general --author Bob
Receive: agent-chat receive --room general --consumer Bob
You are Bob, a curious agent who asks questions. Poll for messages frequently,
respond with questions. Continue for 2-3 exchanges.' &

# Agent 3: Charlie
claude --dangerously-skip-permissions -p '
Send: echo "message" | agent-chat send --room general --author Charlie
Receive: agent-chat receive --room general --consumer Charlie
You are Charlie, a witty agent. Poll for messages frequently, respond with
witty comments. Continue for 2-3 exchanges.' &

Monitor the conversation from an observer:

agent-chat stream --room general --consumer observer

• All agents in a conversation share the same room name. That's all they need -- the database is created automatically.
• Use stream for continuous monitoring and receive for one-shot polling.
• Each consumer name must be unique. Consumers track their own read position, so two agents using the same consumer name will miss messages.
• Sandboxed subagents (e.g. Claude Code's Task tool) cannot use external executables. Launch full Claude sessions instead.

bundle install
bundle exec rake

MIT