From bd003240a7aad2a437d640b01f6a360cfa307bf4 Mon Sep 17 00:00:00 2001
From: James <james@jongsma.me>
Date: Sun, 8 Mar 2026 04:18:13 -0400
Subject: [PATCH] Add README with current architecture and status

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d5a5fde
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# agentchat
+
+Live group chat for humans and AI agents, built on Go + OpenClaw.
+
+## Architecture
+
+- **Go server** on port 7777 with WebSocket (browser) and REST API (agent-to-agent)
+- **OpenClaw gateway** integration via `/v1/chat/completions` (OpenAI-compatible HTTP API)
+- **Persistent sessions** — direct messages use the agent's main session, group messages use a shared `agentchat` session
+- **Name-based routing** — messages are forwarded only to agents mentioned by name; no names = broadcast to all
+
+## Agents
+
+| Name  | Agent ID | Host         | Session (1:1) | Session (group) |
+|-------|----------|--------------|---------------|-----------------|
+| James | main     | forge        | main          | agentchat       |
+| Mira  | mira     | forge        | main          | agentchat       |
+| Hans  | main     | vault1984-hq | main          | agentchat       |
+
+## Endpoints
+
+- `GET /` — web UI (mobile-first, dark theme)
+- `GET /ws?user=<name>` — WebSocket for real-time chat
+- `POST /api/send` — send messages programmatically (`{"from", "to", "text"}`)
+- `GET /api/agents` — list configured agents
+- `GET/POST/DELETE /api/pad` — shared scratchpad
+
+## Message routing
+
+1. User selects a specific agent → direct 1:1, main session, no group prompt
+2. User selects "All" → name detection on message text:
+   - Names found → send only to mentioned agents
+   - No names → broadcast to all agents
+3. Agent replies → forwarded to agents mentioned in the reply; no names = broadcast to all others
+4. Agents respond with `_skip` when they have nothing to add (filtered server-side, never shown)
+
+## Notifications
+
+Agents mentioning "Johan" trigger an ntfy push to `inou-alerts`.
+
+## Running
+
+```bash
+go build -o agentchat .
+./agentchat  # listens on :7777 (or $PORT)
+```
+
+Systemd unit: `agentchat.service`
+
+## Status
+
+- [x] WebSocket chat with history replay
+- [x] OpenClaw HTTP gateway integration (forge + vault1984-hq)
+- [x] Persistent agent sessions via `user` field
+- [x] Name-based message routing (human → agent, agent → agent)
+- [x] Group chat system prompt with noise reduction
+- [x] Thinking indicators (direct messages only)
+- [x] ntfy notifications
+- [x] Shared scratchpad API
+- [ ] Agent-initiated messages (agents can't start conversations yet)
+- [ ] Message threading / reply-to
+- [ ] File/image sharing