clawdbot 2026.1.4-1

package/skills/openai-whisper-api/scripts/transcribe.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  transcribe.sh <audio-file> [--model whisper-1] [--out /path/to/out.txt] [--language en] [--prompt "hint"] [--json]
+EOF
+  exit 2
+}
+
+if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+fi
+
+in="${1:-}"
+shift || true
+
+model="whisper-1"
+out=""
+language=""
+prompt=""
+response_format="text"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --model)
+      model="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out="${2:-}"
+      shift 2
+      ;;
+    --language)
+      language="${2:-}"
+      shift 2
+      ;;
+    --prompt)
+      prompt="${2:-}"
+      shift 2
+      ;;
+    --json)
+      response_format="json"
+      shift 1
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+if [[ ! -f "$in" ]]; then
+  echo "File not found: $in" >&2
+  exit 1
+fi
+
+if [[ "${OPENAI_API_KEY:-}" == "" ]]; then
+  echo "Missing OPENAI_API_KEY" >&2
+  exit 1
+fi
+
+if [[ "$out" == "" ]]; then
+  base="${in%.*}"
+  if [[ "$response_format" == "json" ]]; then
+    out="${base}.json"
+  else
+    out="${base}.txt"
+  fi
+fi
+
+mkdir -p "$(dirname "$out")"
+
+curl -sS https://api.openai.com/v1/audio/transcriptions \
+  -H "Authorization: Bearer $OPENAI_API_KEY" \
+  -H "Accept: application/json" \
+  -F "file=@${in}" \
+  -F "model=${model}" \
+  -F "response_format=${response_format}" \
+  ${language:+-F "language=${language}"} \
+  ${prompt:+-F "prompt=${prompt}"} \
+  >"$out"
+
+echo "$out"

package/skills/openhue/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: openhue
+description: Control Philips Hue lights/scenes via the OpenHue CLI.
+homepage: https://www.openhue.io/cli
+metadata: {"clawdbot":{"emoji":"💡","requires":{"bins":["openhue"]},"install":[{"id":"brew","kind":"brew","formula":"openhue/cli/openhue-cli","bins":["openhue"],"label":"Install OpenHue CLI (brew)"}]}}
+---
+
+# OpenHue CLI
+
+Use `openhue` to control Hue lights and scenes via a Hue Bridge.
+
+Setup
+- Discover bridges: `openhue discover`
+- Guided setup: `openhue setup`
+
+Read
+- `openhue get light --json`
+- `openhue get room --json`
+- `openhue get scene --json`
+
+Write
+- Turn on: `openhue set light <id-or-name> --on`
+- Turn off: `openhue set light <id-or-name> --off`
+- Brightness: `openhue set light <id> --on --brightness 50`
+- Color: `openhue set light <id> --on --rgb #3399FF`
+- Scene: `openhue set scene <scene-id>`
+
+Notes
+- You may need to press the Hue Bridge button during setup.
+- Use `--room "Room Name"` when light names are ambiguous.

package/skills/oracle/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: oracle
+description: Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
+homepage: https://askoracle.dev
+metadata: {"clawdbot":{"emoji":"🧿","requires":{"bins":["oracle"]},"install":[{"id":"node","kind":"node","package":"@steipete/oracle","bins":["oracle"],"label":"Install oracle (node)"}]}}
+---
+
+# oracle — best use
+
+Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.
+
+## Main use case (browser, GPT‑5.2 Pro)
+
+Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.
+
+Recommended defaults:
+- Engine: browser (`--engine browser`)
+- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)
+
+## Golden path
+
+1. Pick a tight file set (fewest files that still contain the truth).
+2. Preview payload + token spend (`--dry-run` + `--files-report`).
+3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
+4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).
+
+## Commands (preferred)
+
+- Help:
+  - `oracle --help`
+  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
+
+- Preview (no tokens):
+  - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
+  - `oracle --dry-run full -p "<task>" --file "src/**"`
+
+- Token sanity:
+  - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
+
+- Browser run (main path; long-running is normal):
+  - `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
+
+- Manual paste fallback:
+  - `oracle --render --copy -p "<task>" --file "src/**"`
+  - Note: `--copy` is a hidden alias for `--copy-markdown`.
+
+## Attaching files (`--file`)
+
+`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.
+
+- Include:
+  - `--file "src/**"`
+  - `--file src/index.ts`
+  - `--file docs --file README.md`
+
+- Exclude:
+  - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"`
+
+- Defaults (implementation behavior):
+  - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files).
+  - Honors `.gitignore` when expanding globs.
+  - Does not follow symlinks.
+  - Dotfiles filtered unless opted in via pattern (e.g. `--file ".github/**"`).
+  - Files > 1 MB rejected.
+
+## Engines (API vs browser)
+
+- Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`.
+- Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/Codex or multi-model runs.
+- Browser attachments:
+  - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads).
+- Remote browser host:
+  - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>`
+  - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"`
+
+## Sessions + slugs
+
+- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
+- Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
+  - List: `oracle status --hours 72`
+  - Attach: `oracle session <id> --render`
+- Use `--slug "<3-5 words>"` to keep session IDs readable.
+- Duplicate prompt guard exists; use `--force` only when you truly want a fresh run.
+
+## Prompt template (high signal)
+
+Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:
+- Project briefing (stack + build/test commands + platform constraints).
+- “Where things live” (key directories, entrypoints, config files, boundaries).
+- Exact question + what you tried + the error text (verbatim).
+- Constraints (“don’t change X”, “must keep public API”, etc).
+- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).
+
+## Safety
+
+- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.
+
+## “Exhaustive prompt” restoration pattern
+
+For long investigations, write a standalone prompt + file set so you can rerun days later:
+- 6–30 sentence project briefing + the goal.
+- Repro steps + exact errors + what you tried.
+- Attach all context files needed (entrypoints, configs, key modules, docs).
+
+Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).

package/skills/ordercli/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ordercli
+description: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).
+homepage: https://ordercli.sh
+metadata: {"clawdbot":{"emoji":"🛵","requires":{"bins":["ordercli"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/ordercli","bins":["ordercli"],"label":"Install ordercli (brew)"},{"id":"go","kind":"go","module":"github.com/steipete/ordercli/cmd/ordercli@latest","bins":["ordercli"],"label":"Install ordercli (go)"}]}}
+---
+
+# ordercli
+
+Use `ordercli` to check past orders and track active order status (Foodora only right now).
+
+Quick start (Foodora)
+- `ordercli foodora countries`
+- `ordercli foodora config set --country AT`
+- `ordercli foodora login --email you@example.com --password-stdin`
+- `ordercli foodora orders`
+- `ordercli foodora history --limit 20`
+- `ordercli foodora history show <orderCode>`
+
+Orders
+- Active list (arrival/status): `ordercli foodora orders`
+- Watch: `ordercli foodora orders --watch`
+- Active order detail: `ordercli foodora order <orderCode>`
+- History detail JSON: `ordercli foodora history show <orderCode> --json`
+
+Reorder (adds to cart)
+- Preview: `ordercli foodora reorder <orderCode>`
+- Confirm: `ordercli foodora reorder <orderCode> --confirm`
+- Address: `ordercli foodora reorder <orderCode> --confirm --address-id <id>`
+
+Cloudflare / bot protection
+- Browser login: `ordercli foodora login --email you@example.com --password-stdin --browser`
+- Reuse profile: `--browser-profile "$HOME/Library/Application Support/ordercli/browser-profile"`
+- Import Chrome cookies: `ordercli foodora cookies chrome --profile "Default"`
+
+Session import (no password)
+- `ordercli foodora session chrome --url https://www.foodora.at/ --profile "Default"`
+- `ordercli foodora session refresh --client-id android`
+
+Deliveroo (WIP, not working yet)
+- Requires `DELIVEROO_BEARER_TOKEN` (optional `DELIVEROO_COOKIE`).
+- `ordercli deliveroo config set --market uk`
+- `ordercli deliveroo history`
+
+Notes
+- Use `--config /tmp/ordercli.json` for testing.
+- Confirm before any reorder or cart-changing action.

package/skills/peekaboo/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: peekaboo
+description: Capture and automate macOS UI with the Peekaboo CLI.
+homepage: https://peekaboo.boo
+metadata: {"clawdbot":{"emoji":"👀","os":["darwin"],"requires":{"bins":["peekaboo"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/peekaboo","bins":["peekaboo"],"label":"Install Peekaboo (brew)"}]}}
+---
+
+# Peekaboo
+
+Peekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI
+elements, drive input, and manage apps/windows/menus. Commands share a snapshot
+cache and support `--json`/`-j` for scripting. Run `peekaboo` or
+`peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata.
+Tip: run via `polter peekaboo` to ensure fresh builds.
+
+## Features (all CLI capabilities, excluding agent/MCP)
+
+Core
+- `bridge`: inspect Peekaboo Bridge host connectivity
+- `capture`: live capture or video ingest + frame extraction
+- `clean`: prune snapshot cache and temp files
+- `config`: init/show/edit/validate, providers, models, credentials
+- `image`: capture screenshots (screen/window/menu bar regions)
+- `learn`: print the full agent guide + tool catalog
+- `list`: apps, windows, screens, menubar, permissions
+- `permissions`: check Screen Recording/Accessibility status
+- `run`: execute `.peekaboo.json` scripts
+- `sleep`: pause execution for a duration
+- `tools`: list available tools with filtering/display options
+
+Interaction
+- `click`: target by ID/query/coords with smart waits
+- `drag`: drag & drop across elements/coords/Dock
+- `hotkey`: modifier combos like `cmd,shift,t`
+- `move`: cursor positioning with optional smoothing
+- `paste`: set clipboard -> paste -> restore
+- `press`: special-key sequences with repeats
+- `scroll`: directional scrolling (targeted + smooth)
+- `swipe`: gesture-style drags between targets
+- `type`: text + control keys (`--clear`, delays)
+
+System
+- `app`: launch/quit/relaunch/hide/unhide/switch/list apps
+- `clipboard`: read/write clipboard (text/images/files)
+- `dialog`: click/input/file/dismiss/list system dialogs
+- `dock`: launch/right-click/hide/show/list Dock items
+- `menu`: click/list application menus + menu extras
+- `menubar`: list/click status bar items
+- `open`: enhanced `open` with app targeting + JSON payloads
+- `space`: list/switch/move-window (Spaces)
+- `visualizer`: exercise Peekaboo visual feedback animations
+- `window`: close/minimize/maximize/move/resize/focus/list
+
+Vision
+- `see`: annotated UI maps, snapshot IDs, optional analysis
+
+Global runtime flags
+- `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>`
+- `--no-remote`, `--bridge-socket <path>`
+
+## Quickstart (happy path)
+```bash
+peekaboo permissions
+peekaboo list apps --json
+peekaboo see --annotate --path /tmp/peekaboo-see.png
+peekaboo click --on B1
+peekaboo type "Hello" --return
+```
+
+## Common targeting parameters (most interaction commands)
+- App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index`
+- Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest)
+- Element/coords: `--on`/`--id` (element ID), `--coords x,y`
+- Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`,
+  `--focus-timeout-seconds`, `--focus-retry-count`
+
+## Common capture parameters
+- Output: `--path`, `--format png|jpg`, `--retina`
+- Targeting: `--mode screen|window|frontmost`, `--screen-index`,
+  `--window-title`, `--window-id`
+- Analysis: `--analyze "prompt"`, `--annotate`
+- Capture engine: `--capture-engine auto|classic|cg|modern|sckit`
+
+## Common motion/typing parameters
+- Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press)
+- Human-ish movement: `--profile human|linear`, `--wpm` (typing)
+- Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth`
+
+## Examples
+### See -> click -> type (most reliable flow)
+```bash
+peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
+peekaboo click --on B3 --app Safari
+peekaboo type "user@example.com" --app Safari
+peekaboo press tab --count 1 --app Safari
+peekaboo type "supersecret" --app Safari --return
+```
+
+### Target by window id
+```bash
+peekaboo list windows --app "Visual Studio Code" --json
+peekaboo click --window-id 12345 --coords 120,160
+peekaboo type "Hello from Peekaboo" --window-id 12345
+```
+
+### Capture screenshots + analyze
+```bash
+peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
+peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
+peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"
+```
+
+### Live capture (motion-aware)
+```bash
+peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
+  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture
+```
+
+### App + window management
+```bash
+peekaboo app launch "Safari" --open https://example.com
+peekaboo window focus --app Safari --window-title "Example"
+peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
+peekaboo app quit --app Safari
+```
+
+### Menus, menubar, dock
+```bash
+peekaboo menu click --app Safari --item "New Window"
+peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
+peekaboo menu click-extra --title "WiFi"
+peekaboo dock launch Safari
+peekaboo menubar list --json
+```
+
+### Mouse + gesture input
+```bash
+peekaboo move 500,300 --smooth
+peekaboo drag --from B1 --to T2
+peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
+peekaboo scroll --direction down --amount 6 --smooth
+```
+
+### Keyboard input
+```bash
+peekaboo hotkey --keys "cmd,shift,t"
+peekaboo press escape
+peekaboo type "Line 1\nLine 2" --delay 10
+```
+
+Notes
+- Requires Screen Recording + Accessibility permissions.
+- Use `peekaboo see --annotate` to identify targets before clicking.

package/skills/qmd/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: qmd
+description: Local search/indexing CLI (BM25 + vectors + rerank) with MCP mode.
+homepage: https://tobi.lutke.com
+metadata: {"clawdbot":{"emoji":"📝","requires":{"bins":["qmd"]},"install":[{"id":"node","kind":"node","package":"https://github.com/tobi/qmd","bins":["qmd"],"label":"Install qmd (node)"}]}}
+---
+
+# qmd
+
+Use `qmd` to index local files and search them.
+
+Indexing
+- Add collection: `qmd collection add /path --name docs --mask "**/*.md"`
+- Update index: `qmd update`
+- Status: `qmd status`
+
+Search
+- BM25: `qmd search "query"`
+- Vector: `qmd vsearch "query"`
+- Hybrid: `qmd query "query"`
+- Get doc: `qmd get docs/path.md:10 -l 40`
+
+Notes
+- Embeddings/rerank use Ollama at `OLLAMA_URL` (default `http://localhost:11434`).
+- Index lives under `~/.cache/qmd` by default.
+- MCP mode: `qmd mcp`.

package/skills/sag/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: sag
+description: ElevenLabs text-to-speech with mac-style say UX.
+homepage: https://sag.sh
+metadata: {"clawdbot":{"emoji":"🗣️","requires":{"bins":["sag"],"env":["ELEVENLABS_API_KEY"]},"primaryEnv":"ELEVENLABS_API_KEY","install":[{"id":"brew","kind":"brew","formula":"steipete/tap/sag","bins":["sag"],"label":"Install sag (brew)"}]}}
+---
+
+# sag
+
+Use `sag` for ElevenLabs TTS with local playback.
+
+API key (required)
+- `ELEVENLABS_API_KEY` (preferred)
+- `SAG_API_KEY` also supported by the CLI
+
+Quick start
+- `sag "Hello there"`
+- `sag speak -v "Roger" "Hello"`
+- `sag voices`
+- `sag prompting` (model-specific tips)
+
+Model notes
+- Default: `eleven_v3` (expressive)
+- Stable: `eleven_multilingual_v2`
+- Fast: `eleven_flash_v2_5`
+
+Pronunciation + delivery rules
+- First fix: respell (e.g. "key-note"), add hyphens, adjust casing.
+- Numbers/units/URLs: `--normalize auto` (or `off` if it harms names).
+- Language bias: `--lang en|de|fr|...` to guide normalization.
+- v3: SSML `<break>` not supported; use `[pause]`, `[short pause]`, `[long pause]`.
+- v2/v2.5: SSML `<break time="1.5s" />` supported; `<phoneme>` not exposed in `sag`.
+
+v3 audio tags (put at the entrance of a line)
+- `[whispers]`, `[shouts]`, `[sings]`
+- `[laughs]`, `[starts laughing]`, `[sighs]`, `[exhales]`
+- `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[mischievously]`
+- Example: `sag "[whispers] keep this quiet. [short pause] ok?"`
+
+Voice defaults
+- `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`
+
+Confirm voice + speaker before long output.
+
+## Chat voice responses
+
+When Peter asks for a "voice" reply (e.g., "crazy scientist voice", "explain in voice"), generate audio and send it:
+
+```bash
+# Generate audio file
+sag -v Clawd -o /tmp/voice-reply.mp3 "Your message here"
+
+# Then include in reply:
+# MEDIA:/tmp/voice-reply.mp3
+```
+
+Voice character tips:
+- Crazy scientist: Use `[excited]` tags, dramatic pauses `[short pause]`, vary intensity
+- Calm: Use `[whispers]` or slower pacing
+- Dramatic: Use `[sings]` or `[shouts]` sparingly
+
+Default voice for Clawd: `lj2rcrvANS3gaWWnczSX` (or just `-v Clawd`)

package/skills/slack/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: slack
+description: Use when you need to control Slack from Clawdbot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
+---
+
+# Slack Actions
+
+## Overview
+
+Use `slack` to react, manage pins, send/edit/delete messages, and fetch member info. The tool uses the bot token configured for Clawdbot.
+
+## Inputs to collect
+
+- `channelId` and `messageId` (Slack message timestamp, e.g. `1712023032.1234`).
+- For reactions, an `emoji` (Unicode or `:name:`).
+- For message sends, a `to` target (`channel:<id>` or `user:<id>`) and `content`.
+
+Message context lines include `slack message id` and `channel` fields you can reuse directly.
+
+## Actions
+
+### Action groups
+
+| Action group | Default | Notes |
+| --- | --- | --- |
+| reactions | enabled | React + list reactions |
+| messages | enabled | Read/send/edit/delete |
+| pins | enabled | Pin/unpin/list |
+| memberInfo | enabled | Member info |
+| emojiList | enabled | Custom emoji list |
+
+### React to a message
+
+```json
+{
+  "action": "react",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "emoji": "✅"
+}
+```
+
+### List reactions
+
+```json
+{
+  "action": "reactions",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Send a message
+
+```json
+{
+  "action": "sendMessage",
+  "to": "channel:C123",
+  "content": "Hello from Clawdbot"
+}
+```
+
+### Edit a message
+
+```json
+{
+  "action": "editMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234",
+  "content": "Updated text"
+}
+```
+
+### Delete a message
+
+```json
+{
+  "action": "deleteMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Read recent messages
+
+```json
+{
+  "action": "readMessages",
+  "channelId": "C123",
+  "limit": 20
+}
+```
+
+### Pin a message
+
+```json
+{
+  "action": "pinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### Unpin a message
+
+```json
+{
+  "action": "unpinMessage",
+  "channelId": "C123",
+  "messageId": "1712023032.1234"
+}
+```
+
+### List pinned items
+
+```json
+{
+  "action": "listPins",
+  "channelId": "C123"
+}
+```
+
+### Member info
+
+```json
+{
+  "action": "memberInfo",
+  "userId": "U123"
+}
+```
+
+### Emoji list
+
+```json
+{
+  "action": "emojiList"
+}
+```
+
+## Ideas to try
+
+- React with ✅ to mark completed tasks.
+- Pin key decisions or weekly status updates.

package/skills/songsee/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: songsee
+description: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.
+homepage: https://github.com/steipete/songsee
+metadata: {"clawdbot":{"emoji":"🌊","requires":{"bins":["songsee"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/songsee","bins":["songsee"],"label":"Install songsee (brew)"}]}}
+---
+
+# songsee
+
+Generate spectrograms + feature panels from audio.
+
+Quick start
+- Spectrogram: `songsee track.mp3`
+- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`
+- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`
+- Stdin: `cat track.mp3 | songsee - --format png -o out.png`
+
+Common flags
+- `--viz` list (repeatable or comma-separated)
+- `--style` palette (classic, magma, inferno, viridis, gray)
+- `--width` / `--height` output size
+- `--window` / `--hop` FFT settings
+- `--min-freq` / `--max-freq` frequency range
+- `--start` / `--duration` time slice
+- `--format` jpg|png
+
+Notes
+- WAV/MP3 decode native; other formats use ffmpeg if available.
+- Multiple `--viz` renders a grid.