5 OneChat is one AI agent in a single chat that never ends. A daemon owns
6 the agent and its files, and a terminal client and a Telegram bot talk
7 to it. It is in early development. Linux is supported.
13 OneChat keeps its data and its token file in one directory. It uses the
16 #. ``ONECHAT_DIR``, when it is set.
17 #. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute
18 path. A relative value is ignored.
19 #. ``~/.local/share/onechat``. With no home directory, OneChat exits
22 OneChat creates the directory with mode 0700.
28 ``config.json`` in the data directory holds the settings. OneChat does
29 not create it. A missing file or field takes the default, and an unknown
35 "endpoint": "chatgpt",
36 "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
40 ``chatgpt`` (the default) sends model calls to the ChatGPT backend
41 with the subscription login. ``api`` sends them to the OpenAI API
42 with the key in ``OPENAI_API_KEY``, which must then be set. With
43 ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``.
46 The model and the reasoning effort of the summaries. The defaults are
47 ``gpt-6.1-sol`` and ``high``.
53 The ``chatgpt`` endpoint needs a login with a ChatGPT account:
59 The command shows a link and a code. Open the link on any device, enter
60 the code, and approve the login. Device code login must be allowed in
61 the ChatGPT security settings. OneChat writes the tokens to
62 ``auth.json`` in the data directory, with mode 0600, and refreshes them
63 before they expire. The file belongs to OneChat only. Do not share it
64 with the Codex CLI, because each program rotates the refresh token and
71 Start the daemon, and then the client in another terminal:
78 ``onechat`` with no command is the same as ``onechat chat``. ``onechat
79 help`` lists the commands.
81 The daemon owns the root agent in ``agent/`` in the data directory and
82 listens on the Unix socket ``onechat.sock`` there. In the client, each
83 line is a message to the agent, the line ``/stop`` interrupts the
84 running turn, the line ``/stop NAME`` stops the subagent NAME, and
85 Ctrl-D ends the client. On terminal output, the client shows ``> ``
86 after each event while idle and clears it before the next event. An
87 event can interrupt a line while the user types. The client shows the
88 replies, the tool calls, and the first lines of each tool result as they
89 happen. Replies and subagent reports render Markdown with styles and
90 wrapped tables only when the output is a terminal, and stay unchanged in
91 a pipe or file. It also shows each message that the user sends from
92 another client, with the client as a mark, such as ``[telegram] text``.
93 When a subagent starts, the client shows ``[NAME] started``, and it
94 shows the whole report of the subagent, which starts with ``[NAME]``,
95 but not the tool calls of the subagent. The daemon is the only process
96 that uses the token file while it runs, so ``onechat login`` and
97 ``onechat probe`` refuse to start until it stops.
99 The agent runs commands with bash as the user in its working directory,
100 with no sandbox. It has the rights of the user, also on the token file.
102 When the user asks for it, the agent starts subagents for long tasks.
103 Each subagent has a name, such as ``GreenOtter``, and runs in the
104 background while the agent answers other messages. It gets the view of
105 the agent and its task, and it runs its tools as the agent does, in
106 ``agent/subagents/NAME/work``. A task in a repository gives the path of
107 the repository. The steps of a subagent go to its own log in
108 ``agent/subagents/NAME``, not to the chat, and its final reply comes
109 back to the agent as one message that starts with ``[NAME]``. The agent
110 can send a subagent more messages: a running subagent reads them between
111 its tool calls, and a finished one goes on from its log, and its reply
112 comes back in the same way. When the user stops a subagent, the chat
113 gets a note, and the report of the subagent is logged, but it starts no
114 turn. Each model call of a subagent has the name in the ``agent`` field
115 of ``agent/usage.jsonl``. ``agent/work.json`` holds the names of the
116 running subagents. A subagent that runs when the daemon stops goes on at
117 the next start: the chat gets the note that the daemon restarted, and
118 the subagent gets the same note and goes on from its log.
120 ``agent/config.json`` holds the settings of the agent. The first start
121 writes it with the defaults and a random ID. Do not change the ID: the
122 prompt cache key comes from it.
128 "id": "0123456789abcdef0123456789abcdef",
129 "model": "gpt-6.1-sol",
131 "workdir": "/home/user"
134 ``workdir`` is an absolute path, and its default is the home directory.
135 ``agent/instructions.md`` holds the user's instructions: who they are,
136 how their files are organized, and how they want work done. The prompt
137 ends with them, and a change applies at the next call. The agent can
138 propose a change to the file, and it makes the change only after the
141 A permanent child agent lives in ``agent/children/NAME/`` with the same
142 files as the root. Create its directory and ``config.json`` by hand
143 before startup. Use the root config fields with a separate random ID,
144 set ``name`` to ``NAME``, and add ``parent`` with the root name and
145 ``responsibility`` with the child's area. The daemon opens all children
146 at startup. A missing or invalid child config stops startup. Only one
147 level of children is supported.
149 Each child has its own memory, model client, usage file, subagents,
150 schedules, and turn loop. Its prompt limits work to its area, asks for
151 only reports that need the parent or the user, and permits an empty
152 reply. Children have no WhatsApp tools and draft replies instead of
153 sending them. Clients and WhatsApp still address only the root. A
154 child's saved schedules and subagents can resume at startup. The ready
155 log line lists the child names.
157 A message from a parent to its own child enters the child's log as
158 ``user`` and wakes it. A child's final reply reaches the parent as
159 ``work`` with the prefix ``[NAME] `` and wakes it. An empty reply sends
160 nothing. A busy recipient takes the message between tool calls or in its
161 next turn. ``agent/messages.json``, with mode 0600, keeps messages until
162 their recipient finishes its turn. A daemon stop preserves queued
163 messages and reports for the next start without a second log entry. An
164 interrupted turn can repeat its model calls and tools after restart.
165 Backups lock this queue with the agent files. No tools send messages
166 between parent and child agents yet.
172 The Nix package includes ``share/systemd/user/onechat.service``. It runs
173 ``onechat daemon`` from that package, starts at login when enabled, and
174 restarts 5 seconds after a failure. A stop sends SIGTERM to the daemon
175 and allows up to 120 seconds for cleanup. Its output goes to the user
176 journal. The service has the rights of the user, as the terminal daemon
179 Build a package with a separate result link. Keep this link so that Nix
180 does not collect the package while the service uses it:
184 nix build --out-link result-service
185 systemctl --user link --force "$PWD/result-service/share/systemd/user/onechat.service"
186 systemctl --user edit onechat.service
188 In the editor, set the data directory with this drop-in. Replace
189 ``DATA_DIR`` with an absolute path to the data directory. Set the same
190 ``ONECHAT_DIR`` for each terminal client. Without a drop-in, the data
191 directory rules above apply to the environment of the user manager, not
192 to the development shell.
197 Environment="ONECHAT_DIR=DATA_DIR"
199 The service does not read the environment of an open terminal. If the
200 agent needs tools from a shell, set ``Environment="PATH=TOOLS_PATH"`` in
201 the same drop-in, with ``TOOLS_PATH`` replaced by the complete search
202 path, including bash. For the API endpoint, use
203 ``EnvironmentFile=ENV_FILE``, with ``ENV_FILE`` replaced by an absolute
204 path to a mode 0600 file that sets ``OPENAI_API_KEY``. Keep secrets out
205 of the unit and Nix sources.
207 Use the existing data directory, or copy the development data before the
208 first service start. For a copy, first stop the terminal daemon with
209 Ctrl-C and wait for it to exit. Replace ``DATA_DIR`` below with a new,
210 empty destination. If the development shell uses a custom
211 ``ONECHAT_DIR``, replace ``.devenv/onechat`` with that source. Copy the
212 whole directory so that ``auth.json``, ``telegram.json``,
213 ``config.json``, ``agent/``, and ``whatsapp/`` stay together, including
214 the WhatsApp session and its database files. The copy preserves the file
215 modes and the source as a backup. Do not copy or use the same data from
220 install -d -m 0700 DATA_DIR
221 cp -a .devenv/onechat/. DATA_DIR/
223 After the terminal daemon exits and the data is ready, enable and start
228 systemctl --user daemon-reload
229 systemctl --user enable --now onechat.service
230 systemctl --user status onechat.service
231 ONECHAT_DIR=DATA_DIR ./result-service/bin/onechat
232 journalctl --user -u onechat.service -f
234 After a pull, update the package and unit with:
241 The script builds with the same ``result-service`` link, reloads the
242 user manager, and restarts the service only if it is active. The unit
243 link follows ``result-service``, so no new link is needed.
245 The service starts with the user manager at login, not at boot without a
246 login. To stop it, or also remove its start at login:
250 systemctl --user stop onechat.service
251 systemctl --user disable onechat.service
257 Back up the running daemon to one mode 0600 ``.tar.gz`` archive. The
258 command prints its path and size in bytes. With no daemon, it fails.
262 onechat backup BACKUP_FILE.tar.gz
263 ONECHAT_DIR=EMPTY_DATA_DIR onechat restore BACKUP_FILE.tar.gz
265 The daemon flushes memory and holds its write locks during the agent
266 copy. It also flushes and locks the child agents and all subagent logs.
267 It copies the WhatsApp session with SQLite ``VACUUM INTO``, not as raw
268 database files. It then compresses the copy and installs the archive
269 through a temporary file and a rename. Use a backup path outside the
272 The archive includes configuration, instructions, the log, tree,
273 indexes, views, layout, schedules, subagents, children, Telegram offset,
274 tokens, and WhatsApp state and session. It excludes sockets, lock files,
275 ``probe/``, and the ``agent-backup-*`` import copies. Links and special
276 files fail, rather than enter the archive. **The archive holds
277 secrets**, including login tokens, the Telegram bot token, and the
278 WhatsApp link. Keep it private. There is no encryption or remote copy.
280 Restore needs a stopped daemon and an empty destination. It checks the
281 token lock and validates the archive before it installs files, with
282 their modes. It rejects unsafe paths, links, and special files. A failed
283 restore can leave ``auth.lock`` in the destination. Use another empty
284 directory for a retry. Do not run the source and restored WhatsApp links
285 at the same time. Check the restored log and view before you use it in
288 For a daily local archive with the last 14 kept, save this script as
289 ``BACKUP_SCRIPT``. Replace ``BACKUP_DIR`` with a private archive
290 directory outside the data directory. Replace ``ONECHAT_BINARY`` with
291 the absolute path through the stable ``result-service/bin/onechat``
292 package link. Make the archive directory with mode 0700 before you
301 ONECHAT_BINARY backup "onechat-$(date +%F).tar.gz"
302 find . -maxdepth 1 -type f -name 'onechat-????-??-??.tar.gz' -printf '%f\n' |
303 sort -r | tail -n +15 |
304 while IFS= read -r file; do
308 Save these units as ``onechat-backup.service`` and
309 ``onechat-backup.timer`` in the systemd user unit directory. Replace
310 ``DATA_DIR`` and ``BACKUP_SCRIPT`` with absolute paths. The service uses
311 the daemon unit from User service above.
316 Description=Back up OneChat data
317 Requires=onechat.service
318 After=onechat.service
322 Environment="ONECHAT_DIR=DATA_DIR"
324 ExecStart=/bin/sh BACKUP_SCRIPT
329 Description=Back up OneChat each day
336 WantedBy=timers.target
338 Enable the timer with the user manager. A failed backup leaves the
339 existing archives in place and skips removal of old archives.
343 systemctl --user daemon-reload
344 systemctl --user enable --now onechat-backup.timer
345 systemctl --user list-timers onechat-backup.timer
351 The daemon writes short events with the part prefix and ordered
352 ``key=value`` attributes. An error cause comes last. Normal events use
353 info, failures that can be retried or lose nothing use warning, and
354 failures that lose data or stop work use error.
356 With ``JOURNAL_STREAM`` set, each line carries a syslog priority without
357 a time stamp or level word. The user journal can show only warnings and
362 journalctl --user -u onechat -p warning
364 The summary warning names its node. A schedule run has ``late`` only
369 <4>onechat: summary failed level=0 index=0: fake failure
370 <6>onechat: schedule ran id=1
371 <6>onechat: schedule ran id=2 late=1m0s
373 Outside the journal, each line starts with the time stamp and level.
379 The daemon also connects the agent to a Telegram bot when
380 ``telegram.json`` exists in the data directory. It polls the Bot API for
381 new messages, so it needs no open port.
383 #. Make a bot with BotFather and keep its token.
385 #. Find your numeric Telegram user ID.
387 #. Write the token and the ID to ``telegram.json``, and give the file
388 mode 0600, because the token is a secret. The daemon refuses the file
391 #. Start the daemon, open a private chat with the bot, and write.
395 {"token": "123456:ABC-token-from-BotFather", "owner": 123456789}
397 The bot reads only the private chat of the owner and ignores all other
398 updates. Each text message goes to the agent as a user message, the line
399 ``/stop`` interrupts the running turn, and the line ``/stop NAME`` stops
400 the subagent NAME. The bot sends the replies in parts of at most 4096
401 characters, with their Markdown as Telegram formats: bold, italic,
402 strikethrough, code, code blocks, links, and headings as bold text. When
403 Telegram refuses the formats of a part, the bot sends the part again as
404 plain text. Each error goes as a short message in plain text. It shows
405 the typing action while a turn runs. It does not send the tool calls.
406 For a subagent it sends only ``[NAME] started`` and ``[NAME] finished``,
407 ``[NAME] stopped``, or ``[NAME] failed``, because the reply of the agent
408 carries the content of the report. It sends each message that the user
409 types in the terminal client, with the mark ``[terminal]``.
411 ``agent/telegram-offset.json`` holds the ID of the next update. The bot
412 moves it past an update only after the message is durable in the log, so
413 a restart of the daemon does not lose a message. A crash just after the
414 write of a message can make the message repeat once. A network failure
415 or a rate limit makes the bot wait and try again, and does not stop the
422 The daemon connects to the WhatsApp account of the user as a linked
423 device. The terminal client and Telegram take three commands:
425 ``/whatsapp pair PHONE``
426 Links the account of PHONE, the number with its country code, such as
427 ``+15550001111``. The daemon answers with the steps and then with a
428 pairing code in its own message: in WhatsApp on the phone, open
429 Linked devices, tap Link a device, then tap Link with phone number
430 instead, and enter the code. The code expires in about 2 minutes, and
431 the same command gives a new code. When the link succeeds, the daemon
432 answers with the linked number. Linked devices on the phone shows the
433 device as OneChat. The name applies at the pairing, so an existing
434 link keeps its old name until ``/whatsapp unlink`` and a new
435 ``/whatsapp pair PHONE``.
438 Shows the link: not linked, linked and connected, or linked and
439 disconnected, with the times of the connection.
442 Ends the link and deletes the session. When WhatsApp is disconnected,
443 the phone does not get the logout, so remove the device in Linked
444 devices on the phone.
446 The answers go only to the client that asked, and the commands do not go
447 to the agent, so the agent never gets the phone number or the code. The
448 chat gets only the notes that WhatsApp is linked or unlinked.
450 The session is ``whatsapp/session.db`` in the data directory, with mode
451 0600 in a directory with mode 0700. It gives full access to the WhatsApp
452 account, so the daemon refuses the file when its mode is not 0600. The
453 shell of the agent runs as the user, so it can read the session. If the
454 session leaks, remove the linked device in WhatsApp on the phone, and
455 the session stops working. Without the file, WhatsApp is not linked.
457 The daemon reads the text messages of the private chats and the groups,
458 from other people and from the user. It does not read media, reactions,
459 edits, deletions, view-once and disappearing messages, or the history
460 from before the link. The messages of one chat form one batch until the
461 chat is quiet for 20 seconds, for 2 minutes or 50 messages at the most.
462 Each batch goes to the chat of the agent as one work message that starts
463 with ``[WhatsApp]``, with the name and the ID of the chat, and the time,
464 the sender, and the text of each message. The messages of the user show
465 as ``You``. ``whatsapp/state.json``, with mode 0600, keeps the batches
466 that are not in the chat yet, so they survive a restart, and the records
467 of the sends. A crash just after a batch goes to the chat can make the
470 A batch of a private chat with a message of another person starts a
471 turn, and so does a batch of a group with a message that mentions the
472 user or replies to a message of the user. The other batches go to the
473 chat with no turn, and the agent sees them at its next turn. A batch
474 that starts a turn ends with a line that tells the agent to end its turn
475 with an empty reply when nothing in the batch needs the user. No client
476 shows an empty reply, so such a batch gives no message in Telegram. The
477 terminal client shows each batch, and Telegram shows none.
479 The phone number of the user never goes to the chat: a mention of the
480 user shows as ``@you``, the number shows as ``OWN``, and the chat of the
481 user with itself is not read. But the IDs of the other chats go to the
482 chat and to the model, because the agent needs them to send. The ID of a
483 private chat holds the phone number of the contact, such as
484 ``15550002222@s.whatsapp.net``, and the ID of a group can hold the
485 number of the person who made it.
487 While the daemon is stopped or disconnected, the WhatsApp servers keep
488 the messages for the linked device and send them at the next connection.
489 They keep them only for a limited time, so a long stop can lose
490 messages. These messages form batches by their original times, as live
491 messages do. The daemon waits for the end of this catch-up, or one
492 minute at the most, and then gives all its batches to the agent in one
493 turn, not one turn for each chat. The batches of ``whatsapp/state.json``
494 at the start wait for the first catch-up in the same way.
496 The agent finds a chat with the tool ``whatsapp_find``: it gives the
497 contacts and the groups whose name holds a text, with no regard to case
498 and accents, with their IDs. The names of the contacts come from the
499 session, and the names of the groups from WhatsApp, kept in memory for
500 one hour. The names arrive from the phone some minutes after the link,
501 and until then the tool says that they are not ready. The agent sends a
502 text message with the tool ``whatsapp_send``, only when the user asks
503 for it. Each send has an ID that the agent gives: a repeated call with
504 the same ID gives the answer of the first call and sends nothing. The
505 state file keeps the last 1000 send records. When the daemon stops
506 during a send, the result is not known, and the tool tells the agent to
507 ask the user to look at the chat in WhatsApp. Without a link, both tools
508 tell the agent to ask the user to run ``/whatsapp pair PHONE``. Only the
509 agent has the WhatsApp tools, not its subagents.
511 Each batch of a group goes to the chat, also with no turn, and the
512 memory tree summarizes it with model calls, which use the quota.
514 When the session holds a linked device, the daemon connects at its
515 start. If the first connection fails, it tries again after 2 seconds,
516 then doubles the wait up to 5 minutes. The inbox and commands stay
517 active during each wait. An unlink or a logout stops these retries.
518 After a network failure of an open connection, the library connects
519 again by itself. When a disconnection lasts 10 minutes, all clients get
520 one notice, and one more when the connection comes back. When WhatsApp
521 ends the connection for good, for example because another program uses
522 the same session, all clients get a notice at once. When the user
523 removes the device in the phone, the daemon deletes the session and
524 tells all clients one time.
526 *************************
527 Import WhatsApp history
528 *************************
530 Stop the daemon and finish all subagents before an import. Export each
531 chat from WhatsApp as a ZIP with ``_chat.txt``. Keep the chat name in
532 the ZIP name, such as ``WhatsApp Chat - Example.zip``. Read the plan
537 onechat import -n CHAT.zip OTHER.zip
538 onechat import CHAT.zip OTHER.zip
540 ``-n`` makes no model call and prints the chats, chat-day batches, local
541 dates, cutoff, text bytes, merged message count, and estimated calls.
542 The import keeps multiline text, system lines, and omitted-media
543 markers. It maps the session's profile name to ``You``. Without that
544 name, it keeps the senders as written and says so in the plan. An exact,
545 unambiguous local contact or batch name supplies the chat ID when known.
546 No network lookup is made.
548 Each chat and local day becomes one work message marked ``(imported)``.
549 Only messages before the first message of the earliest live WhatsApp
550 batch enter the import. Live times have minute precision, so the cutoff
551 excludes that whole minute. A chat-day already imported is skipped.
552 Overlapping chat-days in the supplied ZIPs are refused. Review the
553 exports before import: their text goes to the model as chat history.
555 The import merges the full log in date order and builds its tree with
556 real compactor calls, the agent prompt, and the agent cache key. It uses
557 a limit of 1,500 calls and the probe's 15-quota-point limit, and prints
558 the same usage report. Its estimate is about 1.3 calls per merged
559 message, not a cost guarantee. A stopped or failed run leaves the agent
560 unchanged. A new run starts over. Success keeps the other agent files
561 and renames the old directory to ``agent-backup-TIMESTAMP`` before it
562 installs the new one. Keep the backup until the new memory is checked,
563 then start the daemon. Message IDs change to their positions in the
570 The agent sets reminders and timed tasks when the user asks for them,
571 such as "remind me tomorrow at 9" or "every weekday at 8, tell me what
572 my WhatsApp groups talked about". A schedule has a text, the task for
573 the agent, and either one time or a cron expression. The agent also
574 lists the schedules with their next times, and removes one when the user
575 asks. Only the agent has the schedule tools, not its subagents.
577 A cron expression has five fields: minute, hour, day of month, month,
578 and day of week, where 0 and 7 are Sunday. A field is a comma list of
579 ``*``, ``N``, and ``N-M``, and ``*`` and ``N-M`` can have a step ``/S``,
580 as in ``0 8 * * 1-5`` or ``*/15 9-17 * * *``. When both day fields start
581 with something other than ``*``, a day matches when either field
582 matches. Names such as ``MON``, macros such as ``@daily``, the
583 characters ``? L W #``, and ``N/S`` are refused. The runs must be at
584 least 5 minutes apart, because each run is a full turn that uses the
585 quota, so ``*/5 * * * *`` is the shortest schedule.
587 The times use the time zone of the machine. A time that the clock skips
588 at the start of daylight saving time runs later by the length of the
589 skip. A time that the clock repeats at its end runs once, at its first
592 At its time, a schedule goes to the chat as a work message that starts
593 with ``[Schedule ID]``, with its time and its text, and it starts a
594 turn. The message ends with a line that tells the agent to end its turn
595 with an empty reply when nothing needs the user. The terminal client
596 shows the message, and Telegram shows only the reply. After its run, a
597 one-time schedule goes, and a repeating schedule gets its next time.
599 ``agent/schedules.json``, with mode 0600, holds the schedules. Each
600 change writes it before the tool answers, so the schedules survive a
601 restart. A schedule that came due while the daemon was stopped runs once
602 at the next start, with its original time and a line that says that the
603 run is late. A repeating schedule that missed several times runs once. A
604 crash just after a run goes to the chat can make the run repeat once.
610 ``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
611 appends the first COUNT messages of LOG, one JSON object ``{"kind",
612 "text"}`` on each line, to a new chat in ``probe/`` in the data
613 directory, and builds its tree with real model calls. The calls use the
614 quota of the account. The run stops at the first failed call, after 660
615 calls, or when the used percent of a quota window grows by more than 15
616 points. At the end it reports the calls per message, the cached share of
617 the input tokens, the retries, the line sizes, and the quota at the
618 first and the last call. BUILDS, from 1 to 8, limits the model calls at
621 A test writes a generated log of readable made-up messages:
625 ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
631 Nix supplies the Go toolchain and all tools. Enter the development shell
638 Or enter it directly:
644 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
645 unless it is already set. Development data goes there, and Git ignores
655 ``onechat version`` prints ``yyyy-mm-dd-gitshort`` for a Nix build, adds
656 ``-dirty`` for a dirty tree, and prints ``dev`` for a direct Go build.
658 Format and check all files:
666 ``bin/check`` and ``nix build`` run a short replay of the synthetic log.
667 ``nix flake check`` also runs the full replay of 100,000 messages.
projects / onechat / blob