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. There
154 are no messages or tools between parent and child agents. A child's
155 saved schedules and subagents can resume at startup. The ready log line
156 lists the child names.
162 The Nix package includes ``share/systemd/user/onechat.service``. It runs
163 ``onechat daemon`` from that package, starts at login when enabled, and
164 restarts 5 seconds after a failure. A stop sends SIGTERM to the daemon
165 and allows up to 120 seconds for cleanup. Its output goes to the user
166 journal. The service has the rights of the user, as the terminal daemon
169 Build a package with a separate result link. Keep this link so that Nix
170 does not collect the package while the service uses it:
174 nix build --out-link result-service
175 systemctl --user link --force "$PWD/result-service/share/systemd/user/onechat.service"
176 systemctl --user edit onechat.service
178 In the editor, set the data directory with this drop-in. Replace
179 ``DATA_DIR`` with an absolute path to the data directory. Set the same
180 ``ONECHAT_DIR`` for each terminal client. Without a drop-in, the data
181 directory rules above apply to the environment of the user manager, not
182 to the development shell.
187 Environment="ONECHAT_DIR=DATA_DIR"
189 The service does not read the environment of an open terminal. If the
190 agent needs tools from a shell, set ``Environment="PATH=TOOLS_PATH"`` in
191 the same drop-in, with ``TOOLS_PATH`` replaced by the complete search
192 path, including bash. For the API endpoint, use
193 ``EnvironmentFile=ENV_FILE``, with ``ENV_FILE`` replaced by an absolute
194 path to a mode 0600 file that sets ``OPENAI_API_KEY``. Keep secrets out
195 of the unit and Nix sources.
197 Use the existing data directory, or copy the development data before the
198 first service start. For a copy, first stop the terminal daemon with
199 Ctrl-C and wait for it to exit. Replace ``DATA_DIR`` below with a new,
200 empty destination. If the development shell uses a custom
201 ``ONECHAT_DIR``, replace ``.devenv/onechat`` with that source. Copy the
202 whole directory so that ``auth.json``, ``telegram.json``,
203 ``config.json``, ``agent/``, and ``whatsapp/`` stay together, including
204 the WhatsApp session and its database files. The copy preserves the file
205 modes and the source as a backup. Do not copy or use the same data from
210 install -d -m 0700 DATA_DIR
211 cp -a .devenv/onechat/. DATA_DIR/
213 After the terminal daemon exits and the data is ready, enable and start
218 systemctl --user daemon-reload
219 systemctl --user enable --now onechat.service
220 systemctl --user status onechat.service
221 ONECHAT_DIR=DATA_DIR ./result-service/bin/onechat
222 journalctl --user -u onechat.service -f
224 After a pull, update the package and unit with:
231 The script builds with the same ``result-service`` link, reloads the
232 user manager, and restarts the service only if it is active. The unit
233 link follows ``result-service``, so no new link is needed.
235 The service starts with the user manager at login, not at boot without a
236 login. To stop it, or also remove its start at login:
240 systemctl --user stop onechat.service
241 systemctl --user disable onechat.service
247 Back up the running daemon to one mode 0600 ``.tar.gz`` archive. The
248 command prints its path and size in bytes. With no daemon, it fails.
252 onechat backup BACKUP_FILE.tar.gz
253 ONECHAT_DIR=EMPTY_DATA_DIR onechat restore BACKUP_FILE.tar.gz
255 The daemon flushes memory and holds its write locks during the agent
256 copy. It also flushes and locks the child agents and all subagent logs.
257 It copies the WhatsApp session with SQLite ``VACUUM INTO``, not as raw
258 database files. It then compresses the copy and installs the archive
259 through a temporary file and a rename. Use a backup path outside the
262 The archive includes configuration, instructions, the log, tree,
263 indexes, views, layout, schedules, subagents, children, Telegram offset,
264 tokens, and WhatsApp state and session. It excludes sockets, lock files,
265 ``probe/``, and the ``agent-backup-*`` import copies. Links and special
266 files fail, rather than enter the archive. **The archive holds
267 secrets**, including login tokens, the Telegram bot token, and the
268 WhatsApp link. Keep it private. There is no encryption or remote copy.
270 Restore needs a stopped daemon and an empty destination. It checks the
271 token lock and validates the archive before it installs files, with
272 their modes. It rejects unsafe paths, links, and special files. A failed
273 restore can leave ``auth.lock`` in the destination. Use another empty
274 directory for a retry. Do not run the source and restored WhatsApp links
275 at the same time. Check the restored log and view before you use it in
278 For a daily local archive with the last 14 kept, save this script as
279 ``BACKUP_SCRIPT``. Replace ``BACKUP_DIR`` with a private archive
280 directory outside the data directory. Replace ``ONECHAT_BINARY`` with
281 the absolute path through the stable ``result-service/bin/onechat``
282 package link. Make the archive directory with mode 0700 before you
291 ONECHAT_BINARY backup "onechat-$(date +%F).tar.gz"
292 find . -maxdepth 1 -type f -name 'onechat-????-??-??.tar.gz' -printf '%f\n' |
293 sort -r | tail -n +15 |
294 while IFS= read -r file; do
298 Save these units as ``onechat-backup.service`` and
299 ``onechat-backup.timer`` in the systemd user unit directory. Replace
300 ``DATA_DIR`` and ``BACKUP_SCRIPT`` with absolute paths. The service uses
301 the daemon unit from User service above.
306 Description=Back up OneChat data
307 Requires=onechat.service
308 After=onechat.service
312 Environment="ONECHAT_DIR=DATA_DIR"
314 ExecStart=/bin/sh BACKUP_SCRIPT
319 Description=Back up OneChat each day
326 WantedBy=timers.target
328 Enable the timer with the user manager. A failed backup leaves the
329 existing archives in place and skips removal of old archives.
333 systemctl --user daemon-reload
334 systemctl --user enable --now onechat-backup.timer
335 systemctl --user list-timers onechat-backup.timer
341 The daemon writes short events with the part prefix and ordered
342 ``key=value`` attributes. An error cause comes last. Normal events use
343 info, failures that can be retried or lose nothing use warning, and
344 failures that lose data or stop work use error.
346 With ``JOURNAL_STREAM`` set, each line carries a syslog priority without
347 a time stamp or level word. The user journal can show only warnings and
352 journalctl --user -u onechat -p warning
354 The summary warning names its node. A schedule run has ``late`` only
359 <4>onechat: summary failed level=0 index=0: fake failure
360 <6>onechat: schedule ran id=1
361 <6>onechat: schedule ran id=2 late=1m0s
363 Outside the journal, each line starts with the time stamp and level.
369 The daemon also connects the agent to a Telegram bot when
370 ``telegram.json`` exists in the data directory. It polls the Bot API for
371 new messages, so it needs no open port.
373 #. Make a bot with BotFather and keep its token.
375 #. Find your numeric Telegram user ID.
377 #. Write the token and the ID to ``telegram.json``, and give the file
378 mode 0600, because the token is a secret. The daemon refuses the file
381 #. Start the daemon, open a private chat with the bot, and write.
385 {"token": "123456:ABC-token-from-BotFather", "owner": 123456789}
387 The bot reads only the private chat of the owner and ignores all other
388 updates. Each text message goes to the agent as a user message, the line
389 ``/stop`` interrupts the running turn, and the line ``/stop NAME`` stops
390 the subagent NAME. The bot sends the replies in parts of at most 4096
391 characters, with their Markdown as Telegram formats: bold, italic,
392 strikethrough, code, code blocks, links, and headings as bold text. When
393 Telegram refuses the formats of a part, the bot sends the part again as
394 plain text. Each error goes as a short message in plain text. It shows
395 the typing action while a turn runs. It does not send the tool calls.
396 For a subagent it sends only ``[NAME] started`` and ``[NAME] finished``,
397 ``[NAME] stopped``, or ``[NAME] failed``, because the reply of the agent
398 carries the content of the report. It sends each message that the user
399 types in the terminal client, with the mark ``[terminal]``.
401 ``agent/telegram-offset.json`` holds the ID of the next update. The bot
402 moves it past an update only after the message is durable in the log, so
403 a restart of the daemon does not lose a message. A crash just after the
404 write of a message can make the message repeat once. A network failure
405 or a rate limit makes the bot wait and try again, and does not stop the
412 The daemon connects to the WhatsApp account of the user as a linked
413 device. The terminal client and Telegram take three commands:
415 ``/whatsapp pair PHONE``
416 Links the account of PHONE, the number with its country code, such as
417 ``+15550001111``. The daemon answers with the steps and then with a
418 pairing code in its own message: in WhatsApp on the phone, open
419 Linked devices, tap Link a device, then tap Link with phone number
420 instead, and enter the code. The code expires in about 2 minutes, and
421 the same command gives a new code. When the link succeeds, the daemon
422 answers with the linked number. Linked devices on the phone shows the
423 device as OneChat. The name applies at the pairing, so an existing
424 link keeps its old name until ``/whatsapp unlink`` and a new
425 ``/whatsapp pair PHONE``.
428 Shows the link: not linked, linked and connected, or linked and
429 disconnected, with the times of the connection.
432 Ends the link and deletes the session. When WhatsApp is disconnected,
433 the phone does not get the logout, so remove the device in Linked
434 devices on the phone.
436 The answers go only to the client that asked, and the commands do not go
437 to the agent, so the agent never gets the phone number or the code. The
438 chat gets only the notes that WhatsApp is linked or unlinked.
440 The session is ``whatsapp/session.db`` in the data directory, with mode
441 0600 in a directory with mode 0700. It gives full access to the WhatsApp
442 account, so the daemon refuses the file when its mode is not 0600. The
443 shell of the agent runs as the user, so it can read the session. If the
444 session leaks, remove the linked device in WhatsApp on the phone, and
445 the session stops working. Without the file, WhatsApp is not linked.
447 The daemon reads the text messages of the private chats and the groups,
448 from other people and from the user. It does not read media, reactions,
449 edits, deletions, view-once and disappearing messages, or the history
450 from before the link. The messages of one chat form one batch until the
451 chat is quiet for 20 seconds, for 2 minutes or 50 messages at the most.
452 Each batch goes to the chat of the agent as one work message that starts
453 with ``[WhatsApp]``, with the name and the ID of the chat, and the time,
454 the sender, and the text of each message. The messages of the user show
455 as ``You``. ``whatsapp/state.json``, with mode 0600, keeps the batches
456 that are not in the chat yet, so they survive a restart, and the records
457 of the sends. A crash just after a batch goes to the chat can make the
460 A batch of a private chat with a message of another person starts a
461 turn, and so does a batch of a group with a message that mentions the
462 user or replies to a message of the user. The other batches go to the
463 chat with no turn, and the agent sees them at its next turn. A batch
464 that starts a turn ends with a line that tells the agent to end its turn
465 with an empty reply when nothing in the batch needs the user. No client
466 shows an empty reply, so such a batch gives no message in Telegram. The
467 terminal client shows each batch, and Telegram shows none.
469 The phone number of the user never goes to the chat: a mention of the
470 user shows as ``@you``, the number shows as ``OWN``, and the chat of the
471 user with itself is not read. But the IDs of the other chats go to the
472 chat and to the model, because the agent needs them to send. The ID of a
473 private chat holds the phone number of the contact, such as
474 ``15550002222@s.whatsapp.net``, and the ID of a group can hold the
475 number of the person who made it.
477 While the daemon is stopped or disconnected, the WhatsApp servers keep
478 the messages for the linked device and send them at the next connection.
479 They keep them only for a limited time, so a long stop can lose
480 messages. These messages form batches by their original times, as live
481 messages do. The daemon waits for the end of this catch-up, or one
482 minute at the most, and then gives all its batches to the agent in one
483 turn, not one turn for each chat. The batches of ``whatsapp/state.json``
484 at the start wait for the first catch-up in the same way.
486 The agent finds a chat with the tool ``whatsapp_find``: it gives the
487 contacts and the groups whose name holds a text, with no regard to case
488 and accents, with their IDs. The names of the contacts come from the
489 session, and the names of the groups from WhatsApp, kept in memory for
490 one hour. The names arrive from the phone some minutes after the link,
491 and until then the tool says that they are not ready. The agent sends a
492 text message with the tool ``whatsapp_send``, only when the user asks
493 for it. Each send has an ID that the agent gives: a repeated call with
494 the same ID gives the answer of the first call and sends nothing. The
495 state file keeps the last 1000 send records. When the daemon stops
496 during a send, the result is not known, and the tool tells the agent to
497 ask the user to look at the chat in WhatsApp. Without a link, both tools
498 tell the agent to ask the user to run ``/whatsapp pair PHONE``. Only the
499 agent has the WhatsApp tools, not its subagents.
501 Each batch of a group goes to the chat, also with no turn, and the
502 memory tree summarizes it with model calls, which use the quota.
504 When the session holds a linked device, the daemon connects at its
505 start. If the first connection fails, it tries again after 2 seconds,
506 then doubles the wait up to 5 minutes. The inbox and commands stay
507 active during each wait. An unlink or a logout stops these retries.
508 After a network failure of an open connection, the library connects
509 again by itself. When a disconnection lasts 10 minutes, all clients get
510 one notice, and one more when the connection comes back. When WhatsApp
511 ends the connection for good, for example because another program uses
512 the same session, all clients get a notice at once. When the user
513 removes the device in the phone, the daemon deletes the session and
514 tells all clients one time.
516 *************************
517 Import WhatsApp history
518 *************************
520 Stop the daemon and finish all subagents before an import. Export each
521 chat from WhatsApp as a ZIP with ``_chat.txt``. Keep the chat name in
522 the ZIP name, such as ``WhatsApp Chat - Example.zip``. Read the plan
527 onechat import -n CHAT.zip OTHER.zip
528 onechat import CHAT.zip OTHER.zip
530 ``-n`` makes no model call and prints the chats, chat-day batches, local
531 dates, cutoff, text bytes, merged message count, and estimated calls.
532 The import keeps multiline text, system lines, and omitted-media
533 markers. It maps the session's profile name to ``You``. Without that
534 name, it keeps the senders as written and says so in the plan. An exact,
535 unambiguous local contact or batch name supplies the chat ID when known.
536 No network lookup is made.
538 Each chat and local day becomes one work message marked ``(imported)``.
539 Only messages before the first message of the earliest live WhatsApp
540 batch enter the import. Live times have minute precision, so the cutoff
541 excludes that whole minute. A chat-day already imported is skipped.
542 Overlapping chat-days in the supplied ZIPs are refused. Review the
543 exports before import: their text goes to the model as chat history.
545 The import merges the full log in date order and builds its tree with
546 real compactor calls, the agent prompt, and the agent cache key. It uses
547 a limit of 1,500 calls and the probe's 15-quota-point limit, and prints
548 the same usage report. Its estimate is about 1.3 calls per merged
549 message, not a cost guarantee. A stopped or failed run leaves the agent
550 unchanged. A new run starts over. Success keeps the other agent files
551 and renames the old directory to ``agent-backup-TIMESTAMP`` before it
552 installs the new one. Keep the backup until the new memory is checked,
553 then start the daemon. Message IDs change to their positions in the
560 The agent sets reminders and timed tasks when the user asks for them,
561 such as "remind me tomorrow at 9" or "every weekday at 8, tell me what
562 my WhatsApp groups talked about". A schedule has a text, the task for
563 the agent, and either one time or a cron expression. The agent also
564 lists the schedules with their next times, and removes one when the user
565 asks. Only the agent has the schedule tools, not its subagents.
567 A cron expression has five fields: minute, hour, day of month, month,
568 and day of week, where 0 and 7 are Sunday. A field is a comma list of
569 ``*``, ``N``, and ``N-M``, and ``*`` and ``N-M`` can have a step ``/S``,
570 as in ``0 8 * * 1-5`` or ``*/15 9-17 * * *``. When both day fields start
571 with something other than ``*``, a day matches when either field
572 matches. Names such as ``MON``, macros such as ``@daily``, the
573 characters ``? L W #``, and ``N/S`` are refused. The runs must be at
574 least 5 minutes apart, because each run is a full turn that uses the
575 quota, so ``*/5 * * * *`` is the shortest schedule.
577 The times use the time zone of the machine. A time that the clock skips
578 at the start of daylight saving time runs later by the length of the
579 skip. A time that the clock repeats at its end runs once, at its first
582 At its time, a schedule goes to the chat as a work message that starts
583 with ``[Schedule ID]``, with its time and its text, and it starts a
584 turn. The message ends with a line that tells the agent to end its turn
585 with an empty reply when nothing needs the user. The terminal client
586 shows the message, and Telegram shows only the reply. After its run, a
587 one-time schedule goes, and a repeating schedule gets its next time.
589 ``agent/schedules.json``, with mode 0600, holds the schedules. Each
590 change writes it before the tool answers, so the schedules survive a
591 restart. A schedule that came due while the daemon was stopped runs once
592 at the next start, with its original time and a line that says that the
593 run is late. A repeating schedule that missed several times runs once. A
594 crash just after a run goes to the chat can make the run repeat once.
600 ``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
601 appends the first COUNT messages of LOG, one JSON object ``{"kind",
602 "text"}`` on each line, to a new chat in ``probe/`` in the data
603 directory, and builds its tree with real model calls. The calls use the
604 quota of the account. The run stops at the first failed call, after 660
605 calls, or when the used percent of a quota window grows by more than 15
606 points. At the end it reports the calls per message, the cached share of
607 the input tokens, the retries, the line sizes, and the quota at the
608 first and the last call. BUILDS, from 1 to 8, limits the model calls at
611 A test writes a generated log of readable made-up messages:
615 ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
621 Nix supplies the Go toolchain and all tools. Enter the development shell
628 Or enter it directly:
634 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
635 unless it is already set. Development data goes there, and Git ignores
645 ``onechat version`` prints ``yyyy-mm-dd-gitshort`` for a Nix build, adds
646 ``-dirty`` for a dirty tree, and prints ``dev`` for a direct Go build.
648 Format and check all files:
656 ``bin/check`` and ``nix build`` run a short replay of the synthetic log.
657 ``nix flake check`` also runs the full replay of 100,000 messages.
projects / onechat / blob