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 files, and a terminal client talks to it. It is in
   7 early development. Linux is supported.
   8
   9 ****************
  10  Data directory
  11 ****************
  12
  13 OneChat keeps its data and its token file in one directory. It uses the
  14 first of these:
  15
  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
  20    with an error.
  21
  22 OneChat creates the directory with mode 0700.
  23
  24 ***************
  25  Configuration
  26 ***************
  27
  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
  30 field is an error.
  31
  32 .. code:: json
  33
  34    {
  35      "endpoint": "chatgpt",
  36      "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
  37    }
  38
  39 ``endpoint``
  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``.
  44
  45 ``compactor``
  46    The model and the reasoning effort of the summaries. The defaults are
  47    ``gpt-6.1-sol`` and ``high``.
  48
  49 *******
  50  Login
  51 *******
  52
  53 The ``chatgpt`` endpoint needs a login with a ChatGPT account:
  54
  55 .. code:: console
  56
  57    onechat login
  58
  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
  65 logs the other out.
  66
  67 *******
  68  Agent
  69 *******
  70
  71 Start the daemon, and then the client in another terminal:
  72
  73 .. code:: console
  74
  75    onechat daemon
  76    onechat chat
  77
  78 The daemon owns the root agent in ``agent/`` in the data directory and
  79 listens on the Unix socket ``onechat.sock`` there. In the client, each
  80 line is a message to the agent, the line ``/stop`` interrupts the
  81 running turn, and Ctrl-D ends the client. The client shows the replies,
  82 the tool calls, and the first lines of each tool result as they happen.
  83 The daemon is the only process that uses the token file while it runs,
  84 so ``onechat login`` and ``onechat probe`` refuse to start until it
  85 stops.
  86
  87 The agent runs commands with bash as the user in its working directory,
  88 with no sandbox. It has the rights of the user, also on the token file.
  89
  90 ``agent/config.json`` holds the settings of the agent. The first start
  91 writes it with the defaults and a random ID. Do not change the ID: the
  92 prompt cache key comes from it.
  93
  94 .. code:: json
  95
  96    {
  97      "name": "OneChat",
  98      "id": "0123456789abcdef0123456789abcdef",
  99      "model": "gpt-6.1-sol",
 100      "effort": "medium",
 101      "workdir": "/home/user"
 102    }
 103
 104 ``workdir`` is an absolute path, and its default is the home directory.
 105 ``agent/instructions.md`` holds the user's instructions: who they are,
 106 how their files are organized, and how they want work done. The prompt
 107 ends with them, and a change applies at the next call.
 108
 109 *******
 110  Probe
 111 *******
 112
 113 ``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
 114 appends the first COUNT messages of LOG, one JSON object ``{"kind",
 115 "text"}`` on each line, to a new chat in ``probe/`` in the data
 116 directory, and builds its tree with real model calls. The calls use the
 117 quota of the account. The run stops at the first failed call, after 660
 118 calls, or when the used percent of a quota window grows by more than 15
 119 points. At the end it reports the calls per message, the cached share of
 120 the input tokens, the retries, the line sizes, and the quota at the
 121 first and the last call. BUILDS, from 1 to 8, limits the model calls at
 122 once in the run.
 123
 124 A test writes a generated log of readable made-up messages:
 125
 126 .. code:: console
 127
 128    ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
 129
 130 *************
 131  Development
 132 *************
 133
 134 Nix supplies the Go toolchain and all tools. Enter the development shell
 135 with direnv:
 136
 137 .. code:: console
 138
 139    direnv allow
 140
 141 Or enter it directly:
 142
 143 .. code:: console
 144
 145    nix develop
 146
 147 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
 148 unless it is already set. Development data goes there, and Git ignores
 149 ``.devenv``.
 150
 151 Build and run:
 152
 153 .. code:: console
 154
 155    nix build
 156    ./result/bin/onechat
 157
 158 Format and check all files:
 159
 160 .. code:: console
 161
 162    bin/format
 163    bin/check
 164    nix flake check