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.1-sol", "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.1-sol`` 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 [BUILDS]`` measures the compactor on a log. It
  71 appends the first COUNT messages of LOG, one JSON object ``{"kind",
  72 "text"}`` on each line, to a new chat in ``probe/`` in the data
  73 directory, and builds its tree with real model calls. The calls use the
  74 quota of the account. The run stops at the first failed call, after 660
  75 calls, or when the used percent of a quota window grows by more than 15
  76 points. At the end it reports the calls per message, the cached share of
  77 the input tokens, the retries, the line sizes, and the quota at the
  78 first and the last call. BUILDS, from 1 to 8, limits the model calls at
  79 once in the run.
  80
  81 A test writes a generated log of readable made-up messages:
  82
  83 .. code:: console
  84
  85    ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
  86
  87 *************
  88  Development
  89 *************
  90
  91 Nix supplies the Go toolchain and all tools. Enter the development shell
  92 with direnv:
  93
  94 .. code:: console
  95
  96    direnv allow
  97
  98 Or enter it directly:
  99
 100 .. code:: console
 101
 102    nix develop
 103
 104 The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
 105 unless it is already set. Development data goes there, and Git ignores
 106 ``.devenv``.
 107
 108 Build and run:
 109
 110 .. code:: console
 111
 112    nix build
 113    ./result/bin/onechat
 114
 115 Format and check all files:
 116
 117 .. code:: console
 118
 119    bin/format
 120    bin/check
 121    nix flake check