- Go 97%
- TypeScript 3%
- Makefile <1%
- Shell <1%
- Astro <1%
chatline #
A command-line client for Chatto that connects agents and scripts with a single static Go binary. It acts as one Chatto bot, and has three parts:
- Commands and an agent skill. Give an agent the skill with
chatline bootstrap, and it can post, read, ask people questions, and wait for answers in Chatto. The commands work from scripts too. It's modelled on slackline:send,read,ask,run,listen,react,permalink,download,profile,rooms,users,search,bot,auth, andinit. - A Claude Code channel (
chatline channel), using Claude Code's channels feature. It pushes Chatto mentions, DMs, thread replies, and reactions into a running Claude Code session, so you can work with the session from Chatto. - A bridge for other agent harnesses (
chatline serve). It speaks JSON lines on stdio: events out, requests in. A harness adapter then only translates, and chatline handles resuming, dedupe, threads, and reconnects.
It works with Chatto servers from 0.5.0 on, and is built against 0.5.0. chatline auth status warns if the server is older than that minimum. The design is in docs/spec.md.
The full documentation is at beardicus.tngl.io/chatline.
Install #
Install the latest release with Homebrew:
brew install beardicus/tap/chatline
Or with Go 1.26 or newer:
go install tangled.org/beardic.us/chatline/cmd/chatline@latest
The binary lands in $(go env GOPATH)/bin (or $GOBIN, if set), which needs to be on your PATH.
Or download a release binary for Linux (amd64, arm64) or macOS (Apple silicon). The install script picks the right one, checks it against SHA256SUMS, and puts it in ~/.local/bin:
curl -fsSL https://tangled.org/beardic.us/chatline/raw/main/install.sh | sh
The binaries and SHA256SUMS are also on the v0.2.0 tag.
To build from a checkout of this repo instead:
make build # ./chatline
make dist # static linux/amd64, linux/arm64, darwin/arm64 binaries + SHA256SUMS in dist/
Put the binary somewhere on your PATH, such as ~/.local/bin.
Set up a bot #
-
In Chatto, open App Preferences (the gear icon), then Bots under the Server heading. Create a bot, and copy its API key. Chatto shows it only once. Chatto's Bots & Webhooks guide has more on bot accounts.
-
Select the bot under Bot Accounts, then Permissions, and grant it permissions in the columns for the rooms it should use. Bots start with none. Typical grants:
message.read+message.post-in-interactionsto answer when spoken tomessage.postto start threadsmessage.reactmessage.attachfor files
-
Add the bot to the room: check the Joined row in the room's column, and confirm. chatline never joins rooms by itself. With
room.join,chatline rooms join ROOMworks. Joining by name also needsroom.list, because without it the bot can't see rooms it isn't in. -
For DMs, grant it
message.readandmessage.postat the Direct messages scope. With those,chatline send --room @loginopens a DM with that person, and people can DM the bot. -
Save the server and key.
initasks for the key without echoing it, checks it against the server, and writes~/.config/chatline/config.json(mode 0600). To keep the key out of that file, use one of the options after these steps instead.chatline init --server https://chatto.example -
Check the bot's identity and permissions:
chatline auth statusIt prints the bot, its owner, the server version, where the key came from, and the bot's permissions in each room.
perms nonemeans step 2 isn't done yet.
Keep the key out of the config file #
- A key file: write the key alone to a file only you can read, then run
chatline init --server https://chatto.example --key-file ~/.config/chatline/bot.key. The config saves only the file's path. - Environment variables:
CHATLINE_SERVER,CHATLINE_API_KEY, andCHATLINE_API_KEY_FILEoverride the config file, and work withoutinit.init --no-store-keychecks the key and saves only the server, for setups that injectCHATLINE_API_KEYat run time, such as 1Password'sop run.
Run multiple bots #
For multiple bots on one machine, give each its own config file with --config or CHATLINE_CONFIG=~/.config/chatline/BOT.json.
Give it to an agent #
With chatline set up, tell your agent:
Run "chatline bootstrap" and follow what it says.
bootstrap prints instructions for the agent, the bot's status, and the using-chatto skill. The agent saves the skill in its skills directory (~/.claude/skills/using-chatto/ for Claude Code) and tells you which bot it is. To install the skill yourself, save the output of chatline skill:
mkdir -p ~/.claude/skills/using-chatto
chatline skill > ~/.claude/skills/using-chatto/SKILL.md
Don't paste the API key into an agent's conversation: run init yourself.
Commands #
--room takes a room ID, name, or #name, or @login for a DM, which send, ask, and run open if need be. chatline COMMAND --help lists every flag.
| Task | Command |
|---|---|
| Check the bot's identity and permissions | chatline auth status |
| List the rooms the bot can see | chatline rooms [--joined] |
| Find a user | chatline users --match bear |
Post (body from -m, --message-file, or stdin) |
chatline send --room ops -m "deploy done" |
| Open a thread | chatline send --room ops --new-thread -m "status?" |
| Reply in a thread | chatline send --room ops --thread ROOT_ID -m "…" |
| Attach files | chatline send --room ops --file out.png -m "graph" |
| DM someone | chatline send --room @dana -m "your export is ready" |
Recent messages (with reactions=… per message) |
chatline read --room ops [--thread ID] [--limit 50] |
| Search past messages (the server must have search on) | chatline search disk full [--room ops] [--from dana] [--newest] |
| Ask a question and wait for the answer | chatline ask --room ops --from beardicus --timeout 10m -m "ok to restart?" |
| Run a command and post how it went | chatline run --room ops --on-failure -- ./backup.sh |
Stream events (types: mention, dm, reply, reaction by default; also message, edit, delete) |
chatline listen [--type mention,dm,reply,reaction] [--resume] |
| React | chatline react --room ops --message-id ID --emoji thumbsup [--remove] |
| Link to a message | chatline permalink --room ops --message-id ID |
| Show or change the bot's profile | chatline profile [--display-name NAME] [--bio TEXT] [--avatar face.png | --no-avatar] |
| Download an attachment | chatline download --room ops --asset ID [--out PATH|-] |
| Download only the inline preview | chatline download --room ops --asset ID --thumbnail (images fit to 960×400, or a video's poster frame) |
Create a bot, or manage bots' keys (needs bot.create or bot.manage) |
chatline bot create reportbot --save-key reportbot.key, chatline bot key create BOT NAME --save-key F |
Output conventions:
- Text output is compact and line-oriented, and safe for
while read -r. Add--format jsonfor JSON lines. - Status lines go to stderr.
listenandaskprintreadythere once they're live. sendprints<room_id> <message_id> <thread_id|->, so scripts can thread follow-ups.
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Server error not covered below, or a network failure |
| 2 | Invalid or revoked key |
| 3 | Missing or invalid config, no key, or an unreadable key file |
| 4 | Bad flags or arguments, or an ambiguous room name |
| 5 | Timed out, such as ask getting no reply |
| 6 | Permission denied: not a member, or a missing grant |
| 7 | Room, user, or message not found |
Errors are a single line on stderr, error: <code>: <detail>, or JSON with --format json.
if reply=$(chatline ask --room ops --from beardicus --timeout 5m -m "Restart nginx on storage?"); then
echo "got: $reply"
elif [ $? -eq 5 ]; then
echo "nobody answered"
fi
# Run the nightly backup from cron; post only if it fails, with the last
# 20 lines of output (and the full log attached if there was more) and a
# ping. The exit status is the backup's, and the backup runs even if Chatto
# is unreachable.
chatline run --room ops --on-failure --name "nightly backup" \
-m "@beardicus the backup failed" -- /usr/local/bin/backup.sh
# Answer each mention in its thread (thread_id, or the message itself if it's a root).
# Assumes rooms with threads enabled; `rooms` shows each room's threading mode.
chatline listen --type mention --format json | while read -r ev; do
room=$(printf '%s' "$ev" | jq -r .room_id)
thread=$(printf '%s' "$ev" | jq -r '.thread_id // .message_id')
chatline send --room "$room" --thread "$thread" -m "on it"
done
Claude Code channel #
Add chatline to the project's .mcp.json:
{ "mcpServers": { "chatline": { "command": "chatline", "args": ["channel"] } } }
Then start Claude Code:
claude --dangerously-load-development-channels server:chatline
How it works:
- Who can reach the session. Only events from the bot's owner get through by default. Use
--allow-from login,...to change that (orchannel.allow_fromin the config). Events from anyone else are dropped; withCHATLINE_LOG_LEVEL=info, each one is logged. - What reaches the session. By default: mentions, DMs, quote-replies to the bot and replies in its threads, and reactions on the bot's messages, so a 👍 can answer Claude's question. Plain room messages (
message), edits (edit), and deletes (delete) are opt-in. List the types you want, such as"args": ["channel", "--type", "mention,dm,reply,reaction,message"]in.mcp.json, or set"channel": {"types": [...]}in the config. Other people's messages still need--allow-from. - What Claude can do. It answers with the
replytool. It also hasreact,read(which shows each message's reactions),search,send,profile, andfetch_attachment. - Attachments.
fetch_attachmentsaves into.chatline/attachments/in the project Claude Code runs in, with a.gitignorein.chatline/(for this default directory only) so nothing gets committed. Files outside the project would make Claude stop on a permission prompt every time it opens one. Override the location with--attachments-dirorCHATLINE_ATTACHMENTS_DIRif you need to, but keep it inside the project. Withthumbnail: trueit fetches the small inline preview of an image or video instead. - What the user sees. While Claude works, the bot shows as typing in Chatto.
- Approving tools from your phone. With
--permission-relay, when Claude wants to run something that needs approval, the prompt also arrives in your DM with the bot, which it opens if need be. Answeryes abcdeorno abcdewith the five-letter ID from the prompt; chatline reacts ✅ or ❌ to show it passed your answer on. The terminal prompt stays open too, and the first answer wins. Only the bot's owner can approve, and only in that DM, whatever--allow-fromsays. - Restarts. Resume state is kept in
~/.local/state/chatline/PROFILE/(--state-dirorCHATLINE_STATE_DIRto move it), so a restart within 15 minutes misses nothing.PROFILEis the config file's name, such asconfig.
Limitations (Claude Code research preview):
- Custom channels need the
--dangerously-load-development-channelsflag. - Channels work in interactive sessions only, not
-p. - They need a claude.ai login or Console key. On Team or Enterprise plans, an owner must enable channels.
- If the session never shows chatline events, try
MCP_PROTOCOL_NEGOTIATION=legacyand checkclaude --debug. chatline already refuses the protocol revision that blocks channels.
Logs go to stderr; set CHATLINE_LOG_LEVEL=info|debug for more. Message bodies are never logged. Claude Code keeps the channel's stderr, so to watch a live session add "--log-file", "/tmp/chatline.log" to the args in .mcp.json (or set CHATLINE_LOG_FILE) and tail -f it.
Other harnesses #
chatline serve runs the same live session as the channel, but as a JSON-lines protocol any language can drive: events and results on stdout, requests (send, edit, react, read, search, fetch, typing, room, dm, permalink, profile) on stdin. It exits when stdin closes. The protocol is in docs/serve.md.
chatline serve --type mention,dm,reply,reaction
Update the Chatto pin #
chatline builds against a pinned copy of the Chatto protocol, and auth status doesn't warn about newer servers. Chatto 0.5 is still a release candidate, so after a server upgrade, move the pin and run the contract tests to check that the behavior chatline relies on still holds:
make vendor-proto TAG=vX.Y.Z CHATTO_REPO=/path/to/chatto
make proto && go build ./... && go test ./...
CHATLINE_IT_IMAGE=ghcr.io/chattocorp/chatto:X.Y.Z make test-contract # Chatto behavior chatline relies on
make test-integration
chatline auth status # warns if the server is older than the minimum supported version
The minimum server version is MinimumChattoVersion in internal/cli/auth.go, separate from the build pin in proto/CHATTO_VERSION: updating the generated client doesn't necessarily require a newer server.
Development #
The generated code is committed, so you only need buf when regenerating it (make proto). The test and eval targets:
make test # unit tests
make test-integration # starts a throwaway Chatto in Docker: real users and bots
make test-contract # only the Chatto contract tests (test/integration/chatto_contract_test.go)
make skill-evals # agents use the skill against a throwaway Chatto; costs Claude tokens (test/skill-evals)
make channel-evals # the same for the channel's tools and instructions
make sandbox # a throwaway Chatto on localhost:4000 with a login link and a bot config; CHATTO=VERSION to pick one
make docs-ref # regenerate the site's command reference from the help text
make site # build the docs site into site/dist
Licensing #
chatline is licensed under the Apache License 2.0, © 2026 Brian Boucheron. See NOTICE for what it includes from others:
- The protos under
proto/chatto/, and the Go code generated from them ingen/, are Apache-2.0, © 2026 ChattoCorp GmbH (seeproto/NOTICE). Only the Apache-2.0api,realtime, anddiscoverypackages are vendored; nothing from Chatto's AGPL code is used. - The NanoClaw adapter's test stand-ins include MIT-licensed code from NanoClaw (
adapters/nanoclaw/test/stubs/LICENSE.nanoclaw).