Add Chronicle agent installation guide

Author: seanap

README.md

@@ -107,6 +107,8 @@ http://localhost:1609
 
 ## Documentation
 - API docs: [`docs/API_DOCUMENTATION.md`](docs/API_DOCUMENTATION.md)
+- Agent installation: [`docs/AGENT_INSTALLATION.md`](docs/AGENT_INSTALLATION.md)
+- Agent architecture: [`docs/AGENT_ARCHITECTURE.md`](docs/AGENT_ARCHITECTURE.md)
 - Android widget companion: [`docs/ANDROID_WIDGET_COMPANION.md`](docs/ANDROID_WIDGET_COMPANION.md)
 - Android widget APK downloads: [GitHub Releases](https://github.com/seanap/Chronicle/releases)
 - Misery Index report: [`docs/MISERY_INDEX_REPORT.md`](docs/MISERY_INDEX_REPORT.md)

ai/chronicle_companion/.env.example

@@ -0,0 +1,11 @@
+CHRONICLE_COMPANION_HOST=0.0.0.0
+CHRONICLE_COMPANION_PORT=8788
+CHRONICLE_COMPANION_API_KEY=replace-with-the-same-value-as-AGENT_REMOTE_API_KEY
+CHRONICLE_COMPANION_HTTP_TIMEOUT_SECONDS=30
+
+# Leave blank if codex is on PATH.
+EDITOR_AI_CODEX_CLI_PATH=
+# Direct Codex at the companion workspace and prompt assets.
+EDITOR_AI_WORKSPACE_DIR=/app/ai/chronicle_companion
+EDITOR_AI_TIMEOUT_SECONDS=120
+EDITOR_AI_CODEX_MODEL=

ai/chronicle_companion/Dockerfile

@@ -0,0 +1,21 @@
+FROM node:24-bookworm-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends python3 python3-pip python3-venv tzdata \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt /app/requirements.txt
+RUN pip3 install --break-system-packages --no-cache-dir -r /app/requirements.txt
+
+RUN npm install -g @openai/codex
+
+COPY . /app
+
+EXPOSE 8788
+
+CMD ["python3", "ai/chronicle_companion/service.py"]

ai/chronicle_companion/chronicle-codex-companion.service.example

@@ -0,0 +1,16 @@
+[Unit]
+Description=Chronicle Codex Companion
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=CHANGE_ME
+WorkingDirectory=/opt/chronicle/Auto-Stat-Description
+EnvironmentFile=/opt/chronicle/Auto-Stat-Description/ai/chronicle_companion/.env
+ExecStart=/opt/chronicle/Auto-Stat-Description/.venv/bin/python ai/chronicle_companion/service.py
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

ai/chronicle_companion/docker-compose.example.yml

@@ -0,0 +1,22 @@
+services:
+  chronicle-codex-companion:
+    build:
+      context: ../..
+      dockerfile: ai/chronicle_companion/Dockerfile
+    image: chronicle-codex-companion:latest
+    container_name: chronicle-codex-companion
+    env_file:
+      - .env
+    environment:
+      - EDITOR_AI_CODEX_CLI_PATH=/usr/local/bin/codex
+      - EDITOR_AI_WORKSPACE_DIR=/app/ai/chronicle_companion
+    working_dir: /app
+    volumes:
+      - ../..:/app
+      - codex-home:/root/.codex
+    ports:
+      - "8788:8788"
+    restart: unless-stopped
+
+volumes:
+  codex-home: