@spinabot/brigade 0.1.1 → 1.0.0

package/skills/peekaboo/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: peekaboo
+description: Capture and automate macOS UI with the Peekaboo CLI.
+homepage: https://peekaboo.boo
+metadata:
+  {
+    "brigade":
+      {
+        "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/sag/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: sag
+description: ElevenLabs text-to-speech with mac-style say UX.
+homepage: https://sag.sh
+metadata:
+  {
+    "brigade":
+      {
+        "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 the user asks for a "voice" reply (e.g., "crazy scientist voice", "explain in voice"), generate audio and send it:
+
+```bash
+# Generate audio file
+sag -v Rachel -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 Rachel: `lj2rcrvANS3gaWWnczSX` (or just `-v Rachel`)

package/skills/session-logs/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: session-logs
+description: Search and analyze your own session logs (older/parent conversations) using jq.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📜",
+        "requires": { "bins": ["jq", "rg"] },
+        "install":
+          [
+            {
+              "id": "brew-jq",
+              "kind": "brew",
+              "formula": "jq",
+              "bins": ["jq"],
+              "label": "Install jq (brew)",
+            },
+            {
+              "id": "brew-rg",
+              "kind": "brew",
+              "formula": "ripgrep",
+              "bins": ["rg"],
+              "label": "Install ripgrep (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# session-logs
+
+Search your complete conversation history stored in session JSONL files. Use this when a user references older/parent conversations or asks what was said before.
+
+## Trigger
+
+Use this skill when the user asks about prior chats, parent conversations, or historical context that isn't in memory files.
+
+## Location
+
+Session logs live under the active state directory:
+`$BRIGADE_STATE_DIR/agents/<agentId>/sessions/` (default: `~/.brigade/agents/<agentId>/sessions/`).
+Use the `agent=<id>` value from the system prompt Runtime line.
+
+- **`sessions.json`** - Index mapping session keys to session IDs
+- **`<session-id>.jsonl`** - Full conversation transcript per session
+
+## Structure
+
+Each `.jsonl` file contains messages with:
+
+- `type`: "session" (metadata) or "message"
+- `timestamp`: ISO timestamp
+- `message.role`: "user", "assistant", or "toolResult"
+- `message.content[]`: Text, thinking, or tool calls (filter `type=="text"` for human-readable content)
+- `message.usage.cost.total`: Cost per response
+
+## Common Queries
+
+### List all sessions by date and size
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  size=$(ls -lh "$f" | awk '{print $5}')
+  echo "$date $size $(basename $f)"
+done | sort -r
+```
+
+### Find sessions from a specific day
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  head -1 "$f" | jq -r '.timestamp' | grep -q "2026-01-06" && echo "$f"
+done
+```
+
+### Extract user messages from a session
+
+```bash
+jq -r 'select(.message.role == "user") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl
+```
+
+### Search for keyword in assistant responses
+
+```bash
+jq -r 'select(.message.role == "assistant") | .message.content[]? | select(.type == "text") | .text' <session>.jsonl | rg -i "keyword"
+```
+
+### Get total cost for a session
+
+```bash
+jq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl
+```
+
+### Daily cost summary
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}/agents/$AGENT_ID/sessions"
+for f in "$SESSION_DIR"/*.jsonl; do
+  date=$(head -1 "$f" | jq -r '.timestamp' | cut -dT -f1)
+  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' "$f")
+  echo "$date $cost"
+done | awk '{a[$1]+=$2} END {for(d in a) print d, "$"a[d]}' | sort -r
+```
+
+### Count messages and tokens in a session
+
+```bash
+jq -s '{
+  messages: length,
+  user: [.[] | select(.message.role == "user")] | length,
+  assistant: [.[] | select(.message.role == "assistant")] | length,
+  first: .[0].timestamp,
+  last: .[-1].timestamp
+}' <session>.jsonl
+```
+
+### Tool usage breakdown
+
+```bash
+jq -r '.message.content[]? | select(.type == "toolCall") | .name' <session>.jsonl | sort | uniq -c | sort -rn
+```
+
+### Search across ALL sessions for a phrase
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}/agents/$AGENT_ID/sessions"
+rg -l "phrase" "$SESSION_DIR"/*.jsonl
+```
+
+## Tips
+
+- Sessions are append-only JSONL (one JSON object per line)
+- Large sessions can be several MB - use `head`/`tail` for sampling
+- The `sessions.json` index maps chat providers (discord, whatsapp, etc.) to session IDs
+- Deleted sessions have `.deleted.<timestamp>` suffix
+
+## Fast text-only hint (low noise)
+
+```bash
+AGENT_ID="<agentId>"
+SESSION_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}/agents/$AGENT_ID/sessions"
+jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' "$SESSION_DIR"/<id>.jsonl | rg 'keyword'
+```

package/skills/share-skills/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: share-skills
+description: Use when you need to author, package, or share a skill folder — understanding the SKILL.md format, where skills live, and how to bundle a folder so it can be shared with others.
+---
+
+# Sharing Skills
+
+This skill explains how skills are structured and how to package one for sharing. It is a companion to skill authoring: where skill-creator helps you write a skill, this covers laying it out correctly and bundling it to hand off.
+
+## Where skills live
+
+Each skill is a folder under the `skills/` directory. The folder name is the skill's identity and must match the `name` field in its frontmatter (lowercase). At minimum a skill folder contains a `SKILL.md`; it may also include supporting files (scripts, reference docs, assets) the skill refers to.
+
+```
+skills/
+  my-skill/
+    SKILL.md
+    reference.md        # optional supporting docs
+    scripts/run.sh      # optional helper scripts
+```
+
+## SKILL.md format
+
+A `SKILL.md` is a Markdown file with a YAML frontmatter block followed by the skill body.
+
+```yaml
+---
+name: my-skill          # must equal the folder name, lowercase
+description: Use when ...  # the "use when" trigger guidance, product-free
+# optional eligibility keys (omit any that don't apply):
+os: [darwin, linux]       # OS restriction
+requires-bins: [foo]      # binaries that MUST be present
+requires-any-bins: [a, b] # at least one of these binaries
+requires-env: [MY_TOKEN]  # required environment variables
+---
+```
+
+Body guidelines:
+
+- Open with a short overview of what the skill does and when to reach for it.
+- Keep instructions truthful: only describe actions the runtime can actually perform.
+- Reference any supporting files by relative path within the folder.
+- Keep it lean — the description and metadata are what get surfaced; the body is read on demand.
+
+## Versioning a shared skill
+
+When you intend to share a skill, keep a changelog note and a version in mind so recipients can tell revisions apart. A simple convention is a `## Changelog` section at the bottom of `SKILL.md` or a sibling `CHANGELOG.md`.
+
+## Packaging a folder to share
+
+To share a skill, bundle its entire folder (so supporting files travel with it) and hand it off as an archive.
+
+```bash
+# from the skills/ directory, archive a single skill folder
+tar -czf my-skill.tar.gz my-skill/
+```
+
+The recipient unpacks the archive into their own `skills/` directory:
+
+```bash
+tar -xzf my-skill.tar.gz -C ./skills/
+```
+
+After unpacking, confirm the folder name still matches the `name` in frontmatter and that any `requires-*` eligibility keys are accurate for the new environment.
+
+## Checklist before sharing
+
+- `name` equals the folder name (lowercase).
+- `description` is present and free of product names.
+- Eligibility keys (`os` / `requires-bins` / `requires-any-bins` / `requires-env`) reflect real requirements — omit them when there are none.
+- Supporting files are inside the folder and referenced by relative path.
+- The body never instructs calling a tool the runtime does not have.

package/skills/sherpa-onnx-tts/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: sherpa-onnx-tts
+description: Local text-to-speech via sherpa-onnx (offline, no cloud)
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "🔉",
+        "os": ["darwin", "linux", "win32"],
+        "requires": { "env": ["SHERPA_ONNX_RUNTIME_DIR", "SHERPA_ONNX_MODEL_DIR"] },
+        "install":
+          [
+            {
+              "id": "download-runtime-macos",
+              "kind": "download",
+              "os": ["darwin"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-osx-universal2-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (macOS)",
+            },
+            {
+              "id": "download-runtime-linux-x64",
+              "kind": "download",
+              "os": ["linux"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-linux-x64-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (Linux x64)",
+            },
+            {
+              "id": "download-runtime-win-x64",
+              "kind": "download",
+              "os": ["win32"],
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-win-x64-shared.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "stripComponents": 1,
+              "targetDir": "runtime",
+              "label": "Download sherpa-onnx runtime (Windows x64)",
+            },
+            {
+              "id": "download-model-lessac",
+              "kind": "download",
+              "url": "https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-high.tar.bz2",
+              "archive": "tar.bz2",
+              "extract": true,
+              "targetDir": "models",
+              "label": "Download Piper en_US lessac (high)",
+            },
+          ],
+      },
+  }
+---
+
+# sherpa-onnx-tts
+
+Local TTS using the sherpa-onnx offline CLI.
+
+## Install
+
+1. Download the runtime for your OS (extracts into `$BRIGADE_STATE_DIR/tools/sherpa-onnx-tts/runtime`, default `~/.brigade/tools/sherpa-onnx-tts/runtime`)
+2. Download a voice model (extracts into `$BRIGADE_STATE_DIR/tools/sherpa-onnx-tts/models`, default `~/.brigade/tools/sherpa-onnx-tts/models`)
+
+Resolve the active state directory first:
+
+```bash
+STATE_DIR="${BRIGADE_STATE_DIR:-$HOME/.brigade}"
+```
+
+Then write those resolved paths into the active Brigade config file (`$BRIGADE_CONFIG_PATH`, default `~/.brigade/brigade.json`):
+
+```json5
+{
+  skills: {
+    entries: {
+      "sherpa-onnx-tts": {
+        env: {
+          SHERPA_ONNX_RUNTIME_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/runtime",
+          SHERPA_ONNX_MODEL_DIR: "/path/to/your/state-dir/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high",
+        },
+      },
+    },
+  },
+}
+```
+
+The wrapper lives in this skill folder. Run it directly, or add the wrapper to PATH:
+
+```bash
+export PATH="{baseDir}/bin:$PATH"
+```
+
+## Usage
+
+```bash
+{baseDir}/bin/sherpa-onnx-tts -o ./tts.wav "Hello from local TTS."
+```
+
+Notes:
+
+- Pick a different model from the sherpa-onnx `tts-models` release if you want another voice.
+- If the model dir has multiple `.onnx` files, set `SHERPA_ONNX_MODEL_FILE` or pass `--model-file`.
+- You can also pass `--tokens-file` or `--data-dir` to override the defaults.
+- Windows: run `node {baseDir}\\bin\\sherpa-onnx-tts -o tts.wav "Hello from local TTS."`