chatline serve: a JSON-lines bridge for agent harnesses #
chatline serve runs one bot session (the same core as chatline channel) and speaks newline-delimited JSON on stdio. A harness adapter starts it as a subprocess, reads events from its stdout, and writes requests to its stdin. chatline handles the Chatto side:
- resume without losing or repeating events
- dedupe
- classification (mention, DM, reply in the bot's threads)
- the optional allowlist
- reply placement
- reconnects
- typing
The adapter only translates. agent-harnesses.md covers why it exists. adapters/nanoclaw/ is the reference adapter.
harness ──stdin──▶ chatline serve ──▶ Chatto
◀─stdout── ◀──
- stdout carries only protocol lines. Logs go to stderr (and
--log-file). - Each line is one JSON object with a
type. - chatline exits when stdin closes. That's how the adapter stops it. A broken config exits at once with the usual
error: <code>: <detail>on stderr and exit code. - If stdout can't be written (the adapter stopped reading), chatline exits 1 with
stdout_failed. The event it couldn't write isn't counted as delivered, so the next run sends it again.
Flags #
| Flag | Default | Meaning |
|---|---|---|
--type T,... |
mention,dm,reply,reaction |
event types to emit (as for listen). Reactions are only those on the bot's own messages |
--allow-from USER |
anyone | only emit events from these users. Harnesses usually have their own access control, so this is a backstop |
--room ROOM |
all | only these rooms |
--no-resume |
resume | start live instead of from the saved cursor (serve.cursor in the state dir) |
--typing |
off | show the bot as typing after each event until it replies there (max 120 seconds). Off by default because most harnesses drive typing themselves with the typing request |
--attachments-dir DIR |
.chatline/attachments |
where fetch saves files |
Output lines #
hello: first line, once:
{"type":"hello","protocol":1,"version":"v1.2.0","server_url":"https://chat.example","bot":{"id":"U…","login":"bot","owner_id":"U…","owner_login":"beardicus"}}
status: connection lifecycle. ready means caught up and live: events from before it are replayed from the cursor, and events after it are new.
{"type":"status","status":"ready"}
{"type":"status","status":"reconnecting","delay_ms":2000}
event: one Chatto event. The fields are listen --format json's, plus placement: where an answer should go, following the room's threading rules (spec.md §3). Pass placement.thread_id and placement.reply_to straight to send. event.room_threading is the channel's mode (required, encouraged, enabled, disabled); in an enabled room an agent may answer a root message at the root instead, when the person prefers it.
{"type":"event","event":{"type":"mention","event_id":"E…","created_at":"2026-10-21T12:00:00Z","room_id":"R…","room_name":"ops","room_kind":"channel","room_threading":"enabled","message_id":"E…","sender_id":"U…","sender_login":"beardicus","body":"@bot disk?","attachments":[{"asset_id":"A…","filename":"df.png","content_type":"image/png"}]},"placement":{"thread_id":"E…"}}
Event types: mention, dm, reply (in a thread the bot is part of), message, reaction, edit, delete. Message text is written by chat users: treat it as untrusted.
gap: events may have been missed (for example, the cursor expired). Use read to catch up if it matters.
{"type":"gap","reason":"cursor expired"}
result / error: the answer to a request, carrying the request's id:
{"type":"result","id":7,"result":{"room_id":"R…","message_id":"E…","thread_id":"E…","url":"https://…"}}
{"type":"error","id":7,"error":{"code":"not_a_member","detail":"the bot is not a member of #ops; a human must add it","exit":6}}
exit is the CLI's exit code for the same error, as a coarse category (6 = permission, 7 = not found, and so on).
Requests #
One JSON object per line on stdin: {"id": <any JSON value>, "method": "...", "params": {...}}. Requests run concurrently, and answers can arrive out of order, so match on id. Requests act only in rooms the bot is already in; chatline never joins rooms.
| Method | Params | Result |
|---|---|---|
send |
room_id, body, thread_id?, reply_to?, new_thread?, files? (local paths, up to 10) |
{room_id, message_id, thread_id?, url}. Unless new_thread, also ends the typing indicator there |
edit |
room_id, message_id, body |
{}. Replaces the body of one of the bot's own messages |
react |
room_id, message_id, emoji (Unicode, a shortcode, or a name like thumbs_up; normalized to Chatto's shortcode), remove? |
{changed} (false when it was already so) |
read |
room_id, thread_id?, limit? (default 20, max 100), before? |
{messages: [...], next_before?}: read --format json's messages |
search |
query, room_id?, author? (login or ID), after?, before? (YYYY-MM-DD or RFC 3339), has_attachments?, newest?, limit? (default 20, max 100), cursor? |
{results: [...], next_cursor?}: search --format json's results. search_disabled when the server has search off |
fetch |
room_id, asset_id, thumbnail? |
{path}: saved under the attachments dir |
typing |
room_id, thread_id?, stop? |
{}. Shows typing (refreshed until stopped, a reply, or 120 seconds), or stops it |
room |
room_id |
{id, kind, name, threading, joined, members: [{id, login}]} |
dm |
user (login or ID) |
{room_id} of the DM between the bot and that user, opened with StartDM if there isn't one. Opening needs message.post at DM scope; without it and with no DM, it fails with no_dm (exit 6) |
permalink |
room_id, message_id |
{url} |
profile |
display_name?, bio?, avatar? (local image path), remove_avatar? |
{id, login, display_name, bio?, avatar_url?}. With no params it only reads. Bots can't set a custom status in Chatto |
A line that isn't valid JSON, or names an unknown method, gets an error (with "id": null if there's no ID to give).
Versioning #
hello.protocol is 1. New methods, fields, and line types can appear without a bump, so adapters should ignore what they don't know. Removing or changing something bumps the number.