clawdbot 2026.1.4

package/docs/assets/terminal.css

@@ -0,0 +1,497 @@
+:root {
+  --font-body: "Fragment Mono", ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  --font-pixel: "Pixelify Sans", system-ui, sans-serif;
+  --radius: 14px;
+  --radius-sm: 10px;
+  --border: 2px;
+  --shadow-px: 0 0 0 var(--border) var(--frame-border), 0 12px 0 -4px rgba(0, 0, 0, 0.25);
+  --scanline-size: 6px;
+  --scanline-opacity: 0.08;
+}
+
+html[data-theme="light"],
+html[data-theme="auto"] {
+  --bg0: #fbf4e7;
+  --bg1: #fffaf0;
+  --panel: #fffdf8;
+  --panel2: #fff6e5;
+  --text: #10221c;
+  --muted: #3e5a50;
+  --faint: #6b7f77;
+  --link: #0f6b4c;
+  --link2: #ff4f40;
+  --accent: #ff4f40;
+  --accent2: #00b88a;
+  --frame-border: #1b2e27;
+  --code-bg: #0b1713;
+  --code-fg: #eafff6;
+  --code-accent: #67ff9b;
+}
+
+html[data-theme="dark"] {
+  --bg0: #06141f;
+  --bg1: #031019;
+  --panel: #061a16;
+  --panel2: #071f19;
+  --text: #d6f6ea;
+  --muted: #95c9b9;
+  --faint: #66a391;
+  --link: #79ffd0;
+  --link2: #ff775f;
+  --accent: #ff4f40;
+  --accent2: #67ff9b;
+  --frame-border: #b7ffe6;
+  --code-bg: #04110d;
+  --code-fg: #dcfff1;
+  --code-accent: #67ff9b;
+}
+
+@media (prefers-color-scheme: dark) {
+  html[data-theme="auto"] {
+    --bg0: #06141f;
+    --bg1: #031019;
+    --panel: #061a16;
+    --panel2: #071f19;
+    --text: #d6f6ea;
+    --muted: #95c9b9;
+    --faint: #66a391;
+    --link: #79ffd0;
+    --link2: #ff775f;
+    --accent: #ff4f40;
+    --accent2: #67ff9b;
+    --frame-border: #b7ffe6;
+    --code-bg: #04110d;
+    --code-fg: #dcfff1;
+    --code-accent: #67ff9b;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  margin: 0;
+  font-family: var(--font-body);
+  color: var(--text);
+  background:
+    radial-gradient(1100px 700px at 20% -10%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 55%),
+    radial-gradient(900px 600px at 95% 10%, color-mix(in oklab, var(--accent2) 14%, transparent), transparent 60%),
+    radial-gradient(900px 600px at 50% 120%, color-mix(in oklab, var(--link) 10%, transparent), transparent 55%),
+    linear-gradient(180deg, var(--bg0), var(--bg1));
+  overflow-x: hidden;
+}
+
+body::before {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0.45;
+  background-image:
+    linear-gradient(to right, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px),
+    linear-gradient(to bottom, color-mix(in oklab, var(--text) 10%, transparent) 1px, transparent 1px);
+  background-size: 28px 28px;
+  mix-blend-mode: overlay;
+}
+
+body::after {
+  content: "";
+  position: fixed;
+  inset: 0;
+  pointer-events: none;
+  background: repeating-linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, var(--scanline-opacity)),
+    rgba(0, 0, 0, var(--scanline-opacity)) 1px,
+    transparent 1px,
+    transparent var(--scanline-size)
+  );
+  opacity: 0.8;
+  mix-blend-mode: multiply;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  body::after {
+    display: none;
+  }
+}
+
+.skip-link {
+  position: absolute;
+  top: 10px;
+  left: 10px;
+  z-index: 10;
+  padding: 10px 12px;
+  border-radius: 999px;
+  background: var(--panel);
+  color: var(--text);
+  text-decoration: none;
+  transform: translateY(-130%);
+  box-shadow: var(--shadow-px);
+}
+
+.skip-link:focus {
+  transform: translateY(0);
+  outline: none;
+}
+
+.shell {
+  padding: 22px 16px 10px;
+}
+
+.shell__frame {
+  max-width: 1120px;
+  margin: 0 auto;
+  border-radius: var(--radius);
+  background:
+    linear-gradient(180deg, color-mix(in oklab, var(--panel2) 88%, transparent), color-mix(in oklab, var(--panel) 92%, transparent));
+  box-shadow: var(--shadow-px);
+  border: var(--border) solid var(--frame-border);
+  overflow: hidden;
+}
+
+.shell__titlebar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 14px 14px 12px;
+  background:
+    linear-gradient(90deg, color-mix(in oklab, var(--accent) 26%, transparent), transparent 42%),
+    linear-gradient(180deg, color-mix(in oklab, var(--panel) 90%, #000 10%), color-mix(in oklab, var(--panel2) 90%, #000 10%));
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  min-width: 0;
+}
+
+.brand__logo {
+  flex: 0 0 auto;
+  width: 40px;
+  height: 40px;
+  image-rendering: pixelated;
+  filter: drop-shadow(0 2px 0 color-mix(in oklab, var(--frame-border) 80%, transparent));
+}
+
+.brand__text {
+  min-width: 0;
+}
+
+.brand__name {
+  font-family: var(--font-pixel);
+  letter-spacing: 0.14em;
+  font-weight: 700;
+  font-size: 18px;
+  line-height: 1.1;
+  text-shadow: 0 1px 0 color-mix(in oklab, var(--frame-border) 55%, transparent);
+}
+
+.brand__hint {
+  margin-top: 2px;
+  font-size: 12px;
+  color: var(--muted);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.titlebar__actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.titlebar__cta {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 12px 8px 10px;
+  border-radius: 12px;
+  background:
+    linear-gradient(140deg, color-mix(in oklab, var(--accent) 10%, transparent), transparent 60%),
+    color-mix(in oklab, var(--panel) 92%, transparent);
+  border: var(--border) solid color-mix(in oklab, var(--frame-border) 80%, transparent);
+  color: var(--text);
+  text-decoration: none;
+  box-shadow:
+    0 6px 0 -3px rgba(0, 0, 0, 0.25),
+    inset 0 0 0 1px color-mix(in oklab, var(--panel2) 55%, transparent);
+}
+
+.titlebar__cta:hover {
+  border-color: color-mix(in oklab, var(--accent2) 45%, transparent);
+  box-shadow:
+    0 0 0 2px color-mix(in oklab, var(--accent2) 30%, transparent),
+    0 6px 0 -3px rgba(0, 0, 0, 0.25);
+}
+
+.titlebar__cta:active {
+  transform: translateY(1px);
+  box-shadow: 0 4px 0 -3px rgba(0, 0, 0, 0.25);
+}
+
+.titlebar__cta:focus-visible {
+  outline: 3px solid color-mix(in oklab, var(--accent2) 60%, transparent);
+  outline-offset: 2px;
+}
+
+.titlebar__cta--accent {
+  background:
+    linear-gradient(120deg, color-mix(in oklab, var(--accent) 22%, transparent), transparent 70%),
+    color-mix(in oklab, var(--panel) 88%, transparent);
+  border-color: color-mix(in oklab, var(--accent) 60%, var(--frame-border));
+}
+
+.titlebar__cta-label {
+  font-family: var(--font-pixel);
+  letter-spacing: 0.12em;
+  font-size: 12px;
+  text-transform: uppercase;
+}
+
+.titlebar__cta-meta {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  height: 20px;
+  padding: 0 8px;
+  border-radius: 999px;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  background: var(--code-bg);
+  color: var(--code-accent);
+  border: 1px solid color-mix(in oklab, var(--code-accent) 30%, transparent);
+  box-shadow: inset 0 0 12px color-mix(in oklab, var(--code-accent) 25%, transparent);
+}
+
+.theme-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  padding: 9px 10px;
+  border-radius: 12px;
+  background: color-mix(in oklab, var(--panel) 92%, transparent);
+  border: var(--border) solid var(--frame-border);
+  color: var(--text);
+  cursor: pointer;
+  box-shadow: 0 6px 0 -3px rgba(0, 0, 0, 0.25);
+  user-select: none;
+}
+
+.theme-toggle:active {
+  transform: translateY(1px);
+  box-shadow: 0 4px 0 -3px rgba(0, 0, 0, 0.25);
+}
+
+.theme-toggle__key {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 28px;
+  border-radius: 9px;
+  background: var(--code-bg);
+  color: var(--code-accent);
+  border: 1px solid color-mix(in oklab, var(--code-accent) 30%, transparent);
+  font-weight: 700;
+  font-size: 12px;
+  letter-spacing: 0.06em;
+  text-shadow: 0 0 14px color-mix(in oklab, var(--code-accent) 55%, transparent);
+}
+
+.theme-toggle__label {
+  font-family: var(--font-pixel);
+  letter-spacing: 0.12em;
+  font-size: 12px;
+  text-transform: uppercase;
+}
+
+.theme-toggle:focus-visible {
+  outline: 3px solid color-mix(in oklab, var(--accent2) 60%, transparent);
+  outline-offset: 2px;
+}
+
+.shell__nav {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 10px 14px 12px;
+  border-top: 1px solid color-mix(in oklab, var(--frame-border) 25%, transparent);
+  background: linear-gradient(180deg, transparent, color-mix(in oklab, var(--panel2) 78%, transparent));
+}
+
+.nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.nav__link {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-radius: 999px;
+  text-decoration: none;
+  color: var(--text);
+  background: color-mix(in oklab, var(--panel) 85%, transparent);
+  border: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+}
+
+.nav__link:hover {
+  border-color: color-mix(in oklab, var(--accent2) 45%, transparent);
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--accent2) 30%, transparent);
+}
+
+.nav__chev {
+  color: var(--accent);
+  font-weight: 700;
+}
+
+.shell__status {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  color: var(--muted);
+  font-size: 12px;
+  white-space: nowrap;
+}
+
+.status__dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+  background: radial-gradient(circle at 30% 30%, var(--accent2), color-mix(in oklab, var(--accent2) 30%, #000));
+  box-shadow: 0 0 0 2px color-mix(in oklab, var(--accent2) 18%, transparent), 0 0 18px color-mix(in oklab, var(--accent2) 50%, transparent);
+}
+
+.content {
+  padding: 18px 16px 48px;
+}
+
+.terminal {
+  position: relative;
+  max-width: 1120px;
+  margin: 0 auto;
+  border-radius: var(--radius);
+  border: var(--border) solid var(--frame-border);
+  background: linear-gradient(180deg, color-mix(in oklab, var(--panel) 92%, transparent), color-mix(in oklab, var(--panel2) 86%, transparent));
+  box-shadow: var(--shadow-px);
+  padding: 18px 16px 16px;
+}
+
+.terminal__prompt {
+  display: block;
+  padding: 10px 12px;
+  border-radius: var(--radius-sm);
+  background: var(--code-bg);
+  color: var(--code-fg);
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+  overflow-x: auto;
+  white-space: nowrap;
+}
+
+.prompt__user {
+  color: var(--code-accent);
+  text-shadow: 0 0 16px color-mix(in oklab, var(--code-accent) 52%, transparent);
+}
+
+.prompt__host {
+  color: color-mix(in oklab, var(--code-fg) 92%, var(--accent2));
+}
+
+.prompt__path {
+  color: color-mix(in oklab, var(--code-fg) 78%, var(--link));
+}
+
+.prompt__cmd {
+  margin-left: 8px;
+  color: color-mix(in oklab, var(--code-fg) 90%, var(--accent));
+}
+
+.terminal__summary {
+  margin: 12px 2px 0;
+  color: var(--muted);
+  font-size: 14px;
+  line-height: 1.5;
+}
+
+.terminal__meta {
+  margin: 12px 2px 0;
+  padding: 12px 12px;
+  border-radius: var(--radius-sm);
+  border: 1px dashed color-mix(in oklab, var(--frame-border) 25%, transparent);
+  background: color-mix(in oklab, var(--panel) 76%, transparent);
+  color: var(--faint);
+  font-size: 13px;
+}
+
+.terminal__meta summary {
+  cursor: pointer;
+  font-family: var(--font-pixel);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--text);
+}
+
+.terminal__meta ul {
+  margin: 10px 0 0 18px;
+}
+
+.terminal__footer {
+  margin-top: 22px;
+  padding-top: 16px;
+  border-top: 1px solid color-mix(in oklab, var(--frame-border) 20%, transparent);
+  color: var(--muted);
+  font-size: 13px;
+}
+
+.footer__actions {
+  margin-top: 14px;
+  display: flex;
+  justify-content: flex-end;
+}
+
+.terminal__footer a {
+  color: var(--link);
+  text-decoration: none;
+  border-bottom: 1px dotted color-mix(in oklab, var(--link) 55%, transparent);
+}
+
+.terminal__footer a:hover {
+  color: var(--link2);
+  border-bottom-color: color-mix(in oklab, var(--link2) 75%, transparent);
+}
+
+.footer__hint {
+  margin-top: 8px;
+  color: var(--faint);
+}
+
+kbd {
+  font-family: var(--font-body);
+  font-size: 0.9em;
+  padding: 2px 6px;
+  border-radius: 8px;
+  border: 1px solid color-mix(in oklab, var(--frame-border) 18%, transparent);
+  background: color-mix(in oklab, var(--panel) 65%, transparent);
+  box-shadow: 0 6px 0 -4px rgba(0, 0, 0, 0.18);
+}
+
+@supports not (color: color-mix(in oklab, black, white)) {
+  body::before,
+  body::after {
+    opacity: 0.2;
+  }
+}

package/docs/assets/theme.js

@@ -0,0 +1,55 @@
+const THEME_STORAGE_KEY = "clawdbot:theme";
+
+function safeGet(key) {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function safeSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // ignore
+  }
+}
+
+function preferredTheme() {
+  const stored = safeGet(THEME_STORAGE_KEY);
+  if (stored === "light" || stored === "dark") return stored;
+  return window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function applyTheme(theme) {
+  document.documentElement.dataset.theme = theme;
+
+  const toggle = document.querySelector("[data-theme-toggle]");
+  const label = document.querySelector("[data-theme-label]");
+
+  if (toggle instanceof HTMLButtonElement) toggle.setAttribute("aria-pressed", theme === "dark" ? "true" : "false");
+  if (label) label.textContent = theme === "dark" ? "dark" : "light";
+}
+
+function toggleTheme() {
+  const current = document.documentElement.dataset.theme === "dark" ? "dark" : "light";
+  const next = current === "dark" ? "light" : "dark";
+  safeSet(THEME_STORAGE_KEY, next);
+  applyTheme(next);
+}
+
+applyTheme(preferredTheme());
+
+document.addEventListener("click", (event) => {
+  const target = event.target;
+  const button = target instanceof Element ? target.closest("[data-theme-toggle]") : null;
+  if (button) toggleTheme();
+});
+
+document.addEventListener("keydown", (event) => {
+  if (event.key === "F2") {
+    event.preventDefault();
+    toggleTheme();
+  }
+});

package/docs/audio.md

@@ -0,0 +1,50 @@
+---
+summary: "How inbound audio/voice notes are downloaded, transcribed, and injected into replies"
+read_when:
+  - Changing audio transcription or media handling
+---
+<!-- {% raw %} -->
+# Audio / Voice Notes — 2025-12-05
+
+## What works
+- **Optional transcription**: If `routing.transcribeAudio.command` is set in `~/.clawdbot/clawdbot.json`, CLAWDBOT will:
+  1) Download inbound audio to a temp path when WhatsApp only provides a URL.
+  2) Run the configured CLI (templated with `{{MediaPath}}`), expecting transcript on stdout.
+  3) Replace `Body` with the transcript, set `{{Transcript}}`, and prepend the original media path plus a `Transcript:` section in the command prompt so models see both.
+  4) Continue through the normal auto-reply pipeline (templating, sessions, Pi command).
+- **Verbose logging**: In `--verbose`, we log when transcription runs and when the transcript replaces the body.
+
+## Config example (OpenAI Whisper CLI)
+Requires `OPENAI_API_KEY` in env and `openai` CLI installed:
+```json5
+{
+  routing: {
+    transcribeAudio: {
+      command: [
+        "openai",
+        "api",
+        "audio.transcriptions.create",
+        "-m",
+        "whisper-1",
+        "-f",
+        "{{MediaPath}}",
+        "--response-format",
+        "text"
+      ],
+      timeoutSeconds: 45
+    }
+  }
+}
+```
+
+## Notes & limits
+- We don’t ship a transcriber; you opt in with any CLI that prints text to stdout (Whisper cloud, whisper.cpp, vosk, Deepgram, etc.).
+- Size guard: inbound audio must be ≤5 MB (matches the temp media store and transcript pipeline).
+- Outbound caps: web send supports audio/voice up to 16 MB (sent as a voice note with `ptt: true`).
+- If transcription fails, we fall back to the original body/media note; replies still go through.
+- Transcript is available to templates as `{{Transcript}}`; models get both the media path and a `Transcript:` block in the prompt when using command mode.
+
+## Gotchas
+- Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.
+- Keep timeouts reasonable (`timeoutSeconds`, default 45s) to avoid blocking the reply queue.
+<!-- {% endraw %} -->

package/docs/background-process.md

@@ -0,0 +1,74 @@
+---
+summary: "Background bash execution and process management"
+read_when:
+  - Adding or modifying background bash behavior
+  - Debugging long-running bash tasks
+---
+
+# Background Bash + Process Tool
+
+Clawdbot runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+
+## bash tool
+
+Key parameters:
+- `command` (required)
+- `yieldMs` (default 10000): auto‑background after this delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill the process after this timeout
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Use the tmux skill.
+- `workdir`, `env`
+
+Behavior:
+- Foreground runs return output directly.
+- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
+- Output is kept in memory until the session is polled or cleared.
+
+Environment overrides:
+- `PI_BASH_YIELD_MS`: default yield (ms)
+- `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)
+- `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
+
+Config (preferred):
+- `agent.bash.backgroundMs` (default 10000)
+- `agent.bash.timeoutSec` (default 1800)
+- `agent.bash.cleanupMs` (default 1800000)
+
+## process tool
+
+Actions:
+- `list`: running + finished sessions
+- `poll`: drain new output for a session (also reports exit status)
+- `log`: read the aggregated output (supports `offset` + `limit`)
+- `write`: send stdin (`data`, optional `eof`)
+- `kill`: terminate a background session
+- `clear`: remove a finished session from memory
+- `remove`: kill if running, otherwise clear if finished
+
+Notes:
+- Only backgrounded sessions are listed/persisted in memory.
+- Sessions are lost on process restart (no disk persistence).
+- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
+- `process list` includes a derived `name` (command verb + target) for quick scans.
+- `process log` uses line-based `offset`/`limit` (omit `offset` to grab the last N lines).
+
+## Examples
+
+Run a long task and poll later:
+```json
+{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}
+```
+```json
+{"tool": "process", "action": "poll", "sessionId": "<id>"}
+```
+
+Start immediately in background:
+```json
+{"tool": "bash", "command": "npm run build", "background": true}
+```
+
+Send stdin:
+```json
+{"tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n"}
+```

package/docs/bash.md

@@ -0,0 +1,32 @@
+---
+summary: "Bash tool usage, stdin modes, and TTY support"
+read_when:
+  - Using or modifying the bash tool
+  - Debugging stdin or TTY behavior
+---
+
+# Bash tool
+
+Run shell commands in the workspace. Supports foreground + background execution via `process`.
+
+## Parameters
+
+- `command` (required)
+- `yieldMs` (default 10000): auto-background after delay
+- `background` (bool): background immediately
+- `timeout` (seconds, default 1800): kill on expiry
+- `elevated` (bool): run on host if elevated mode is enabled/allowed
+- Need a real TTY? Use the tmux skill.
+
+## Examples
+
+Foreground:
+```json
+{"tool":"bash","command":"ls -la"}
+```
+
+Background + poll:
+```json
+{"tool":"bash","command":"npm run build","yieldMs":1000}
+{"tool":"process","action":"poll","sessionId":"<id>"}
+```