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

   1 #########
   2  OneChat
   3 #########
   4
   5 OneChat is a Go program. It prints its name. It is in early development.
   6 Linux is supported.
   7
   8 ****************
   9  Data directory
  10 ****************
  11
  12 OneChat keeps its data and its token file in one directory. It uses the
  13 first of these:
  14
  15 #. ``ONECHAT_DIR``, when it is set.
  16 #. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute
  17    path. A relative value is ignored.
  18 #. ``~/.local/share/onechat``. With no home directory, OneChat exits
  19    with an error.
  20
  21 OneChat creates the directory with mode 0700.
  22
  23 ***************
  24  Configuration
  25 ***************
  26
  27 ``config.json`` in the data directory holds the settings. OneChat does
  28 not create it. A missing file or field takes the default, and an unknown
  29 field is an error.
  30
  31 .. code:: json
  32
  33    {
  34      "endpoint": "chatgpt",
  35      "compactor": {"model": "gpt-6-luna", "effort": "high"}
  36    }
  37
  38 ``endpoint``
  39    ``chatgpt`` (the default) sends model calls to the ChatGPT backend
  40    with the subscription login. ``api`` sends them to the OpenAI API
  41    with the key in ``OPENAI_API_KEY``, which must then be set. With
  42    ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``.
  43
  44 ``compactor``
  45    The model and the reasoning effort of the summaries. The defaults are
  46    ``gpt-6-luna`` and ``high``.
  47
  48 *******
  49  Login
  50 *******
  51
  52 The ``chatgpt`` endpoint needs a login with a ChatGPT account:
  53
  54 .. code:: console
  55
  56    onechat login
  57
  58 The command shows a link and a code. Open the link on any device, enter
  59 the code, and approve the login. Device code login must be allowed in
  60 the ChatGPT security settings. OneChat writes the tokens to
  61 ``auth.json`` in the data directory, with mode 0600, and refreshes them
  62 before they expire. The file belongs to OneChat only. Do not share it
  63 with the Codex CLI, because each program rotates the refresh token and
  64 logs the other out.
  65
  66 *******
  67  Probe
  68 *******
  69
  70 ``onechat probe LOG COUNT`` measures the compactor on a log. It appends
  71 the first COUNT messages of LOG, one JSON object ``{"kind", "text"}`` on
  72 each line, to a new chat in ``probe/`` in the data directory, and builds
  73 its tree with real model calls. The calls use the quota of the account.
  74 The run stops at the first failed call, or when the used percent of a
  75 quota window grows by more than 15 points. At the end it reports the
  76 calls per message, the cached share of the input tokens, the retries,
  77 the line sizes, and the quota at the first and the last call.
  78
  79 A test writes a generated log of readable made-up messages:
  80
  81 .. code:: console
  82
  83    ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
  84
  85 *************
  86  Development
  87 *************
  88
  89 Nix supplies the Go toolchain and all tools. Enter the development shell
  90 with direnv:
  91
  92 .. code:: console
  93
  94    direnv allow
  95
  96 Or enter it directly:
  97
  98 .. code:: console
  99
 100    nix develop
 101
 102 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
 103 unless it is already set. Development data goes there, and Git ignores
 104 ``.devenv``.
 105
 106 Build and run:
 107
 108 .. code:: console
 109
 110    nix build
 111    ./result/bin/onechat
 112
 113 Format and check all files:
 114
 115 .. code:: console
 116
 117    bin/format
 118    bin/check
 119    nix flake check