git.giacomolli.uk - onechat/blob - README.rst

   1 #########
   2  OneChat
   3 #########
   4
   5 OneChat is one AI agent in a single chat that never ends. A daemon owns
   6 the agent and its memory, and you talk to it from a terminal client,
   7 Telegram, and through your WhatsApp chats. It is in early development.
   8 Linux is supported.
   9
  10 *******
  11  Setup
  12 *******
  13
  14 Data directory
  15 ==============
  16
  17 OneChat keeps all its data in one directory, with mode 0700. It uses
  18 ``ONECHAT_DIR`` when it is set, else ``$XDG_DATA_HOME/onechat``, else
  19 ``~/.local/share/onechat``. The development shell sets ``ONECHAT_DIR``
  20 to ``.devenv/onechat`` in the checkout.
  21
  22 Optional settings go in ``config.json`` in the data directory:
  23
  24 .. code:: json
  25
  26    {
  27      "endpoint": "chatgpt",
  28      "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
  29    }
  30
  31 ``endpoint`` is ``chatgpt`` (the ChatGPT subscription, the default) or
  32 ``api`` (the OpenAI API, with ``OPENAI_API_KEY`` set). ``compactor`` is
  33 the model and effort of the memory summaries.
  34
  35 Login
  36 =====
  37
  38 .. code:: console
  39
  40    onechat login
  41
  42 Open the link on any device and enter the code. Device code login must
  43 be allowed in the ChatGPT security settings. Do not share the login with
  44 the Codex CLI: each program logs the other out.
  45
  46 Telegram
  47 ========
  48
  49 #. Make a bot with BotFather and keep its token.
  50 #. Find your numeric Telegram user ID.
  51 #. Write both to ``telegram.json`` in the data directory, with mode
  52    0600:
  53
  54 .. code:: json
  55
  56    {"token": "123456:ABC-token-from-BotFather", "owner": 123456789}
  57
  58 Start the daemon and write to the bot in a private chat. It answers only
  59 you.
  60
  61 WhatsApp
  62 ========
  63
  64 Link your WhatsApp account as a linked device from the terminal client
  65 or Telegram:
  66
  67 ``/whatsapp pair PHONE``
  68    Gives a pairing code. On the phone, open Linked devices, Link a
  69    device, Link with phone number instead, and enter the code.
  70
  71 ``/whatsapp status``
  72    Shows the link and the routes of chats to child agents.
  73
  74 ``/whatsapp unlink``
  75    Ends the link.
  76
  77 The session file gives full access to the account. If it leaks, remove
  78 the device in Linked devices on the phone.
  79
  80 External events
  81 ===============
  82
  83 Use ``onechat notify --source CHECK --id EVENT --text TEXT`` to send
  84 external data to the root at its next turn. Success means accepted, not
  85 processed. See ``onechat notify --help`` for the local test limits.
  86
  87 User service
  88 ============
  89
  90 Run the daemon as a systemd user service. Keep the ``result-service``
  91 link, so that Nix keeps the package:
  92
  93 .. code:: console
  94
  95    nix build --out-link result-service
  96    systemctl --user link --force "$PWD/result-service/share/systemd/user/onechat.service"
  97    systemctl --user edit onechat.service
  98
  99 In the editor, set the data directory, and the tools that the agent may
 100 use in its shell:
 101
 102 .. code:: ini
 103
 104    [Service]
 105    Environment="ONECHAT_DIR=DATA_DIR"
 106    Environment="PATH=TOOLS_PATH"
 107
 108 Then start it, and let it run while you are logged out:
 109
 110 .. code:: console
 111
 112    systemctl --user daemon-reload
 113    systemctl --user enable --now onechat.service
 114    loginctl enable-linger "$USER"
 115
 116 After a ``git pull``, ``bin/service-update`` builds and restarts it.
 117 Never run two daemons on the same data.
 118
 119 Backups
 120 =======
 121
 122 .. code:: console
 123
 124    onechat backup BACKUP_DIR/onechat.tar.gz
 125    ONECHAT_DIR=EMPTY_DIR onechat restore BACKUP_DIR/onechat.tar.gz
 126
 127 A backup runs while the daemon runs. Restore needs a stopped daemon and
 128 an empty directory. **An archive holds your logins, the bot token, and
 129 the WhatsApp link**, so keep it private.
 130
 131 For a daily backup with the last 14 kept, save this script, with
 132 ``BACKUP_DIR`` replaced by a private directory outside the data
 133 directory:
 134
 135 .. code:: sh
 136
 137    #!/bin/sh
 138    set -eu
 139    umask 077
 140    cd BACKUP_DIR
 141    onechat backup "onechat-$(date +%F).tar.gz"
 142    ls -1 onechat-????-??-??.tar.gz | sort -r | tail -n +15 | xargs -r rm --
 143
 144 and run it from a ``Type=oneshot`` user service with the same
 145 ``ONECHAT_DIR`` and an ``OnCalendar=daily`` timer.
 146
 147 *********
 148  Talking
 149 *********
 150
 151 .. code:: console
 152
 153    onechat
 154
 155 ``onechat`` connects to the running daemon. Each line is a message, and
 156 replies show with Markdown styles and tables. These lines are commands:
 157
 158 ``/stop``
 159    Interrupts the running turn.
 160
 161 ``/stop NAME``
 162    Stops the subagent NAME.
 163
 164 ``/image PATH [caption]``
 165    Sends a JPEG, PNG, or WebP image. Quote a path with spaces.
 166
 167 ``/whatsapp ...``
 168    The WhatsApp commands above.
 169
 170 In Telegram, write as in the client, also with photos and image files.
 171 ``onechat help`` lists all commands.
 172
 173 *********************
 174  What the agent does
 175 *********************
 176
 177 Memory
 178    The agent remembers the whole chat as summaries that it can open
 179    again, so it never starts over. ``agent/instructions.md`` holds your
 180    lasting preferences. The agent can propose a change to it and makes
 181    the change only after you agree.
 182
 183 Tools
 184    The agent runs shell commands as you, in its working directory, with
 185    no sandbox.
 186
 187 Subagents
 188    For long tasks it starts subagents in the background, such as
 189    ``GreenOtter``, and gets their reports as messages.
 190
 191 Child agents
 192    A child is a permanent agent for one area of your life, such as
 193    ``House``, with its own memory. The root creates it, talks to it, and
 194    hears from it only what needs you. Children never send WhatsApp
 195    messages; they draft replies for you to approve.
 196
 197 WhatsApp
 198    The agent reads your chats in batches and wakes for a private message
 199    or a mention of you. It finds chats and sends messages only when you
 200    ask. It proposes to route a chat that is only about one area to the
 201    child of that area, and sets the route after you agree.
 202
 203 Images
 204    Send a photo in Telegram, WhatsApp, or with ``/image`` to the agent.
 205    Its memory keeps what the image shows, and it can look at an older
 206    image again. Ask it to show an image or send one to a WhatsApp chat.
 207
 208 Voice notes
 209    The agent hears Telegram and WhatsApp voice notes through local
 210    Whisper. Nix includes the small model. Outside Nix, set
 211    ``voice.model`` in ``config.json`` and install ``whisper-cli``.
 212    ``voice.transcriber`` selects another executable. No audio goes to a
 213    transcription service.
 214
 215 Schedules
 216    Ask for reminders and timed tasks, such as "every weekday at 8, tell
 217    me what my groups talked about". Each run uses the quota, so runs are
 218    at least 5 minutes apart.
 219
 220 Import
 221    Old WhatsApp chats can join the memory in date order. Stop the
 222    daemon, export the chat as a ZIP, and run the plan before the import.
 223    The import rebuilds the target's memory with model calls:
 224
 225 .. code:: console
 226
 227    onechat import -n [--agent NAME] CHAT.zip
 228    onechat import [--agent NAME] CHAT.zip
 229
 230 *****
 231  Log
 232 *****
 233
 234 The daemon writes short events with ``key=value`` attributes to the user
 235 journal, at three levels: info, warning for a failure that is retried or
 236 loses nothing, and error for a failure that loses data or stops work.
 237
 238 .. code:: console
 239
 240    journalctl --user -u onechat -f
 241    journalctl --user -u onechat -p warning
 242
 243 *************
 244  Development
 245 *************
 246
 247 Nix supplies the Go toolchain and all tools. Enter the development shell
 248 with ``direnv allow`` or ``nix develop``. Then:
 249
 250 .. code:: console
 251
 252    nix build
 253    ./result/bin/onechat version
 254    bin/format
 255    bin/check
 256    nix flake check
 257
 258 ``onechat version`` prints ``yyyy-mm-dd-gitshort`` for a Nix build and
 259 ``dev`` for a direct Go build. ``bin/check`` runs the linters and a
 260 short replay of a synthetic log, and ``nix flake check`` also runs the
 261 full replay of 100,000 messages. ``onechat probe LOG COUNT`` measures
 262 the memory summaries on a log with real model calls.