chatmux

Local-first personal chat data layer daemon. Connects IM platforms (v0.1: LINE) via child-process adapters, stores messages to JSONL + SQLite/FTS5, exposes MCP tools for AI clients.

The three repos

chatmux is the core. Platforms plug in below it, consumers sit above it, and both sides of that boundary live in their own repos:

Adapters speak the adapter protocol; consumers speak MCP. Either side can be replaced without touching the other.

Quickstart

1. Install

git clone https://github.com/echoedinvoker/chatmux.git
cd chatmux
bun install

2. Decide whether to connect an account yet

With no adapters.json, bun run start launches the LINE adapter, which means step 3 puts your LINE account on the line — read Account Risk Warning before you run it. If you would rather look around first, start with no adapter at all:

mkdir -p ~/.local/share/chatmux
cat > ~/.local/share/chatmux/adapters.json <<'JSON'
{
  "adapters": [],
  "mcp": { "port": 7717 }
}
JSON
bun run start

The daemon comes up with storage and the full MCP interface — you can initialize, list tools, and read resources. There is simply no chat data behind them until an adapter is connected. Set CHATMUX_DATA_DIR to keep this trial run out of your real data directory:

CHATMUX_DATA_DIR=/tmp/chatmux-trial bun run start

Each entry in adapters takes platform, a command string, and an args array (plus optional cwd and env):

{ "platform": "telegram", "command": "python", "args": ["-m", "chatmux_adapter_telegram"] }

For Telegram, follow the setup in chatmux-adapter-telegram — it has its own credentials and login flow, and does not involve LINE.

3. First login (QR code)

bun run start
# A QR code will appear in the terminal
# Open LINE on your phone → open the QR scanner → scan
#   iOS:     Home → the scan icon
#   Android: Home → Add friends → QR code
# After successful login, authToken is saved for future auto-login

4. Connect Claude Code

Register the daemon's MCP endpoint with Claude Code:

claude mcp add --transport http chatmux http://127.0.0.1:7717/mcp
claude mcp list   # chatmux: ... - ✔ Connected

The daemon listens on two transports at once: a TCP port on 127.0.0.1 (default 7717) for standard MCP clients like Claude Code, and a unix socket for same-host sidecar consumers like chat.nvim. Use the TCP url for Claude Code — the MCP spec only defines stdio and streamable HTTP transports, so no MCP client accepts a unix socket path.

Port is configurable via CHATMUX_MCP_PORT, or mcp.port in adapters.json; set it to 0 to disable the TCP listener. See docs/mcp-interface.md.

Architecture

LINE adapter ←── stdio JSON-RPC ──→ core daemon ←── MCP Streamable HTTP ──→ Claude Code
(Node+tsx)        (child process)    (Bun)         (127.0.0.1 TCP / unix)     (MCP client)
                                     ├─ SafetyRail
                                     ├─ Storage (JSONL → SQLite/FTS5)
                                     ├─ Adapter Runner
                                     └─ MCP Server

• Core daemon (Bun): central process managing storage, safety, and MCP server
• LINE adapter (Node+tsx): child process connecting to LINE via IOSIPAD slot
• Storage: JSONL append-only truth source + SQLite/FTS5 queryable view
• MCP server: Streamable HTTP over TCP (standard MCP clients; loopback by default, settable for containers) + unix socket (same-host sidecars), 8 tools + 4 resources

MCP Tools

MCP Resources

Writing a consumer

Core exposes primitives, not policy. Anything that decides what matters — which chats are worth surfacing, where a notification goes, when to stay quiet — belongs in a consumer, on the far side of the MCP boundary.

examples/notifier/ is a working reference: it tails the event log with a persisted cursor and hands each message to a hook you fill in. Its mcp-client.ts uses raw fetch rather than the TypeScript SDK, so it doubles as a wire-protocol reference for consumers in any language.

systemd Service

cp config/chatmux.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now chatmux

Edit WorkingDirectory to point at your clone before copying it.

How it comes back

The unit ships Restart=always, not on-failure. A chat backend is supposed to be there all day, and there are three ways it can stop being there — it crashes, something sends it a signal, or it exits cleanly — of which on-failure only recovers from the first. systemctl --user stop still stops it: a stop you asked for is not a failure, under either setting.

⚠️ If you are on an older unit with Restart=on-failure, kill -TERM will not bring it back — and that is not a missing restart policy. systemd counts SIGTERM, SIGHUP, SIGINT and SIGPIPE as an intended stop, so on-failure leaves the service sitting in inactive after any of them. Only kill -9 (SIGKILL) counts as a failure there.

With the Restart=always this unit now ships, TERM comes back too — measured 2026-08-02: kill -TERM $MainPID moved NRestarts 1 → 2 and produced a new MainPID within the 10s RestartSec. That makes TERM the useful test: kill -9 restarts under either setting, so it cannot tell you which one is in effect. If you want to confirm always is live, send TERM and watch systemctl --user show chatmux -p MainPID,NRestarts change.

StartLimitIntervalSec=300 / StartLimitBurst=5 cap a crash loop: five starts inside five minutes and systemd stops trying, leaving the unit failed for you to look at rather than restarting into the same wall forever. Clear it with systemctl --user reset-failed chatmux.

Containers

A systemd user service is the intended way to run chatmux. If you want it in a container instead, deploy/container/ is a reference that builds and answers — not an official image, and it runs zero adapters, because adapters hold logged-in sessions and a container you rebuild is the wrong home for those.

The one thing you cannot skip is CHATMUX_MCP_HOST. The daemon binds 127.0.0.1 by default, which inside a container is the container's own loopback — a published port then maps to a socket nobody is listening on, and every connection is refused while the logs look perfectly healthy. Read deploy/container/README.md before assuming your port mapping is broken.

Development

bun run dev     # Start with --watch (auto-reload)
bun test        # Run all tests
bun run start   # Start daemon

See docs/ for detailed architecture and protocol documentation.

Limitations

Known and accepted, with what would make each worth revisiting.