#########
 OneChat
#########

OneChat is one AI agent in a single chat that never ends. A daemon owns
the agent and its files, and a terminal client talks to it. It is in
early development. Linux is supported.

****************
 Data directory
****************

OneChat keeps its data and its token file in one directory. It uses the
first of these:

#. ``ONECHAT_DIR``, when it is set.
#. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute
   path. A relative value is ignored.
#. ``~/.local/share/onechat``. With no home directory, OneChat exits
   with an error.

OneChat creates the directory with mode 0700.

***************
 Configuration
***************

``config.json`` in the data directory holds the settings. OneChat does
not create it. A missing file or field takes the default, and an unknown
field is an error.

.. code:: json

   {
     "endpoint": "chatgpt",
     "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
   }

``endpoint``
   ``chatgpt`` (the default) sends model calls to the ChatGPT backend
   with the subscription login. ``api`` sends them to the OpenAI API
   with the key in ``OPENAI_API_KEY``, which must then be set. With
   ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``.

``compactor``
   The model and the reasoning effort of the summaries. The defaults are
   ``gpt-6.1-sol`` and ``high``.

*******
 Login
*******

The ``chatgpt`` endpoint needs a login with a ChatGPT account:

.. code:: console

   onechat login

The command shows a link and a code. Open the link on any device, enter
the code, and approve the login. Device code login must be allowed in
the ChatGPT security settings. OneChat writes the tokens to
``auth.json`` in the data directory, with mode 0600, and refreshes them
before they expire. The file belongs to OneChat only. Do not share it
with the Codex CLI, because each program rotates the refresh token and
logs the other out.

*******
 Agent
*******

Start the daemon, and then the client in another terminal:

.. code:: console

   onechat daemon
   onechat chat

The daemon owns the root agent in ``agent/`` in the data directory and
listens on the Unix socket ``onechat.sock`` there. In the client, each
line is a message to the agent, the line ``/stop`` interrupts the
running turn, and Ctrl-D ends the client. The client shows the replies,
the tool calls, and the first lines of each tool result as they happen.
The daemon is the only process that uses the token file while it runs,
so ``onechat login`` and ``onechat probe`` refuse to start until it
stops.

The agent runs commands with bash as the user in its working directory,
with no sandbox. It has the rights of the user, also on the token file.

``agent/config.json`` holds the settings of the agent. The first start
writes it with the defaults and a random ID. Do not change the ID: the
prompt cache key comes from it.

.. code:: json

   {
     "name": "OneChat",
     "id": "0123456789abcdef0123456789abcdef",
     "model": "gpt-6.1-sol",
     "effort": "medium",
     "workdir": "/home/user"
   }

``workdir`` is an absolute path, and its default is the home directory.
``agent/instructions.md`` holds the user's instructions: who they are,
how their files are organized, and how they want work done. The prompt
ends with them, and a change applies at the next call.

*******
 Probe
*******

``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
appends the first COUNT messages of LOG, one JSON object ``{"kind",
"text"}`` on each line, to a new chat in ``probe/`` in the data
directory, and builds its tree with real model calls. The calls use the
quota of the account. The run stops at the first failed call, after 660
calls, or when the used percent of a quota window grows by more than 15
points. At the end it reports the calls per message, the cached share of
the input tokens, the retries, the line sizes, and the quota at the
first and the last call. BUILDS, from 1 to 8, limits the model calls at
once in the run.

A test writes a generated log of readable made-up messages:

.. code:: console

   ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix

*************
 Development
*************

Nix supplies the Go toolchain and all tools. Enter the development shell
with direnv:

.. code:: console

   direnv allow

Or enter it directly:

.. code:: console

   nix develop

The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
unless it is already set. Development data goes there, and Git ignores
``.devenv``.

Build and run:

.. code:: console

   nix build
   ./result/bin/onechat

Format and check all files:

.. code:: console

   bin/format
   bin/check
   nix flake check