Serve the agent to a terminal client

[onechat] / README.rst

diff --git a/README.rst b/README.rst
index 04dcafb923096b07be3965e6b847bc706e8f39d0..c0c6c5d2b16a6457a56a6716229ceb37b8ecd989 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -2,8 +2,9 @@
  OneChat
 #########
 
  OneChat
 #########
 

-OneChat is a Go program. It prints its name. It is in early development.
-Linux is supported.
+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
 
 ****************
  Data directory


@@ -63,6 +64,48 @@ 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.
 
 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
 *******
 *******
  Probe
 *******