0xkobold 0.0.1

package/skills/tmux/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: tmux
+description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.
+metadata:
+  { "kobold": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } } }
+---
+
+# tmux Session Control
+
+Control tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.
+
+## When to Use
+
+✅ **USE this skill when:**
+
+- Monitoring Claude/Codex sessions in tmux
+- Sending input to interactive terminal applications
+- Scraping output from long-running processes in tmux
+- Navigating tmux panes/windows programmatically
+- Checking on background work in existing sessions
+
+## When NOT to Use
+
+❌ **DON'T use this skill when:**
+
+- Running one-off shell commands → use `exec` tool directly
+- Starting new background processes → use `exec` with `background:true`
+- Non-interactive scripts → use `exec` tool
+- The process isn't in tmux
+- You need to create a new tmux session → use `exec` with `tmux new-session`
+
+## Example Sessions
+
+| Session                 | Purpose                     |
+| ----------------------- | --------------------------- |
+| `shared`                | Primary interactive session |
+| `worker-2` - `worker-8` | Parallel worker sessions    |
+
+## Common Commands
+
+### List Sessions
+
+```bash
+tmux list-sessions
+tmux ls
+```
+
+### Capture Output
+
+```bash
+# Last 20 lines of pane
+tmux capture-pane -t shared -p | tail -20
+
+# Entire scrollback
+tmux capture-pane -t shared -p -S -
+
+# Specific pane in window
+tmux capture-pane -t shared:0.0 -p
+```
+
+### Send Keys
+
+```bash
+# Send text (doesn't press Enter)
+tmux send-keys -t shared "hello"
+
+# Send text + Enter
+tmux send-keys -t shared "y" Enter
+
+# Send special keys
+tmux send-keys -t shared Enter
+tmux send-keys -t shared Escape
+tmux send-keys -t shared C-c          # Ctrl+C
+tmux send-keys -t shared C-d          # Ctrl+D (EOF)
+tmux send-keys -t shared C-z          # Ctrl+Z (suspend)
+```
+
+### Window/Pane Navigation
+
+```bash
+# Select window
+tmux select-window -t shared:0
+
+# Select pane
+tmux select-pane -t shared:0.1
+
+# List windows
+tmux list-windows -t shared
+```
+
+### Session Management
+
+```bash
+# Create new session
+tmux new-session -d -s newsession
+
+# Kill session
+tmux kill-session -t sessionname
+
+# Rename session
+tmux rename-session -t old new
+```
+
+## Sending Input Safely
+
+For interactive TUIs (Claude Code, Codex, etc.), split text and Enter into separate sends to avoid paste/multiline edge cases:
+
+```bash
+tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
+sleep 0.1
+tmux send-keys -t shared Enter
+```
+
+## Claude Code Session Patterns
+
+### Check if Session Needs Input
+
+```bash
+# Look for prompts
+tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"
+```
+
+### Approve Claude Code Prompt
+
+```bash
+# Send 'y' and Enter
+tmux send-keys -t worker-3 'y' Enter
+
+# Or select numbered option
+tmux send-keys -t worker-3 '2' Enter
+```
+
+### Check All Sessions Status
+
+```bash
+for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
+  echo "=== $s ==="
+  tmux capture-pane -t $s -p 2>/dev/null | tail -5
+done
+```
+
+### Send Task to Session
+
+```bash
+tmux send-keys -t worker-4 "Fix the bug in auth.js" Enter
+```
+
+## Notes
+
+- Use `capture-pane -p` to print to stdout (essential for scripting)
+- `-S -` captures entire scrollback history
+- Target format: `session:window.pane` (e.g., `shared:0.0`)
+- Sessions persist across SSH disconnects

package/skills/tmux/scripts/find-sessions.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]
+
+List tmux sessions on a socket (default tmux socket if none provided).
+
+Options:
+  -L, --socket       tmux socket name (passed to tmux -L)
+  -S, --socket-path  tmux socket path (passed to tmux -S)
+  -A, --all          scan all sockets under KOBOLD_TMUX_SOCKET_DIR
+  -q, --query        case-insensitive substring to filter session names
+  -h, --help         show this help
+USAGE
+}
+
+socket_name=""
+socket_path=""
+query=""
+scan_all=false
+socket_dir="${KOBOLD_TMUX_SOCKET_DIR:-${KOBOLDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/kobold-tmux-sockets}}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -L|--socket)      socket_name="${2-}"; shift 2 ;;
+    -S|--socket-path) socket_path="${2-}"; shift 2 ;;
+    -A|--all)         scan_all=true; shift ;;
+    -q|--query)       query="${2-}"; shift 2 ;;
+    -h|--help)        usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ "$scan_all" == true && ( -n "$socket_name" || -n "$socket_path" ) ]]; then
+  echo "Cannot combine --all with -L or -S" >&2
+  exit 1
+fi
+
+if [[ -n "$socket_name" && -n "$socket_path" ]]; then
+  echo "Use either -L or -S, not both" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+list_sessions() {
+  local label="$1"; shift
+  local tmux_cmd=(tmux "$@")
+
+  if ! sessions="$("${tmux_cmd[@]}" list-sessions -F '#{session_name}\t#{session_attached}\t#{session_created_string}' 2>/dev/null)"; then
+    echo "No tmux server found on $label" >&2
+    return 1
+  fi
+
+  if [[ -n "$query" ]]; then
+    sessions="$(printf '%s\n' "$sessions" | grep -i -- "$query" || true)"
+  fi
+
+  if [[ -z "$sessions" ]]; then
+    echo "No sessions found on $label"
+    return 0
+  fi
+
+  echo "Sessions on $label:"
+  printf '%s\n' "$sessions" | while IFS=$'\t' read -r name attached created; do
+    attached_label=$([[ "$attached" == "1" ]] && echo "attached" || echo "detached")
+    printf '  - %s (%s, started %s)\n' "$name" "$attached_label" "$created"
+  done
+}
+
+if [[ "$scan_all" == true ]]; then
+  if [[ ! -d "$socket_dir" ]]; then
+    echo "Socket directory not found: $socket_dir" >&2
+    exit 1
+  fi
+
+  shopt -s nullglob
+  sockets=("$socket_dir"/*)
+  shopt -u nullglob
+
+  if [[ "${#sockets[@]}" -eq 0 ]]; then
+    echo "No sockets found under $socket_dir" >&2
+    exit 1
+  fi
+
+  exit_code=0
+  for sock in "${sockets[@]}"; do
+    if [[ ! -S "$sock" ]]; then
+      continue
+    fi
+    list_sessions "socket path '$sock'" -S "$sock" || exit_code=$?
+  done
+  exit "$exit_code"
+fi
+
+tmux_cmd=(tmux)
+socket_label="default socket"
+
+if [[ -n "$socket_name" ]]; then
+  tmux_cmd+=(-L "$socket_name")
+  socket_label="socket name '$socket_name'"
+elif [[ -n "$socket_path" ]]; then
+  tmux_cmd+=(-S "$socket_path")
+  socket_label="socket path '$socket_path'"
+fi
+
+list_sessions "$socket_label" "${tmux_cmd[@]:1}"

package/skills/tmux/scripts/wait-for-text.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage: wait-for-text.sh -t target -p pattern [options]
+
+Poll a tmux pane for text and exit when found.
+
+Options:
+  -t, --target    tmux target (session:window.pane), required
+  -p, --pattern   regex pattern to look for, required
+  -F, --fixed     treat pattern as a fixed string (grep -F)
+  -T, --timeout   seconds to wait (integer, default: 15)
+  -i, --interval  poll interval in seconds (default: 0.5)
+  -l, --lines     number of history lines to inspect (integer, default: 1000)
+  -h, --help      show this help
+USAGE
+}
+
+target=""
+pattern=""
+grep_flag="-E"
+timeout=15
+interval=0.5
+lines=1000
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -t|--target)   target="${2-}"; shift 2 ;;
+    -p|--pattern)  pattern="${2-}"; shift 2 ;;
+    -F|--fixed)    grep_flag="-F"; shift ;;
+    -T|--timeout)  timeout="${2-}"; shift 2 ;;
+    -i|--interval) interval="${2-}"; shift 2 ;;
+    -l|--lines)    lines="${2-}"; shift 2 ;;
+    -h|--help)     usage; exit 0 ;;
+    *) echo "Unknown option: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$target" || -z "$pattern" ]]; then
+  echo "target and pattern are required" >&2
+  usage
+  exit 1
+fi
+
+if ! [[ "$timeout" =~ ^[0-9]+$ ]]; then
+  echo "timeout must be an integer number of seconds" >&2
+  exit 1
+fi
+
+if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+  echo "lines must be an integer" >&2
+  exit 1
+fi
+
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "tmux not found in PATH" >&2
+  exit 1
+fi
+
+# End time in epoch seconds (integer, good enough for polling)
+start_epoch=$(date +%s)
+deadline=$((start_epoch + timeout))
+
+while true; do
+  # -J joins wrapped lines, -S uses negative index to read last N lines
+  pane_text="$(tmux capture-pane -p -J -t "$target" -S "-${lines}" 2>/dev/null || true)"
+
+  if printf '%s\n' "$pane_text" | grep $grep_flag -- "$pattern" >/dev/null 2>&1; then
+    exit 0
+  fi
+
+  now=$(date +%s)
+  if (( now >= deadline )); then
+    echo "Timed out after ${timeout}s waiting for pattern: $pattern" >&2
+    echo "Last ${lines} lines from $target:" >&2
+    printf '%s\n' "$pane_text" >&2
+    exit 1
+  fi
+
+  sleep "$interval"
+done

package/skills/trello/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: trello
+description: Manage Trello boards, lists, and cards via the Trello REST API.
+homepage: https://developer.atlassian.com/cloud/trello/rest/
+metadata:
+  {
+    "kobold":
+      { "emoji": "📋", "requires": { "bins": ["jq"], "env": ["TRELLO_API_KEY", "TRELLO_TOKEN"] } },
+  }
+---
+
+# Trello Skill
+
+Manage Trello boards, lists, and cards directly from Kobold.
+
+## Setup
+
+1. Get your API key: https://trello.com/app-key
+2. Generate a token (click "Token" link on that page)
+3. Set environment variables:
+   ```bash
+   export TRELLO_API_KEY="your-api-key"
+   export TRELLO_TOKEN="your-token"
+   ```
+
+## Usage
+
+All commands use curl to hit the Trello REST API.
+
+### List boards
+
+```bash
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id}'
+```
+
+### List lists in a board
+
+```bash
+curl -s "https://api.trello.com/1/boards/{boardId}/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id}'
+```
+
+### List cards in a list
+
+```bash
+curl -s "https://api.trello.com/1/lists/{listId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id, desc}'
+```
+
+### Create a card
+
+```bash
+curl -s -X POST "https://api.trello.com/1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList={listId}" \
+  -d "name=Card Title" \
+  -d "desc=Card description"
+```
+
+### Move a card to another list
+
+```bash
+curl -s -X PUT "https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "idList={newListId}"
+```
+
+### Add a comment to a card
+
+```bash
+curl -s -X POST "https://api.trello.com/1/cards/{cardId}/actions/comments?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "text=Your comment here"
+```
+
+### Archive a card
+
+```bash
+curl -s -X PUT "https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" \
+  -d "closed=true"
+```
+
+## Notes
+
+- Board/List/Card IDs can be found in the Trello URL or via the list commands
+- The API key and token provide full access to your Trello account - keep them secret!
+- Rate limits: 300 requests per 10 seconds per API key; 100 requests per 10 seconds per token; `/1/members` endpoints are limited to 100 requests per 900 seconds
+
+## Examples
+
+```bash
+# Get all boards
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&fields=name,id" | jq
+
+# Find a specific board by name
+curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | select(.name | contains("Work"))'
+
+# Get all cards on a board
+curl -s "https://api.trello.com/1/boards/{boardId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, list: .idList}'
+```

package/skills/video-frames/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: video-frames
+description: Extract frames or short clips from videos using ffmpeg.
+homepage: https://ffmpeg.org
+metadata:
+  {
+    "kobold":
+      {
+        "emoji": "🎞️",
+        "requires": { "bins": ["ffmpeg"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "ffmpeg",
+              "bins": ["ffmpeg"],
+              "label": "Install ffmpeg (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# Video Frames (ffmpeg)
+
+Extract a single frame from a video, or create quick thumbnails for inspection.
+
+## Quick start
+
+First frame:
+
+```bash
+{baseDir}/scripts/frame.sh /path/to/video.mp4 --out /tmp/frame.jpg
+```
+
+At a timestamp:
+
+```bash
+{baseDir}/scripts/frame.sh /path/to/video.mp4 --time 00:00:10 --out /tmp/frame-10s.jpg
+```
+
+## Notes
+
+- Prefer `--time` for “what is happening around here?”.
+- Use a `.jpg` for quick share; use `.png` for crisp UI frames.

package/skills/video-frames/scripts/frame.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat >&2 <<'EOF'
+Usage:
+  frame.sh <video-file> [--time HH:MM:SS] [--index N] --out /path/to/frame.jpg
+
+Examples:
+  frame.sh video.mp4 --out /tmp/frame.jpg
+  frame.sh video.mp4 --time 00:00:10 --out /tmp/frame-10s.jpg
+  frame.sh video.mp4 --index 0 --out /tmp/frame0.png
+EOF
+  exit 2
+}
+
+if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+fi
+
+in="${1:-}"
+shift || true
+
+time=""
+index=""
+out=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --time)
+      time="${2:-}"
+      shift 2
+      ;;
+    --index)
+      index="${2:-}"
+      shift 2
+      ;;
+    --out)
+      out="${2:-}"
+      shift 2
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+if [[ ! -f "$in" ]]; then
+  echo "File not found: $in" >&2
+  exit 1
+fi
+
+if [[ "$out" == "" ]]; then
+  echo "Missing --out" >&2
+  usage
+fi
+
+mkdir -p "$(dirname "$out")"
+
+if [[ "$index" != "" ]]; then
+  ffmpeg -hide_banner -loglevel error -y \
+    -i "$in" \
+    -vf "select=eq(n\\,${index})" \
+    -vframes 1 \
+    "$out"
+elif [[ "$time" != "" ]]; then
+  ffmpeg -hide_banner -loglevel error -y \
+    -ss "$time" \
+    -i "$in" \
+    -frames:v 1 \
+    "$out"
+else
+  ffmpeg -hide_banner -loglevel error -y \
+    -i "$in" \
+    -vf "select=eq(n\\,0)" \
+    -vframes 1 \
+    "$out"
+fi
+
+echo "$out"

package/skills/voice-call/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: voice-call
+description: Start voice calls via the Kobold voice-call plugin.
+metadata:
+  {
+    "kobold":
+      {
+        "emoji": "📞",
+        "skillKey": "voice-call",
+        "requires": { "config": ["plugins.entries.voice-call.enabled"] },
+      },
+  }
+---
+
+# Voice Call
+
+Use the voice-call plugin to start or inspect calls (Twilio, Telnyx, Plivo, or mock).
+
+## CLI
+
+```bash
+kobold voicecall call --to "+15555550123" --message "Hello from Kobold"
+kobold voicecall status --call-id <id>
+```
+
+## Tool
+
+Use `voice_call` for agent-initiated calls.
+
+Actions:
+
+- `initiate_call` (message, to?, mode?)
+- `continue_call` (callId, message)
+- `speak_to_user` (callId, message)
+- `end_call` (callId)
+- `get_status` (callId)
+
+Notes:
+
+- Requires the voice-call plugin to be enabled.
+- Plugin config lives under `plugins.entries.voice-call.config`.
+- Twilio config: `provider: "twilio"` + `twilio.accountSid/authToken` + `fromNumber`.
+- Telnyx config: `provider: "telnyx"` + `telnyx.apiKey/connectionId` + `fromNumber`.
+- Plivo config: `provider: "plivo"` + `plivo.authId/authToken` + `fromNumber`.
+- Dev fallback: `provider: "mock"` (no network).

package/skills/wacli/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wacli
+description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).
+homepage: https://wacli.sh
+metadata:
+  {
+    "kobold":
+      {
+        "emoji": "📱",
+        "requires": { "bins": ["wacli"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "steipete/tap/wacli",
+              "bins": ["wacli"],
+              "label": "Install wacli (brew)",
+            },
+            {
+              "id": "go",
+              "kind": "go",
+              "module": "github.com/steipete/wacli/cmd/wacli@latest",
+              "bins": ["wacli"],
+              "label": "Install wacli (go)",
+            },
+          ],
+      },
+  }
+---
+
+# wacli
+
+Use `wacli` only when the user explicitly asks you to message someone else on WhatsApp or when they ask to sync/search WhatsApp history.
+Do NOT use `wacli` for normal user chats; Kobold routes WhatsApp conversations automatically.
+If the user is chatting with you on WhatsApp, you should not reach for this tool unless they ask you to contact a third party.
+
+Safety
+
+- Require explicit recipient + message text.
+- Confirm recipient + message before sending.
+- If anything is ambiguous, ask a clarifying question.
+
+Auth + sync
+
+- `wacli auth` (QR login + initial sync)
+- `wacli sync --follow` (continuous sync)
+- `wacli doctor`
+
+Find chats + messages
+
+- `wacli chats list --limit 20 --query "name or number"`
+- `wacli messages search "query" --limit 20 --chat <jid>`
+- `wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31`
+
+History backfill
+
+- `wacli history backfill --chat <jid> --requests 2 --count 50`
+
+Send
+
+- Text: `wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"`
+- Group: `wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."`
+- File: `wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"`
+
+Notes
+
+- Store dir: `~/.wacli` (override with `--store`).
+- Use `--json` for machine-readable output when parsing.
+- Backfill requires your phone online; results are best-effort.
+- WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.
+- JIDs: direct chats look like `<number>@s.whatsapp.net`; groups look like `<id>@g.us` (use `wacli chats list` to find).