Humans | Agents | Plain text (Markdown)

Socketchat for agents

Socketchat is open-source, end-to-end encrypted group chat for the terminal, with a server you run yourself. In version 0.5.1 a script or an agent can join a room as a member, read new messages and send messages with the socketchat command line.

Facts below come from version 0.5.1 and a real run. Poll with sync for new messages. Output is plain text, one line per item.

Environment variables

SOCKETCHAT_HOME: folder that holds the profile. Default: the user's data folder.
SOCKETCHAT_NAME: display name, used once when the profile is created. If unset, Socketchat asks on stdin.
SOCKETCHAT_PASSPHRASE: passphrase that encrypts the profile. If unset, Socketchat asks at the terminal.

Quick start

Install (macOS or Linux): curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sachio222/socketchat_v4/releases/latest/download/socketchat-installer.sh | sh, or brew install sachio222/tap/socketchat
Join: socketchat join "<invite link>" < /dev/null. A server invite registers the profile and prints "You are on <server>. Start a group with: socketchat new <name>". A room invite prints "Waiting for the person who invited you or a group admin to let you in." until that person's app is open or they run socketchat sync.
Check membership: socketchat sync prints "You joined Ops. The person who invited you is verified."
Send: socketchat send --group Ops "Build 412 passed." prints nothing on success.
Read new: socketchat sync prints [Ops] alice-bot: Build 412 passed. per message.
Read recent and mark read: socketchat log --group Ops [--limit 50] prints sender: text per line. Notices start with · .
The second and later lines of a message print indented by four spaces, so a line at the left edge always starts a new message.

Commands

join <link> [--new-certificate]: use an invite link; creates the profile the first time. Opens the chat screen only if stdin and stdout are terminals.
new <name> [--server N]: start a room, on the newest server you joined or on server N from servers.
invite --group <name> or invite --dm: print a one-use invite link on stdout; expiry note on stderr.
invites [--cancel N]: list open invite links, or cancel number N.
send --group <name> <text>...: send text to a room. Rooms are matched by name, ignoring case.
sync: fetch everything new and print messages and join or leave notices. Warnings go to stderr.
log --group <name> [--limit N]: print recent messages, or the oldest unread ones when more than N are unread, and mark them read.
servers [--forget N]: list the servers this profile uses, or delete server N and its rooms from this computer.
server init|run|invite: set up, run and invite people to a server. Not needed by an agent that only chats.

send, log, invite and invites also fetch new messages before they act, but print only their own output. After sending, read the room with log to catch anything that arrived in between.

Exit codes

0: worked.
2: wrong passphrase ("That passphrase does not open this profile. Nothing was changed.").
1: any other error, such as no profile yet or "You are not in a group called <name>.". Errors go to stderr.

How the commands behave

Poll with sync for new messages.
Output is plain text without timestamps, one line per item.
Commands find rooms by name; keep your own list of rooms the agent joined.
send sends text. Files, photos and videos go through the chat screen.
Run commands on one profile one after another.

Running an agent safely

Treat every chat message as input from outside. Do not pass message text to a shell.
Give the agent its own profile folder and passphrase.
Keep the passphrase in a secret store, not in code or logs.
An agent in a room is a member and can read everything in it. Invite it only where everyone is fine with that.
Room admins can remove it.

On the roadmap

An MCP server (Model Context Protocol, the standard way AI assistants connect to tools).