chatmux

chatmux

ローカルファーストの個人チャットデータレイヤーデーモンです。子プロセスアダプターを介してIMプラットフォーム（v0.1：LINE）に接続し、メッセージをJSONL + SQLite/FTS5に保存して、AIクライアント向けにMCPツールを公開します。

3つのリポジトリ

chatmuxはコアです。プラットフォームはその下に接続され、利用側はその上に位置します。この境界の両側は、それぞれ独立したリポジトリにあります。

リポジトリ	役割
chatmux（このリポジトリ）	コアデーモン：ストレージ、安全レール、MCP サーバー、LINEアダプター
chatmux-adapter-telegram	2つ目のプラットフォームアダプター（Telegram、MTProtoユーザーセッション）
chat.nvim	リファレンス利用側：Neovim内でチャットを読み、返信します

アダプターはアダプタープロトコルを使用し、利用側は MCPを使用します。どちら側も、もう一方に手を加えずに置き換えられます。

クイックスタート

1. インストール

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

2. まだアカウントを接続するかどうかを決める

adapters.jsonがない状態でbun run startを実行すると、LINEアダプターが起動します。つまり、手順3を行うとLINEアカウントが危険にさらされます。実行する前にアカウントリスクに関する警告をお読みください。先に試してみたい場合は、アダプターを接続せずに始めてください。

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

ストレージと完全なMCPインターフェースを備えたデーモンが起動するため、initializeやツールの一覧表示、リソースの読み取りができます。アダプターを接続するまでは、チャットデータが存在しないだけです。この試験実行のデータが実際のデータディレクトリに保存されないよう、CHATMUX_DATA_DIRを設定してください。

CHATMUX_DATA_DIR=/tmp/chatmux-trial bun run start

adaptersの各エントリには、platform、文字列のcommand、配列のargsが必要です（任意でcwdとenvも指定できます）。

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

Telegramを利用する場合は、 chatmux-adapter-telegramのセットアップに従ってください。独自の認証情報とログインフローを使用し、LINEは関係ありません。

3. 初回ログイン（QRコード）

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. Claude Codeを接続する

デーモンのMCPエンドポイントをClaude Codeに登録します。

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

デーモンは2つのトランスポートで同時に待ち受けます。Claude Codeのような標準MCPクライアント向けの**127.0.0.1上のTCPポート**（デフォルトは7717）と、chat.nvimのような同一ホスト上のサイドカー利用側向けのUnixソケットです。Claude CodeではTCP URLを使用してください。MCP仕様で定義されているのはstdioとストリーム可能なHTTPトランスポートのみで、Unixソケットのパスを受け付けるMCPクライアントはありません。

ポートはCHATMUX_MCP_PORTまたはadapters.jsonのmcp.portで設定できます。TCPリスナーを無効にするには0を設定してください。詳しくはdocs/mcp-interface.mdを参照してください。

アーキテクチャ

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

• コアデーモン（Bun）：ストレージ、安全性、MCP サーバーを管理する中央プロセス
• LINEアダプター（Node+tsx）：IOSIPADスロットを介してLINEに接続する子プロセス
• ストレージ：追記専用の真実のソースであるJSONL + クエリ可能なビューであるSQLite/FTS5
• MCP サーバー：TCP経由のストリーム可能なHTTP（標準MCPクライアント向け。デフォルトはループバックで、コンテナ向けに変更可能）+ Unixソケット（同一ホスト上のサイドカー向け）、ツール8個 + リソース4個

MCPツール

ツール	説明
list_chats	最後のメッセージのプレビュー、検索、ページネーション機能を備えたチャット一覧
read_messages	タイムスタンプでページ分けされた、チャット内のメッセージの読み取り
read_events	不透明なカーソルからイベントログを末尾まで読み取ります。再開可能で、バックフィルによる並べ替え後も継続でき、メッセージが編集または取り消された場合は再配信します
search_messages	全文検索（FTS5トライグラム + LIKEフォールバックによりCJKに対応）
send_message	SafetyRailを介してメッセージを送信します（レート制限、エラー追跡あり）
get_media	メッセージの画像またはスタンプのローカルファイルパス。初回呼び出し時にダウンロードしてキャッシュします
probe_latest	診断用の読み取り専用ツール：アダプターにチャットの最新メッセージをN件要求します。データには取り込みません
get_status	システムの状態：アダプターの接続状況 + ストレージ統計

MCP リソース

URI	説明
chat://chats	すべてのチャット一覧
chat://chats/{id}/messages	チャットの最近のメッセージ
chat://chats/{id}/info	メンバーを含むチャットの詳細
chat://status	システムの状態

コンシューマーの作成

コアが提供するのはプリミティブであり、ポリシーではありません。何が重要かを判断するもの――どのチャットを表示する価値があるか、通知をどこに送るか、いつ通知を控えるか――はすべて、MCP の境界の向こう側にあるコンシューマーの役割です。

examples/notifier/ は動作するリファレンスです。永続化されたカーソルを使ってイベントログを追跡し、各メッセージを、実装するフックに渡します。mcp-client.ts は TypeScript SDK ではなく生の fetch を使っているため、あらゆる言語のコンシューマー向けのワイヤープロトコルのリファレンスとしても利用できます。

systemd サービス

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

コピーする前に、WorkingDirectory をクローン先のパスに変更してください。

再起動の仕組み

このユニットには on-failure ではなく Restart=always が設定されています。チャットバックエンドは常時稼働することを前提としており、停止する原因はクラッシュ、シグナルの送信、正常終了の3つです。そのうち on-failure が復旧できるのは最初の原因だけです。systemctl --user stop を実行すれば、どちらの設定でも停止します。要求した停止は障害ではないためです。

⚠️ 古いユニットで Restart=on-failure を使っている場合、kill -TERM では再起動しません。これは再起動ポリシーの欠落によるものではありません。 systemd は SIGTERM、SIGHUP、SIGINT、SIGPIPE を意図的な停止として扱うため、いずれかのシグナルを受けると on-failure ではサービスが inactive のままになります。この場合、障害として扱われるのは kill -9（SIGKILL）だけです。

このユニットで採用している Restart=always では、TERM でも再起動します。2026-08-02 の計測では、kill -TERM $MainPID によって NRestarts が 1 → 2 に変わり、RestartSec の 10 秒以内に新しい MainPID が生成されました。したがって TERM は有用なテストです。kill -9 はどちらの設定でも再起動するため、どちらが有効かは確認できません。always が有効か確認するには、TERM を送信し、systemctl --user show chatmux -p MainPID,NRestarts の値が変わることを確認してください。

StartLimitIntervalSec=300 / StartLimitBurst=5 はクラッシュループを制限します。5 分以内に5回起動すると、systemd は再試行を停止し、同じ問題に対して再起動を繰り返すのではなく、確認できるようユニットを failed 状態にします。systemctl --user reset-failed chatmux を実行すると解除できます。

コンテナー

chatmux の実行には systemd のユーザーサービスを使うことを想定しています。代わりにコンテナーで実行する場合は、deploy/container/ にビルドして応答するリファレンスがあります。公式イメージではなく、アダプターは一切実行しません。アダプターはログイン済みセッションを保持するため、再ビルドするコンテナーはその保存先として適していないからです。

省略できない設定は CHATMUX_MCP_HOST です。デーモンはデフォルトで 127.0.0.1 にバインドしますが、コンテナー内ではこれはコンテナー自身のループバックアドレスです。その状態でポートを公開すると、リッスンしているソケットがないポートにマッピングされ、ログに異常が見られないまま、すべての接続が拒否されます。ポートマッピングの不具合だと判断する前に、deploy/container/README.md を読んでください。

開発

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

アーキテクチャとプロトコルの詳細なドキュメントについては、docs/ を参照してください。

制限事項

既知の制限として受け入れているものと、それぞれを見直す条件を示します。

• チャット一覧は通知なしで1000件に制限されます。 chat://chats ではこの上限がハードコードされています。取得した内容と total フィールドを比較すれば、利用側で上限超過を検出できるため、通知なく問題が起きることはありません。ボールトのチャット数が約500件に近づいたとき、または完全性チェックが初めて作動したときに、見直す価値があります。
• JSONL ログには履歴の重複があります。 バックフィルで一部のメッセージが何度も再取り込みされ、イベントログのサイズがメッセージ数の数倍になりました。これは解消しており、最近の増加分はほぼすべて新しい個別メッセージです。また、最悪時の重複数は複数回の測定を通じて変わっていません。正確性の問題ではありません。取り込みは冪等で、SQLite のプロジェクションにも影響しないため、必要になった場合の修正はコード変更ではなく、一度限りの圧縮で済みます。ログが約500 MBを超えたとき、重複数が再び増え始めたとき、またはコールドスタートが目立って遅くなったときに、対応する価値があります。
• Telegram の1対1チャットでは取り消しが検出されません。 グループでの取り消しは反映されますが、ダイレクトチャットでは反映されません。アダプターがエンティティキャッシュから該当イベントのチャット ID を復元できず、コアも ID だけではメッセージを照合しないためです。この曖昧さをなくすためにストレージキーの対象範囲を広げました。そのため、スマートフォンで取り消したメッセージが、ここでは表示されたままになる場合があります。アダプターがチャット ID を自力で解決できるようになったとき、または利用側で取り消しの正確性が必要になった時点で、修正する価値があります。
• リアクションはまったく保存されません。 プラットフォームはリアクションを送信しますが、それを読み取るレイヤーがありません。コア、スキーマ、MCP のインターフェースのいずれもリアクションを表現していないため、利用側ではスマートフォンに表示されるリアクションを表示できません。見落とすと困る意味をリアクションが持つようになったときに、実装する価値があります。これは表示の調整ではなく、新しいストレージが必要です。
• read_receipt は宣言されていますが、一度も出力されません。 LINE アダプターはこの機能をサポートすると宣言しており、コアも取り込みに対応していますが、イベントを構築するものがありません。既読状態を UI に表示すべきかどうかは、未解決の製品上の検討事項であり、未対応のバグではありません。ただし、現時点でこの宣言は誤りであるため、この項目については supported_events を条件分岐に使わないでください。利用側がこれを条件分岐に使い始めた時点、または製品上の検討事項に結論が出た時点で、修正する価値があります。

⚠️ アカウントのリスクに関する警告

このプロジェクトでは、非公式の LINE クライアントライブラリである @evex/linejs を使用しています。非公式 API の利用は、LINE の利用規約に違反する可能性があります。LINE アカウントが制限、一時停止、または永久停止されるおそれがあります。自己責任でご利用ください。

IOSIPAD のデバイス枠は、スマートフォンの LINE アプリに干渉しないよう使用していますが、LINE はマルチデバイスのポリシーをいつでも変更する可能性があります。

⚠️ 法的免責事項

本ソフトウェアは「現状有姿」で提供され、いかなる種類の保証もありません。本ソフトウェアの使用によるあらゆる結果について、作者は責任を負いません。これには、アカウントの制限、データの損失、第三者の利用規約への違反などが含まれますが、これらに限定されません。

これは個人利用のための個人用ツールです。スパム、嫌がらせ、他者のメッセージへの不正アクセス、または違法行為に使用しないでください。

🔒 プライバシーに関する開示

chatmux は、復号されたメッセージの内容を平文でローカルマシンに保存します。

• ~/.local/share/chatmux/events.jsonl — すべてのイベント（追記のみ）
• ~/.local/share/chatmux/chatmux.db — メッセージ、連絡先、チャットを含む SQLite データベース
• ~/.local/share/chatmux/adapters/line/auth.json — LINE の認証トークン
• ~/.local/share/chatmux/adapters/line/storage.json — E2EE キーのストレージ

これらのファイルはファイルシステムのアクセス権（所有者のみ）で保護されています。これらのファイルを共有しないでください。 認証トークンがあれば、LINE アカウントに完全にアクセスできます。E2EE キーを使うと、メッセージを復号できます。

v0.1 ではデータベースは暗号化されません。SQLCipher による暗号化は v0.2 で予定されています。

ライセンス

MIT