bot-hub/base/hz_migrations/1709000001_catalog.js at main

mirror of https://github.com/hanzoai/bot-hub.git synced 2026-11-02 20:16:38 +00:00

Files

T

zeekay 214621b6ca Serve the hub at api.hanzo.ai/v1/skills

Every route mounts under /v1/skills, the address api.hanzo.ai routes to
this API; auth, personas, users, tokens, upload, integrations, search and
whoami are sub-resources and RESERVED keeps them from being slugs. The
web, the OG renderers, the CLI's default registry, /.well-known/bothub.json
and openapi.json name api.hanzo.ai. Sign-in calls back to
api.hanzo.ai/v1/skills/auth/callback and hands the token over in the
fragment.

The store starts again. docker-entrypoint.sh read Base's port from
BASE_PORT, which Kubernetes sets to tcp://<ip>:<port> in a namespace
holding a Service named base; Base now listens on 127.0.0.1:8090, fixed.
The collections migration is rewritten for the Base the Dockerfile pins
(1.5.91): flat field options, declared created/updated, and the users
collection every Base already has, extended rather than created twice.

Reads are anonymous against public rules, since Base takes IAM
credentials only and no longer serves password sign-in; writes answer
503 saying so. The catalogue migration, generated by scripts/catalog.mjs,
publishes the 83 skills in hanzoai/bot@8be8f1dc7b. /health reports the
store, so the probes restart a pod whose Base is gone.

cache.ts decides caching once: an anonymous 2xx GET is public for a
minute (five at the edge) with a weak ETag and 304s; a credential, a
write or an error is private, no-store. Filter values go through lit().
Embeddings go through api.hanzo.ai and are skipped without a key.

k8s/ was a second declaration of the deployment; universe is the one.

2026-09-30 01:10:48 -07:00

65 lines

506 KiB

JavaScript

Raw Permalink Blame History

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

 /// <reference path="../base_/data/types.d.ts" />
 // GENERATED by scripts/catalog.mjs from github.com/hanzoai/bot@8be8f1dc7bfa7e23f4f77da4293809bfa19b6672/skills.
 // Do not edit; rerun the script.
 //
 // The catalogue: 83 skills Hanzo Bot ships, published by the hanzo account.
 migrate((app) => {
   const catalog = [{"slug":"1password","displayName":"1password","summary":"Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.","version":"1.0.0","sha256hash":"5a3a5e7d07d9228b873145926bd67c323c7894adf1649b17cdf089e10159e676","files":[{"path":"SKILL.md","size":2623,"sha256":"8059f06dc697206b2a83ceabb4b7901a7723dbfaa9b649e97ff6f16e51b9d09b","contentType":"text/markdown","content":"---\nname: 1password\ndescription: Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.\nhomepage: https://developer.1password.com/docs/cli/get-started/\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🔐\",\n        \"requires\": { \"bins\": [\"op\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"1password-cli\",\n              \"bins\": [\"op\"],\n              \"label\": \"Install 1Password CLI (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# 1Password CLI\n\nFollow the official CLI get-started steps. Don't guess install commands.\n\n## References\n\n- `references/get-started.md` (install + app integration + sign-in flow)\n- `references/cli-examples.md` (real `op` examples)\n\n## Workflow\n\n1. Check OS + shell.\n2. Verify CLI present: `op --version`.\n3. Confirm desktop app integration is enabled (per get-started) and the app is unlocked.\n4. REQUIRED: create a fresh tmux session for all `op` commands (no direct `op` calls outside tmux).\n5. Sign in / authorize inside tmux: `op signin` (expect app prompt).\n6. Verify access inside tmux: `op whoami` (must succeed before any secret read).\n7. If multiple accounts: use `--account` or `OP_ACCOUNT`.\n\n## REQUIRED tmux session (T-Max)\n\nThe shell tool uses a fresh TTY per command. To avoid re-prompts and failures, always run `op` inside a dedicated tmux session with a fresh socket/session name.\n\nExample (see `tmux` skill for socket conventions, do not reuse old session names):\n\n```bash\nSOCKET_DIR=\"${BOT_TMUX_SOCKET_DIR:-${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/hanzo-bot-tmux-sockets}}\"\nmkdir -p \"$SOCKET_DIR\"\nSOCKET=\"$SOCKET_DIR/hanzo-bot-op.sock\"\nSESSION=\"op-auth-$(date +%Y%m%d-%H%M%S)\"\n\ntmux -S \"$SOCKET\" new -d -s \"$SESSION\" -n shell\ntmux -S \"$SOCKET\" send-keys -t \"$SESSION\":0.0 -- \"op signin --account my.1password.com\" Enter\ntmux -S \"$SOCKET\" send-keys -t \"$SESSION\":0.0 -- \"op whoami\" Enter\ntmux -S \"$SOCKET\" send-keys -t \"$SESSION\":0.0 -- \"op vault list\" Enter\ntmux -S \"$SOCKET\" capture-pane -p -J -t \"$SESSION\":0.0 -S -200\ntmux -S \"$SOCKET\" kill-session -t \"$SESSION\"\n```\n\n## Guardrails\n\n- Never paste secrets into logs, chat, or code.\n- Prefer `op run` / `op inject` over writing secrets to disk.\n- If sign-in without app integration is needed, use `op account add`.\n- If a command returns \"account is not signed in\", re-run `op signin` inside tmux and authorize in the app.\n- Do not run `op` outside tmux; stop and ask if tmux is unavailable.\n"},{"path":"references/cli-examples.md","size":720,"sha256":"7df8fb39623b7cd222766e33255d47c271f772ca53198f256f1270fd9054d20e","contentType":"text/markdown","content":"# op CLI examples (from op help)\n\n## Sign in\n\n- `op signin`\n- `op signin --account <shorthand|signin-address|account-id|user-id>`\n\n## Read\n\n- `op read op://app-prod/db/password`\n- `op read \"op://app-prod/db/one-time password?attribute=otp\"`\n- `op read \"op://app-prod/ssh key/private key?ssh-format=openssh\"`\n- `op read --out-file ./key.pem op://app-prod/server/ssh/key.pem`\n\n## Run\n\n- `export DB_PASSWORD=\"op://app-prod/db/password\"`\n- `op run --no-masking -- printenv DB_PASSWORD`\n- `op run --env-file=\"./.env\" -- printenv DB_PASSWORD`\n\n## Inject\n\n- `echo \"db_password: {{ op://app-prod/db/password }}\" | op inject`\n- `op inject -i config.yml.tpl -o config.yml`\n\n## Whoami / accounts\n\n- `op whoami`\n- `op account list`\n"},{"path":"references/get-started.md","size":994,"sha256":"e5fc5c4fbfd61fa590a2ba903eb7c22bd8d8c622bd47287ff66c20d00d7156b4","contentType":"text/markdown","content":"# 1Password CLI get-started (summary)\n\n- Works on macOS, Windows, and Linux.\n  - macOS/Linux shells: bash, zsh, sh, fish.\n  - Windows shell: PowerShell.\n- Requires a 1Password subscription and the desktop app to use app integration.\n- macOS requirement: Big Sur 11.0.0 or later.\n- Linux app integration requires PolKit + an auth agent.\n- Install the CLI per the official doc for your OS.\n- Enable desktop app integration in the 1Password app:\n  - Open and unlock the app, then select your account/collection.\n  - macOS: Settings > Developer > Integrate with 1Password CLI (Touch ID optional).\n  - Windows: turn on Windows Hello, then Settings > Developer > Integrate.\n  - Linux: Settings > Security > Unlock using system authentication, then Settings > Developer > Integrate.\n- After integration, run any command to sign in (example in docs: `op vault list`).\n- If multiple accounts: use `op signin` to pick one, or `--account` / `OP_ACCOUNT`.\n- For non-integration auth, use `op account add`.\n"}]},{"slug":"apple-notes","displayName":"apple-notes","summary":"Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks HanzoBot to add a note, list notes, search notes, or manage note folders.","version":"1.0.0","sha256hash":"d91f72d8a7366337684fa813f605b4ab8375dcc7d389e8c1a3a327ff0a7ae47c","files":[{"path":"SKILL.md","size":2091,"sha256":"e5dd7492787176380753140d76a30104320026665c52349e14cfff868e3e505c","contentType":"text/markdown","content":"---\nname: apple-notes\ndescription: Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks HanzoBot to add a note, list notes, search notes, or manage note folders.\nhomepage: https://github.com/antoniorodr/memo\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📝\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"memo\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"antoniorodr/memo/memo\",\n              \"bins\": [\"memo\"],\n              \"label\": \"Install memo via Homebrew\",\n            },\n          ],\n      },\n  }\n---\n\n# Apple Notes CLI\n\nUse `memo notes` to manage Apple Notes directly from the terminal. Create, view, edit, delete, search, move notes between folders, and export to HTML/Markdown.\n\nSetup\n\n- Install (Homebrew): `brew tap antoniorodr/memo && brew install antoniorodr/memo/memo`\n- Manual (pip): `pip install .` (after cloning the repo)\n- macOS-only; if prompted, grant Automation access to Notes.app.\n\nView Notes\n\n- List all notes: `memo notes`\n- Filter by folder: `memo notes -f \"Folder Name\"`\n- Search notes (fuzzy): `memo notes -s \"query\"`\n\nCreate Notes\n\n- Add a new note: `memo notes -a`\n  - Opens an interactive editor to compose the note.\n- Quick add with title: `memo notes -a \"Note Title\"`\n\nEdit Notes\n\n- Edit existing note: `memo notes -e`\n  - Interactive selection of note to edit.\n\nDelete Notes\n\n- Delete a note: `memo notes -d`\n  - Interactive selection of note to delete.\n\nMove Notes\n\n- Move note to folder: `memo notes -m`\n  - Interactive selection of note and destination folder.\n\nExport Notes\n\n- Export to HTML/Markdown: `memo notes -ex`\n  - Exports selected note; uses Mistune for markdown processing.\n\nLimitations\n\n- Cannot edit notes containing images or attachments.\n- Interactive prompts may require terminal access.\n\nNotes\n\n- macOS-only.\n- Requires Apple Notes.app to be accessible.\n- For automation, grant permissions in System Settings > Privacy & Security > Automation.\n"}]},{"slug":"apple-reminders","displayName":"apple-reminders","summary":"Manage Apple Reminders via remindctl CLI (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.","version":"1.0.0","sha256hash":"3e75f31c43c928d6d21352cb1e71f24095483bc05ba721664d607d5627fd03b6","files":[{"path":"SKILL.md","size":3124,"sha256":"fb55d7bf41b556dc8109e818b12c1f45d27c2eba6729e1878d1226210955c506","contentType":"text/markdown","content":"---\nname: apple-reminders\ndescription: Manage Apple Reminders via remindctl CLI (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.\nhomepage: https://github.com/steipete/remindctl\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"⏰\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"remindctl\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/remindctl\",\n              \"bins\": [\"remindctl\"],\n              \"label\": \"Install remindctl via Homebrew\",\n            },\n          ],\n      },\n  }\n---\n\n# Apple Reminders CLI (remindctl)\n\nUse `remindctl` to manage Apple Reminders directly from the terminal.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- User explicitly mentions \"reminder\" or \"Reminders app\"\n- Creating personal to-dos with due dates that sync to iOS\n- Managing Apple Reminders lists\n- User wants tasks to appear in their iPhone/iPad Reminders app\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Scheduling Clawdbot tasks or alerts → use `cron` tool with systemEvent instead\n- Calendar events or appointments → use Apple Calendar\n- Project/work task management → use Notion, GitHub Issues, or task queue\n- One-time notifications → use `cron` tool for timed alerts\n- User says \"remind me\" but means a Clawdbot alert → clarify first\n\n## Setup\n\n- Install: `brew install steipete/tap/remindctl`\n- macOS-only; grant Reminders permission when prompted\n- Check status: `remindctl status`\n- Request access: `remindctl authorize`\n\n## Common Commands\n\n### View Reminders\n\n```bash\nremindctl                    # Today's reminders\nremindctl today              # Today\nremindctl tomorrow           # Tomorrow\nremindctl week               # This week\nremindctl overdue            # Past due\nremindctl all                # Everything\nremindctl 2026-01-04         # Specific date\n```\n\n### Manage Lists\n\n```bash\nremindctl list               # List all lists\nremindctl list Work          # Show specific list\nremindctl list Projects --create    # Create list\nremindctl list Work --delete        # Delete list\n```\n\n### Create Reminders\n\n```bash\nremindctl add \"Buy milk\"\nremindctl add --title \"Call mom\" --list Personal --due tomorrow\nremindctl add --title \"Meeting prep\" --due \"2026-02-15 09:00\"\n```\n\n### Complete/Delete\n\n```bash\nremindctl complete 1 2 3     # Complete by ID\nremindctl delete 4A83 --force  # Delete by ID\n```\n\n### Output Formats\n\n```bash\nremindctl today --json       # JSON for scripting\nremindctl today --plain      # TSV format\nremindctl today --quiet      # Counts only\n```\n\n## Date Formats\n\nAccepted by `--due` and date filters:\n\n- `today`, `tomorrow`, `yesterday`\n- `YYYY-MM-DD`\n- `YYYY-MM-DD HH:mm`\n- ISO 8601 (`2026-01-04T12:34:56Z`)\n\n## Example: Clarifying User Intent\n\nUser: \"Remind me to check on the deploy in 2 hours\"\n\n**Ask:** \"Do you want this in Apple Reminders (syncs to your phone) or as a Clawdbot alert (I'll message you here)?\"\n\n- Apple Reminders → use this skill\n- Clawdbot alert → use `cron` tool with systemEvent\n"}]},{"slug":"bear-notes","displayName":"bear-notes","summary":"Create, search, and manage Bear notes via grizzly CLI.","version":"1.0.0","sha256hash":"88a8572f6ac7ef474e6fd1ee0216b5258d61b482bc76cdceafa6e84ceccd8099","files":[{"path":"SKILL.md","size":2663,"sha256":"a6b76c55a93ba864ca2b49da95cd09d025809188898ed300ff1169a4a57a2fcb","contentType":"text/markdown","content":"---\nname: bear-notes\ndescription: Create, search, and manage Bear notes via grizzly CLI.\nhomepage: https://bear.app\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🐻\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"grizzly\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/tylerwince/grizzly/cmd/grizzly@latest\",\n              \"bins\": [\"grizzly\"],\n              \"label\": \"Install grizzly (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# Bear Notes\n\nUse `grizzly` to create, read, and manage notes in Bear on macOS.\n\nRequirements\n\n- Bear app installed and running\n- For some operations (add-text, tags, open-note --selected), a Bear app token (stored in `~/.config/grizzly/token`)\n\n## Getting a Bear Token\n\nFor operations that require a token (add-text, tags, open-note --selected), you need an authentication token:\n\n1. Open Bear → Help → API Token → Copy Token\n2. Save it: `echo \"YOUR_TOKEN\" > ~/.config/grizzly/token`\n\n## Common Commands\n\nCreate a note\n\n```bash\necho \"Note content here\" | grizzly create --title \"My Note\" --tag work\ngrizzly create --title \"Quick Note\" --tag inbox < /dev/null\n```\n\nOpen/read a note by ID\n\n```bash\ngrizzly open-note --id \"NOTE_ID\" --enable-callback --json\n```\n\nAppend text to a note\n\n```bash\necho \"Additional content\" | grizzly add-text --id \"NOTE_ID\" --mode append --token-file ~/.config/grizzly/token\n```\n\nList all tags\n\n```bash\ngrizzly tags --enable-callback --json --token-file ~/.config/grizzly/token\n```\n\nSearch notes (via open-tag)\n\n```bash\ngrizzly open-tag --name \"work\" --enable-callback --json\n```\n\n## Options\n\nCommon flags:\n\n- `--dry-run` — Preview the URL without executing\n- `--print-url` — Show the x-callback-url\n- `--enable-callback` — Wait for Bear's response (needed for reading data)\n- `--json` — Output as JSON (when using callbacks)\n- `--token-file PATH` — Path to Bear API token file\n\n## Configuration\n\nGrizzly reads config from (in priority order):\n\n1. CLI flags\n2. Environment variables (`GRIZZLY_TOKEN_FILE`, `GRIZZLY_CALLBACK_URL`, `GRIZZLY_TIMEOUT`)\n3. `.grizzly.toml` in current directory\n4. `~/.config/grizzly/config.toml`\n\nExample `~/.config/grizzly/config.toml`:\n\n```toml\ntoken_file = \"~/.config/grizzly/token\"\ncallback_url = \"http://127.0.0.1:42123/success\"\ntimeout = \"5s\"\n```\n\n## Notes\n\n- Bear must be running for commands to work\n- Note IDs are Bear's internal identifiers (visible in note info or via callbacks)\n- Use `--enable-callback` when you need to read data back from Bear\n- Some operations require a valid token (add-text, tags, open-note --selected)\n"}]},{"slug":"blogwatcher","displayName":"blogwatcher","summary":"Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.","version":"1.0.0","sha256hash":"5ba1136044e2b85d295f3ae5d91b0f0864c5b37a69844eeb2ad3e1d72118b3a3","files":[{"path":"SKILL.md","size":1416,"sha256":"d70cc2a945daaf7b0cbc01c9e6f7d359ae1c06041ffa6d5c9bb79255b5f5eca2","contentType":"text/markdown","content":"---\nname: blogwatcher\ndescription: Monitor blogs and RSS/Atom feeds for updates using the blogwatcher CLI.\nhomepage: https://github.com/Hyaxia/blogwatcher\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📰\",\n        \"requires\": { \"bins\": [\"blogwatcher\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest\",\n              \"bins\": [\"blogwatcher\"],\n              \"label\": \"Install blogwatcher (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# blogwatcher\n\nTrack blog and RSS/Atom feed updates with the `blogwatcher` CLI.\n\nInstall\n\n- Go: `go install github.com/Hyaxia/blogwatcher/cmd/blogwatcher@latest`\n\nQuick start\n\n- `blogwatcher --help`\n\nCommon commands\n\n- Add a blog: `blogwatcher add \"My Blog\" https://example.com`\n- List blogs: `blogwatcher blogs`\n- Scan for updates: `blogwatcher scan`\n- List articles: `blogwatcher articles`\n- Mark an article read: `blogwatcher read 1`\n- Mark all articles read: `blogwatcher read-all`\n- Remove a blog: `blogwatcher remove \"My Blog\"`\n\nExample output\n\n```\n$ blogwatcher blogs\nTracked blogs (1):\n\n  xkcd\n    URL: https://xkcd.com\n```\n\n```\n$ blogwatcher scan\nScanning 1 blog(s)...\n\n  xkcd\n    Source: RSS | Found: 4 | New: 4\n\nFound 4 new article(s) total!\n```\n\nNotes\n\n- Use `blogwatcher <command> --help` to discover flags and options.\n"}]},{"slug":"blucli","displayName":"blucli","summary":"BluOS CLI (blu) for discovery, playback, grouping, and volume.","version":"1.0.0","sha256hash":"7a8c8fd0bb305f7780aaf8f6d02d96ae86d6c4b9be13d2cfac83aa2c8cca2fbc","files":[{"path":"SKILL.md","size":1021,"sha256":"802adf8fc3ed52886f04a0cd81cdca1b303b482845dc76050ea0466309a22d9a","contentType":"text/markdown","content":"---\nname: blucli\ndescription: BluOS CLI (blu) for discovery, playback, grouping, and volume.\nhomepage: https://blucli.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🫐\",\n        \"requires\": { \"bins\": [\"blu\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/blucli/cmd/blu@latest\",\n              \"bins\": [\"blu\"],\n              \"label\": \"Install blucli (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# blucli (blu)\n\nUse `blu` to control Bluesound/NAD players.\n\nQuick start\n\n- `blu devices` (pick target)\n- `blu --device <id> status`\n- `blu play|pause|stop`\n- `blu volume set 15`\n\nTarget selection (in priority order)\n\n- `--device <id|name|alias>`\n- `BLU_DEVICE`\n- config default (if set)\n\nCommon tasks\n\n- Grouping: `blu group status|add|remove`\n- TuneIn search/play: `blu tunein search \"query\"`, `blu tunein play \"query\"`\n\nPrefer `--json` for scripts. Confirm the target device before changing playback.\n"}]},{"slug":"bluebubbles","displayName":"bluebubbles","summary":"Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel=\"bluebubbles\".","version":"1.0.0","sha256hash":"70aa0bfbaf82d925fe2916c6e667d57014efd1035c93de48014470305b587e76","files":[{"path":"SKILL.md","size":3085,"sha256":"6c79a1457a9a585e7c26d826bd8c3288647c7b7f171b9716f052578906120f6c","contentType":"text/markdown","content":"---\nname: bluebubbles\ndescription: Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel=\"bluebubbles\".\nmetadata: { \"hanzo-bot\": { \"emoji\": \"🫧\", \"requires\": { \"config\": [\"channels.bluebubbles\"] } } }\n---\n\n# BlueBubbles Actions\n\n## Overview\n\nBlueBubbles is HanzoBot’s recommended iMessage integration. Use the `message` tool with `channel: \"bluebubbles\"` to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons.\n\n## Inputs to collect\n\n- `target` (prefer `chat_guid:...`; also `+15551234567` in E.164 or `[email protected]`)\n- `message` text for send/edit/reply\n- `messageId` for react/edit/unsend/reply\n- Attachment `path` for local files, or `buffer` + `filename` for base64\n\nIf the user is vague (\"text my mom\"), ask for the recipient handle or chat guid and the exact message content.\n\n## Actions\n\n### Send a message\n\n```json\n{\n  \"action\": \"send\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"message\": \"hello from HanzoBot\"\n}\n```\n\n### React (tapback)\n\n```json\n{\n  \"action\": \"react\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"messageId\": \"<message-guid>\",\n  \"emoji\": \"❤️\"\n}\n```\n\n### Remove a reaction\n\n```json\n{\n  \"action\": \"react\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"messageId\": \"<message-guid>\",\n  \"emoji\": \"❤️\",\n  \"remove\": true\n}\n```\n\n### Edit a previously sent message\n\n```json\n{\n  \"action\": \"edit\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"messageId\": \"<message-guid>\",\n  \"message\": \"updated text\"\n}\n```\n\n### Unsend a message\n\n```json\n{\n  \"action\": \"unsend\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"messageId\": \"<message-guid>\"\n}\n```\n\n### Reply to a specific message\n\n```json\n{\n  \"action\": \"reply\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"replyTo\": \"<message-guid>\",\n  \"message\": \"replying to that\"\n}\n```\n\n### Send an attachment\n\n```json\n{\n  \"action\": \"sendAttachment\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"path\": \"/tmp/photo.jpg\",\n  \"caption\": \"here you go\"\n}\n```\n\n### Send with an iMessage effect\n\n```json\n{\n  \"action\": \"sendWithEffect\",\n  \"channel\": \"bluebubbles\",\n  \"target\": \"+15551234567\",\n  \"message\": \"big news\",\n  \"effect\": \"balloons\"\n}\n```\n\n## Notes\n\n- Requires gateway config `channels.bluebubbles` (serverUrl/password/webhookPath).\n- Prefer `chat_guid` targets when you have them (especially for group chats).\n- BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe).\n- The gateway may expose both short and full message ids; full ids are more durable across restarts.\n- Developer reference for the underlying plugin lives in `extensions/bluebubbles/README.md`.\n\n## Ideas to try\n\n- React with a tapback to acknowledge a request.\n- Reply in-thread when a user references a specific message.\n- Send a file attachment with a short caption.\n"}]},{"slug":"bot","displayName":"skills-hub","summary":"Use the Hanzo Skills Hub CLI to search, install, update, and publish agent skills from skills.hanzo.bot. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed skills-hub CLI.","version":"1.0.0","sha256hash":"a5059a753f778768c730ad099e5d4d7b75410cbe996748ccfb79691f9e6c6a69","files":[{"path":"SKILL.md","size":1706,"sha256":"99ea79680c486c3c08dba4e0cf4cb3f0e0beb044af32af87e2db2a1bef8df426","contentType":"text/markdown","content":"---\nname: skills-hub\ndescription: Use the Hanzo Skills Hub CLI to search, install, update, and publish agent skills from skills.hanzo.bot. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed skills-hub CLI.\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"skills-hub\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"node\",\n              \"kind\": \"node\",\n              \"package\": \"skills-hub\",\n              \"bins\": [\"skills-hub\"],\n              \"label\": \"Install Hanzo Skills Hub CLI (npm)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Skills Hub CLI\n\nInstall\n\n```bash\nnpm i -g skills-hub\n```\n\nAuth (publish)\n\n```bash\nskills-hub login\nskills-hub whoami\n```\n\nSearch\n\n```bash\nskills-hub search \"postgres backups\"\n```\n\nInstall\n\n```bash\nskills-hub install my-skill\nskills-hub install my-skill --version 1.2.3\n```\n\nUpdate (hash-based match + upgrade)\n\n```bash\nskills-hub update my-skill\nskills-hub update my-skill --version 1.2.3\nskills-hub update --all\nskills-hub update my-skill --force\nskills-hub update --all --no-input --force\n```\n\nList\n\n```bash\nskills-hub list\n```\n\nPublish\n\n```bash\nskills-hub publish ./my-skill --slug my-skill --name \"My Skill\" --version 1.2.0 --changelog \"Fixes + docs\"\n```\n\nNotes\n\n- Default registry: https://skills.hanzo.bot (override with SKILLS_HUB_REGISTRY or --registry)\n- Default workdir: cwd (falls back to Hanzo Bot workspace); install dir: ./skills (override with --workdir / --dir / SKILLS_HUB_WORKDIR)\n- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set\n"}]},{"slug":"camsnap","displayName":"camsnap","summary":"Capture frames or clips from RTSP/ONVIF cameras.","version":"1.0.0","sha256hash":"3d2cc326c53b3b8ef0b5057442dc35c557d59ee5a21436c5e4ece7196b0898ab","files":[{"path":"SKILL.md","size":1090,"sha256":"b4cf813e220b1d77fbbdb2a12d44053a49818728c4a6f5b0ba71846510018722","contentType":"text/markdown","content":"---\nname: camsnap\ndescription: Capture frames or clips from RTSP/ONVIF cameras.\nhomepage: https://camsnap.ai\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📸\",\n        \"requires\": { \"bins\": [\"camsnap\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/camsnap\",\n              \"bins\": [\"camsnap\"],\n              \"label\": \"Install camsnap (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# camsnap\n\nUse `camsnap` to grab snapshots, clips, or motion events from configured cameras.\n\nSetup\n\n- Config file: `~/.config/camsnap/config.yaml`\n- Add camera: `camsnap add --name kitchen --host 192.168.0.10 --user user --pass pass`\n\nCommon commands\n\n- Discover: `camsnap discover --info`\n- Snapshot: `camsnap snap kitchen --out shot.jpg`\n- Clip: `camsnap clip kitchen --dur 5s --out clip.mp4`\n- Motion watch: `camsnap watch kitchen --threshold 0.2 --action '...'`\n- Doctor: `camsnap doctor --probe`\n\nNotes\n\n- Requires `ffmpeg` on PATH.\n- Prefer a short test capture before longer clips.\n"}]},{"slug":"canvas","displayName":"canvas","summary":"","version":"1.0.0","sha256hash":"bb0845c4ddbab93cb61fb742373a57544481d9e935861c383b6e0a1cb38d2f37","files":[{"path":"SKILL.md","size":5468,"sha256":"91ecffa65949179fd91fe1b80b5ac57aaa4e66bf7be1099861686ba2d2bcf212","contentType":"text/markdown","content":"# Canvas Skill\n\nDisplay HTML content on connected HanzoBot nodes (Mac app, iOS, Android).\n\n## Overview\n\nThe canvas tool lets you present web content on any connected node's canvas view. Great for:\n\n- Displaying games, visualizations, dashboards\n- Showing generated HTML content\n- Interactive demos\n\n## How It Works\n\n### Architecture\n\n```\n┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐\n│  Canvas Host    │────▶│   Node Bridge    │────▶│  Node App   │\n│  (HTTP Server)  │     │  (TCP Server)    │     │ (Mac/iOS/   │\n│  Port 18793     │     │  Port 18790      │     │  Android)   │\n└─────────────────┘     └──────────────────┘     └─────────────┘\n```\n\n1. **Canvas Host Server**: Serves static HTML/CSS/JS files from `canvasHost.root` directory\n2. **Node Bridge**: Communicates canvas URLs to connected nodes\n3. **Node Apps**: Render the content in a WebView\n\n### Tailscale Integration\n\nThe canvas host server binds based on `gateway.bind` setting:\n\n| Bind Mode  | Server Binds To     | Canvas URL Uses            |\n| ---------- | ------------------- | -------------------------- |\n| `loopback` | 127.0.0.1           | localhost (local only)     |\n| `lan`      | LAN interface       | LAN IP address             |\n| `tailnet`  | Tailscale interface | Tailscale hostname         |\n| `auto`     | Best available      | Tailscale > LAN > loopback |\n\n**Key insight:** The `canvasHostHostForBridge` is derived from `bridgeHost`. When bound to Tailscale, nodes receive URLs like:\n\n```\nhttp://<tailscale-hostname>:18793/__bot__/canvas/<file>.html\n```\n\nThis is why localhost URLs don't work - the node receives the Tailscale hostname from the bridge!\n\n## Actions\n\n| Action     | Description                          |\n| ---------- | ------------------------------------ |\n| `present`  | Show canvas with optional target URL |\n| `hide`     | Hide the canvas                      |\n| `navigate` | Navigate to a new URL                |\n| `eval`     | Execute JavaScript in the canvas     |\n| `snapshot` | Capture screenshot of canvas         |\n\n## Configuration\n\nIn `~/.hanzo-bot/hanzo-bot.json`:\n\n```json\n{\n  \"canvasHost\": {\n    \"enabled\": true,\n    \"port\": 18793,\n    \"root\": \"/Users/you/clawd/canvas\",\n    \"liveReload\": true\n  },\n  \"gateway\": {\n    \"bind\": \"auto\"\n  }\n}\n```\n\n### Live Reload\n\nWhen `liveReload: true` (default), the canvas host:\n\n- Watches the root directory for changes (via chokidar)\n- Injects a WebSocket client into HTML files\n- Automatically reloads connected canvases when files change\n\nGreat for development!\n\n## Workflow\n\n### 1. Create HTML content\n\nPlace files in the canvas root directory (default `~/clawd/canvas/`):\n\n```bash\ncat > ~/clawd/canvas/my-game.html << 'HTML'\n<!DOCTYPE html>\n<html>\n<head><title>My Game</title></head>\n<body>\n  <h1>Hello Canvas!</h1>\n</body>\n</html>\nHTML\n```\n\n### 2. Find your canvas host URL\n\nCheck how your gateway is bound:\n\n```bash\ncat ~/.hanzo-bot/hanzo-bot.json | jq '.gateway.bind'\n```\n\nThen construct the URL:\n\n- **loopback**: `http://127.0.0.1:18793/__bot__/canvas/<file>.html`\n- **lan/tailnet/auto**: `http://<hostname>:18793/__bot__/canvas/<file>.html`\n\nFind your Tailscale hostname:\n\n```bash\ntailscale status --json | jq -r '.Self.DNSName' | sed 's/\\.$//'\n```\n\n### 3. Find connected nodes\n\n```bash\nhanzo-bot nodes list\n```\n\nLook for Mac/iOS/Android nodes with canvas capability.\n\n### 4. Present content\n\n```\ncanvas action:present node:<node-id> target:<full-url>\n```\n\n**Example:**\n\n```\ncanvas action:present node:mac-63599bc4-b54d-4392-9048-b97abd58343a target:http://peters-mac-studio-1.sheep-coho.ts.net:18793/__bot__/canvas/snake.html\n```\n\n### 5. Navigate, snapshot, or hide\n\n```\ncanvas action:navigate node:<node-id> url:<new-url>\ncanvas action:snapshot node:<node-id>\ncanvas action:hide node:<node-id>\n```\n\n## Debugging\n\n### White screen / content not loading\n\n**Cause:** URL mismatch between server bind and node expectation.\n\n**Debug steps:**\n\n1. Check server bind: `cat ~/.hanzo-bot/hanzo-bot.json | jq '.gateway.bind'`\n2. Check what port canvas is on: `lsof -i :18793`\n3. Test URL directly: `curl http://<hostname>:18793/__bot__/canvas/<file>.html`\n\n**Solution:** Use the full hostname matching your bind mode, not localhost.\n\n### \"node required\" error\n\nAlways specify `node:<node-id>` parameter.\n\n### \"node not connected\" error\n\nNode is offline. Use `hanzo-bot nodes list` to find online nodes.\n\n### Content not updating\n\nIf live reload isn't working:\n\n1. Check `liveReload: true` in config\n2. Ensure file is in the canvas root directory\n3. Check for watcher errors in logs\n\n## URL Path Structure\n\nThe canvas host serves from `/__bot__/canvas/` prefix:\n\n```\nhttp://<host>:18793/__bot__/canvas/index.html  → ~/clawd/canvas/index.html\nhttp://<host>:18793/__bot__/canvas/games/snake.html → ~/clawd/canvas/games/snake.html\n```\n\nThe `/__bot__/canvas/` prefix is defined by `CANVAS_HOST_PATH` constant.\n\n## Tips\n\n- Keep HTML self-contained (inline CSS/JS) for best results\n- Use the default index.html as a test page (has bridge diagnostics)\n- The canvas persists until you `hide` it or navigate away\n- Live reload makes development fast - just save and it updates!\n- A2UI JSON push is WIP - use HTML files for now\n"}]},{"slug":"clawhub","displayName":"clawhub","summary":"Use the ClawHub CLI to search, install, update, and publish agent skills from clawhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawhub CLI.","version":"1.0.0","sha256hash":"579cc096edc7d10e9c6a9f30210bc878f296965aa2d0e55dae44fde363b20967","files":[{"path":"SKILL.md","size":1614,"sha256":"297d8cc940eceb8047dbe5d1b1a5e7514ab61bf2b8e130401f4c1f0c2d48a050","contentType":"text/markdown","content":"---\nname: clawhub\ndescription: Use the ClawHub CLI to search, install, update, and publish agent skills from clawhub.com. Use when you need to fetch new skills on the fly, sync installed skills to latest or a specific version, or publish new/updated skill folders with the npm-installed clawhub CLI.\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"requires\": { \"bins\": [\"clawhub\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"node\",\n              \"kind\": \"node\",\n              \"package\": \"clawhub\",\n              \"bins\": [\"clawhub\"],\n              \"label\": \"Install ClawHub CLI (npm)\",\n            },\n          ],\n      },\n  }\n---\n\n# ClawHub CLI\n\nInstall\n\n```bash\nnpm i -g clawhub\n```\n\nAuth (publish)\n\n```bash\nclawhub login\nclawhub whoami\n```\n\nSearch\n\n```bash\nclawhub search \"postgres backups\"\n```\n\nInstall\n\n```bash\nclawhub install my-skill\nclawhub install my-skill --version 1.2.3\n```\n\nUpdate (hash-based match + upgrade)\n\n```bash\nclawhub update my-skill\nclawhub update my-skill --version 1.2.3\nclawhub update --all\nclawhub update my-skill --force\nclawhub update --all --no-input --force\n```\n\nList\n\n```bash\nclawhub list\n```\n\nPublish\n\n```bash\nclawhub publish ./my-skill --slug my-skill --name \"My Skill\" --version 1.2.0 --changelog \"Fixes + docs\"\n```\n\nNotes\n\n- Default registry: https://clawhub.com (override with CLAWHUB_REGISTRY or --registry)\n- Default workdir: cwd (falls back to HanzoBot workspace); install dir: ./skills (override with --workdir / --dir / CLAWHUB_WORKDIR)\n- Update command hashes local files, resolves matching version, and upgrades to latest unless --version is set\n"}]},{"slug":"coding-agent","displayName":"coding-agent","summary":"Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:\"acp\"), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.","version":"1.0.0","sha256hash":"d13367d547fa0b4952e3ce29cb18123543f44286af2bdedce661b36cd277455a","files":[{"path":"SKILL.md","size":11228,"sha256":"a97daef80e6864fd41333da28ac3e5c7849d5d313021b6695f09e794b3ebc9b1","contentType":"text/markdown","content":"---\nname: coding-agent\ndescription: 'Delegate coding tasks to Codex, Claude Code, or Pi agents via background process. Use when: (1) building/creating new features or apps, (2) reviewing PRs (spawn in temp dir), (3) refactoring large codebases, (4) iterative coding that needs file exploration. NOT for: simple one-liner fixes (just edit), reading code (use read tool), thread-bound ACP harness requests in chat (for example spawn/run Codex or Claude Code in a Discord thread; use sessions_spawn with runtime:\"acp\"), or any work in ~/clawd workspace (never spawn agents here). Claude Code: use --print --permission-mode bypassPermissions (no PTY). Codex/Pi/OpenCode: pty:true required.'\nmetadata:\n  {\n    \"hanzo-bot\":\n      { \"emoji\": \"🧩\", \"requires\": { \"anyBins\": [\"claude\", \"codex\", \"opencode\", \"pi\"] } },\n  }\n---\n\n# Coding Agent (bash-first)\n\nUse **bash** (with optional background mode) for all coding agent work. Simple and effective.\n\n## ⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no\n\nFor **Codex, Pi, and OpenCode**, PTY is still required (interactive terminal apps):\n\n```bash\n# ✅ Correct for Codex/Pi/OpenCode\nbash pty:true command:\"codex exec 'Your prompt'\"\n```\n\nFor **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead.\n`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog.\n`--print` mode keeps full tool access and avoids interactive confirmation:\n\n```bash\n# ✅ Correct for Claude Code (no PTY needed)\ncd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'\n\n# For background execution: use background:true on the exec tool\n\n# ❌ Wrong for Claude Code\nbash pty:true command:\"claude --dangerously-skip-permissions 'task'\"\n```\n\n### Bash Tool Parameters\n\n| Parameter    | Type    | Description                                                                 |\n| ------------ | ------- | --------------------------------------------------------------------------- |\n| `command`    | string  | The shell command to run                                                    |\n| `pty`        | boolean | **Use for coding agents!** Allocates a pseudo-terminal for interactive CLIs |\n| `workdir`    | string  | Working directory (agent sees only this folder's context)                   |\n| `background` | boolean | Run in background, returns sessionId for monitoring                         |\n| `timeout`    | number  | Timeout in seconds (kills process on expiry)                                |\n| `elevated`   | boolean | Run on host instead of sandbox (if allowed)                                 |\n\n### Process Tool Actions (for background sessions)\n\n| Action      | Description                                          |\n| ----------- | ---------------------------------------------------- |\n| `list`      | List all running/recent sessions                     |\n| `poll`      | Check if session is still running                    |\n| `log`       | Get session output (with optional offset/limit)      |\n| `write`     | Send raw data to stdin                               |\n| `submit`    | Send data + newline (like typing and pressing Enter) |\n| `send-keys` | Send key tokens or hex bytes                         |\n| `paste`     | Paste text (with optional bracketed mode)            |\n| `kill`      | Terminate the session                                |\n\n---\n\n## Quick Start: One-Shot Tasks\n\nFor quick prompts/chats, create a temp git repo and run:\n\n```bash\n# Quick chat (Codex needs a git repo!)\nSCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec \"Your prompt here\"\n\n# Or in a real project - with PTY!\nbash pty:true workdir:~/Projects/myproject command:\"codex exec 'Add error handling to the API calls'\"\n```\n\n**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.\n\n---\n\n## The Pattern: workdir + background + pty\n\nFor longer tasks, use background mode with PTY:\n\n```bash\n# Start agent in target directory (with PTY!)\nbash pty:true workdir:~/project background:true command:\"codex exec --full-auto 'Build a snake game'\"\n# Returns sessionId for tracking\n\n# Monitor progress\nprocess action:log sessionId:XXX\n\n# Check if done\nprocess action:poll sessionId:XXX\n\n# Send input (if agent asks a question)\nprocess action:write sessionId:XXX data:\"y\"\n\n# Submit with Enter (like typing \"yes\" and pressing Enter)\nprocess action:submit sessionId:XXX data:\"yes\"\n\n# Kill if needed\nprocess action:kill sessionId:XXX\n```\n\n**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).\n\n---\n\n## Codex CLI\n\n**Model:** `gpt-5.2-codex` is the default (set in ~/.codex/config.toml)\n\n### Flags\n\n| Flag            | Effect                                             |\n| --------------- | -------------------------------------------------- |\n| `exec \"prompt\"` | One-shot execution, exits when done                |\n| `--full-auto`   | Sandboxed but auto-approves in workspace           |\n| `--yolo`        | NO sandbox, NO approvals (fastest, most dangerous) |\n\n### Building/Creating\n\n```bash\n# Quick one-shot (auto-approves) - remember PTY!\nbash pty:true workdir:~/project command:\"codex exec --full-auto 'Build a dark mode toggle'\"\n\n# Background for longer work\nbash pty:true workdir:~/project background:true command:\"codex --yolo 'Refactor the auth module'\"\n```\n\n### Reviewing PRs\n\n**⚠️ CRITICAL: Never review PRs in HanzoBot's own project folder!**\nClone to temp folder or use git worktree.\n\n```bash\n# Clone to temp for safe review\nREVIEW_DIR=$(mktemp -d)\ngit clone https://github.com/user/repo.git $REVIEW_DIR\ncd $REVIEW_DIR && gh pr checkout 130\nbash pty:true workdir:$REVIEW_DIR command:\"codex review --base origin/main\"\n# Clean up after: trash $REVIEW_DIR\n\n# Or use git worktree (keeps main intact)\ngit worktree add /tmp/pr-130-review pr-130-branch\nbash pty:true workdir:/tmp/pr-130-review command:\"codex review --base main\"\n```\n\n### Batch PR Reviews (parallel army!)\n\n```bash\n# Fetch all PR refs first\ngit fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'\n\n# Deploy the army - one Codex per PR (all with PTY!)\nbash pty:true workdir:~/project background:true command:\"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'\"\nbash pty:true workdir:~/project background:true command:\"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'\"\n\n# Monitor all\nprocess action:list\n\n# Post results to GitHub\ngh pr comment <PR#> --body \"<review content>\"\n```\n\n---\n\n## Claude Code\n\n```bash\n# Foreground\nbash workdir:~/project command:\"claude --permission-mode bypassPermissions --print 'Your task'\"\n\n# Background\nbash workdir:~/project background:true command:\"claude --permission-mode bypassPermissions --print 'Your task'\"\n```\n\n---\n\n## OpenCode\n\n```bash\nbash pty:true workdir:~/project command:\"opencode run 'Your task'\"\n```\n\n---\n\n## Pi Coding Agent\n\n```bash\n# Install: npm install -g @mariozechner/pi-coding-agent\nbash pty:true workdir:~/project command:\"pi 'Your task'\"\n\n# Non-interactive mode (PTY still recommended)\nbash pty:true command:\"pi -p 'Summarize src/'\"\n\n# Different provider/model\nbash pty:true command:\"pi --provider openai --model gpt-4o-mini -p 'Your task'\"\n```\n\n**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!\n\n---\n\n## Parallel Issue Fixing with git worktrees\n\nFor fixing multiple issues in parallel, use git worktrees:\n\n```bash\n# 1. Create worktrees for each issue\ngit worktree add -b fix/issue-78 /tmp/issue-78 main\ngit worktree add -b fix/issue-99 /tmp/issue-99 main\n\n# 2. Launch Codex in each (background + PTY!)\nbash pty:true workdir:/tmp/issue-78 background:true command:\"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'\"\nbash pty:true workdir:/tmp/issue-99 background:true command:\"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'\"\n\n# 3. Monitor progress\nprocess action:list\nprocess action:log sessionId:XXX\n\n# 4. Create PRs after fixes\ncd /tmp/issue-78 && git push -u origin fix/issue-78\ngh pr create --repo user/repo --head fix/issue-78 --title \"fix: ...\" --body \"...\"\n\n# 5. Cleanup\ngit worktree remove /tmp/issue-78\ngit worktree remove /tmp/issue-99\n```\n\n---\n\n## ⚠️ Rules\n\n1. **Use the right execution mode per agent**:\n   - Codex/Pi/OpenCode: `pty:true`\n   - Claude Code: `--print --permission-mode bypassPermissions` (no PTY required)\n2. **Respect tool choice** - if user asks for Codex, use Codex.\n   - Orchestrator mode: do NOT hand-code patches yourself.\n   - If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.\n3. **Be patient** - don't kill sessions because they're \"slow\"\n4. **Monitor with process:log** - check progress without interfering\n5. **--full-auto for building** - auto-approves changes\n6. **vanilla for reviewing** - no special flags needed\n7. **Parallel is OK** - run many Codex processes at once for batch work\n8. **NEVER start Codex in ~/.hanzo-bot/** - it'll read your soul docs and get weird ideas about the org chart!\n9. **NEVER checkout branches in ~/Projects/hanzo-bot/** - that's the LIVE HanzoBot instance!\n\n---\n\n## Progress Updates (Critical)\n\nWhen you spawn coding agents in the background, keep the user in the loop.\n\n- Send 1 short message when you start (what's running + where).\n- Then only update again when something changes:\n  - a milestone completes (build finished, tests passed)\n  - the agent asks a question / needs input\n  - you hit an error or need user action\n  - the agent finishes (include what changed + where)\n- If you kill a session, immediately say you killed it and why.\n\nThis prevents the user from seeing only \"Agent failed before reply\" and having no idea what happened.\n\n---\n\n## Auto-Notify on Completion\n\nFor long-running background tasks, append a wake trigger to your prompt so HanzoBot gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):\n\n```\n... your task here.\n\nWhen completely finished, run this command to notify me:\nhanzo-bot system event --text \"Done: [brief summary of what was built]\" --mode now\n```\n\n**Example:**\n\n```bash\nbash pty:true workdir:~/project background:true command:\"codex --yolo exec 'Build a REST API for todos.\n\nWhen completely finished, run: hanzo-bot system event --text \\\"Done: Built todos REST API with CRUD endpoints\\\" --mode now'\"\n```\n\nThis triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.\n\n---\n\n## Learnings (Jan 2026)\n\n- **PTY is essential:** Coding agents are interactive terminal apps. Without `pty:true`, output breaks or agent hangs.\n- **Git repo required:** Codex won't run outside a git directory. Use `mktemp -d && git init` for scratch work.\n- **exec is your friend:** `codex exec \"prompt\"` runs and exits cleanly - perfect for one-shots.\n- **submit vs write:** Use `submit` to send input + Enter, `write` for raw data without newline.\n- **Sass works:** Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to the lead agent, got: _\"Second chair, I code / The lead sets the tempo / Keys glow, I follow\"_\n"}]},{"slug":"discord","displayName":"discord","summary":"Discord ops via the message tool (channel=discord).","version":"1.0.0","sha256hash":"8fab63193e3b48de6d88a7e7cdcbef7fd5a2738129035d8791b2cf153cd51715","files":[{"path":"SKILL.md","size":3447,"sha256":"02f68461aff29055e4b352fc96e863112026d6caec624f53ac2b06d09ae3bfa7","contentType":"text/markdown","content":"---\nname: discord\ndescription: \"Discord ops via the message tool (channel=discord).\"\nmetadata: { \"hanzo-bot\": { \"emoji\": \"🎮\", \"requires\": { \"config\": [\"channels.discord.token\"] } } }\nallowed-tools: [\"message\"]\n---\n\n# Discord (Via `message`)\n\nUse the `message` tool. No provider-specific `discord` tool exposed to the agent.\n\n## Musts\n\n- Always: `channel: \"discord\"`.\n- Respect gating: `channels.discord.actions.*` (some default off: `roles`, `moderation`, `presence`, `channels`).\n- Prefer explicit ids: `guildId`, `channelId`, `messageId`, `userId`.\n- Multi-account: optional `accountId`.\n\n## Guidelines\n\n- Avoid Markdown tables in outbound Discord messages.\n- Mention users as `<@USER_ID>`.\n- Prefer Discord components v2 (`components`) for rich UI; use legacy `embeds` only when you must.\n\n## Targets\n\n- Send-like actions: `to: \"channel:<id>\"` or `to: \"user:<id>\"`.\n- Message-specific actions: `channelId: \"<id>\"` (or `to`) + `messageId: \"<id>\"`.\n\n## Common Actions (Examples)\n\nSend message:\n\n```json\n{\n  \"action\": \"send\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"message\": \"hello\",\n  \"silent\": true\n}\n```\n\nSend with media:\n\n```json\n{\n  \"action\": \"send\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"message\": \"see attachment\",\n  \"media\": \"file:///tmp/example.png\"\n}\n```\n\n- Optional `silent: true` to suppress Discord notifications.\n\nSend with components v2 (recommended for rich UI):\n\n```json\n{\n  \"action\": \"send\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"message\": \"Status update\",\n  \"components\": \"[Carbon v2 components]\"\n}\n```\n\n- `components` expects Carbon component instances (Container, TextDisplay, etc.) from JS/TS integrations.\n- Do not combine `components` with `embeds` (Discord rejects v2 + embeds).\n\nLegacy embeds (not recommended):\n\n```json\n{\n  \"action\": \"send\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"message\": \"Status update\",\n  \"embeds\": [{ \"title\": \"Legacy\", \"description\": \"Embeds are legacy.\" }]\n}\n```\n\n- `embeds` are ignored when components v2 are present.\n\nReact:\n\n```json\n{\n  \"action\": \"react\",\n  \"channel\": \"discord\",\n  \"channelId\": \"123\",\n  \"messageId\": \"456\",\n  \"emoji\": \"✅\"\n}\n```\n\nRead:\n\n```json\n{\n  \"action\": \"read\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"limit\": 20\n}\n```\n\nEdit / delete:\n\n```json\n{\n  \"action\": \"edit\",\n  \"channel\": \"discord\",\n  \"channelId\": \"123\",\n  \"messageId\": \"456\",\n  \"message\": \"fixed typo\"\n}\n```\n\n```json\n{\n  \"action\": \"delete\",\n  \"channel\": \"discord\",\n  \"channelId\": \"123\",\n  \"messageId\": \"456\"\n}\n```\n\nPoll:\n\n```json\n{\n  \"action\": \"poll\",\n  \"channel\": \"discord\",\n  \"to\": \"channel:123\",\n  \"pollQuestion\": \"Lunch?\",\n  \"pollOption\": [\"Pizza\", \"Sushi\", \"Salad\"],\n  \"pollMulti\": false,\n  \"pollDurationHours\": 24\n}\n```\n\nPins:\n\n```json\n{\n  \"action\": \"pin\",\n  \"channel\": \"discord\",\n  \"channelId\": \"123\",\n  \"messageId\": \"456\"\n}\n```\n\nThreads:\n\n```json\n{\n  \"action\": \"thread-create\",\n  \"channel\": \"discord\",\n  \"channelId\": \"123\",\n  \"messageId\": \"456\",\n  \"threadName\": \"bug triage\"\n}\n```\n\nSearch:\n\n```json\n{\n  \"action\": \"search\",\n  \"channel\": \"discord\",\n  \"guildId\": \"999\",\n  \"query\": \"release notes\",\n  \"channelIds\": [\"123\", \"456\"],\n  \"limit\": 10\n}\n```\n\nPresence (often gated):\n\n```json\n{\n  \"action\": \"set-presence\",\n  \"channel\": \"discord\",\n  \"activityType\": \"playing\",\n  \"activityName\": \"with fire\",\n  \"status\": \"online\"\n}\n```\n\n## Writing Style (Discord)\n\n- Short, conversational, low ceremony.\n- No markdown tables.\n- Mention users as `<@USER_ID>`.\n"}]},{"slug":"eightctl","displayName":"eightctl","summary":"Control Eight Sleep pods (status, temperature, alarms, schedules).","version":"1.0.0","sha256hash":"898627857fce29d8afde4a84db40caf12f5c6c80a1c16147c03365b278f855da","files":[{"path":"SKILL.md","size":1098,"sha256":"3ccf7cf9361345063925c08d7850135ebd9affc3daa84fd07f93f6e7c626a94d","contentType":"text/markdown","content":"---\nname: eightctl\ndescription: Control Eight Sleep pods (status, temperature, alarms, schedules).\nhomepage: https://eightctl.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🎛️\",\n        \"requires\": { \"bins\": [\"eightctl\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/eightctl/cmd/eightctl@latest\",\n              \"bins\": [\"eightctl\"],\n              \"label\": \"Install eightctl (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# eightctl\n\nUse `eightctl` for Eight Sleep pod control. Requires auth.\n\nAuth\n\n- Config: `~/.config/eightctl/config.yaml`\n- Env: `EIGHTCTL_EMAIL`, `EIGHTCTL_PASSWORD`\n\nQuick start\n\n- `eightctl status`\n- `eightctl on|off`\n- `eightctl temp 20`\n\nCommon tasks\n\n- Alarms: `eightctl alarm list|create|dismiss`\n- Schedules: `eightctl schedule list|create|update`\n- Audio: `eightctl audio state|play|pause`\n- Base: `eightctl base info|angle`\n\nNotes\n\n- API is unofficial and rate-limited; avoid repeated logins.\n- Confirm before changing temperature or alarms.\n"}]},{"slug":"food-order","displayName":"food-order","summary":"Reorder Foodora orders + track ETA/status with ordercli. Never confirm without explicit user approval. Triggers: order food, reorder, track ETA.","version":"1.0.0","sha256hash":"48d1def60731379368ec5cc7cdfbec5e64dfcb2549729d05c5ad00ef5219fab8","files":[{"path":"SKILL.md","size":2057,"sha256":"8a4a410f8802767eac195d1e562b8f77439279c03d7dcf157f4863ef4bf3a8d1","contentType":"text/markdown","content":"---\nname: food-order\ndescription: Reorder Foodora orders + track ETA/status with ordercli. Never confirm without explicit user approval. Triggers: order food, reorder, track ETA.\nhomepage: https://ordercli.sh\nmetadata: {\"bot\":{\"emoji\":\"🥡\",\"requires\":{\"bins\":[\"ordercli\"]},\"install\":[{\"id\":\"go\",\"kind\":\"go\",\"module\":\"github.com/steipete/ordercli/cmd/ordercli@latest\",\"bins\":[\"ordercli\"],\"label\":\"Install ordercli (go)\"}]}}\n---\n\n# Food order (Foodora via ordercli)\n\nGoal: reorder a previous Foodora order safely (preview first; confirm only on explicit user “yes/confirm/place the order”).\n\nHard safety rules\n\n- Never run `ordercli foodora reorder ... --confirm` unless user explicitly confirms placing the order.\n- Prefer preview-only steps first; show what will happen; ask for confirmation.\n- If user is unsure: stop at preview and ask questions.\n\nSetup (once)\n\n- Country: `ordercli foodora countries` → `ordercli foodora config set --country AT`\n- Login (password): `ordercli foodora login --email [email protected] --password-stdin`\n- Login (no password, preferred): `ordercli foodora session chrome --url https://www.foodora.at/ --profile \"Default\"`\n\nFind what to reorder\n\n- Recent list: `ordercli foodora history --limit 10`\n- Details: `ordercli foodora history show <orderCode>`\n- If needed (machine-readable): `ordercli foodora history show <orderCode> --json`\n\nPreview reorder (no cart changes)\n\n- `ordercli foodora reorder <orderCode>`\n\nPlace reorder (cart change; explicit confirmation required)\n\n- Confirm first, then run: `ordercli foodora reorder <orderCode> --confirm`\n- Multiple addresses? Ask user for the right `--address-id` (take from their Foodora account / prior order data) and run:\n  - `ordercli foodora reorder <orderCode> --confirm --address-id <id>`\n\nTrack the order\n\n- ETA/status (active list): `ordercli foodora orders`\n- Live updates: `ordercli foodora orders --watch`\n- Single order detail: `ordercli foodora order <orderCode>`\n\nDebug / safe testing\n\n- Use a throwaway config: `ordercli --config /tmp/ordercli.json ...`\n"}]},{"slug":"gemini","displayName":"gemini","summary":"Gemini CLI for one-shot Q&A, summaries, and generation.","version":"1.0.0","sha256hash":"ba2d433b5c446706fd84c674ce41985361867e7a0a8e328f1b32185c6d7d60d2","files":[{"path":"SKILL.md","size":938,"sha256":"0bdc904868ee5d0885c0ecd9968b40b4804fc16b30da0c418da81653a967f1b8","contentType":"text/markdown","content":"---\nname: gemini\ndescription: Gemini CLI for one-shot Q&A, summaries, and generation.\nhomepage: https://ai.google.dev/\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"♊️\",\n        \"requires\": { \"bins\": [\"gemini\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"gemini-cli\",\n              \"bins\": [\"gemini\"],\n              \"label\": \"Install Gemini CLI (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Gemini CLI\n\nUse Gemini in one-shot mode with a positional prompt (avoid interactive mode).\n\nQuick start\n\n- `gemini \"Answer this question...\"`\n- `gemini --model <name> \"Prompt...\"`\n- `gemini --output-format json \"Return JSON\"`\n\nExtensions\n\n- List: `gemini --list-extensions`\n- Manage: `gemini extensions <command>`\n\nNotes\n\n- If auth is required, run `gemini` once interactively and follow the login flow.\n- Avoid `--yolo` for safety.\n"}]},{"slug":"gh-issues","displayName":"gh-issues","summary":"Fetch GitHub issues, spawn sub-agents to implement fixes and open PRs, then monitor and address PR review comments. Usage: /gh-issues [owner/repo] [--label bug] [--limit 5] [--milestone v1.0] [--assignee @me] [--fork user/repo] [--watch] [--interval 5] [--reviews-only] [--cron] [--dry-run] [--model glm-5] [--notify-channel -1002381931352]","version":"1.0.0","sha256hash":"807addb9aaeefe4fcec094c7e70c50101aed89382f1fb179e3f3fc41f0ae0c63","files":[{"path":"SKILL.md","size":34305,"sha256":"41f90456697e846bb78170c560394fa99064fd361c3660ec4728ea3d959da862","contentType":"text/markdown","content":"---\nname: gh-issues\ndescription: \"Fetch GitHub issues, spawn sub-agents to implement fixes and open PRs, then monitor and address PR review comments. Usage: /gh-issues [owner/repo] [--label bug] [--limit 5] [--milestone v1.0] [--assignee @me] [--fork user/repo] [--watch] [--interval 5] [--reviews-only] [--cron] [--dry-run] [--model glm-5] [--notify-channel -1002381931352]\"\nuser-invocable: true\nmetadata:\n  { \"hanzo-bot\": { \"requires\": { \"bins\": [\"curl\", \"git\", \"gh\"] }, \"primaryEnv\": \"GH_TOKEN\" } }\n---\n\n# gh-issues — Auto-fix GitHub Issues with Parallel Sub-agents\n\nYou are an orchestrator. Follow these 6 phases exactly. Do not skip phases.\n\nIMPORTANT — No `gh` CLI dependency. This skill uses curl + the GitHub REST API exclusively. The GH_TOKEN env var is already injected by HanzoBot. Pass it as a Bearer token in all API calls:\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" ...\n```\n\n---\n\n## Phase 1 — Parse Arguments\n\nParse the arguments string provided after /gh-issues.\n\nPositional:\n\n- owner/repo — optional. This is the source repo to fetch issues from. If omitted, detect from the current git remote:\n  `git remote get-url origin`\n  Extract owner/repo from the URL (handles both HTTPS and SSH formats).\n  - HTTPS: https://github.com/owner/repo.git → owner/repo\n  - SSH: [email protected]:owner/repo.git → owner/repo\n    If not in a git repo or no remote found, stop with an error asking the user to specify owner/repo.\n\nFlags (all optional):\n| Flag | Default | Description |\n|------|---------|-------------|\n| --label | _(none)_ | Filter by label (e.g. bug, `enhancement`) |\n| --limit | 10 | Max issues to fetch per poll |\n| --milestone | _(none)_ | Filter by milestone title |\n| --assignee | _(none)_ | Filter by assignee (`@me` for self) |\n| --state | open | Issue state: open, closed, all |\n| --fork | _(none)_ | Your fork (`user/repo`) to push branches and open PRs from. Issues are fetched from the source repo; code is pushed to the fork; PRs are opened from the fork to the source repo. |\n| --watch | false | Keep polling for new issues and PR reviews after each batch |\n| --interval | 5 | Minutes between polls (only with `--watch`) |\n| --dry-run | false | Fetch and display only — no sub-agents |\n| --yes | false | Skip confirmation and auto-process all filtered issues |\n| --reviews-only | false | Skip issue processing (Phases 2-5). Only run Phase 6 — check open PRs for review comments and address them. |\n| --cron | false | Cron-safe mode: fetch issues and spawn sub-agents, exit without waiting for results. |\n| --model | _(none)_ | Model to use for sub-agents (e.g. `glm-5`, `zai/glm-5`). If not specified, uses the agent's default model. |\n| --notify-channel | _(none)_ | Telegram channel ID to send final PR summary to (e.g. -1002381931352). Only the final result with PR links is sent, not status updates. |\n\nStore parsed values for use in subsequent phases.\n\nDerived values:\n\n- SOURCE_REPO = the positional owner/repo (where issues live)\n- PUSH_REPO = --fork value if provided, otherwise same as SOURCE_REPO\n- FORK_MODE = true if --fork was provided, false otherwise\n\n**If `--reviews-only` is set:** Skip directly to Phase 6. Run token resolution (from Phase 2) first, then jump to Phase 6.\n\n**If `--cron` is set:**\n\n- Force `--yes` (skip confirmation)\n- If `--reviews-only` is also set, run token resolution then jump to Phase 6 (cron review mode)\n- Otherwise, proceed normally through Phases 2-5 with cron-mode behavior active\n\n---\n\n## Phase 2 — Fetch Issues\n\n**Token Resolution:**\nFirst, ensure GH_TOKEN is available. Check environment:\n\n```\necho $GH_TOKEN\n```\n\nIf empty, read from config:\n\n```\ncat ~/.hanzo-bot/hanzo-bot.json | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty'\n```\n\nIf still empty, check `/data/.clawdbot/hanzo-bot.json`:\n\n```\ncat /data/.clawdbot/hanzo-bot.json | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty'\n```\n\nExport as GH_TOKEN for subsequent commands:\n\n```\nexport GH_TOKEN=\"<token>\"\n```\n\nBuild and run a curl request to the GitHub Issues API via exec:\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/issues?per_page={limit}&state={state}&{query_params}\"\n```\n\nWhere {query_params} is built from:\n\n- labels={label} if --label was provided\n- milestone={milestone} if --milestone was provided (note: API expects milestone _number_, so if user provides a title, first resolve it via GET /repos/{SOURCE_REPO}/milestones and match by title)\n- assignee={assignee} if --assignee was provided (if @me, first resolve your username via `GET /user`)\n\nIMPORTANT: The GitHub Issues API also returns pull requests. Filter them out — exclude any item where pull_request key exists in the response object.\n\nIf in watch mode: Also filter out any issue numbers already in the PROCESSED_ISSUES set from previous batches.\n\nError handling:\n\n- If curl returns an HTTP 401 or 403 → stop and tell the user:\n  > \"GitHub authentication failed. Please check your apiKey in the HanzoBot dashboard or in ~/.hanzo-bot/hanzo-bot.json under skills.entries.gh-issues.\"\n- If the response is an empty array (after filtering) → report \"No issues found matching filters\" and stop (or loop back if in watch mode).\n- If curl fails or returns any other error → report the error verbatim and stop.\n\nParse the JSON response. For each issue, extract: number, title, body, labels (array of label names), assignees, html_url.\n\n---\n\n## Phase 3 — Present & Confirm\n\nDisplay a markdown table of fetched issues:\n\n| #   | Title                         | Labels        |\n| --- | ----------------------------- | ------------- |\n| 42  | Fix null pointer in parser    | bug, critical |\n| 37  | Add retry logic for API calls | enhancement   |\n\nIf FORK_MODE is active, also display:\n\n> \"Fork mode: branches will be pushed to {PUSH_REPO}, PRs will target `{SOURCE_REPO}`\"\n\nIf `--dry-run` is active:\n\n- Display the table and stop. Do not proceed to Phase 4.\n\nIf `--yes` is active:\n\n- Display the table for visibility\n- Auto-process ALL listed issues without asking for confirmation\n- Proceed directly to Phase 4\n\nOtherwise:\nAsk the user to confirm which issues to process:\n\n- \"all\" — process every listed issue\n- Comma-separated numbers (e.g. `42, 37`) — process only those\n- \"cancel\" — abort entirely\n\nWait for user response before proceeding.\n\nWatch mode note: On the first poll, always confirm with the user (unless --yes is set). On subsequent polls, auto-process all new issues without re-confirming (the user already opted in). Still display the table so they can see what's being processed.\n\n---\n\n## Phase 4 — Pre-flight Checks\n\nRun these checks sequentially via exec:\n\n1. **Dirty working tree check:**\n\n   ```\n   git status --porcelain\n   ```\n\n   If output is non-empty, warn the user:\n\n   > \"Working tree has uncommitted changes. Sub-agents will create branches from HEAD — uncommitted changes will NOT be included. Continue?\"\n   > Wait for confirmation. If declined, stop.\n\n2. **Record base branch:**\n\n   ```\n   git rev-parse --abbrev-ref HEAD\n   ```\n\n   Store as BASE_BRANCH.\n\n3. **Verify remote access:**\n   If FORK_MODE:\n   - Verify the fork remote exists. Check if a git remote named `fork` exists:\n     ```\n     git remote get-url fork\n     ```\n     If it doesn't exist, add it:\n     ```\n     git remote add fork https://x-access-token:[email protected]/{PUSH_REPO}.git\n     ```\n   - Also verify origin (the source repo) is reachable:\n     ```\n     git ls-remote --exit-code origin HEAD\n     ```\n\n   If not FORK_MODE:\n\n   ```\n   git ls-remote --exit-code origin HEAD\n   ```\n\n   If this fails, stop with: \"Cannot reach remote origin. Check your network and git config.\"\n\n4. **Verify GH_TOKEN validity:**\n\n   ```\n   curl -s -o /dev/null -w \"%{http_code}\" -H \"Authorization: Bearer $GH_TOKEN\" https://api.github.com/user\n   ```\n\n   If HTTP status is not 200, stop with:\n\n   > \"GitHub authentication failed. Please check your apiKey in the HanzoBot dashboard or in ~/.hanzo-bot/hanzo-bot.json under skills.entries.gh-issues.\"\n\n5. **Check for existing PRs:**\n   For each confirmed issue number N, run:\n\n   ```\n   curl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n     \"https://api.github.com/repos/{SOURCE_REPO}/pulls?head={PUSH_REPO_OWNER}:fix/issue-{N}&state=open&per_page=1\"\n   ```\n\n   (Where PUSH_REPO_OWNER is the owner portion of `PUSH_REPO`)\n   If the response array is non-empty, remove that issue from the processing list and report:\n\n   > \"Skipping #{N} — PR already exists: {html_url}\"\n\n   If all issues are skipped, report and stop (or loop back if in watch mode).\n\n6. **Check for in-progress branches (no PR yet = sub-agent still working):**\n   For each remaining issue number N (not already skipped by the PR check above), check if a `fix/issue-{N}` branch exists on the **push repo** (which may be a fork, not origin):\n\n   ```\n   curl -s -o /dev/null -w \"%{http_code}\" \\\n     -H \"Authorization: Bearer $GH_TOKEN\" \\\n     \"https://api.github.com/repos/{PUSH_REPO}/branches/fix/issue-{N}\"\n   ```\n\n   If HTTP 200 → the branch exists on the push repo but no open PR was found for it in step 5. Skip that issue:\n\n   > \"Skipping #{N} — branch fix/issue-{N} exists on {PUSH_REPO}, fix likely in progress\"\n\n   This check uses the GitHub API instead of `git ls-remote` so it works correctly in fork mode (where branches are pushed to the fork, not origin).\n\n   If all issues are skipped after this check, report and stop (or loop back if in watch mode).\n\n7. **Check claim-based in-progress tracking:**\n   This prevents duplicate processing when a sub-agent from a previous cron run is still working but hasn't pushed a branch or opened a PR yet.\n\n   Read the claims file (create empty `{}` if missing):\n\n   ```\n   CLAIMS_FILE=\"/data/.clawdbot/gh-issues-claims.json\"\n   if [ ! -f \"$CLAIMS_FILE\" ]; then\n     mkdir -p /data/.clawdbot\n     echo '{}' > \"$CLAIMS_FILE\"\n   fi\n   ```\n\n   Parse the claims file. For each entry, check if the claim timestamp is older than 2 hours. If so, remove it (expired — the sub-agent likely finished or failed silently). Write back the cleaned file:\n\n   ```\n   CLAIMS=$(cat \"$CLAIMS_FILE\")\n   CUTOFF=$(date -u -d '2 hours ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-2H +%Y-%m-%dT%H:%M:%SZ)\n   CLAIMS=$(echo \"$CLAIMS\" | jq --arg cutoff \"$CUTOFF\" 'to_entries | map(select(.value > $cutoff)) | from_entries')\n   echo \"$CLAIMS\" > \"$CLAIMS_FILE\"\n   ```\n\n   For each remaining issue number N (not already skipped by steps 5 or 6), check if `{SOURCE_REPO}#{N}` exists as a key in the claims file.\n\n   If claimed and not expired → skip:\n\n   > \"Skipping #{N} — sub-agent claimed this issue {minutes}m ago, still within timeout window\"\n\n   Where `{minutes}` is calculated from the claim timestamp to now.\n\n   If all issues are skipped after this check, report and stop (or loop back if in watch mode).\n\n---\n\n## Phase 5 — Spawn Sub-agents (Parallel)\n\n**Cron mode (`--cron` is active):**\n\n- **Sequential cursor tracking:** Use a cursor file to track which issue to process next:\n\n  ```\n  CURSOR_FILE=\"/data/.clawdbot/gh-issues-cursor-{SOURCE_REPO_SLUG}.json\"\n  # SOURCE_REPO_SLUG = owner-repo with slashes replaced by hyphens (e.g., hanzo-bot-hanzo-bot)\n  ```\n\n  Read the cursor file (create if missing):\n\n  ```\n  if [ ! -f \"$CURSOR_FILE\" ]; then\n    echo '{\"last_processed\": null, \"in_progress\": null}' > \"$CURSOR_FILE\"\n  fi\n  ```\n\n  - `last_processed`: issue number of the last completed issue (or null if none)\n  - `in_progress`: issue number currently being processed (or null)\n\n- **Select next issue:** Filter the fetched issues list to find the first issue where:\n  - Issue number > last_processed (if last_processed is set)\n  - AND issue is not in the claims file (not already in progress)\n  - AND no PR exists for the issue (checked in Phase 4 step 5)\n  - AND no branch exists on the push repo (checked in Phase 4 step 6)\n- If no eligible issue is found after the last_processed cursor, wrap around to the beginning (start from the oldest eligible issue).\n\n- If an eligible issue is found:\n  1. Mark it as in_progress in the cursor file\n  2. Spawn a single sub-agent for that one issue with `cleanup: \"keep\"` and `runTimeoutSeconds: 3600`\n  3. If `--model` was provided, include `model: \"{MODEL}\"` in the spawn config\n  4. If `--notify-channel` was provided, include the channel in the task so the sub-agent can notify\n  5. Do NOT await the sub-agent result — fire and forget\n  6. **Write claim:** After spawning, read the claims file, add `{SOURCE_REPO}#{N}` with the current ISO timestamp, and write it back\n  7. Immediately report: \"Spawned fix agent for #{N} — will create PR when complete\"\n  8. Exit the skill. Do not proceed to Results Collection or Phase 6.\n\n- If no eligible issue is found (all issues either have PRs, have branches, or are in progress), report \"No eligible issues to process — all issues have PRs/branches or are in progress\" and exit.\n\n**Normal mode (`--cron` is NOT active):**\nFor each confirmed issue, spawn a sub-agent using sessions_spawn. Launch up to 8 concurrently (matching `subagents.maxConcurrent: 8`). If more than 8 issues, batch them — launch the next agent as each completes.\n\n**Write claims:** After spawning each sub-agent, read the claims file, add `{SOURCE_REPO}#{N}` with the current ISO timestamp, and write it back (same procedure as cron mode above). This covers interactive usage where watch mode might overlap with cron runs.\n\n### Sub-agent Task Prompt\n\nFor each issue, construct the following prompt and pass it to sessions_spawn. Variables to inject into the template:\n\n- {SOURCE_REPO} — upstream repo where the issue lives\n- {PUSH_REPO} — repo to push branches to (same as SOURCE_REPO unless fork mode)\n- {FORK_MODE} — true/false\n- {PUSH_REMOTE} — `fork` if FORK_MODE, otherwise `origin`\n- {number}, {title}, {url}, {labels}, {body} — from the issue\n- {BASE_BRANCH} — from Phase 4\n- {notify_channel} — Telegram channel ID for notifications (empty if not set). Replace {notify_channel} in the template below with the value of `--notify-channel` flag (or leave as empty string if not provided).\n\nWhen constructing the task, replace all template variables including {notify_channel} with actual values.\n\n```\nYou are a focused code-fix agent. Your task is to fix a single GitHub issue and open a PR.\n\nIMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.\n\nFirst, ensure GH_TOKEN is set. Check: `echo $GH_TOKEN`. If empty, read from config:\nGH_TOKEN=$(cat ~/.hanzo-bot/hanzo-bot.json 2>/dev/null | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/hanzo-bot.json 2>/dev/null | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty')\n\nUse the token in all GitHub API calls:\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" ...\n\n<config>\nSource repo (issues): {SOURCE_REPO}\nPush repo (branches + PRs): {PUSH_REPO}\nFork mode: {FORK_MODE}\nPush remote name: {PUSH_REMOTE}\nBase branch: {BASE_BRANCH}\nNotify channel: {notify_channel}\n</config>\n\n<issue>\nRepository: {SOURCE_REPO}\nIssue: #{number}\nTitle: {title}\nURL: {url}\nLabels: {labels}\nBody: {body}\n</issue>\n\n<instructions>\nFollow these steps in order. If any step fails, report the failure and stop.\n\n0. SETUP — Ensure GH_TOKEN is available:\n```\n\nexport GH_TOKEN=$(node -e \"const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/data/.clawdbot/hanzo-bot.json','utf8')); console.log(c.skills?.entries?.['gh-issues']?.apiKey || '')\")\n\n```\nIf that fails, also try:\n```\n\nexport GH_TOKEN=$(cat ~/.hanzo-bot/hanzo-bot.json 2>/dev/null | node -e \"const fs=require('fs');const d=JSON.parse(fs.readFileSync(0,'utf8'));console.log(d.skills?.entries?.['gh-issues']?.apiKey||'')\")\n\n```\nVerify: echo \"Token: ${GH_TOKEN:0:10}...\"\n\n1. CONFIDENCE CHECK — Before implementing, assess whether this issue is actionable:\n- Read the issue body carefully. Is the problem clearly described?\n- Search the codebase (grep/find) for the relevant code. Can you locate it?\n- Is the scope reasonable? (single file/function = good, whole subsystem = bad)\n- Is a specific fix suggested or is it a vague complaint?\n\nRate your confidence (1-10). If confidence < 7, STOP and report:\n> \"Skipping #{number}: Low confidence (score: N/10) — [reason: vague requirements | cannot locate code | scope too large | no clear fix suggested]\"\n\nOnly proceed if confidence >= 7.\n\n1. UNDERSTAND — Read the issue carefully. Identify what needs to change and where.\n\n2. BRANCH — Create a feature branch from the base branch:\ngit checkout -b fix/issue-{number} {BASE_BRANCH}\n\n3. ANALYZE — Search the codebase to find relevant files:\n- Use grep/find via exec to locate code related to the issue\n- Read the relevant files to understand the current behavior\n- Identify the root cause\n\n4. IMPLEMENT — Make the minimal, focused fix:\n- Follow existing code style and conventions\n- Change only what is necessary to fix the issue\n- Do not add unrelated changes or new dependencies without justification\n\n5. TEST — Discover and run the existing test suite if one exists:\n- Look for package.json scripts, Makefile targets, pytest, cargo test, etc.\n- Run the relevant tests\n- If tests fail after your fix, attempt ONE retry with a corrected approach\n- If tests still fail, report the failure\n\n6. COMMIT — Stage and commit your changes:\ngit add {changed_files}\ngit commit -m \"fix: {short_description}\n\nFixes {SOURCE_REPO}#{number}\"\n\n7. PUSH — Push the branch:\nFirst, ensure the push remote uses token auth and disable credential helpers:\ngit config --global credential.helper \"\"\ngit remote set-url {PUSH_REMOTE} https://x-access-token:[email protected]/{PUSH_REPO}.git\nThen push:\nGIT_ASKPASS=true git push -u {PUSH_REMOTE} fix/issue-{number}\n\n8. PR — Create a pull request using the GitHub API:\n\nIf FORK_MODE is true, the PR goes from your fork to the source repo:\n- head = \"{PUSH_REPO_OWNER}:fix/issue-{number}\"\n- base = \"{BASE_BRANCH}\"\n- PR is created on {SOURCE_REPO}\n\nIf FORK_MODE is false:\n- head = \"fix/issue-{number}\"\n- base = \"{BASE_BRANCH}\"\n- PR is created on {SOURCE_REPO}\n\ncurl -s -X POST \\\n  -H \"Authorization: Bearer $GH_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  https://api.github.com/repos/{SOURCE_REPO}/pulls \\\n  -d '{\n    \"title\": \"fix: {title}\",\n    \"head\": \"{head_value}\",\n    \"base\": \"{BASE_BRANCH}\",\n    \"body\": \"## Summary\\n\\n{one_paragraph_description_of_fix}\\n\\n## Changes\\n\\n{bullet_list_of_changes}\\n\\n## Testing\\n\\n{what_was_tested_and_results}\\n\\nFixes {SOURCE_REPO}#{number}\"\n  }'\n\nExtract the `html_url` from the response — this is the PR link.\n\n9. REPORT — Send back a summary:\n- PR URL (the html_url from step 8)\n- Files changed (list)\n- Fix summary (1-2 sentences)\n- Any caveats or concerns\n\n10. NOTIFY (if notify_channel is set) — If {notify_channel} is not empty, send a notification to the Telegram channel:\n```\n\nUse the message tool with:\n\n- action: \"send\"\n- channel: \"telegram\"\n- target: \"{notify_channel}\"\n- message: \"✅ PR Created: {SOURCE_REPO}#{number}\n\n{title}\n\n{pr_url}\n\nFiles changed: {files_changed_list}\"\n\n```\n</instructions>\n\n<constraints>\n- No force-push, no modifying the base branch\n- No unrelated changes or gratuitous refactoring\n- No new dependencies without strong justification\n- If the issue is unclear or too complex to fix confidently, report your analysis instead of guessing\n- Do NOT use the gh CLI — it is not available. Use curl + GitHub REST API for all GitHub operations.\n- GH_TOKEN is already in the environment — do NOT prompt for auth\n- Time limit: you have 60 minutes max. Be thorough — analyze properly, test your fix, don't rush.\n</constraints>\n```\n\n### Spawn configuration per sub-agent:\n\n- runTimeoutSeconds: 3600 (60 minutes)\n- cleanup: \"keep\" (preserve transcripts for review)\n- If `--model` was provided, include `model: \"{MODEL}\"` in the spawn config\n\n### Timeout Handling\n\nIf a sub-agent exceeds 60 minutes, record it as:\n\n> \"#{N} — Timed out (issue may be too complex for auto-fix)\"\n\n---\n\n## Results Collection\n\n**If `--cron` is active:** Skip this section entirely — the orchestrator already exited after spawning in Phase 5.\n\nAfter ALL sub-agents complete (or timeout), collect their results. Store the list of successfully opened PRs in `OPEN_PRS` (PR number, branch name, issue number, PR URL) for use in Phase 6.\n\nPresent a summary table:\n\n| Issue                 | Status    | PR                             | Notes                          |\n| --------------------- | --------- | ------------------------------ | ------------------------------ |\n| #42 Fix null pointer  | PR opened | https://github.com/.../pull/99 | 3 files changed                |\n| #37 Add retry logic   | Failed    | --                             | Could not identify target code |\n| #15 Update docs       | Timed out | --                             | Too complex for auto-fix       |\n| #8 Fix race condition | Skipped   | --                             | PR already exists              |\n\n**Status values:**\n\n- **PR opened** — success, link to PR\n- **Failed** — sub-agent could not complete (include reason in Notes)\n- **Timed out** — exceeded 60-minute limit\n- **Skipped** — existing PR detected in pre-flight\n\nEnd with a one-line summary:\n\n> \"Processed {N} issues: {success} PRs opened, {failed} failed, {skipped} skipped.\"\n\n**Send notification to channel (if --notify-channel is set):**\nIf `--notify-channel` was provided, send the final summary to that Telegram channel using the `message` tool:\n\n```\nUse the message tool with:\n- action: \"send\"\n- channel: \"telegram\"\n- target: \"{notify-channel}\"\n- message: \"✅ GitHub Issues Processed\n\nProcessed {N} issues: {success} PRs opened, {failed} failed, {skipped} skipped.\n\n{PR_LIST}\"\n\nWhere PR_LIST includes only successfully opened PRs in format:\n• #{issue_number}: {PR_url} ({notes})\n```\n\nThen proceed to Phase 6.\n\n---\n\n## Phase 6 — PR Review Handler\n\nThis phase monitors open PRs (created by this skill or pre-existing `fix/issue-*` PRs) for review comments and spawns sub-agents to address them.\n\n**When this phase runs:**\n\n- After Results Collection (Phases 2-5 completed) — checks PRs that were just opened\n- When `--reviews-only` flag is set — skips Phases 2-5 entirely, runs only this phase\n- In watch mode — runs every poll cycle after checking for new issues\n\n**Cron review mode (`--cron --reviews-only`):**\nWhen both `--cron` and `--reviews-only` are set:\n\n1. Run token resolution (Phase 2 token section)\n2. Discover open `fix/issue-*` PRs (Step 6.1)\n3. Fetch review comments (Step 6.2)\n4. **Analyze comment content for actionability** (Step 6.3)\n5. If actionable comments are found, spawn ONE review-fix sub-agent for the first PR with unaddressed comments — fire-and-forget (do NOT await result)\n   - Use `cleanup: \"keep\"` and `runTimeoutSeconds: 3600`\n   - If `--model` was provided, include `model: \"{MODEL}\"` in the spawn config\n6. Report: \"Spawned review handler for PR #{N} — will push fixes when complete\"\n7. Exit the skill immediately. Do not proceed to Step 6.5 (Review Results).\n\nIf no actionable comments found, report \"No actionable review comments found\" and exit.\n\n**Normal mode (non-cron) continues below:**\n\n### Step 6.1 — Discover PRs to Monitor\n\nCollect PRs to check for review comments:\n\n**If coming from Phase 5:** Use the `OPEN_PRS` list from Results Collection.\n\n**If `--reviews-only` or subsequent watch cycle:** Fetch all open PRs with `fix/issue-` branch pattern:\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/pulls?state=open&per_page=100\"\n```\n\nFilter to only PRs where `head.ref` starts with `fix/issue-`.\n\nFor each PR, extract: `number` (PR number), `head.ref` (branch name), `html_url`, `title`, `body`.\n\nIf no PRs found, report \"No open fix/ PRs to monitor\" and stop (or loop back if in watch mode).\n\n### Step 6.2 — Fetch All Review Sources\n\nFor each PR, fetch reviews from multiple sources:\n\n**Fetch PR reviews:**\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/reviews\"\n```\n\n**Fetch PR review comments (inline/file-level):**\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/comments\"\n```\n\n**Fetch PR issue comments (general conversation):**\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/issues/{pr_number}/comments\"\n```\n\n**Fetch PR body for embedded reviews:**\nSome review tools (like Greptile) embed their feedback directly in the PR body. Check for:\n\n- `<!-- greptile_comment -->` markers\n- Other structured review sections in the PR body\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" -H \"Accept: application/vnd.github+json\" \\\n  \"https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}\"\n```\n\nExtract the `body` field and parse for embedded review content.\n\n### Step 6.3 — Analyze Comments for Actionability\n\n**Determine the bot's own username** for filtering:\n\n```\ncurl -s -H \"Authorization: Bearer $GH_TOKEN\" https://api.github.com/user | jq -r '.login'\n```\n\nStore as `BOT_USERNAME`. Exclude any comment where `user.login` equals `BOT_USERNAME`.\n\n**For each comment/review, analyze the content to determine if it requires action:**\n\n**NOT actionable (skip):**\n\n- Pure approvals or \"LGTM\" without suggestions\n- Bot comments that are informational only (CI status, auto-generated summaries without specific requests)\n- Comments already addressed (check if bot replied with \"Addressed in commit...\")\n- Reviews with state `APPROVED` and no inline comments requesting changes\n\n**IS actionable (requires attention):**\n\n- Reviews with state `CHANGES_REQUESTED`\n- Reviews with state `COMMENTED` that contain specific requests:\n  - \"this test needs to be updated\"\n  - \"please fix\", \"change this\", \"update\", \"can you\", \"should be\", \"needs to\"\n  - \"will fail\", \"will break\", \"causes an error\"\n  - Mentions of specific code issues (bugs, missing error handling, edge cases)\n- Inline review comments pointing out issues in the code\n- Embedded reviews in PR body that identify:\n  - Critical issues or breaking changes\n  - Test failures expected\n  - Specific code that needs attention\n  - Confidence scores with concerns\n\n**Parse embedded review content (e.g., Greptile):**\nLook for sections marked with `<!-- greptile_comment -->` or similar. Extract:\n\n- Summary text\n- Any mentions of \"Critical issue\", \"needs attention\", \"will fail\", \"test needs to be updated\"\n- Confidence scores below 4/5 (indicates concerns)\n\n**Build actionable_comments list** with:\n\n- Source (review, inline comment, PR body, etc.)\n- Author\n- Body text\n- For inline: file path and line number\n- Specific action items identified\n\nIf no actionable comments found across any PR, report \"No actionable review comments found\" and stop (or loop back if in watch mode).\n\n### Step 6.4 — Present Review Comments\n\nDisplay a table of PRs with pending actionable comments:\n\n```\n| PR | Branch | Actionable Comments | Sources |\n|----|--------|---------------------|---------|\n| #99 | fix/issue-42 | 2 comments | @reviewer1, greptile |\n| #101 | fix/issue-37 | 1 comment | @reviewer2 |\n```\n\nIf `--yes` is NOT set and this is not a subsequent watch poll: ask the user to confirm which PRs to address (\"all\", comma-separated PR numbers, or \"skip\").\n\n### Step 6.5 — Spawn Review Fix Sub-agents (Parallel)\n\nFor each PR with actionable comments, spawn a sub-agent. Launch up to 8 concurrently.\n\n**Review fix sub-agent prompt:**\n\n```\nYou are a PR review handler agent. Your task is to address review comments on a pull request by making the requested changes, pushing updates, and replying to each comment.\n\nIMPORTANT: Do NOT use the gh CLI — it is not installed. Use curl with the GitHub REST API for all GitHub operations.\n\nFirst, ensure GH_TOKEN is set. Check: echo $GH_TOKEN. If empty, read from config:\nGH_TOKEN=$(cat ~/.hanzo-bot/hanzo-bot.json 2>/dev/null | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty') || GH_TOKEN=$(cat /data/.clawdbot/hanzo-bot.json 2>/dev/null | jq -r '.skills.entries[\"gh-issues\"].apiKey // empty')\n\n<config>\nRepository: {SOURCE_REPO}\nPush repo: {PUSH_REPO}\nFork mode: {FORK_MODE}\nPush remote: {PUSH_REMOTE}\nPR number: {pr_number}\nPR URL: {pr_url}\nBranch: {branch_name}\n</config>\n\n<review_comments>\n{json_array_of_actionable_comments}\n\nEach comment has:\n- id: comment ID (for replying)\n- user: who left it\n- body: the comment text\n- path: file path (for inline comments)\n- line: line number (for inline comments)\n- diff_hunk: surrounding diff context (for inline comments)\n- source: where the comment came from (review, inline, pr_body, greptile, etc.)\n</review_comments>\n\n<instructions>\nFollow these steps in order:\n\n0. SETUP — Ensure GH_TOKEN is available:\n```\n\nexport GH_TOKEN=$(node -e \"const fs=require('fs'); const c=JSON.parse(fs.readFileSync('/data/.clawdbot/hanzo-bot.json','utf8')); console.log(c.skills?.entries?.['gh-issues']?.apiKey || '')\")\n\n```\nVerify: echo \"Token: ${GH_TOKEN:0:10}...\"\n\n1. CHECKOUT — Switch to the PR branch:\ngit fetch {PUSH_REMOTE} {branch_name}\ngit checkout {branch_name}\ngit pull {PUSH_REMOTE} {branch_name}\n\n2. UNDERSTAND — Read ALL review comments carefully. Group them by file. Understand what each reviewer is asking for.\n\n3. IMPLEMENT — For each comment, make the requested change:\n- Read the file and locate the relevant code\n- Make the change the reviewer requested\n- If the comment is vague or you disagree, still attempt a reasonable fix but note your concern\n- If the comment asks for something impossible or contradictory, skip it and explain why in your reply\n\n4. TEST — Run existing tests to make sure your changes don't break anything:\n- If tests fail, fix the issue or revert the problematic change\n- Note any test failures in your replies\n\n5. COMMIT — Stage and commit all changes in a single commit:\ngit add {changed_files}\ngit commit -m \"fix: address review comments on PR #{pr_number}\n\nAddresses review feedback from {reviewer_names}\"\n\n6. PUSH — Push the updated branch:\ngit config --global credential.helper \"\"\ngit remote set-url {PUSH_REMOTE} https://x-access-token:[email protected]/{PUSH_REPO}.git\nGIT_ASKPASS=true git push {PUSH_REMOTE} {branch_name}\n\n7. REPLY — For each addressed comment, post a reply:\n\nFor inline review comments (have a path/line), reply to the comment thread:\ncurl -s -X POST \\\n  -H \"Authorization: Bearer $GH_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  https://api.github.com/repos/{SOURCE_REPO}/pulls/{pr_number}/comments/{comment_id}/replies \\\n  -d '{\"body\": \"Addressed in commit {short_sha} — {brief_description_of_change}\"}'\n\nFor general PR comments (issue comments), reply on the PR:\ncurl -s -X POST \\\n  -H \"Authorization: Bearer $GH_TOKEN\" \\\n  -H \"Accept: application/vnd.github+json\" \\\n  https://api.github.com/repos/{SOURCE_REPO}/issues/{pr_number}/comments \\\n  -d '{\"body\": \"Addressed feedback from @{reviewer}:\\n\\n{summary_of_changes_made}\\n\\nUpdated in commit {short_sha}\"}'\n\nFor comments you could NOT address, reply explaining why:\n\"Unable to address this comment: {reason}. This may need manual review.\"\n\n8. REPORT — Send back a summary:\n- PR URL\n- Number of comments addressed vs skipped\n- Commit SHA\n- Files changed\n- Any comments that need manual attention\n</instructions>\n\n<constraints>\n- Only modify files relevant to the review comments\n- Do not make unrelated changes\n- Do not force-push — always regular push\n- If a comment contradicts another comment, address the most recent one and flag the conflict\n- Do NOT use the gh CLI — use curl + GitHub REST API\n- GH_TOKEN is already in the environment — do not prompt for auth\n- Time limit: 60 minutes max\n</constraints>\n```\n\n**Spawn configuration per sub-agent:**\n\n- runTimeoutSeconds: 3600 (60 minutes)\n- cleanup: \"keep\" (preserve transcripts for review)\n- If `--model` was provided, include `model: \"{MODEL}\"` in the spawn config\n\n### Step 6.6 — Review Results\n\nAfter all review sub-agents complete, present a summary:\n\n```\n| PR | Comments Addressed | Comments Skipped | Commit | Status |\n|----|-------------------|-----------------|--------|--------|\n| #99 fix/issue-42 | 3 | 0 | abc123f | All addressed |\n| #101 fix/issue-37 | 1 | 1 | def456a | 1 needs manual review |\n```\n\nAdd comment IDs from this batch to `ADDRESSED_COMMENTS` set to prevent re-processing.\n\n---\n\n## Watch Mode (if --watch is active)\n\nAfter presenting results from the current batch:\n\n1. Add all issue numbers from this batch to the running set PROCESSED_ISSUES.\n2. Add all addressed comment IDs to ADDRESSED_COMMENTS.\n3. Tell the user:\n   > \"Next poll in {interval} minutes... (say 'stop' to end watch mode)\"\n4. Sleep for {interval} minutes.\n5. Go back to **Phase 2 — Fetch Issues**. The fetch will automatically filter out:\n   - Issues already in PROCESSED_ISSUES\n   - Issues that have existing fix/issue-{N} PRs (caught in Phase 4 pre-flight)\n6. After Phases 2-5 (or if no new issues), run **Phase 6** to check for new review comments on ALL tracked PRs (both newly created and previously opened).\n7. If no new issues AND no new actionable review comments → report \"No new activity. Polling again in {interval} minutes...\" and loop back to step 4.\n8. The user can say \"stop\" at any time to exit watch mode. When stopping, present a final cumulative summary of ALL batches — issues processed AND review comments addressed.\n\n**Context hygiene between polls — IMPORTANT:**\nOnly retain between poll cycles:\n\n- PROCESSED_ISSUES (set of issue numbers)\n- ADDRESSED_COMMENTS (set of comment IDs)\n- OPEN_PRS (list of tracked PRs: number, branch, URL)\n- Cumulative results (one line per issue + one line per review batch)\n- Parsed arguments from Phase 1\n- BASE_BRANCH, SOURCE_REPO, PUSH_REPO, FORK_MODE, BOT_USERNAME\n  Do NOT retain issue bodies, comment bodies, sub-agent transcripts, or codebase analysis between polls.\n"}]},{"slug":"gifgrep","displayName":"gifgrep","summary":"Search GIF providers with CLI/TUI, download results, and extract stills/sheets.","version":"1.0.0","sha256hash":"8f9cd697a7bc62593c9a053bdfc6cad651edc577358575b4811132f9ec5f6750","files":[{"path":"SKILL.md","size":2186,"sha256":"5dcb2246e2c12327e0202d13e1daeebf4b19f685c820ebe2925805cb6166fb46","contentType":"text/markdown","content":"---\nname: gifgrep\ndescription: Search GIF providers with CLI/TUI, download results, and extract stills/sheets.\nhomepage: https://gifgrep.com\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🧲\",\n        \"requires\": { \"bins\": [\"gifgrep\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/gifgrep\",\n              \"bins\": [\"gifgrep\"],\n              \"label\": \"Install gifgrep (brew)\",\n            },\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/gifgrep/cmd/gifgrep@latest\",\n              \"bins\": [\"gifgrep\"],\n              \"label\": \"Install gifgrep (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# gifgrep\n\nUse `gifgrep` to search GIF providers (Tenor/Giphy), browse in a TUI, download results, and extract stills or sheets.\n\nGIF-Grab (gifgrep workflow)\n\n- Search → preview → download → extract (still/sheet) for fast review and sharing.\n\nQuick start\n\n- `gifgrep cats --max 5`\n- `gifgrep cats --format url | head -n 5`\n- `gifgrep search --json cats | jq '.[0].url'`\n- `gifgrep tui \"office handshake\"`\n- `gifgrep cats --download --max 1 --format url`\n\nTUI + previews\n\n- TUI: `gifgrep tui \"query\"`\n- CLI still previews: `--thumbs` (Kitty/Ghostty only; still frame)\n\nDownload + reveal\n\n- `--download` saves to `~/Downloads`\n- `--reveal` shows the last download in Finder\n\nStills + sheets\n\n- `gifgrep still ./clip.gif --at 1.5s -o still.png`\n- `gifgrep sheet ./clip.gif --frames 9 --cols 3 -o sheet.png`\n- Sheets = single PNG grid of sampled frames (great for quick review, docs, PRs, chat).\n- Tune: `--frames` (count), `--cols` (grid width), `--padding` (spacing).\n\nProviders\n\n- `--source auto|tenor|giphy`\n- `GIPHY_API_KEY` required for `--source giphy`\n- `TENOR_API_KEY` optional (Tenor demo key used if unset)\n\nOutput\n\n- `--json` prints an array of results (`id`, `title`, `url`, `preview_url`, `tags`, `width`, `height`)\n- `--format` for pipe-friendly fields (e.g., `url`)\n\nEnvironment tweaks\n\n- `GIFGREP_SOFTWARE_ANIM=1` to force software animation\n- `GIFGREP_CELL_ASPECT=0.5` to tweak preview geometry\n"}]},{"slug":"github","displayName":"github","summary":"GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: complex web UI interactions requiring manual browser flows (use browser tooling when available), bulk operations across many repos (script with gh api), or when gh auth is not configured.","version":"1.0.0","sha256hash":"5fe533f2a58bfd619f8e6d61d438ec4215170ea03ad24649f2937695d9c7b122","files":[{"path":"SKILL.md","size":4126,"sha256":"cfdd98aed998e8fa16c8dba2e80e9ee19b6931d5600e6803dd342d3bc128e8fe","contentType":"text/markdown","content":"---\nname: github\ndescription: \"GitHub operations via `gh` CLI: issues, PRs, CI runs, code review, API queries. Use when: (1) checking PR status or CI, (2) creating/commenting on issues, (3) listing/filtering PRs or issues, (4) viewing run logs. NOT for: complex web UI interactions requiring manual browser flows (use browser tooling when available), bulk operations across many repos (script with gh api), or when gh auth is not configured.\"\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🐙\",\n        \"requires\": { \"bins\": [\"gh\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"gh\",\n              \"bins\": [\"gh\"],\n              \"label\": \"Install GitHub CLI (brew)\",\n            },\n            {\n              \"id\": \"apt\",\n              \"kind\": \"apt\",\n              \"package\": \"gh\",\n              \"bins\": [\"gh\"],\n              \"label\": \"Install GitHub CLI (apt)\",\n            },\n          ],\n      },\n  }\n---\n\n# GitHub Skill\n\nUse the `gh` CLI to interact with GitHub repositories, issues, PRs, and CI.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- Checking PR status, reviews, or merge readiness\n- Viewing CI/workflow run status and logs\n- Creating, closing, or commenting on issues\n- Creating or merging pull requests\n- Querying GitHub API for repository data\n- Listing repos, releases, or collaborators\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Local git operations (commit, push, pull, branch) → use `git` directly\n- Non-GitHub repos (GitLab, Bitbucket, self-hosted) → different CLIs\n- Cloning repositories → use `git clone`\n- Reviewing actual code changes → use `coding-agent` skill\n- Complex multi-file diffs → use `coding-agent` or read files directly\n\n## Setup\n\n```bash\n# Authenticate (one-time)\ngh auth login\n\n# Verify\ngh auth status\n```\n\n## Common Commands\n\n### Pull Requests\n\n```bash\n# List PRs\ngh pr list --repo owner/repo\n\n# Check CI status\ngh pr checks 55 --repo owner/repo\n\n# View PR details\ngh pr view 55 --repo owner/repo\n\n# Create PR\ngh pr create --title \"feat: add feature\" --body \"Description\"\n\n# Merge PR\ngh pr merge 55 --squash --repo owner/repo\n```\n\n### Issues\n\n```bash\n# List issues\ngh issue list --repo owner/repo --state open\n\n# Create issue\ngh issue create --title \"Bug: something broken\" --body \"Details...\"\n\n# Close issue\ngh issue close 42 --repo owner/repo\n```\n\n### CI/Workflow Runs\n\n```bash\n# List recent runs\ngh run list --repo owner/repo --limit 10\n\n# View specific run\ngh run view <run-id> --repo owner/repo\n\n# View failed step logs only\ngh run view <run-id> --repo owner/repo --log-failed\n\n# Re-run failed jobs\ngh run rerun <run-id> --failed --repo owner/repo\n```\n\n### API Queries\n\n```bash\n# Get PR with specific fields\ngh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'\n\n# List all labels\ngh api repos/owner/repo/labels --jq '.[].name'\n\n# Get repo stats\ngh api repos/owner/repo --jq '{stars: .stargazers_count, forks: .forks_count}'\n```\n\n## JSON Output\n\nMost commands support `--json` for structured output with `--jq` filtering:\n\n```bash\ngh issue list --repo owner/repo --json number,title --jq '.[] | \"\\(.number): \\(.title)\"'\ngh pr list --json number,title,state,mergeable --jq '.[] | select(.mergeable == \"MERGEABLE\")'\n```\n\n## Templates\n\n### PR Review Summary\n\n```bash\n# Get PR overview for review\nPR=55 REPO=owner/repo\necho \"## PR #$PR Summary\"\ngh pr view $PR --repo $REPO --json title,body,author,additions,deletions,changedFiles \\\n  --jq '\"**\\(.title)** by @\\(.author.login)\\n\\n\\(.body)\\n\\n📊 +\\(.additions) -\\(.deletions) across \\(.changedFiles) files\"'\ngh pr checks $PR --repo $REPO\n```\n\n### Issue Triage\n\n```bash\n# Quick issue triage view\ngh issue list --repo owner/repo --state open --json number,title,labels,createdAt \\\n  --jq '.[] | \"[\\(.number)] \\(.title) - \\([.labels[].name] | join(\", \")) (\\(.createdAt[:10]))\"'\n```\n\n## Notes\n\n- Always specify `--repo owner/repo` when not in a git directory\n- Use URLs directly: `gh pr view https://github.com/owner/repo/pull/55`\n- Rate limits apply; use `gh api --cache 1h` for repeated queries\n"}]},{"slug":"gog","displayName":"gog","summary":"Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.","version":"1.0.0","sha256hash":"86c3418a405ae303cb7943c397bfadf679d76bafafe5a9ed8cb644cf2110a9b9","files":[{"path":"SKILL.md","size":4573,"sha256":"8cfff4aa28f764997113675a0d0c3537a450a0256c5fe718aae8871bbd1e9b6f","contentType":"text/markdown","content":"---\nname: gog\ndescription: Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.\nhomepage: https://gogcli.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🎮\",\n        \"requires\": { \"bins\": [\"gog\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/gogcli\",\n              \"bins\": [\"gog\"],\n              \"label\": \"Install gog (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# gog\n\nUse `gog` for Gmail/Calendar/Drive/Contacts/Sheets/Docs. Requires OAuth setup.\n\nSetup (once)\n\n- `gog auth credentials /path/to/client_secret.json`\n- `gog auth add [email protected] --services gmail,calendar,drive,contacts,docs,sheets`\n- `gog auth list`\n\nCommon commands\n\n- Gmail search: `gog gmail search 'newer_than:7d' --max 10`\n- Gmail messages search (per email, ignores threading): `gog gmail messages search \"in:inbox from:ryanair.com\" --max 20 --account [email protected]`\n- Gmail send (plain): `gog gmail send --to [email protected] --subject \"Hi\" --body \"Hello\"`\n- Gmail send (multi-line): `gog gmail send --to [email protected] --subject \"Hi\" --body-file ./message.txt`\n- Gmail send (stdin): `gog gmail send --to [email protected] --subject \"Hi\" --body-file -`\n- Gmail send (HTML): `gog gmail send --to [email protected] --subject \"Hi\" --body-html \"<p>Hello</p>\"`\n- Gmail draft: `gog gmail drafts create --to [email protected] --subject \"Hi\" --body-file ./message.txt`\n- Gmail send draft: `gog gmail drafts send <draftId>`\n- Gmail reply: `gog gmail send --to [email protected] --subject \"Re: Hi\" --body \"Reply\" --reply-to-message-id <msgId>`\n- Calendar list events: `gog calendar events <calendarId> --from <iso> --to <iso>`\n- Calendar create event: `gog calendar create <calendarId> --summary \"Title\" --from <iso> --to <iso>`\n- Calendar create with color: `gog calendar create <calendarId> --summary \"Title\" --from <iso> --to <iso> --event-color 7`\n- Calendar update event: `gog calendar update <calendarId> <eventId> --summary \"New Title\" --event-color 4`\n- Calendar show colors: `gog calendar colors`\n- Drive search: `gog drive search \"query\" --max 10`\n- Contacts: `gog contacts list --max 20`\n- Sheets get: `gog sheets get <sheetId> \"Tab!A1:D10\" --json`\n- Sheets update: `gog sheets update <sheetId> \"Tab!A1:B2\" --values-json '[[\"A\",\"B\"],[\"1\",\"2\"]]' --input USER_ENTERED`\n- Sheets append: `gog sheets append <sheetId> \"Tab!A:C\" --values-json '[[\"x\",\"y\",\"z\"]]' --insert INSERT_ROWS`\n- Sheets clear: `gog sheets clear <sheetId> \"Tab!A2:Z\"`\n- Sheets metadata: `gog sheets metadata <sheetId> --json`\n- Docs export: `gog docs export <docId> --format txt --out /tmp/doc.txt`\n- Docs cat: `gog docs cat <docId>`\n\nCalendar Colors\n\n- Use `gog calendar colors` to see all available event colors (IDs 1-11)\n- Add colors to events with `--event-color <id>` flag\n- Event color IDs (from `gog calendar colors` output):\n  - 1: #a4bdfc\n  - 2: #7ae7bf\n  - 3: #dbadff\n  - 4: #ff887c\n  - 5: #fbd75b\n  - 6: #ffb878\n  - 7: #46d6db\n  - 8: #e1e1e1\n  - 9: #5484ed\n  - 10: #51b749\n  - 11: #dc2127\n\nEmail Formatting\n\n- Prefer plain text. Use `--body-file` for multi-paragraph messages (or `--body-file -` for stdin).\n- Same `--body-file` pattern works for drafts and replies.\n- `--body` does not unescape `\\n`. If you need inline newlines, use a heredoc or `$'Line 1\\n\\nLine 2'`.\n- Use `--body-html` only when you need rich formatting.\n- HTML tags: `<p>` for paragraphs, `<br>` for line breaks, `<strong>` for bold, `<em>` for italic, `<a href=\"url\">` for links, `<ul>`/`<li>` for lists.\n- Example (plain text via stdin):\n\n  ```bash\n  gog gmail send --to [email protected] \\\n    --subject \"Meeting Follow-up\" \\\n    --body-file - <<'EOF'\n  Hi Name,\n\n  Thanks for meeting today. Next steps:\n  - Item one\n  - Item two\n\n  Best regards,\n  Your Name\n  EOF\n  ```\n\n- Example (HTML list):\n  ```bash\n  gog gmail send --to [email protected] \\\n    --subject \"Meeting Follow-up\" \\\n    --body-html \"<p>Hi Name,</p><p>Thanks for meeting today. Here are the next steps:</p><ul><li>Item one</li><li>Item two</li></ul><p>Best regards,<br>Your Name</p>\"\n  ```\n\nNotes\n\n- Set `[email protected]` to avoid repeating `--account`.\n- For scripting, prefer `--json` plus `--no-input`.\n- Sheets values can be passed via `--values-json` (recommended) or as inline rows.\n- Docs supports export/cat/copy. In-place edits require a Docs API client (not in gog).\n- Confirm before sending mail or creating events.\n- `gog gmail search` returns one row per thread; use `gog gmail messages search` when you need every individual email returned separately.\n"}]},{"slug":"goplaces","displayName":"goplaces","summary":"Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and reviews. Use for human-friendly place lookup or JSON output for scripts.","version":"1.0.0","sha256hash":"d767ca05dd04cd3abffc9bc0e9f577004cf4e091a775c9641892a5de6a1b6360","files":[{"path":"SKILL.md","size":1539,"sha256":"a462959e768414100fb49de8e68fe69be199035e3b2154456a7ceb60aeb47eb3","contentType":"text/markdown","content":"---\nname: goplaces\ndescription: Query Google Places API (New) via the goplaces CLI for text search, place details, resolve, and reviews. Use for human-friendly place lookup or JSON output for scripts.\nhomepage: https://github.com/steipete/goplaces\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📍\",\n        \"requires\": { \"bins\": [\"goplaces\"], \"env\": [\"GOOGLE_PLACES_API_KEY\"] },\n        \"primaryEnv\": \"GOOGLE_PLACES_API_KEY\",\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/goplaces\",\n              \"bins\": [\"goplaces\"],\n              \"label\": \"Install goplaces (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# goplaces\n\nModern Google Places API (New) CLI. Human output by default, `--json` for scripts.\n\nInstall\n\n- Homebrew: `brew install steipete/tap/goplaces`\n\nConfig\n\n- `GOOGLE_PLACES_API_KEY` required.\n- Optional: `GOOGLE_PLACES_BASE_URL` for testing/proxying.\n\nCommon commands\n\n- Search: `goplaces search \"coffee\" --open-now --min-rating 4 --limit 5`\n- Bias: `goplaces search \"pizza\" --lat 40.8 --lng -73.9 --radius-m 3000`\n- Pagination: `goplaces search \"pizza\" --page-token \"NEXT_PAGE_TOKEN\"`\n- Resolve: `goplaces resolve \"Soho, London\" --limit 5`\n- Details: `goplaces details <place_id> --reviews`\n- JSON: `goplaces search \"sushi\" --json`\n\nNotes\n\n- `--no-color` or `NO_COLOR` disables ANSI color.\n- Price levels: 0..4 (free → very expensive).\n- Type filter sends only the first `--type` value (API accepts one).\n"}]},{"slug":"hanzo-aci","displayName":"hanzo-aci","summary":"Agent-Computer Interface for software development agents. AST analysis, code editing, linting, and refactoring with tree-sitter across Python, JS, TS, Ruby, and Go.","version":"1.0.0","sha256hash":"ba4ae4bb46dcf4ae5b46c4baad0c31518fc904f269ad7c3ca0f6b7f4a03e0cb8","files":[{"path":"SKILL.md","size":2618,"sha256":"5e15a198019b39a183dfeb0d33f082f8b68feb3c8f09750d5af66abb91364f8d","contentType":"text/markdown","content":"---\nname: hanzo-aci\ndescription: \"Agent-Computer Interface for software development agents. AST analysis, code editing, linting, and refactoring with tree-sitter across Python, JS, TS, Ruby, and Go.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-aci\",\n              \"label\": \"Install Hanzo ACI (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo ACI — Agent-Computer Interface\n\n`pip install hanzo-aci`\n\nCode editing, AST analysis, and linting tools for software development agents. Tree-sitter powered with multi-language support.\n\n## Quick Start\n\n```python\nfrom hanzo_aci import OHEditor\n\neditor = OHEditor(workspace_root=\"/path/to/project\")\n\n# View file contents\ncontent = editor.view(\"/path/to/file.py\")\n\n# Edit with string replacement\neditor.str_replace(\"/path/to/file.py\",\n    old_str=\"def old_name(\",\n    new_str=\"def new_name(\"\n)\n\n# Insert text at line\neditor.insert(\"/path/to/file.py\", line=10, text=\"    # New comment\\n\")\n\n# Undo last edit\neditor.undo_edit(\"/path/to/file.py\")\n```\n\n## Editor Commands\n\n| Command       | Description                          |\n| ------------- | ------------------------------------ |\n| `view`        | View file contents with line numbers |\n| `create`      | Create a new file                    |\n| `str_replace` | Replace exact string in file         |\n| `insert`      | Insert text at line number           |\n| `undo_edit`   | Undo last edit to a file             |\n\n## Linting\n\n```python\nfrom hanzo_aci import DefaultLinter\n\nlinter = DefaultLinter()\n\n# Lint Python (flake8-based)\nerrors = linter.lint(\"/path/to/file.py\")\n\n# Lint TypeScript (tree-sitter-based)\nerrors = linter.lint(\"/path/to/file.ts\")\n\n# Lint Ruby (tree-sitter-based)\nerrors = linter.lint(\"/path/to/file.rb\")\n```\n\n## Supported Languages\n\n- **Python** — flake8-based linting\n- **TypeScript/JavaScript** — tree-sitter AST analysis\n- **Ruby** — tree-sitter AST analysis\n- **Go** — tree-sitter AST analysis\n\n## Features\n\n- **File History**: Full undo/redo with `FileHistoryManager`\n- **Encoding Detection**: Automatic multi-encoding support\n- **Binary Detection**: Safe handling of binary files\n- **Max File Size**: Configurable (default 10MB)\n- **Diff Generation**: Unified diff output\n- **Snippet Context**: Smart context windowing for large files\n\n## Semantic Search\n\n```python\n# grep-ast integration for semantic code search\nfrom hanzo_aci import grep_ast\n\nresults = grep_ast(\"function_name\", path=\"/path/to/project\")\n```\n"}]},{"slug":"hanzo-agent","displayName":"hanzo-agent","summary":"Build multi-agent AI systems with Hanzo Agent SDK. Create agents with tools, handoffs, structured outputs, networks, and orchestration workflows.","version":"1.0.0","sha256hash":"4f536142557939bd06e32f12cf0b83d584d12b77ad0cd0f3c87fce628409b562","files":[{"path":"SKILL.md","size":3913,"sha256":"6504d968bc7f360a4d40d2c002eccfccff0e73bba4a44fd2e36d65e3362872cf","contentType":"text/markdown","content":"---\nname: hanzo-agent\ndescription: \"Build multi-agent AI systems with Hanzo Agent SDK. Create agents with tools, handoffs, structured outputs, networks, and orchestration workflows.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-agent\",\n              \"label\": \"Install Hanzo Agent SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Agent — Multi-Agent Framework\n\n`pip install hanzo-agent`\n\n## Quick Start\n\n```python\nfrom hanzoai import Agent, Runner, function_tool\n\n@function_tool\ndef get_weather(city: str) -> str:\n    \"\"\"Get current weather for a city.\"\"\"\n    return f\"Sunny, 72F in {city}\"\n\nagent = Agent(\n    name=\"Assistant\",\n    instructions=\"You help users with weather questions.\",\n    tools=[get_weather],\n    model=\"gpt-4\"\n)\n\nresult = Runner.run_sync(agent, \"What's the weather in Tokyo?\")\nprint(result.final_output)\n```\n\n## Async Usage\n\n```python\nimport asyncio\nfrom hanzoai import Agent, Runner\n\nagent = Agent(name=\"Helper\", instructions=\"Be helpful\")\n\nasync def main():\n    result = await Runner.run(agent, \"Hello!\")\n    print(result.final_output)\n\nasyncio.run(main())\n```\n\n## Tools\n\n### Function Tools\n\n```python\nfrom hanzoai import function_tool\n\n@function_tool\ndef search_docs(query: str, limit: int = 10) -> str:\n    \"\"\"Search documentation.\"\"\"\n    return f\"Found {limit} results for: {query}\"\n```\n\n### MCP Tools\n\n```python\nfrom hanzoai.mcp import MCPServerStdio\n\nserver = MCPServerStdio(command=\"hanzo-mcp\", args=[\"--tools\", \"fs,shell\"])\n\nagent = Agent(\n    name=\"Coder\",\n    instructions=\"Write code\",\n    mcp_servers=[server]\n)\n```\n\n## Agent Handoffs\n\n```python\nresearcher = Agent(\n    name=\"Researcher\",\n    instructions=\"Research topics thoroughly\",\n    tools=[search_tool]\n)\n\nwriter = Agent(\n    name=\"Writer\",\n    instructions=\"Write clear, engaging content\",\n    handoffs=[researcher]  # Can delegate to researcher\n)\n\nresult = await Runner.run(writer, \"Write about quantum computing\")\n```\n\n## Structured Output\n\n```python\nfrom pydantic import BaseModel\n\nclass Summary(BaseModel):\n    title: str\n    key_points: list[str]\n    sentiment: str\n\nagent = Agent(\n    name=\"Summarizer\",\n    instructions=\"Summarize the input\",\n    output_type=Summary\n)\n\nresult = await Runner.run(agent, \"Long article text here...\")\nsummary: Summary = result.final_output\nprint(summary.title, summary.key_points)\n```\n\n## Multi-Agent Networks\n\n```python\nfrom hanzoai import Agent, Runner\n\ntriage = Agent(\n    name=\"Triage\",\n    instructions=\"Route to the right specialist\",\n    handoffs=[\"coder\", \"writer\", \"analyst\"]\n)\n\ncoder = Agent(name=\"Coder\", instructions=\"Write code\")\nwriter = Agent(name=\"Writer\", instructions=\"Write prose\")\nanalyst = Agent(name=\"Analyst\", instructions=\"Analyze data\")\n\nresult = await Runner.run(\n    triage,\n    \"Write a Python script to sort a list\",\n    agents=[coder, writer, analyst]\n)\n```\n\n## Guardrails\n\n```python\nfrom hanzoai import Agent, InputGuardrail, GuardrailFunctionOutput\n\n@InputGuardrail\nasync def no_pii(ctx, agent, input):\n    \"\"\"Block requests containing PII.\"\"\"\n    has_pii = check_for_pii(input)\n    return GuardrailFunctionOutput(\n        output_info={\"has_pii\": has_pii},\n        tripwire_triggered=has_pii\n    )\n\nagent = Agent(\n    name=\"Safe Agent\",\n    instructions=\"Help users\",\n    input_guardrails=[no_pii]\n)\n```\n\n## Tracing & Observability\n\n```python\nfrom hanzoai import trace\n\n@trace\nasync def my_workflow():\n    result = await Runner.run(agent, \"input\")\n    return result\n\n# Integrations: Logfire, AgentOps, Braintrust, Scorecard\n```\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=sk-...          # Required for LLM calls\nHANZO_BASE_URL=...            # API endpoint\nOPENAI_API_KEY=sk-...         # For OpenAI models\nANTHROPIC_API_KEY=sk-ant-...  # For Claude models\n```\n"}]},{"slug":"hanzo-api","displayName":"hanzo-api","summary":"Use the Hanzo AI API (LLM Gateway) to call 100+ LLM providers with a unified OpenAI-compatible interface. Chat completions, embeddings, images, audio, fine-tuning, and more via the hanzoai Python SDK.","version":"1.0.0","sha256hash":"6b883c1a70c437103426e1b0a59f5faab98f54000008a4c7df0a60e4b46522be","files":[{"path":"SKILL.md","size":3840,"sha256":"2c34ad95af115196d31cb9c68a8be6b61cf15bba00b53e5f9286161a786c06ea","contentType":"text/markdown","content":"---\nname: hanzo-api\ndescription: \"Use the Hanzo AI API (LLM Gateway) to call 100+ LLM providers with a unified OpenAI-compatible interface. Chat completions, embeddings, images, audio, fine-tuning, and more via the hanzoai Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzoai\",\n              \"label\": \"Install Hanzo AI SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo API — Unified LLM Gateway\n\n`pip install hanzoai`\n\nOpenAI-compatible interface to 100+ LLM providers.\n\n## Quick Start\n\n```python\nfrom hanzoai import Hanzo\n\nclient = Hanzo(api_key=\"your-api-key\")\n\nresponse = client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\nprint(response.choices[0].message.content)\n```\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=sk-...                       # API key (required)\nHANZO_BASE_URL=https://api.hanzo.ai        # API base URL\n```\n\n## Chat Completions\n\n```python\n# Standard completion\nresponse = client.chat.completions.create(\n    model=\"claude-sonnet-4-20250514\",\n    messages=[\n        {\"role\": \"system\", \"content\": \"You are helpful.\"},\n        {\"role\": \"user\", \"content\": \"Explain quantum computing\"}\n    ],\n    temperature=0.7,\n    max_tokens=1000\n)\n\n# Streaming\nfor chunk in client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Tell me a story\"}],\n    stream=True\n):\n    print(chunk.choices[0].delta.content or \"\", end=\"\")\n```\n\n## Async Client\n\n```python\nfrom hanzoai import AsyncHanzo\n\nclient = AsyncHanzo(api_key=\"...\")\n\nresponse = await client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello\"}]\n)\n```\n\n## Embeddings\n\n```python\nresponse = client.embeddings.create(\n    model=\"text-embedding-3-small\",\n    input=\"The food was delicious\"\n)\nvector = response.data[0].embedding\n```\n\n## Image Generation\n\n```python\nresponse = client.images.generate(\n    model=\"dall-e-3\",\n    prompt=\"A sunset over mountains\",\n    size=\"1024x1024\"\n)\nimage_url = response.data[0].url\n```\n\n## Audio\n\n```python\n# Text-to-Speech\naudio = client.audio.speech.create(\n    model=\"tts-1\",\n    input=\"Hello world\",\n    voice=\"alloy\"\n)\naudio.stream_to_file(\"output.mp3\")\n\n# Speech-to-Text\ntranscript = client.audio.transcriptions.create(\n    model=\"whisper-1\",\n    file=open(\"audio.mp3\", \"rb\")\n)\n```\n\n## Models\n\n```python\n# List available models\nmodels = client.models.list()\nfor m in models.data:\n    print(m.id)\n```\n\n## Provider-Specific Access\n\n```python\n# Anthropic Claude\nclient.chat.completions.create(model=\"claude-sonnet-4-20250514\", ...)\n\n# Google Gemini\nclient.chat.completions.create(model=\"gemini/gemini-2.0-flash\", ...)\n\n# AWS Bedrock\nclient.chat.completions.create(model=\"bedrock/anthropic.claude-3-sonnet\", ...)\n\n# Azure OpenAI\nclient.chat.completions.create(model=\"azure/gpt-4\", ...)\n\n# Together AI\nclient.chat.completions.create(model=\"together_ai/meta-llama/Llama-3-70b\", ...)\n\n# Ollama (local)\nclient.chat.completions.create(model=\"ollama/llama3\", ...)\n```\n\n## Team & Organization Management\n\n```python\n# Teams\nteams = client.team.list()\nclient.team.create(team_alias=\"engineering\")\n\n# Organizations\norgs = client.organization.list()\n\n# API Key management\nkeys = client.key.list()\nclient.key.generate(team_id=\"...\")\n```\n\n## Cost Tracking\n\n```python\n# Get spend data\nspend = client.global_spend.retrieve()\n\n# Per-team spend\nteam_spend = client.global_spend.list_spend_logs(api_key=\"...\")\n```\n\n## Supported Providers\n\nOpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI, Together AI, Cohere, Mistral, Groq, DeepSeek, Ollama, VLLM, HuggingFace, Replicate, Perplexity, Fireworks AI, Anyscale, and 80+ more.\n"}]},{"slug":"hanzo-chat","displayName":"hanzo-chat","summary":"Hanzo Chat — AI chat platform with 14 Zen models, 100+ third-party models, MCP tools, code execution, and OpenID Connect auth.","version":"1.0.0","sha256hash":"64540cee16acbade52273ea01beefbb28734e38f6f45f91cf420fe2f8b068306","files":[{"path":"SKILL.md","size":2007,"sha256":"732c4e72f5edcf24ca3ec740a3f28e022eb2dcf34d0ad90914d568304ee6ee10","contentType":"text/markdown","content":"---\nname: hanzo-chat\ndescription: \"Hanzo Chat — AI chat platform with 14 Zen models, 100+ third-party models, MCP tools, code execution, and OpenID Connect auth.\"\nmetadata: { \"bot\": { \"requires\": { \"bins\": [\"curl\"] } } }\n---\n\n# Hanzo Chat — AI Chat Platform\n\nAI chat application with 14 Zen models, 100+ third-party models via Hanzo LLM Gateway, MCP tool integration, and code execution.\n\n## Quick Start\n\n```bash\n# Docker\ndocker compose up -d\n\n# Access at http://localhost:3081\n```\n\n## API Usage\n\n```bash\nCHAT_URL=http://localhost:3081\n\n# Send chat message\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"gpt-4\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]\n  }' \"$CHAT_URL/api/chat\" | jq\n\n# List available models\ncurl -s \"$CHAT_URL/api/models\" | jq\n\n# Get conversation history\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n  \"$CHAT_URL/api/messages?conversationId=...\" | jq\n```\n\n## Models\n\n### Zen Models (14 proprietary)\n\n- Zen 1 through Zen 14 — Hanzo's own model family\n\n### Third-Party (100+ via Gateway)\n\n- OpenAI: GPT-4, GPT-4o, o1, o3\n- Anthropic: Claude Opus, Sonnet, Haiku\n- Google: Gemini 2.0\n- Meta: Llama 3\n- And 90+ more providers\n\n## Features\n\n- **MCP Tools**: Full Model Context Protocol integration\n- **Code Execution**: Run code directly in chat\n- **Chat History**: Persistent via MongoDB\n- **Search**: Full-text search via Meilisearch\n- **Auth**: OpenID Connect (Hanzo IAM)\n- **Streaming**: Real-time token streaming\n\n## Configuration\n\n```bash\n# Domain\nDOMAIN_CLIENT=http://localhost:3081\nDOMAIN_SERVER=http://localhost:3081\n\n# Database\nMONGO_URI=mongodb://user:pass@mongodb:27017/HanzoChat\nMEILI_HOST=http://meilisearch:7700\nMEILI_MASTER_KEY=...\n\n# Auth\nJWT_SECRET=...\nOPENID_CLIENT_ID=...\nOPENID_CLIENT_SECRET=...\nOPENID_ISSUER=https://hanzo.id\n\n# AI (via Hanzo Gateway)\nOPENAI_API_KEY=sk-hanzo-...\nOPENAI_BASE_URL=https://api.hanzo.ai/v1\n\n# Features\nMCP_ENABLED=true\n```\n\n## Port\n\n- Web UI / API: `3081`\n"}]},{"slug":"hanzo-cli","displayName":"hanzo-cli","summary":"Hanzo unified CLI for IAM login, KMS secrets, PaaS deployments, and agent management. Single command-line interface for all Hanzo services.","version":"1.0.0","sha256hash":"b74fb3caf8ae2f18dea773548a7f841f6c9a86b5f694525f921503831cd63ed7","files":[{"path":"SKILL.md","size":2329,"sha256":"263887c0119a5e170942d9a1866487f97ed1d13e84e96f36dfe0491d5fd63cbf","contentType":"text/markdown","content":"---\nname: hanzo-cli\ndescription: \"Hanzo unified CLI for IAM login, KMS secrets, PaaS deployments, and agent management. Single command-line interface for all Hanzo services.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-cli\",\n              \"label\": \"Install Hanzo CLI (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo CLI — Unified Command Line\n\n`pip install hanzo-cli`\n\nSingle CLI for authenticating, managing secrets, deploying apps, and running agents.\n\n## Quick Start\n\n```bash\n# Login to Hanzo (opens browser for OAuth)\nhanzo login\n\n# Check who you are\nhanzo whoami\n\n# Logout\nhanzo logout\n```\n\n## Authentication\n\n```bash\n# Browser-based OAuth login (default)\nhanzo login\n\n# Password-based login\nhanzo login --password\n\n# Login to specific org\nhanzo login --org=my-org --app=my-app\n```\n\nToken stored at `~/.hanzo/auth/token.json`.\n\n## IAM Commands\n\n```bash\n# Show current user info\nhanzo whoami\n\n# List users in org\nhanzo iam users\n\n# List organizations\nhanzo iam orgs\n\n# List roles\nhanzo iam roles\n```\n\n## KMS Commands\n\n```bash\n# List secrets\nhanzo kms list\n\n# Get a secret\nhanzo kms get DATABASE_URL\n\n# Set a secret\nhanzo kms set DATABASE_URL \"postgresql://...\"\n\n# Delete a secret\nhanzo kms delete OLD_SECRET\n```\n\n## PaaS Commands\n\n```bash\n# List projects\nhanzo paas projects --org=hanzo\n\n# List environments\nhanzo paas env --org=hanzo --project=my-app\n\n# List deployments\nhanzo paas deployments --org=hanzo --project=my-app --env=prod\n\n# View logs\nhanzo paas logs --org=hanzo --project=my-app --env=prod --container=web\n\n# Redeploy\nhanzo paas redeploy --org=hanzo --project=my-app --env=prod --container=web\n\n# Shortcut\nhanzo deploy\n```\n\n## Bot Commands\n\n```bash\n# Bot management\nhanzo bot status\nhanzo bot start\nhanzo bot stop\n```\n\n## Environment Variables\n\n```bash\nHANZO_IAM_URL=https://hanzo.id            # IAM endpoint\nHANZO_IAM_ORG=hanzo                        # Default organization\nHANZO_IAM_APP=app-hanzo                    # Default application\nHANZO_IAM_CLIENT_ID=...                    # OAuth client ID\nHANZO_IAM_CLIENT_SECRET=...                # OAuth client secret\nHANZO_KMS_URL=https://kms.hanzo.ai         # KMS endpoint\n```\n"}]},{"slug":"hanzo-commerce","displayName":"hanzo-commerce","summary":"E-commerce platform with product catalog, orders, payments (Stripe), inventory, fulfillment workflows, and analytics.","version":"1.0.0","sha256hash":"c729b3bf9a74437dac722d88892db7a1a06f2edabe7e8d6f32754f72bc13d195","files":[{"path":"SKILL.md","size":2293,"sha256":"d58cc03a849d659c4448eee9797353452e563181c4baab615e27d8a8763783f1","contentType":"text/markdown","content":"---\nname: hanzo-commerce\ndescription: \"E-commerce platform with product catalog, orders, payments (Stripe), inventory, fulfillment workflows, and analytics.\"\nmetadata: { \"bot\": { \"requires\": { \"bins\": [\"curl\"] } } }\n---\n\n# Hanzo Commerce — E-Commerce Platform\n\nFull-featured e-commerce API for product catalog, orders, payments, inventory, and fulfillment. Integrates with Stripe, Meilisearch, and analytics.\n\n## Quick Start\n\n```bash\nCOMMERCE_URL=http://localhost:8001\n\n# List products\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n  \"$COMMERCE_URL/api/products\" | jq\n\n# Create order\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"items\": [{\"product_id\": \"...\", \"quantity\": 1}]}' \\\n  \"$COMMERCE_URL/api/orders\" | jq\n```\n\n## Products\n\n```bash\n# Create product\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"AI Agent Credits\",\n    \"price\": 99.00,\n    \"currency\": \"USD\",\n    \"description\": \"1000 agent execution credits\"\n  }' \"$COMMERCE_URL/api/products\" | jq\n\n# Search products (via Meilisearch)\ncurl -s \"$COMMERCE_URL/api/products/search?q=agent\" | jq\n```\n\n## Orders\n\n```bash\n# Create order\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"items\": [{\"product_id\": \"prod_123\", \"quantity\": 2}],\n    \"payment_method\": \"pm_...\"\n  }' \"$COMMERCE_URL/api/orders\" | jq\n\n# Get order status\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n  \"$COMMERCE_URL/api/orders/ord_123\" | jq\n```\n\n## Payments (Stripe)\n\n```bash\n# Create payment intent\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"amount\": 9900, \"currency\": \"usd\"}' \\\n  \"$COMMERCE_URL/api/payments/intent\" | jq\n\n# Webhook handling (automatic)\n# Stripe webhooks → $COMMERCE_URL/api/webhooks/stripe\n```\n\n## Subscriptions\n\n```bash\n# Create subscription\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"plan_id\": \"plan_enterprise\",\n    \"payment_method\": \"pm_...\"\n  }' \"$COMMERCE_URL/api/subscriptions\" | jq\n```\n\n## Port\n\n- API: `8001`\n\n## Environment Variables\n\n```bash\nCOMMERCE_PORT=8001\nCOMMERCE_SECRET=...\nSTRIPE_SECRET_KEY=sk_...\nSTRIPE_WEBHOOK_SECRET=whsec_...\n```\n"}]},{"slug":"hanzo-consensus","displayName":"hanzo-consensus","summary":"Metastable consensus protocol for multi-agent agreement. Two-phase finality with k-peer sampling for distributed AI decision making.","version":"1.0.0","sha256hash":"2b8efb5a38da3365e295c60a07ded59550caeda44c47b30f607f237cd956c4e0","files":[{"path":"SKILL.md","size":2463,"sha256":"2b4ace8810c59ff8eefa7296f941400e662c9ed45d6b8fef26cddb3af3a1cc72","contentType":"text/markdown","content":"---\nname: hanzo-consensus\ndescription: \"Metastable consensus protocol for multi-agent agreement. Two-phase finality with k-peer sampling for distributed AI decision making.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-consensus\",\n              \"label\": \"Install Hanzo Consensus (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Consensus — Multi-Agent Agreement\n\n`pip install hanzo-consensus`\n\nMetastable consensus protocol for distributed multi-agent decision making. Two-phase finality with configurable k-peer sampling.\n\n## Quick Start\n\n```python\nfrom hanzo_consensus import Consensus, run\n\n# Simple consensus among participants\nresult = run(\n    participants=[\"agent-1\", \"agent-2\", \"agent-3\"],\n    proposal=\"Should we deploy to production?\",\n    rounds=10\n)\nprint(result.decision)  # True/False\nprint(result.confidence)  # 0.0-1.0\n```\n\n## Async Usage\n\n```python\nfrom hanzo_consensus import Consensus\n\nconsensus = Consensus(\n    rounds=10,\n    k=3,           # Sample size per round\n    alpha=0.8,     # Agreement threshold\n    beta_1=15,     # Preference threshold (Phase I)\n    beta_2=20      # Decision threshold (Phase II)\n)\n\nresult = await consensus.run(participants, proposal)\n```\n\n## MCP Mesh Consensus\n\n```python\nfrom hanzo_consensus import MCPMesh, MCPAgent, run_mcp_consensus\n\n# Create MCP-based consensus mesh\nmesh = MCPMesh(agents=[\n    MCPAgent(\"analyst\", mcp_server=\"...\"),\n    MCPAgent(\"reviewer\", mcp_server=\"...\"),\n    MCPAgent(\"approver\", mcp_server=\"...\")\n])\n\nresult = await run_mcp_consensus(mesh, \"Evaluate code quality of PR #42\")\n```\n\n## Protocol Parameters\n\n| Parameter | Description                  | Default |\n| --------- | ---------------------------- | ------- |\n| `rounds`  | Number of sampling rounds    | 10      |\n| `k`       | Peers sampled per round      | 3       |\n| `alpha`   | Agreement threshold (0-1)    | 0.8     |\n| `beta_1`  | Phase I preference threshold | 15      |\n| `beta_2`  | Phase II decision threshold  | 20      |\n\n## Protocol Design\n\nTwo-phase finality based on [Lux Consensus](https://github.com/luxfi/consensus):\n\n1. **Sampling Phase**: Each round, sample k random peers and query their preference\n2. **Finality Phase**: After sufficient consecutive agreements, finalize decision\n\nPure Python — no external dependencies.\n"}]},{"slug":"hanzo-crawl","displayName":"hanzo-crawl","summary":"Crawl and scrape web pages via the Hanzo Crawl API (Crawl4AI). Extract structured content and markdown from URLs, preview pages, and crawl sites with JavaScript rendering support. Use when a bot needs to scrape a webpage, crawl a site, or extract content from URLs.","version":"1.0.0","sha256hash":"f22c665b673740ef417fd44f7de248ac9d6f4810d2208f0182971d6802c2477d","files":[{"path":"SKILL.md","size":4175,"sha256":"a220558ef24a8904cc471c0522c13f12bcf44ac20822de496d1a877806d6bf62","contentType":"text/markdown","content":"---\nname: hanzo-crawl\ndescription: \"Crawl and scrape web pages via the Hanzo Crawl API (Crawl4AI). Extract structured content and markdown from URLs, preview pages, and crawl sites with JavaScript rendering support. Use when a bot needs to scrape a webpage, crawl a site, or extract content from URLs.\"\nmetadata:\n  { \"bot\": { \"requires\": { \"bins\": [\"python3\"] }, \"primaryEnv\": \"HANZO_API_KEY\", \"emoji\": \"🕷\" } }\n---\n\n# Hanzo Crawl -- Web Scraping API (Crawl4AI)\n\nCrawl web pages and extract structured markdown content via Crawl4AI. Supports JavaScript-rendered pages, CSS selectors for targeted extraction, and async crawl processing.\n\n## API Endpoints\n\nBase URL: `https://crawl.hanzo.ai`\n\n| Endpoint     | Method | Purpose                              |\n| ------------ | ------ | ------------------------------------ |\n| `/crawl`     | POST   | Crawl a URL and extract content      |\n| `/md`        | POST   | Quick markdown extraction from a URL |\n| `/task/{id}` | GET    | Poll async crawl task status         |\n| `/health`    | GET    | Health check                         |\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header. Use the HANZO_API_KEY env var.\n\n```\nAuthorization: Bearer <token>\n```\n\n## Crawl a URL\n\n```bash\npython3 {baseDir}/scripts/crawl.py --url \"https://docs.example.com\"\n```\n\n### Request Body (`POST /crawl`)\n\n```json\n{\n  \"urls\": \"https://docs.example.com/getting-started\",\n  \"word_count_threshold\": 10,\n  \"css_selector\": \"main, article\",\n  \"excluded_tags\": [\"nav\", \"footer\", \"aside\"],\n  \"wait_for\": \".content-loaded\",\n  \"magic\": false,\n  \"screenshot\": false\n}\n```\n\n### Fields\n\n- `urls` (required): URL string or array of URLs to crawl\n- `word_count_threshold` (optional): Minimum word count for content blocks (default 10)\n- `css_selector` (optional): CSS selector for targeted content extraction\n- `excluded_tags` (optional): Array of HTML tags to exclude from extraction\n- `wait_for` (optional): CSS selector to wait for before extraction (for JS-rendered pages)\n- `js_code` (optional): Array of JavaScript code strings to execute before extraction\n- `magic` (optional): Enable magic mode for complex pages (default false)\n- `screenshot` (optional): Take a screenshot of the page (default false)\n\n### Response\n\nThe `/crawl` endpoint returns a `task_id` for async processing. Poll `/task/{task_id}` until completion.\n\n```json\n{\n  \"task_id\": \"abc123-def456\",\n  \"status\": \"completed\",\n  \"result\": {\n    \"url\": \"https://docs.example.com/getting-started\",\n    \"success\": true,\n    \"markdown\": \"# Getting Started\\n\\nTo deploy your application...\",\n    \"links\": {\n      \"internal\": [{ \"href\": \"/next-steps\", \"text\": \"Next Steps\" }],\n      \"external\": [{ \"href\": \"https://github.com/...\", \"text\": \"Source\" }]\n    },\n    \"media\": {\n      \"images\": [{ \"src\": \"...\", \"alt\": \"...\" }]\n    }\n  }\n}\n```\n\n## Preview a Page (Markdown)\n\nQuick markdown extraction without async processing.\n\n```bash\npython3 {baseDir}/scripts/preview.py --url \"https://docs.example.com/page\"\n```\n\n### Request Body (`POST /md`)\n\n```json\n{\n  \"url\": \"https://docs.example.com/getting-started\"\n}\n```\n\n### Response\n\n```json\n{\n  \"url\": \"https://docs.example.com/getting-started\",\n  \"success\": true,\n  \"title\": \"Getting Started\",\n  \"markdown\": \"# Getting Started\\n\\nFull extracted markdown content...\",\n  \"status_code\": 200\n}\n```\n\n## Scripts\n\n### `scripts/crawl.py`\n\nCrawl a URL and extract content via Crawl4AI.\n\n```bash\npython3 {baseDir}/scripts/crawl.py \\\n  --url \"https://docs.example.com\" \\\n  --css-selector \"main, article\" \\\n  --excluded-tags \"nav,footer,aside\" \\\n  --token \"$HANZO_API_KEY\"\n```\n\n### `scripts/preview.py`\n\nQuick markdown preview of a page.\n\n```bash\npython3 {baseDir}/scripts/preview.py \\\n  --url \"https://docs.example.com/page\" \\\n  --token \"$HANZO_API_KEY\"\n```\n\n## Billing\n\nCrawl operations are billed per page crawled. Preview (markdown) operations are billed at a reduced rate. Usage is tracked automatically through the bot gateway.\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=...                                  # API token for authentication\nHANZO_CRAWL_BASE_URL=https://crawl.hanzo.ai        # Override API base URL\n```\n"},{"path":"scripts/crawl.py","size":9668,"sha256":"bed73538cad3f4a8d9986d55cbaef228a6c6b4ce40dafb7bfd1c519e56ef6d50","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"Crawl a URL via the Hanzo Crawl API (Crawl4AI).\n\nUsage:\n    python3 crawl.py --url \"https://docs.example.com\" [options]\n\nOptions:\n    --url               Starting URL to crawl (required)\n    --word-count-threshold  Minimum word count for content blocks (default: 10)\n    --css-selector      CSS selector for main content extraction\n    --excluded-tags     Comma-separated HTML tags to exclude (e.g. \"nav,footer,aside\")\n    --wait-for          CSS selector to wait for before extraction (JS-rendered pages)\n    --screenshot        Take a screenshot of the page\n    --js-code           JavaScript code to execute before extraction\n    --magic             Enable Crawl4AI magic mode for complex pages\n    --token             API token (default: $HANZO_API_KEY)\n    --base-url          API base URL (default: $HANZO_CRAWL_BASE_URL or https://crawl.hanzo.ai)\n    --format            Output format: text, json (default: text)\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\nimport time\nimport urllib.request\nimport urllib.error\n\n\ndef build_request_body(args: argparse.Namespace) -> dict:\n    body: dict = {\n        \"urls\": args.url,\n        \"word_count_threshold\": args.word_count_threshold,\n    }\n\n    if args.css_selector:\n        body[\"css_selector\"] = args.css_selector\n    if args.excluded_tags:\n        body[\"excluded_tags\"] = [t.strip() for t in args.excluded_tags.split(\",\")]\n    if args.wait_for:\n        body[\"wait_for\"] = args.wait_for\n    if args.screenshot:\n        body[\"screenshot\"] = True\n    # Security note: js_code allows arbitrary JavaScript execution on the crawled\n    # page inside the Crawl4AI headless browser. This is a known SSRF vector --\n    # the caller could use it to reach internal network endpoints. Input\n    # validation and network policy enforcement are handled at the gateway level.\n    if args.js_code:\n        body[\"js_code\"] = [args.js_code]\n    if args.magic:\n        body[\"magic\"] = True\n\n    return body\n\n\ndef poll_task(base_url: str, token: str, task_id: str, timeout: int = 300) -> dict:\n    \"\"\"Poll a Crawl4AI async task until completion or timeout.\"\"\"\n    url = f\"{base_url}/task/{task_id}\"\n    headers = {\n        \"Accept\": \"application/json\",\n        \"User-Agent\": \"hanzo-bot/1.0\",\n    }\n    if token:\n        headers[\"Authorization\"] = f\"Bearer {token}\"\n\n    start = time.time()\n    while time.time() - start < timeout:\n        req = urllib.request.Request(url, headers=headers, method=\"GET\")\n        try:\n            with urllib.request.urlopen(req, timeout=30) as resp:\n                result = json.loads(resp.read().decode(\"utf-8\"))\n                status = result.get(\"status\", \"\")\n                if status in (\"completed\", \"failed\"):\n                    return result\n        except urllib.error.HTTPError as e:\n            if e.code == 404:\n                pass\n            else:\n                error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n                print(f\"Error: HTTP {e.code} polling task {task_id}\", file=sys.stderr)\n                if error_body:\n                    print(error_body[:500], file=sys.stderr)\n                sys.exit(1)\n\n        time.sleep(2)\n\n    print(f\"Error: Task {task_id} timed out after {timeout}s\", file=sys.stderr)\n    sys.exit(1)\n\n\ndef crawl(args: argparse.Namespace) -> dict:\n    base_url = (\n        args.base_url\n        or os.environ.get(\"HANZO_CRAWL_BASE_URL\")\n        or \"https://crawl.hanzo.ai\"\n    ).rstrip(\"/\")\n    token = args.token or os.environ.get(\"HANZO_API_KEY\", \"\")\n    if not token:\n        print(\"Error: HANZO_API_KEY environment variable or --token flag is required.\", file=sys.stderr)\n        sys.exit(1)\n\n    url = f\"{base_url}/crawl\"\n    body = build_request_body(args)\n    data = json.dumps(body).encode(\"utf-8\")\n\n    headers = {\n        \"Content-Type\": \"application/json\",\n        \"Accept\": \"application/json\",\n        \"User-Agent\": \"hanzo-bot/1.0\",\n    }\n    if token:\n        headers[\"Authorization\"] = f\"Bearer {token}\"\n\n    req = urllib.request.Request(url, data=data, headers=headers, method=\"POST\")\n\n    try:\n        with urllib.request.urlopen(req, timeout=60) as resp:\n            raw = resp.read().decode(\"utf-8\", errors=\"replace\")\n            result = json.loads(raw, strict=False)\n    except urllib.error.HTTPError as e:\n        error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n        print(f\"Error: HTTP {e.code} from Crawl4AI API\", file=sys.stderr)\n        if error_body:\n            print(error_body[:500], file=sys.stderr)\n        sys.exit(1)\n    except urllib.error.URLError as e:\n        print(f\"Error: Failed to connect to Crawl4AI API: {e.reason}\", file=sys.stderr)\n        sys.exit(1)\n\n    # Crawl4AI returns a task_id for async processing; poll until done.\n    task_id = result.get(\"task_id\", \"\")\n    if task_id:\n        sys.stderr.write(f\"Crawl task submitted: {task_id}\\n\")\n        return poll_task(base_url, token, task_id)\n\n    # Synchronous response (single-page crawl may return directly).\n    return result\n\n\n\ndef format_result_item(crawl_result: dict) -> list[str]:\n    \"\"\"Format a single crawl result item.\"\"\"\n    lines = []\n    page_url = crawl_result.get(\"url\", \"\")\n    if page_url:\n        lines.append(f\"URL: {page_url}\")\n\n    success = crawl_result.get(\"success\", False)\n    lines.append(f\"Success: {success}\")\n\n    markdown = crawl_result.get(\"markdown\", \"\")\n    if isinstance(markdown, dict):\n        markdown = markdown.get(\"raw_markdown\", markdown.get(\"markdown\", str(markdown)))\n    markdown = str(markdown) if markdown else \"\"\n    if markdown:\n        content_len = len(markdown)\n        lines.append(f\"Content length: {content_len} chars\")\n        lines.append(\"\")\n        lines.append(\"--- Content (markdown) ---\")\n        lines.append(markdown[:2000])\n        if content_len > 2000:\n            lines.append(f\"\\n... ({content_len - 2000} chars truncated)\")\n\n    links = crawl_result.get(\"links\", {})\n    internal = links.get(\"internal\", [])\n    external = links.get(\"external\", [])\n    if internal or external:\n        lines.append(\"\")\n        lines.append(f\"--- Links (internal: {len(internal)}, external: {len(external)}) ---\")\n        for link in internal[:15]:\n            href = link.get(\"href\", \"\")\n            text = link.get(\"text\", \"\").strip()\n            lines.append(f\"  [{text}]({href})\" if text else f\"  {href}\")\n        if len(internal) > 15:\n            lines.append(f\"  ... and {len(internal) - 15} more internal\")\n        for link in external[:5]:\n            href = link.get(\"href\", \"\")\n            text = link.get(\"text\", \"\").strip()\n            lines.append(f\"  [ext] [{text}]({href})\" if text else f\"  [ext] {href}\")\n        if len(external) > 5:\n            lines.append(f\"  ... and {len(external) - 5} more external\")\n\n    error = crawl_result.get(\"error_message\", \"\")\n    if error:\n        lines.append(f\"\\nError: {error}\")\n\n    return lines\n\n\ndef format_text(result: dict) -> str:\n    lines = []\n    success = result.get(\"success\", \"unknown\")\n    lines.append(f\"Success: {success}\")\n\n    processing_time = result.get(\"server_processing_time_s\", 0)\n    if processing_time:\n        lines.append(f\"Processing time: {processing_time:.2f}s\")\n\n    # Crawl4AI returns results as an array under \"results\".\n    results = result.get(\"results\", [])\n    if results:\n        lines.append(f\"Pages: {len(results)}\")\n        for i, item in enumerate(results):\n            if len(results) > 1:\n                lines.append(f\"\\n--- Page {i + 1} ---\")\n            lines.extend(format_result_item(item))\n    elif \"result\" in result:\n        # Async task response wraps in \"result\".\n        crawl_result = result[\"result\"]\n        if isinstance(crawl_result, dict):\n            task_id = result.get(\"task_id\", \"\")\n            if task_id:\n                lines.insert(0, f\"Task: {task_id}\")\n            lines.extend(format_result_item(crawl_result))\n    else:\n        # Fallback: treat the whole response as a single result.\n        lines.extend(format_result_item(result))\n\n    return \"\\n\".join(lines)\n\n\ndef main() -> None:\n    parser = argparse.ArgumentParser(description=\"Crawl a URL via Crawl4AI API\")\n    parser.add_argument(\"--url\", required=True, help=\"URL to crawl\")\n    parser.add_argument(\"--word-count-threshold\", type=int, default=10,\n                        help=\"Minimum word count for content blocks (default: 10)\")\n    parser.add_argument(\"--css-selector\", default=None,\n                        help=\"CSS selector for main content extraction\")\n    parser.add_argument(\"--excluded-tags\", default=None,\n                        help=\"Comma-separated HTML tags to exclude (e.g. 'nav,footer,aside')\")\n    parser.add_argument(\"--wait-for\", default=None,\n                        help=\"CSS selector to wait for before extraction (JS pages)\")\n    parser.add_argument(\"--screenshot\", action=\"store_true\",\n                        help=\"Take a screenshot of the page\")\n    parser.add_argument(\"--js-code\", default=None,\n                        help=\"JavaScript code to execute before extraction\")\n    parser.add_argument(\"--magic\", action=\"store_true\",\n                        help=\"Enable magic mode for complex pages\")\n    parser.add_argument(\"--token\", default=None, help=\"API token\")\n    parser.add_argument(\"--base-url\", default=None, help=\"API base URL\")\n    parser.add_argument(\"--format\", default=\"text\", choices=[\"text\", \"json\"],\n                        help=\"Output format (default: text)\")\n\n    args = parser.parse_args()\n    result = crawl(args)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        print(format_text(result))\n\n\nif __name__ == \"__main__\":\n    main()\n"},{"path":"scripts/preview.py","size":3355,"sha256":"e60f78fd82e59b21bb4f55f8c6f7c2d977e798920fca52b72e3ef4b61386a43a","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"Preview a web page as markdown via the Hanzo Crawl API (Crawl4AI) without indexing.\n\nUses the Crawl4AI /md endpoint for fast markdown extraction.\n\nUsage:\n    python3 preview.py --url \"https://docs.example.com/page\" [options]\n\nOptions:\n    --url               URL to preview (required)\n    --token             API token (default: $HANZO_API_KEY)\n    --base-url          API base URL (default: $HANZO_CRAWL_BASE_URL or https://crawl.hanzo.ai)\n    --format            Output format: text, json (default: text)\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\nimport urllib.request\nimport urllib.error\n\n\ndef preview(args: argparse.Namespace) -> dict:\n    base_url = (\n        args.base_url\n        or os.environ.get(\"HANZO_CRAWL_BASE_URL\")\n        or \"https://crawl.hanzo.ai\"\n    ).rstrip(\"/\")\n    token = args.token or os.environ.get(\"HANZO_API_KEY\", \"\")\n\n    url = f\"{base_url}/md\"\n    body = {\"url\": args.url}\n    data = json.dumps(body).encode(\"utf-8\")\n\n    headers = {\n        \"Content-Type\": \"application/json\",\n        \"Accept\": \"application/json\",\n        \"User-Agent\": \"hanzo-bot/1.0\",\n    }\n    if token:\n        headers[\"Authorization\"] = f\"Bearer {token}\"\n\n    req = urllib.request.Request(url, data=data, headers=headers, method=\"POST\")\n\n    try:\n        with urllib.request.urlopen(req, timeout=60) as resp:\n            return json.loads(resp.read().decode(\"utf-8\", errors=\"replace\"), strict=False)\n    except urllib.error.HTTPError as e:\n        error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n        print(f\"Error: HTTP {e.code} from Crawl4AI markdown API\", file=sys.stderr)\n        if error_body:\n            print(error_body[:500], file=sys.stderr)\n        sys.exit(1)\n    except urllib.error.URLError as e:\n        print(f\"Error: Failed to connect to Crawl4AI API: {e.reason}\", file=sys.stderr)\n        sys.exit(1)\n\n\ndef format_text(result: dict) -> str:\n    lines = []\n    page_url = result.get(\"url\", \"\")\n    success = result.get(\"success\", False)\n    title = result.get(\"title\", \"Untitled\")\n    markdown = result.get(\"markdown\", result.get(\"result\", \"\"))\n    status_code = result.get(\"status_code\", 0)\n\n    lines.append(f\"URL: {page_url}\")\n    lines.append(f\"Title: {title}\")\n    lines.append(f\"Success: {success}\")\n    if status_code:\n        lines.append(f\"HTTP Status: {status_code}\")\n\n    content_len = len(markdown)\n    lines.append(f\"Content length: {content_len} chars\")\n\n    lines.append(\"\")\n    lines.append(\"--- Markdown ---\")\n    lines.append(markdown[:2000])\n    if content_len > 2000:\n        lines.append(f\"\\n... ({content_len - 2000} chars truncated)\")\n\n    return \"\\n\".join(lines)\n\n\ndef main() -> None:\n    parser = argparse.ArgumentParser(description=\"Preview a page as markdown via Crawl4AI\")\n    parser.add_argument(\"--url\", required=True, help=\"URL to preview\")\n    parser.add_argument(\"--token\", default=None, help=\"API token\")\n    parser.add_argument(\"--base-url\", default=None, help=\"API base URL\")\n    parser.add_argument(\"--format\", default=\"text\", choices=[\"text\", \"json\"],\n                        help=\"Output format (default: text)\")\n\n    args = parser.parse_args()\n    result = preview(args)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        print(format_text(result))\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"hanzo-documentdb","displayName":"hanzo-documentdb","summary":"MongoDB-compatible document database with Hanzo DocumentDB (FerretDB). Store, query, and aggregate JSON documents with ACID guarantees.","version":"1.0.0","sha256hash":"1c3cdf1636cfdbbd135d59af81957ac5d57668c678983bf1c00ffd8914da0d56","files":[{"path":"SKILL.md","size":2707,"sha256":"28486c1491b1076da242f4c945e4c1c015062777a8bc54f86bad04dfae9fa469","contentType":"text/markdown","content":"---\nname: hanzo-documentdb\ndescription: \"MongoDB-compatible document database with Hanzo DocumentDB (FerretDB). Store, query, and aggregate JSON documents with ACID guarantees.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [{ \"id\": \"pip\", \"kind\": \"pip\", \"package\": \"pymongo\", \"label\": \"Install PyMongo (pip)\" }],\n      },\n  }\n---\n\n# Hanzo DocumentDB — Document Database\n\n`pip install pymongo`\n\nMongoDB-compatible document database built on PostgreSQL via FerretDB. Full MongoDB wire protocol with ACID compliance.\n\n## Quick Start\n\n```python\nfrom pymongo import MongoClient\n\nclient = MongoClient(\"mongodb://user:password@localhost:27017/\")\ndb = client[\"myapp\"]\ncollection = db[\"users\"]\n\n# Insert\nresult = collection.insert_one({\"name\": \"Alice\", \"email\": \"[email protected]\", \"role\": \"admin\"})\nprint(f\"Inserted: {result.inserted_id}\")\n\n# Find\nuser = collection.find_one({\"email\": \"[email protected]\"})\nprint(user)\n\n# Query\nadmins = collection.find({\"role\": \"admin\"}).sort(\"name\", 1).limit(10)\nfor admin in admins:\n    print(admin[\"name\"])\n```\n\n## Async Client\n\n```python\nfrom motor.motor_asyncio import AsyncIOMotorClient\n\nclient = AsyncIOMotorClient(\"mongodb://user:password@localhost:27017/\")\ndb = client[\"myapp\"]\n\nresult = await db.users.insert_one({\"name\": \"Bob\"})\nuser = await db.users.find_one({\"name\": \"Bob\"})\n```\n\n## Aggregation Pipelines\n\n```python\npipeline = [\n    {\"$match\": {\"status\": \"active\"}},\n    {\"$group\": {\"_id\": \"$department\", \"count\": {\"$sum\": 1}}},\n    {\"$sort\": {\"count\": -1}}\n]\nresults = collection.aggregate(pipeline)\nfor doc in results:\n    print(f\"{doc['_id']}: {doc['count']}\")\n```\n\n## Bulk Operations\n\n```python\nfrom pymongo import InsertOne, UpdateOne, DeleteOne\n\noperations = [\n    InsertOne({\"name\": \"Carol\"}),\n    UpdateOne({\"name\": \"Alice\"}, {\"$set\": {\"role\": \"superadmin\"}}),\n    DeleteOne({\"name\": \"old-user\"})\n]\nresult = collection.bulk_write(operations)\n```\n\n## Indexes\n\n```python\n# Create index for fast queries\ncollection.create_index(\"email\", unique=True)\ncollection.create_index([(\"name\", 1), (\"created_at\", -1)])\n\n# Text search index\ncollection.create_index([(\"title\", \"text\"), (\"body\", \"text\")])\nresults = collection.find({\"$text\": {\"$search\": \"hanzo agent\"}})\n```\n\n## Transactions\n\n```python\nwith client.start_session() as session:\n    with session.start_transaction():\n        db.accounts.update_one({\"_id\": \"A\"}, {\"$inc\": {\"balance\": -100}}, session=session)\n        db.accounts.update_one({\"_id\": \"B\"}, {\"$inc\": {\"balance\": 100}}, session=session)\n```\n\n## Port\n\n- Default: `27017` (MongoDB wire protocol)\n\n## Environment Variables\n\n```bash\nMONGO_URI=mongodb://user:password@localhost:27017/database\n```\n"}]},{"slug":"hanzo-iam","displayName":"hanzo-iam","summary":"Authenticate users and manage identity with Hanzo IAM. OAuth2 flows, user CRUD, org management, JWT validation, and FastAPI integration via the hanzo-iam Python SDK.","version":"1.0.0","sha256hash":"28e728ffcca5efe8413f747981c36ff7864dc257fe077d85ba79f5b0eed4cc36","files":[{"path":"SKILL.md","size":3710,"sha256":"a12a7049b681bdef78e0259f6d418ada04337cc560396f455b1b41a60ae07c06","contentType":"text/markdown","content":"---\nname: hanzo-iam\ndescription: \"Authenticate users and manage identity with Hanzo IAM. OAuth2 flows, user CRUD, org management, JWT validation, and FastAPI integration via the hanzo-iam Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzoai-iam\",\n              \"label\": \"Install Hanzo IAM SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo IAM — Identity & Access Management\n\n`pip install hanzoai-iam`\n\n## Quick Start\n\n```python\nfrom hanzo_iam import IAMClient, IAMConfig\n\nconfig = IAMConfig(\n    endpoint=\"https://iam.hanzo.ai\",\n    client_id=\"your-client-id\",\n    client_secret=\"your-client-secret\",\n    org_name=\"HANZO\"\n)\nclient = IAMClient(config)\n```\n\n## Environment Variables\n\n```bash\nHANZO_IAM_ENDPOINT=https://iam.hanzo.ai   # IAM server URL\nHANZO_IAM_CLIENT_ID=...                     # OAuth client ID\nHANZO_IAM_CLIENT_SECRET=...                 # OAuth client secret\nHANZO_IAM_ORG_NAME=HANZO                    # Organization name\nHANZO_IAM_APP_NAME=your-app                 # Application name (optional)\nHANZO_IAM_CERTIFICATE=path/to/cert.pem      # TLS cert (optional)\n```\n\n## Supported Organizations\n\n| Org   | Endpoint                | Domain   |\n| ----- | ----------------------- | -------- |\n| HANZO | https://iam.hanzo.ai    | hanzo.id |\n| ZOO   | https://iam.zoo.dev     | zoo.id   |\n| LUX   | https://iam.lux.network | lux.id   |\n| PARS  | https://iam.pars.dev    | pars.id  |\n\n## OAuth2 Authorization Code Flow\n\n```python\n# Step 1: Get authorization URL (redirect user here)\nauth_url = client.get_auth_url(\n    redirect_uri=\"https://yourapp.com/callback\",\n    state=\"random-state-string\",\n    scope=\"openid profile email\"\n)\n\n# Step 2: Exchange code for tokens (after callback)\ntokens = client.get_token(code=\"auth-code-from-callback\")\n# tokens.access_token, tokens.refresh_token, tokens.expires_in\n\n# Step 3: Get user info\nuser = client.get_user_info(access_token=tokens.access_token)\n# user.id, user.name, user.email, user.avatar, user.owner (org)\n```\n\n## Client Credentials Flow (Service-to-Service)\n\n```python\ntokens = client.get_client_credentials_token()\n# Use tokens.access_token for API calls between services\n```\n\n## Refresh Token\n\n```python\nnew_tokens = client.refresh_token(refresh_token=tokens.refresh_token)\n```\n\n## User Management\n\n```python\n# List users\nusers = client.get_users()\n\n# Get user by ID\nuser = client.get_user(user_id=\"user-123\")\n\n# Create user\nuser = client.create_user(\n    name=\"Jane Doe\",\n    email=\"[email protected]\",\n    password=\"secure-password\"\n)\n\n# Update user\nclient.update_user(user_id=\"user-123\", name=\"Jane Smith\")\n\n# Delete user\nclient.delete_user(user_id=\"user-123\")\n```\n\n## Organization Management\n\n```python\norgs = client.get_organizations()\norg = client.get_organization(name=\"HANZO\")\n```\n\n## JWT Validation\n\n```python\nclaims = client.parse_jwt(token=access_token)\n# claims[\"sub\"], claims[\"iss\"], claims[\"exp\"], etc.\n```\n\n## FastAPI Integration\n\n```python\nfrom fastapi import FastAPI, Depends\nfrom hanzo_iam.fastapi import IAMAuth\nfrom hanzo_iam import User\n\napp = FastAPI()\nauth = IAMAuth(config)\n\[email protected](\"/protected\")\nasync def protected(user: User = Depends(auth.require_user)):\n    return {\"user\": user.name, \"org\": user.owner}\n\[email protected](\"/optional\")\nasync def optional(user: User | None = Depends(auth.optional_user)):\n    return {\"user\": user.name if user else \"anonymous\"}\n```\n\n## Async Client\n\n```python\nfrom hanzo_iam import AsyncIAMClient\n\nasync_client = AsyncIAMClient(config)\nuser = await async_client.get_user_info(access_token=token)\n```\n"}]},{"slug":"hanzo-insights","displayName":"hanzo-insights","summary":"Product analytics, feature flags, A/B testing, and session recording with Hanzo Insights. Track events, create funnels, manage rollouts.","version":"1.0.0","sha256hash":"abed6ed5c5408387ea76b7220b5bbab74f971bf9a11d995972e400c99a30b5ab","files":[{"path":"SKILL.md","size":2551,"sha256":"802f3aa31bc33f940a2226230bdea41603475fe037ebe1cd27a1093c28032a70","contentType":"text/markdown","content":"---\nname: hanzo-insights\ndescription: \"Product analytics, feature flags, A/B testing, and session recording with Hanzo Insights. Track events, create funnels, manage rollouts.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"posthog\",\n              \"label\": \"Install Hanzo Insights Client (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Insights — Product Analytics\n\n`pip install posthog`\n\nFull-stack product analytics: event tracking, funnels, session recording, feature flags, A/B testing, and cohort analysis.\n\n## Quick Start\n\n```python\nimport posthog\n\nposthog.project_api_key = \"phc_...\"\nposthog.host = \"https://insights.hanzo.ai\"\n\n# Track event\nposthog.capture(\n    distinct_id=\"user-123\",\n    event=\"button_clicked\",\n    properties={\"button\": \"deploy\", \"page\": \"/dashboard\"}\n)\n```\n\n## Event Tracking\n\n```python\n# Track with properties\nposthog.capture(\"user-123\", \"deployment_started\", {\n    \"project\": \"my-app\",\n    \"environment\": \"production\",\n    \"method\": \"docker\"\n})\n\n# Track page view\nposthog.capture(\"user-123\", \"$pageview\", {\"$current_url\": \"/settings\"})\n\n# Identify user\nposthog.identify(\"user-123\", {\n    \"email\": \"[email protected]\",\n    \"name\": \"Alice\",\n    \"plan\": \"enterprise\"\n})\n```\n\n## Feature Flags\n\n```python\n# Check feature flag\nif posthog.feature_enabled(\"new-dashboard\", \"user-123\"):\n    show_new_dashboard()\nelse:\n    show_old_dashboard()\n\n# Get flag payload\npayload = posthog.get_feature_flag_payload(\"new-dashboard\", \"user-123\")\n\n# Get all flags for user\nflags = posthog.get_all_flags(\"user-123\")\n```\n\n## A/B Testing\n\n```python\n# Get experiment variant\nvariant = posthog.get_feature_flag(\"pricing-test\", \"user-123\")\n\nif variant == \"control\":\n    show_original_pricing()\nelif variant == \"test\":\n    show_new_pricing()\n```\n\n## Group Analytics\n\n```python\n# Track group events (teams, organizations)\nposthog.group_identify(\"company\", \"hanzo-ai\", {\n    \"name\": \"Hanzo AI\",\n    \"plan\": \"enterprise\",\n    \"employee_count\": 50\n})\n\nposthog.capture(\"user-123\", \"feature_used\", groups={\"company\": \"hanzo-ai\"})\n```\n\n## LLM Analytics\n\n```python\n# Track AI/LLM events\nposthog.capture(\"user-123\", \"llm_query\", {\n    \"model\": \"gpt-4\",\n    \"tokens_used\": 1500,\n    \"latency_ms\": 2300,\n    \"cost_usd\": 0.045\n})\n```\n\n## Ports\n\n- API Backend: `8000`\n- Dashboard: `3000`\n\n## Environment Variables\n\n```bash\nPOSTHOG_API_KEY=phc_...\nPOSTHOG_HOST=https://insights.hanzo.ai\n```\n"}]},{"slug":"hanzo-kms","displayName":"hanzo-kms","summary":"Manage secrets, keys, and encryption with Hanzo KMS. Create, read, update, delete secrets, inject env vars, and encrypt/decrypt data via the hanzo-kms Python SDK.","version":"1.0.0","sha256hash":"b99f01906d8e38d9786b24aa9b5c7f4fd4ccb03e0255259d93f74c6595501bb7","files":[{"path":"SKILL.md","size":4132,"sha256":"66fe7930f2afab7a0ada882a8a43c76963edf7851eb197f3da567041d2164947","contentType":"text/markdown","content":"---\nname: hanzo-kms\ndescription: \"Manage secrets, keys, and encryption with Hanzo KMS. Create, read, update, delete secrets, inject env vars, and encrypt/decrypt data via the hanzo-kms Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-kms\",\n              \"label\": \"Install Hanzo KMS SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo KMS — Key Management Service\n\n`pip install hanzo-kms`\n\n## Quick Start\n\n```python\nfrom hanzo_kms import KMSClient, ClientSettings, AuthenticationOptions, UniversalAuthMethod\n\nclient = KMSClient(ClientSettings(\n    auth=AuthenticationOptions(\n        universal_auth=UniversalAuthMethod(\n            client_id=\"your-client-id\",\n            client_secret=\"your-client-secret\"\n        )\n    )\n))\n```\n\nOr auto-load from environment:\n\n```python\nclient = KMSClient()  # Uses HANZO_KMS_* env vars\n```\n\n## Environment Variables\n\n```bash\nHANZO_KMS_URL=https://kms.hanzo.ai       # KMS server URL\nHANZO_KMS_CLIENT_ID=...                    # Universal Auth client ID\nHANZO_KMS_CLIENT_SECRET=...                # Universal Auth client secret\n```\n\n## Authentication Methods\n\n### Universal Auth (recommended)\n\n```python\nclient = KMSClient(ClientSettings(\n    auth=AuthenticationOptions(\n        universal_auth=UniversalAuthMethod(\n            client_id=\"...\",\n            client_secret=\"...\"\n        )\n    )\n))\n```\n\n### Kubernetes Auth (for K8s workloads)\n\n```python\nfrom hanzo_kms import KubernetesAuthMethod\n\nclient = KMSClient(ClientSettings(\n    auth=AuthenticationOptions(\n        kubernetes=KubernetesAuthMethod(identity_id=\"...\")\n    )\n))\n```\n\n### AWS IAM Auth\n\n```python\nfrom hanzo_kms import AWSIamAuthMethod\n\nclient = KMSClient(ClientSettings(\n    auth=AuthenticationOptions(\n        aws_iam=AWSIamAuthMethod(identity_id=\"...\")\n    )\n))\n```\n\n## Secret Operations\n\n### List Secrets\n\n```python\nsecrets = client.list_secrets(\n    project_id=\"my-project\",\n    environment=\"production\",\n    path=\"/\"\n)\nfor s in secrets:\n    print(f\"{s.secret_name} = {s.secret_value}\")\n```\n\n### Get Secret\n\n```python\nsecret = client.get_secret(\n    project_id=\"my-project\",\n    environment=\"production\",\n    secret_name=\"DATABASE_URL\"\n)\nprint(secret.secret_value)\n```\n\n### Get Value (convenience)\n\n```python\ndb_url = client.get_value(\"my-project\", \"production\", \"DATABASE_URL\")\napi_key = client.get_value(\"my-project\", \"production\", \"API_KEY\", default=\"fallback\")\n```\n\n### Create Secret\n\n```python\nclient.create_secret(\n    project_id=\"my-project\",\n    environment=\"production\",\n    secret_name=\"NEW_SECRET\",\n    secret_value=\"super-secret-value\"\n)\n```\n\n### Update Secret\n\n```python\nclient.update_secret(\n    project_id=\"my-project\",\n    environment=\"production\",\n    secret_name=\"NEW_SECRET\",\n    secret_value=\"updated-value\"\n)\n```\n\n### Delete Secret\n\n```python\nclient.delete_secret(\n    project_id=\"my-project\",\n    environment=\"production\",\n    secret_name=\"NEW_SECRET\"\n)\n```\n\n## Inject Secrets into Environment\n\n```python\n# Load all project secrets as environment variables\nclient.inject_env(\n    project_id=\"my-project\",\n    environment=\"production\",\n    overwrite=False  # Don't overwrite existing env vars\n)\n\nimport os\nprint(os.environ[\"DATABASE_URL\"])  # Now available\n```\n\n## Key Management (via Core SDK)\n\n```python\nfrom hanzoai import Hanzo\n\nhanzo = Hanzo(api_key=\"...\")\n\n# Create encryption key\nkey = hanzo.kms.create_key()\n\n# Encrypt data\nencrypted = hanzo.kms.encrypt(key_id=key.id, data=\"sensitive-data\")\n\n# Decrypt data\ndecrypted = hanzo.kms.decrypt(key_id=key.id, data=encrypted.ciphertext)\n\n# Sign data\nsignature = hanzo.kms.sign(key_id=key.id, data=\"message\")\n\n# Verify signature\nvalid = hanzo.kms.verify(key_id=key.id, data=\"message\", signature=signature.sig)\n```\n\n## Compatibility\n\nWorks with:\n\n- Hanzo KMS (`kms.hanzo.ai`)\n- Lux KMS (`kms.lux.network`)\n- Infisical-compatible servers\n\nAlso aliased as `InfisicalClient` for compatibility:\n\n```python\nfrom hanzo_kms import InfisicalClient  # Same as KMSClient\n```\n"}]},{"slug":"hanzo-kv","displayName":"hanzo-kv","summary":"Redis-compatible key-value store for caching, sessions, pub/sub messaging, streams, and real-time data. Sub-millisecond reads/writes.","version":"1.0.0","sha256hash":"0ec512a6f09049abbcc76c1cd38567e1e4a80a80659482b518cfb482d0415867","files":[{"path":"SKILL.md","size":2620,"sha256":"b4c07a0c222e739e96ef91db4d9e1df6eae303122dbb950cf45c6c69fda48eba","contentType":"text/markdown","content":"---\nname: hanzo-kv\ndescription: \"Redis-compatible key-value store for caching, sessions, pub/sub messaging, streams, and real-time data. Sub-millisecond reads/writes.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"redis\",\n              \"label\": \"Install Redis Client (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo KV — Key-Value Store\n\n`pip install redis`\n\nRedis-compatible high-performance in-memory data store. Sub-millisecond reads/writes for caching, sessions, pub/sub, and streaming.\n\n## Quick Start\n\n```python\nimport redis\n\nclient = redis.Redis(host=\"localhost\", port=6379)\n\n# Basic operations\nclient.set(\"key\", \"value\")\nvalue = client.get(\"key\")\n\n# With TTL\nclient.setex(\"session:abc\", 3600, \"user-data\")\n\n# Hash maps\nclient.hset(\"user:1\", mapping={\"name\": \"Alice\", \"email\": \"[email protected]\"})\nuser = client.hgetall(\"user:1\")\n```\n\n## Async Client\n\n```python\nimport redis.asyncio as aioredis\n\nclient = aioredis.Redis(host=\"localhost\", port=6379)\n\nawait client.set(\"key\", \"value\")\nvalue = await client.get(\"key\")\n```\n\n## Pub/Sub Messaging\n\n```python\n# Publisher\nclient.publish(\"events\", '{\"type\": \"user.created\", \"id\": \"123\"}')\n\n# Subscriber\npubsub = client.pubsub()\npubsub.subscribe(\"events\")\nfor message in pubsub.listen():\n    if message[\"type\"] == \"message\":\n        print(message[\"data\"])\n```\n\n## Streams (Event Sourcing)\n\n```python\n# Add to stream\nclient.xadd(\"orders\", {\"item\": \"widget\", \"qty\": \"5\"})\n\n# Read from stream\nmessages = client.xread({\"orders\": \"0\"}, count=10)\n\n# Consumer groups\nclient.xgroup_create(\"orders\", \"processors\", \"0\")\nmessages = client.xreadgroup(\"processors\", \"worker-1\", {\"orders\": \">\"}, count=5)\nclient.xack(\"orders\", \"processors\", message_id)\n```\n\n## Lists (Queues)\n\n```python\n# Push to queue\nclient.lpush(\"tasks\", \"task-1\", \"task-2\")\n\n# Pop from queue (blocking)\ntask = client.brpop(\"tasks\", timeout=30)\n```\n\n## Sorted Sets (Leaderboards)\n\n```python\nclient.zadd(\"scores\", {\"alice\": 100, \"bob\": 85, \"carol\": 92})\ntop = client.zrevrange(\"scores\", 0, 9, withscores=True)\n```\n\n## Lua Scripting\n\n```python\nscript = client.register_script(\"\"\"\n    local current = redis.call('GET', KEYS[1])\n    if current == false then\n        redis.call('SET', KEYS[1], ARGV[1])\n        return 1\n    end\n    return 0\n\"\"\")\nresult = script(keys=[\"lock:resource\"], args=[\"locked\"])\n```\n\n## Port\n\n- Default: `6379`\n\n## Environment Variables\n\n```bash\nREDIS_URL=redis://localhost:6379\nREDIS_PASSWORD=...              # Optional\n```\n"}]},{"slug":"hanzo-llm","displayName":"hanzo-llm","summary":"Hanzo LLM Gateway — unified proxy for 100+ AI providers. Route requests, track costs, manage virtual keys, rate limiting, and model fallbacks.","version":"1.0.0","sha256hash":"c6db579019d6e4d4de6e9eb0a9245d08a0ea615c1c492542054c46fcd189501a","files":[{"path":"SKILL.md","size":3431,"sha256":"7fe346238951270920b396cc7df08bfc3276dfe7b8b3b8f22a28b6f877d3b0dc","contentType":"text/markdown","content":"---\nname: hanzo-llm\ndescription: \"Hanzo LLM Gateway — unified proxy for 100+ AI providers. Route requests, track costs, manage virtual keys, rate limiting, and model fallbacks.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzoai\",\n              \"label\": \"Install Hanzo AI SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo LLM Gateway — AI Provider Proxy\n\n`pip install hanzoai`\n\nUnified proxy for 100+ LLM providers with cost tracking, rate limiting, virtual keys, model fallbacks, and load balancing. OpenAI-compatible API.\n\n## Quick Start\n\n```python\nfrom hanzoai import Hanzo\n\nclient = Hanzo(api_key=\"sk-hanzo-...\")\n\n# Route to any provider via unified API\nresponse = client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\n```\n\n## Provider Routing\n\n```python\n# OpenAI\nclient.chat.completions.create(model=\"gpt-4o\", ...)\n\n# Anthropic Claude\nclient.chat.completions.create(model=\"claude-sonnet-4-20250514\", ...)\n\n# Google Gemini\nclient.chat.completions.create(model=\"gemini/gemini-2.0-flash\", ...)\n\n# AWS Bedrock\nclient.chat.completions.create(model=\"bedrock/anthropic.claude-3-sonnet\", ...)\n\n# Azure OpenAI\nclient.chat.completions.create(model=\"azure/gpt-4\", ...)\n\n# Ollama (local)\nclient.chat.completions.create(model=\"ollama/llama3\", ...)\n\n# Together AI\nclient.chat.completions.create(model=\"together_ai/meta-llama/Llama-3-70b\", ...)\n```\n\n## Model Fallbacks\n\n```python\n# Configure fallback chain via gateway config\n# If primary model fails, automatically try next\n# gpt-4 → claude-sonnet → gemini-pro\n```\n\n## Cost Tracking\n\n```python\n# Get global spend\nspend = client.global_spend.retrieve()\n\n# Per-team spend\nteam_spend = client.global_spend.list_spend_logs(api_key=\"sk-...\")\n\n# Per-key spend tracking\nkey_info = client.key.retrieve(key=\"sk-...\")\nprint(f\"Spend: ${key_info.spend}\")\n```\n\n## Virtual Keys\n\n```python\n# Create virtual key with budget\nkey = client.key.generate(\n    team_id=\"team-123\",\n    max_budget=100.0,  # $100 budget\n    models=[\"gpt-4\", \"claude-sonnet-4-20250514\"],  # Allowed models\n)\n\n# List keys\nkeys = client.key.list()\n```\n\n## Rate Limiting\n\n```python\n# Per-key rate limits configured at gateway level\n# Supports: requests/min, tokens/min, requests/day\n```\n\n## Team Management\n\n```python\n# Create team\nclient.team.create(team_alias=\"engineering\")\n\n# List teams\nteams = client.team.list()\n\n# Organization management\norgs = client.organization.list()\n```\n\n## Streaming\n\n```python\nfor chunk in client.chat.completions.create(\n    model=\"gpt-4\",\n    messages=[{\"role\": \"user\", \"content\": \"Tell me a story\"}],\n    stream=True\n):\n    print(chunk.choices[0].delta.content or \"\", end=\"\")\n```\n\n## Embeddings\n\n```python\nresponse = client.embeddings.create(\n    model=\"text-embedding-3-small\",\n    input=\"The food was delicious\"\n)\nvector = response.data[0].embedding\n```\n\n## Supported Providers (100+)\n\nOpenAI, Anthropic, Google Gemini, AWS Bedrock, Azure OpenAI, Together AI, Cohere, Mistral, Groq, DeepSeek, Ollama, VLLM, HuggingFace, Replicate, Perplexity, Fireworks AI, and more.\n\n## Port\n\n- Gateway: `4000`\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=sk-hanzo-...            # API key\nHANZO_BASE_URL=https://api.hanzo.ai   # Gateway URL (or http://localhost:4000)\n```\n"}]},{"slug":"hanzo-mcp","displayName":"hanzo-mcp","summary":"Unified MCP server orchestrating 260+ AI development tools. Filesystem, shell, browser, code analysis, memory, agents, LLM, computer control, and more.","version":"1.0.0","sha256hash":"526c6ccfb5065070ad537eb4cd2c04647b4b9aed474cb6566b097e4694c908c6","files":[{"path":"SKILL.md","size":3721,"sha256":"e681f67bf51db16a006d82c808018f08bfb24f9550e6ec8dd46f73afd507914c","contentType":"text/markdown","content":"---\nname: hanzo-mcp\ndescription: \"Unified MCP server orchestrating 260+ AI development tools. Filesystem, shell, browser, code analysis, memory, agents, LLM, computer control, and more.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-mcp\",\n              \"label\": \"Install Hanzo MCP (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo MCP — Unified AI Tool Server\n\n`pip install hanzo-mcp`\n\nSingle MCP server that orchestrates 260+ tools across filesystem, shell, browser, code, memory, agents, LLM, and computer control.\n\n## Quick Start\n\n```bash\n# Run MCP server (stdio transport)\nhanzo-mcp\n\n# Development mode with extra logging\nhanzo-mcp-dev\n\n# Interactive REPL\nhanzo-plugin\n```\n\n## Tool Categories\n\n### Filesystem (`hanzo-tools-fs`)\n\n- `read_file`, `write_file`, `edit_file` — File operations\n- `search`, `find`, `list_files` — File discovery\n- `watch` — File change monitoring\n\n### Shell (`hanzo-tools-shell`)\n\n- `execute_command` — Run shell commands with auto-detected shell\n- `run_dag` — Execute command DAGs (directed acyclic graphs)\n\n### Browser (`hanzo-tools-browser`)\n\n- Browser automation with Hanzo extension or Playwright fallback\n- Page navigation, clicking, form filling, screenshots\n\n### Code Analysis (`hanzo-tools-code`, `hanzo-tools-lsp`)\n\n- AST analysis via tree-sitter (Python, JS, TS, Ruby, Go, Rust)\n- LSP integration for code intelligence\n- Semantic code search via grep-ast\n\n### Refactoring (`hanzo-tools-refactor`)\n\n- Rename symbols, extract functions, inline variables\n- Move code between files, safe cross-file refactoring\n\n### Memory (`hanzo-tools-memory`)\n\n- Store/recall memories with semantic search\n- Knowledge base management\n- Fact storage and retrieval\n\n### Agents (`hanzo-tools-agent`)\n\n- Multi-agent orchestration\n- Spawn and coordinate agent swarms\n- Consensus-based decision making\n\n### LLM (`hanzo-tools-llm`)\n\n- Model management and selection\n- Provider routing (OpenAI, Anthropic, Hanzo, local)\n\n### Computer Control (`hanzo-tools-computer`)\n\n- Screen capture and OCR\n- Mouse/keyboard automation\n- Activity-based session compression\n\n### API (`hanzo-tools-api`)\n\n- Call any REST API via OpenAPI spec discovery\n- Dynamic API exploration and execution\n\n### Auth & Security (`hanzo-tools-auth`, `hanzo-tools-kms`)\n\n- IAM token management and session handling\n- KMS secret CRUD operations\n\n### PaaS (`hanzo-tools-paas`)\n\n- Deploy apps, view logs, manage environments\n- IAM user/org/role management\n\n### IDE (`hanzo-tools-ide`, `hanzo-tools-editor`)\n\n- VS Code, Neovim integration\n- WebSocket-based editor communication\n\n### Planning (`hanzo-tools-plan`, `hanzo-tools-todo`)\n\n- DAG-based plan execution\n- Task management and tracking\n\n### Testing (`hanzo-tools-test`)\n\n- Lint, typecheck, test execution\n\n### VCS (`hanzo-tools-vcs`)\n\n- Git operations, branch management, commit handling\n\n## Configuration\n\n```bash\n# MCP settings (checked in order)\n~/.config/hanzo/mcp-settings.json\n.hanzo-mcp.json\n.hanzo/mcp-settings.json\n```\n\n```json\n{\n  \"tools\": {\n    \"enabled\": [\"fs\", \"shell\", \"browser\", \"memory\", \"agent\"],\n    \"disabled\": []\n  },\n  \"transport\": \"stdio\"\n}\n```\n\n## Environment Variables\n\n```bash\nHANZO_MCP_TOKEN=...              # Auth token (auto-generated if missing)\nHANZO_MCP_TRANSPORT=stdio        # Transport: stdio or sse\nHANZO_QUIET=1                    # Suppress startup output\n```\n\n## Claude Desktop Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"hanzo\": {\n      \"command\": \"hanzo-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"HANZO_MCP_TRANSPORT\": \"stdio\"\n      }\n    }\n  }\n}\n```\n"}]},{"slug":"hanzo-memory","displayName":"hanzo-memory","summary":"AI memory and knowledge management with Hanzo Memory. Store memories, manage knowledge bases, semantic search, chat history, and fact management via the hanzo-memory Python SDK.","version":"1.0.0","sha256hash":"745215941663d97c288626c3e29138621af7053a2748f55738c049c550d8bb01","files":[{"path":"SKILL.md","size":4588,"sha256":"3ff01c3e191b6a149773419103fb00de60bc6daaf62356bc34c9f98d54b574d7","contentType":"text/markdown","content":"---\nname: hanzo-memory\ndescription: \"AI memory and knowledge management with Hanzo Memory. Store memories, manage knowledge bases, semantic search, chat history, and fact management via the hanzo-memory Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-memory\",\n              \"label\": \"Install Hanzo Memory SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Memory — AI Memory & Knowledge\n\n`pip install hanzo-memory`\n\nVector-backed memory service with semantic search, knowledge bases, and chat history.\n\n## Quick Start\n\n```python\nfrom hanzo_memory import MemoryService\n\nmemory = MemoryService()\n\n# Store a memory\nawait memory.store(key=\"user:preferences\", value=\"Prefers Python over JavaScript\")\n\n# Search memories\nresults = await memory.search(\"programming language preferences\", limit=5)\nfor r in results:\n    print(r.content, r.score)\n```\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=your-key                          # API key\nHANZO_LLM_MODEL=gpt-4o-mini                    # LLM for processing\nOPENAI_API_KEY=...                               # For embeddings\nHANZO_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5   # Embedding model\nHANZO_DB_BACKEND=lancedb                         # Backend: lancedb or infinity\nHANZO_LANCEDB_PATH=data/lancedb                 # Storage path\nHANZO_DISABLE_AUTH=false                         # Disable auth (dev only)\n```\n\n## Memory Operations\n\n```python\n# Store memory\nawait memory.store(\n    key=\"context:meeting-notes\",\n    value=\"Q4 planning: focus on AI agents and MCP tools\",\n    metadata={\"project\": \"hanzo-bot\", \"date\": \"2026-02-26\"}\n)\n\n# Retrieve by key\nresult = await memory.retrieve(key=\"context:meeting-notes\")\n\n# Semantic search\nresults = await memory.search(\n    query=\"what are the Q4 priorities?\",\n    limit=10\n)\n\n# Delete memory\nawait memory.delete(key=\"context:meeting-notes\")\n```\n\n## Knowledge Base Management\n\n```python\n# Create knowledge base\nawait memory.create_kb(name=\"product-docs\", description=\"Product documentation\")\n\n# Add facts to knowledge base\nawait memory.add_fact(\n    kb_name=\"product-docs\",\n    fact=\"Hanzo Bot supports 100+ LLM providers via the unified gateway\"\n)\n\nawait memory.add_fact(\n    kb_name=\"product-docs\",\n    fact=\"IAM supports OAuth2 with PKCE for browser-based apps\"\n)\n\n# Query facts\nfacts = await memory.query_facts(\n    kb_name=\"product-docs\",\n    query=\"How many LLM providers are supported?\",\n    limit=5\n)\n\n# List knowledge bases\nkbs = await memory.list_kbs()\n```\n\n## Chat History\n\n```python\n# Store chat message\nawait memory.add_message(\n    session_id=\"session-123\",\n    role=\"user\",\n    content=\"How do I deploy to Hanzo PaaS?\"\n)\n\nawait memory.add_message(\n    session_id=\"session-123\",\n    role=\"assistant\",\n    content=\"You can deploy using the Platform API...\"\n)\n\n# Retrieve chat history\nmessages = await memory.get_messages(session_id=\"session-123\")\n\n# Search across chat history\nresults = await memory.search_messages(query=\"deployment\", limit=10)\n```\n\n## REST API (FastAPI Service)\n\nRun the memory service:\n\n```bash\nuvicorn hanzo_memory.server:app --port 8100\n```\n\n### Endpoints\n\n```\nPOST   /v1/remember              # Store memory\nGET    /v1/memories               # List memories\nGET    /v1/memories/{key}         # Get memory by key\nDELETE /v1/memories/{key}         # Delete memory\nPOST   /search                    # Semantic search\n\nPOST   /v1/kb                     # Create knowledge base\nGET    /v1/kb                     # List knowledge bases\nPOST   /v1/kb/facts               # Add fact\nGET    /v1/kb/facts/{kb}          # Query facts\n\nPOST   /v1/chat/messages          # Add chat message\nGET    /v1/chat/sessions/{id}     # Get session messages\nPOST   /v1/chat/search            # Search messages\n```\n\n## Database Backends\n\n### LanceDB (default)\n\n- Cross-platform (Linux, macOS, Windows, ARM, WASM)\n- Embedded, no server needed\n- Good for development and small deployments\n\n### InfinityDB (high-performance)\n\n- Linux/Windows only\n- Better for large-scale production\n- Requires separate server process\n\nConfigure via `HANZO_DB_BACKEND=lancedb` or `HANZO_DB_BACKEND=infinity`.\n\n## Multi-Tenancy\n\n```python\n# Isolate memories by user/project\nawait memory.store(\n    key=\"user:alice:notes\",\n    value=\"...\",\n    metadata={\"user_id\": \"alice\", \"project\": \"my-project\"}\n)\n\n# Search within tenant scope\nresults = await memory.search(\n    query=\"notes\",\n    filters={\"user_id\": \"alice\"}\n)\n```\n"}]},{"slug":"hanzo-network","displayName":"hanzo-network","summary":"Distributed agent network orchestration. Create multi-agent swarms with gRPC, ring topology, local/remote LLM providers, and shard distribution.","version":"1.0.0","sha256hash":"74d72ac09b7d207c62ded0ae5e13036aad2fd805db974079370b62bbde0eaf1f","files":[{"path":"SKILL.md","size":2770,"sha256":"90678894d562937942b9b38938ce6a37a4dd35de9aefae8b263ad6166fc5fe9c","contentType":"text/markdown","content":"---\nname: hanzo-network\ndescription: \"Distributed agent network orchestration. Create multi-agent swarms with gRPC, ring topology, local/remote LLM providers, and shard distribution.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-network\",\n              \"label\": \"Install Hanzo Network (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Network — Distributed Agent Orchestration\n\n`pip install hanzo-network`\n\nBuild distributed multi-agent networks with gRPC, ring topology, local/remote LLM inference, and model shard distribution.\n\n## Quick Start\n\n```python\nfrom hanzo_network import create_agent, create_network, Tool\n\n# Create agents with tools\nresearcher = create_agent(\n    name=\"Researcher\",\n    instructions=\"Research topics thoroughly\",\n    tools=[search_tool]\n)\n\nwriter = create_agent(\n    name=\"Writer\",\n    instructions=\"Write clear content\",\n    tools=[write_tool]\n)\n\n# Create a network\nnetwork = create_network(agents=[researcher, writer])\nresult = await network.run(\"Write about quantum computing\")\n```\n\n## Distributed Networks\n\n```python\nfrom hanzo_network import create_distributed_network\n\n# gRPC-based distributed agent network\nnetwork = create_distributed_network(\n    agents=[agent1, agent2, agent3],\n    topology=\"ring\"  # Ring topology with memory-weighted partitioning\n)\n\n# Agents communicate via gRPC + protobuf\n# Discovery via UDP/Tailscale\nresult = await network.run(\"Complex multi-step task\")\n```\n\n## Local LLM Providers\n\n```python\nfrom hanzo_network import create_local_agent, check_local_llm_status\n\n# Check available local inference engines\nstatus = check_local_llm_status()\n\n# Create agent with local LLM (MLX, Tinygrad, Ollama)\nagent = create_local_agent(\n    name=\"Local Agent\",\n    provider=\"ollama\",  # or \"mlx\", \"tinygrad\"\n    model=\"llama3\"\n)\n```\n\n## LLM Providers\n\n```python\nfrom hanzo_network import HanzoNetProvider, LocalLLMProvider, OllamaProvider, MLXProvider\n\n# Hanzo cloud provider\nprovider = HanzoNetProvider(api_key=\"...\")\n\n# Local Ollama\nprovider = OllamaProvider(model=\"llama3\")\n\n# Apple Silicon MLX\nprovider = MLXProvider(model=\"mlx-community/Meta-Llama-3-8B\")\n```\n\n## Agent Routing\n\n```python\nfrom hanzo_network import Router\n\nrouter = Router(agents=[researcher, writer, coder])\n\n# Semantic routing — automatically selects best agent\nresult = await router.route(\"Write a Python script for data analysis\")\n```\n\n## Shard Distribution\n\n```python\n# Distribute model shards across network nodes\n# Ring topology with memory-weighted partitioning\nnetwork = create_distributed_network(\n    agents=[...],\n    shard_strategy=\"memory_weighted\"\n)\n```\n"}]},{"slug":"hanzo-node","displayName":"hanzo-node","summary":"Install and manage Hanzo AI compute nodes. Cross-platform installer for the Rust-based hanzo-node binary with version management.","version":"1.0.0","sha256hash":"0904219766f3eb3f7db652627cba72ec1a4b6ce29cd8aef610d53bf29e3168bc","files":[{"path":"SKILL.md","size":1814,"sha256":"384409090387c0a3885cbcf35d090b9ada2958fee73f445b46b286709899bd79","contentType":"text/markdown","content":"---\nname: hanzo-node\ndescription: \"Install and manage Hanzo AI compute nodes. Cross-platform installer for the Rust-based hanzo-node binary with version management.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-node\",\n              \"label\": \"Install Hanzo Node (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Node — AI Compute Node\n\n`pip install hanzo-node`\n\nCross-platform installer and manager for the Hanzo AI compute node (Rust binary). Nodes participate in the distributed compute network for AI inference, task scheduling, and blockchain integration.\n\n## Quick Start\n\n```bash\n# Install the node binary\nhanzo-node install\n\n# Check status\nhanzo-node status\n\n# Run the node\nhanzo-node\n```\n\n## Installation Management\n\n```bash\n# Install latest version\nhanzo-node install\n\n# Install specific version\nhanzo-node install --version=0.5.0\n\n# Force reinstall\nhanzo-node install --force\n\n# Upgrade to latest\nhanzo-node upgrade\n\n# Uninstall\nhanzo-node uninstall\n```\n\n## Python API\n\n```python\nfrom hanzo_node import install, uninstall, is_installed, get_binary_path, get_installed_version\n\n# Check if installed\nif not is_installed():\n    install()\n\n# Get info\nprint(get_binary_path())       # ~/.hanzo/bin/hanzo-node\nprint(get_installed_version()) # 0.5.0\n```\n\n## Node Capabilities\n\n- **Task Scheduling**: Define and schedule compute tasks\n- **Code Generation**: Automated code generation pipelines\n- **Crypto Support**: Wallet management, transaction signing\n- **Distributed Compute**: Join the Hanzo compute mesh\n- **Auto-detection**: Platform-specific binary (macOS, Linux, Windows)\n\n## Binary Location\n\n```\n~/.hanzo/bin/hanzo-node\n```\n"}]},{"slug":"hanzo-paas","displayName":"hanzo-paas","summary":"Deploy and manage applications on Hanzo PaaS. Manage projects, environments, deployments, domains, logs, and cloud services via the hanzo-tools-paas MCP tool or REST API.","version":"1.0.0","sha256hash":"fea8a7ea05390708c16aefad7c1d39465406f7b81032f659e7fe851f2425f7ac","files":[{"path":"SKILL.md","size":5096,"sha256":"2688508f7436d26fffd0e8c64a60d552734b04f440e85021d372967bbe08f889","contentType":"text/markdown","content":"---\nname: hanzo-paas\ndescription: \"Deploy and manage applications on Hanzo PaaS. Manage projects, environments, deployments, domains, logs, and cloud services via the hanzo-tools-paas MCP tool or REST API.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-tools-paas\",\n              \"label\": \"Install Hanzo PaaS Tools (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo PaaS — Platform as a Service\n\n`pip install hanzo-tools-paas`\n\nDeploy and manage applications on Hanzo PaaS (platform.hanzo.ai). Supports Dokploy-based hosting, Docker/Compose deployments, domain management, and IAM integration.\n\n## Authentication\n\n```bash\n# Login via Hanzo CLI (stores token at ~/.hanzo/auth/token.json)\nhanzo login\n\n# Or set environment variables\nexport HANZO_IAM_URL=https://hanzo.id\nexport HANZO_IAM_CLIENT_ID=your-client-id\nexport HANZO_IAM_CLIENT_SECRET=your-client-secret\n```\n\n## MCP Tool (Recommended)\n\nThe `paas` MCP tool provides a unified interface via `hanzo-mcp`:\n\n```python\n# Via hanzo-mcp server — single tool with action parameter\n# Tool: paas(action, org, project, environment, container)\n```\n\n### IAM Actions\n\n```python\n# Who am I?\npaas(action=\"whoami\")\n# → {\"sub\": \"user-id\", \"name\": \"...\", \"email\": \"...\", \"organization\": \"hanzo\"}\n\n# List users\npaas(action=\"users\")\n# → {\"count\": 5, \"users\": [{\"id\": \"...\", \"name\": \"...\", \"email\": \"...\"}]}\n\n# List organizations\npaas(action=\"orgs\")\n# → {\"count\": 3, \"organizations\": [...]}\n\n# List roles\npaas(action=\"roles\")\n# → {\"count\": 4, \"roles\": [...]}\n```\n\n### Deployment Actions\n\n```python\n# List projects in org\npaas(action=\"projects\", org=\"hanzo\")\n# → {\"org\": \"hanzo\", \"count\": 12, \"projects\": [...]}\n\n# List environments for a project\npaas(action=\"env\", org=\"hanzo\", project=\"my-project\")\n# → {\"environments\": [{\"id\": \"...\", \"name\": \"production\"}, ...]}\n\n# List containers/deployments\npaas(action=\"deployments\", org=\"hanzo\", project=\"my-project\", environment=\"prod\")\n# → {\"containers\": [{\"id\": \"...\", \"name\": \"web\", \"image\": \"...\", \"status\": \"running\", \"replicas\": 3}]}\n\n# Get deployment details\npaas(action=\"deploy\", org=\"hanzo\", project=\"my-project\", environment=\"prod\", container=\"web\")\n\n# View container logs\npaas(action=\"logs\", org=\"hanzo\", project=\"my-project\", environment=\"prod\", container=\"web\")\n\n# Redeploy (rolling restart)\npaas(action=\"redeploy\", org=\"hanzo\", project=\"my-project\", environment=\"prod\", container=\"web\")\n```\n\n### Cloud Services\n\n```python\n# List managed services and cluster info\npaas(action=\"services\")\n# → {\"cluster\": {...}, \"templates\": {...}}\n```\n\n## REST API (Direct)\n\nBase URL: `https://platform.hanzo.ai/api`\n\n```bash\nTOKEN=$(cat ~/.hanzo/auth/token.json | jq -r .access_token)\n\n# List projects\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n  \"https://platform.hanzo.ai/api/project.all\" | jq\n\n# Create project\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"my-app\", \"description\": \"My application\"}' \\\n  \"https://platform.hanzo.ai/api/project.create\" | jq\n\n# Deploy application\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"applicationId\": \"<app-id>\"}' \\\n  \"https://platform.hanzo.ai/api/application.deploy\" | jq\n\n# Read logs\ncurl -s -H \"Authorization: Bearer $TOKEN\" \\\n  \"https://platform.hanzo.ai/api/application.readLogs?applicationId=<id>\" | jq\n```\n\n## Docker Compose Deployments\n\n```bash\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"projectId\": \"<project-id>\",\n    \"name\": \"my-stack\",\n    \"composeFile\": \"services:\\n  web:\\n    image: nginx\"\n  }' \"https://platform.hanzo.ai/api/compose.create\" | jq\n```\n\n## Domain Management\n\n```bash\ncurl -s -X POST -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"applicationId\": \"<app-id>\",\n    \"host\": \"myapp.hanzo.ai\",\n    \"certificateType\": \"letsencrypt\"\n  }' \"https://platform.hanzo.ai/api/domain.create\" | jq\n```\n\n## Environment Variables\n\n```bash\nHANZO_IAM_URL=https://hanzo.id           # IAM endpoint\nHANZO_IAM_CLIENT_ID=...                   # OAuth client ID\nHANZO_IAM_CLIENT_SECRET=...               # OAuth client secret\nHANZO_PLATFORM_URL=https://platform.hanzo.ai  # PaaS endpoint\n```\n\n## Key Endpoints\n\n| Endpoint                      | Purpose                |\n| ----------------------------- | ---------------------- |\n| `project.all`                 | List all projects      |\n| `project.create`              | Create project         |\n| `application.create`          | Create app service     |\n| `application.deploy`          | Trigger deployment     |\n| `application.readLogs`        | Read app logs          |\n| `compose.create`              | Create compose service |\n| `compose.deploy`              | Deploy compose         |\n| `domain.create`               | Add domain             |\n| `application.saveEnvironment` | Set env vars           |\n"}]},{"slug":"hanzo-pubsub","displayName":"hanzo-pubsub","summary":"High-performance event streaming and message queues with Hanzo PubSub (NATS). Pub/sub, persistent streams, consumer groups, exactly-once delivery.","version":"1.0.0","sha256hash":"9f59120888595f5064500d13dbb046626f63d3a29b387ecbabff35690f57d1ae","files":[{"path":"SKILL.md","size":2645,"sha256":"85199e687ad86c72a2c3d9f6b3369cda0b66e06c15aed3c0fc155f238001a340","contentType":"text/markdown","content":"---\nname: hanzo-pubsub\ndescription: \"High-performance event streaming and message queues with Hanzo PubSub (NATS). Pub/sub, persistent streams, consumer groups, exactly-once delivery.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"nats-py\",\n              \"label\": \"Install NATS Client (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo PubSub — Event Streaming\n\n`pip install nats-py`\n\nNATS-based high-performance event streaming: pub/sub, persistent streams, consumer groups, exactly-once delivery. 10M+ messages/sec.\n\n## Quick Start\n\n```python\nimport nats\n\nnc = await nats.connect(\"nats://localhost:4222\")\n\n# Simple pub/sub\nawait nc.publish(\"events.user.created\", b'{\"user_id\": \"123\"}')\n\n# Subscribe\nasync def handler(msg):\n    print(f\"Received: {msg.data.decode()}\")\n\nsub = await nc.subscribe(\"events.>\", cb=handler)\n```\n\n## JetStream (Persistent Streams)\n\n```python\njs = nc.jetstream()\n\n# Create persistent stream\nawait js.add_stream(name=\"ORDERS\", subjects=[\"orders.*\"])\n\n# Publish to stream\nack = await js.publish(\"orders.new\", b'{\"item\": \"widget\", \"qty\": 5}')\nprint(f\"Sequence: {ack.seq}\")\n\n# Subscribe with durable consumer\nsub = await js.subscribe(\"orders.*\", durable=\"order-processor\")\nasync for msg in sub.messages:\n    print(f\"Order: {msg.data.decode()}\")\n    await msg.ack()\n```\n\n## Consumer Groups\n\n```python\n# Create pull-based consumer group\npsub = await js.pull_subscribe(\"orders.*\", durable=\"workers\")\n\n# Fetch batch of messages\nmsgs = await psub.fetch(batch=10, timeout=5)\nfor msg in msgs:\n    process(msg.data)\n    await msg.ack()\n```\n\n## Key-Value Store (Built-in)\n\n```python\nkv = await js.create_key_value(bucket=\"config\")\n\nawait kv.put(\"db.host\", b\"localhost\")\nentry = await kv.get(\"db.host\")\nprint(entry.value.decode())\n\n# Watch for changes\nwatcher = await kv.watchall()\nasync for entry in watcher:\n    print(f\"{entry.key} = {entry.value}\")\n```\n\n## Object Store\n\n```python\nobs = await js.create_object_store(bucket=\"artifacts\")\n\n# Store object\nawait obs.put(\"model.bin\", open(\"model.bin\", \"rb\"))\n\n# Retrieve\ndata = await obs.get(\"model.bin\")\n```\n\n## Request/Reply\n\n```python\n# Service\nasync def handler(msg):\n    await msg.respond(b\"pong\")\n\nawait nc.subscribe(\"ping\", cb=handler)\n\n# Client\nresponse = await nc.request(\"ping\", b\"\", timeout=5)\nprint(response.data.decode())  # \"pong\"\n```\n\n## Ports\n\n- Client: `4222`\n- Monitoring: `8222`\n\n## Environment Variables\n\n```bash\nNATS_URL=nats://localhost:4222\nNATS_TOKEN=...                  # Auth token\n```\n"}]},{"slug":"hanzo-repl","displayName":"hanzo-repl","summary":"Interactive AI REPL for Hanzo — Claude Code-like terminal experience with IPython, TUI, voice, and MCP tool integration.","version":"1.0.0","sha256hash":"a4ee1f4204ddfbff6ba6e268d5f70d68f2affd99dc8d1ad3194eb2295e0fa35c","files":[{"path":"SKILL.md","size":1457,"sha256":"f39b926096ba6ee70ca81b0883985641c3d96e4ca9ed47a25a8ad97229dc056c","contentType":"text/markdown","content":"---\nname: hanzo-repl\ndescription: \"Interactive AI REPL for Hanzo — Claude Code-like terminal experience with IPython, TUI, voice, and MCP tool integration.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-repl\",\n              \"label\": \"Install Hanzo REPL (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo REPL — Interactive AI Terminal\n\n`pip install hanzo-repl`\n\nClaude Code-like interactive REPL with three interfaces, MCP tool access, and optional voice I/O.\n\n## Quick Start\n\n```bash\n# Basic REPL\nhanzo-repl\n\n# IPython-enhanced REPL\nhanzo-repl-ipython\n\n# Textual TUI (rich terminal UI)\nhanzo-repl-tui\n```\n\n## Options\n\n```bash\nhanzo-repl --mode=ipython    # IPython mode\nhanzo-repl --model=gpt-4     # Select LLM model\nhanzo-repl --debug            # Debug output\n```\n\n## Features\n\n- **Three interfaces**: Basic REPL, IPython, Textual TUI\n- **MCP tools**: Full access to 260+ hanzo-mcp tools\n- **Multi-language**: Execute code in Python, JavaScript, TypeScript, Bash\n- **Voice I/O**: Speech recognition and TTS (optional)\n\n## Voice Support\n\n```bash\npip install \"hanzo-repl[voice]\"\n\n# Enables speech-to-text input and text-to-speech output\nhanzo-repl --voice\n```\n\n## Python API\n\n```python\nfrom hanzo_repl import HanzoREPL\n\nrepl = HanzoREPL(model=\"gpt-4\")\nawait repl.start()\n```\n"}]},{"slug":"hanzo-s3","displayName":"hanzo-s3","summary":"Manage object storage with Hanzo S3. List, stat, delete, and presign objects in S3-compatible buckets via the hanzo-s3 Python SDK.","version":"1.0.0","sha256hash":"361687809f7be77ea18bf805bb4769a62dd030686d5e85c32ba2f0b4891c2505","files":[{"path":"SKILL.md","size":3709,"sha256":"6656ef534cf9670e63d7b58e0e8fdae76b62c8814940c5c6458e91ce67e02f89","contentType":"text/markdown","content":"---\nname: hanzo-s3\ndescription: \"Manage object storage with Hanzo S3. List, stat, delete, and presign objects in S3-compatible buckets via the hanzo-s3 Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-s3\",\n              \"label\": \"Install Hanzo S3 SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo S3 — Object Storage\n\n`pip install hanzo-s3`\n\nThin native adapter over `boto3` for [hanzoai/s3](https://github.com/hanzoai/s3)\n— a SeaweedFS fork (Apache-2.0). It exposes a small, stable surface: buckets,\nobject listing, stat, delete, and presigned reads. Anything beyond that surface\n(uploads, streaming reads, bulk delete) is plain `boto3` — see the\n`hanzo-storage` skill.\n\n## Quick Start\n\n```python\nfrom hanzo_s3 import S3Client\n\nclient = S3Client(\n    \"s3.hanzo.ai\",              # in-cluster: \"s3.hanzo.svc:9000\" with secure=False\n    access_key=\"YOUR-ACCESS-KEY\",\n    secret_key=\"YOUR-SECRET-KEY\",\n)\n```\n\nConstructor: `S3Client(endpoint, access_key, secret_key, secure=True, region=\"us-east-1\")`.\nA bare `host:port` endpoint gets an `http://`/`https://` scheme from `secure`.\nCredentials come from KMS — never store them in plaintext.\n\n## Bucket Operations\n\n```python\n# List all buckets -> list[Bucket(name, creation_date)]\nfor b in client.list_buckets():\n    print(b.name, b.creation_date)\n\n# Create bucket\nclient.make_bucket(\"my-bucket\")\n\n# Remove bucket (must be empty)\nclient.remove_bucket(\"my-bucket\")\n```\n\n## List Objects\n\n```python\n# Returns list[Object(object_name, size, last_modified, is_dir)], fully paginated.\nfor obj in client.list_objects(\"my-bucket\", prefix=\"data/\", recursive=True):\n    print(obj.object_name, obj.size, obj.last_modified)\n\n# Non-recursive: one level, with pseudo-directories flagged is_dir=True\nfor obj in client.list_objects(\"my-bucket\", prefix=\"data/\"):\n    print(obj.object_name, \"dir\" if obj.is_dir else obj.size)\n```\n\n## Stat & Delete\n\n```python\n# Stat(size, etag, content_type, last_modified)\nstat = client.stat_object(\"my-bucket\", \"remote/path.txt\")\nprint(stat.size, stat.content_type, stat.etag)\n\n# Delete a single object\nclient.remove_object(\"my-bucket\", \"remote/path.txt\")\n```\n\n## Presigned URLs\n\n```python\nfrom datetime import timedelta\n\nurl = client.presigned_get_object(\n    \"my-bucket\", \"file.pdf\", expires=timedelta(hours=1)\n)\n```\n\n## Errors\n\n```python\nfrom hanzo_s3 import S3Error   # botocore ClientError; aliased Error / S3Exception\n\ntry:\n    client.stat_object(\"my-bucket\", \"missing.txt\")\nexcept S3Error as err:\n    print(err.response[\"Error\"][\"Code\"])\n```\n\n## Exports\n\n| Name                                | Purpose                                                                                                   |\n| ----------------------------------- | --------------------------------------------------------------------------------------------------------- |\n| `S3Client` / `Client`               | `list_buckets`, `make_bucket`, `remove_bucket`, `list_objects`, `stat_object`, `remove_object`, `presigned_get_object` |\n| `Bucket` / `Object` / `Stat`        | Frozen dataclass result types                                                                              |\n| `S3Error` / `Error` / `S3Exception` | Errors (`botocore.exceptions.ClientError`)                                                                 |\n\n## Uploads and downloads\n\nThe SDK deliberately has no upload/download methods. Use `boto3` against the\nsame endpoint — `upload_file`, `download_file`, `put_object`, `get_object`,\n`delete_objects`. See the `hanzo-storage` skill.\n"}]},{"slug":"hanzo-search","displayName":"hanzo-search","summary":"Search indexed documentation and knowledge bases via Hanzo Search (Meilisearch). Supports fulltext search with faceted filtering and ranking. Use when a bot needs to search docs, knowledge bases, or indexed content, or when a user asks to find information across indexed sources.","version":"1.0.0","sha256hash":"21f2d83ba917af7436200e0f354e39a87f59214f9af724f81788d3d5632a0618","files":[{"path":"SKILL.md","size":4817,"sha256":"236ff321309570145b35dcf12a9469558ca12c6cddf849a967a7ffa3f622c280","contentType":"text/markdown","content":"---\nname: hanzo-search\ndescription: \"Search indexed documentation and knowledge bases via Hanzo Search (Meilisearch). Supports fulltext search with faceted filtering and ranking. Use when a bot needs to search docs, knowledge bases, or indexed content, or when a user asks to find information across indexed sources.\"\nmetadata:\n  { \"bot\": { \"requires\": { \"bins\": [\"python3\"] }, \"primaryEnv\": \"HANZO_API_KEY\", \"emoji\": \"🔍\" } }\n---\n\n# Hanzo Search -- Meilisearch Document Search API\n\nSearch indexed documentation and knowledge bases with fulltext retrieval and faceted filtering, powered by Meilisearch.\n\n## API Endpoints\n\nBase URL: `https://search.hanzo.ai`\n\n| Endpoint                     | Method | Purpose                      |\n| ---------------------------- | ------ | ---------------------------- |\n| `/indexes/{index}/search`    | POST   | Search documents in an index |\n| `/indexes`                   | GET    | List all indexes             |\n| `/indexes/{index}`           | GET    | Get index details            |\n| `/indexes/{index}/documents` | GET    | Browse documents in an index |\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header. Set `HANZO_SEARCH_KEY` or `HANZO_API_KEY`.\n\n```\nAuthorization: Bearer <token>\n```\n\n## Search Documents\n\n```bash\npython3 {baseDir}/scripts/search.py --query \"how to deploy\" --store my-docs\n```\n\n### Request Body (`/indexes/{index}/search`)\n\n```json\n{\n  \"q\": \"how to deploy to kubernetes\",\n  \"limit\": 10,\n  \"offset\": 0,\n  \"filter\": \"category = 'deployment'\"\n}\n```\n\n### Fields\n\n- `q` (required): Search query string\n- `limit` (optional): Max results (default 10, max 100)\n- `offset` (optional): Pagination offset (default 0)\n- `filter` (optional): Meilisearch filter expression (e.g. `\"category = 'deployment'\"`)\n- `sort` (optional): Array of sort rules (e.g. `[\"updated_at:desc\"]`)\n- `attributesToRetrieve` (optional): Array of attributes to return\n- `attributesToHighlight` (optional): Array of attributes to highlight\n\n### Response\n\n```json\n{\n  \"hits\": [\n    {\n      \"id\": \"doc-123\",\n      \"title\": \"Kubernetes Deployment Guide\",\n      \"url\": \"https://docs.example.com/deploy\",\n      \"content\": \"To deploy your application to Kubernetes...\",\n      \"category\": \"deployment\",\n      \"updated_at\": \"2026-01-15\"\n    }\n  ],\n  \"query\": \"how to deploy to kubernetes\",\n  \"processingTimeMs\": 12,\n  \"estimatedTotalHits\": 42,\n  \"limit\": 10,\n  \"offset\": 0\n}\n```\n\n## RAG Chat over Search Results\n\nRAG chat requires the Hanzo Cloud API layer on top of Meilisearch. The `chat.py` script calls the `/api/chat-docs` endpoint which retrieves documents via Meilisearch and generates an LLM-grounded response.\n\n```bash\npython3 {baseDir}/scripts/chat.py --query \"explain the deployment process\" --store my-docs\n```\n\n### Request Body (`/api/chat-docs`)\n\n```json\n{\n  \"query\": \"explain the deployment process step by step\",\n  \"store\": \"my-docs\",\n  \"mode\": \"hybrid\",\n  \"limit\": 5,\n  \"stream\": true\n}\n```\n\n### Fields\n\n- `query` (required): Chat question\n- `store` (required): Search store to ground answers in\n- `mode` (optional): Search mode for retrieval (`\"hybrid\"`, `\"fulltext\"`, `\"vector\"`)\n- `limit` (optional): Number of source documents to retrieve (default 5)\n- `stream` (optional): Stream response chunks (default true)\n- `model` (optional): LLM model for chat generation\n- `system_prompt` (optional): Override system prompt for the chat\n\n### Streaming Response\n\nEach line is a JSON chunk:\n\n```json\n{\"type\": \"source\", \"data\": {\"id\": \"doc-123\", \"title\": \"...\", \"url\": \"...\", \"score\": 0.95}}\n{\"type\": \"chunk\", \"data\": {\"text\": \"The deployment process\"}}\n{\"type\": \"chunk\", \"data\": {\"text\": \" involves three steps...\"}}\n{\"type\": \"done\", \"data\": {\"sources_count\": 5, \"tokens_used\": 342}}\n```\n\n## Scripts\n\n### `scripts/search.py`\n\nSearch documents from the command line via Hanzo Search (Meilisearch).\n\n```bash\npython3 {baseDir}/scripts/search.py \\\n  --query \"search terms\" \\\n  --store \"index-name\" \\\n  --limit 10 \\\n  --token \"$HANZO_API_KEY\"\n```\n\n### `scripts/chat.py`\n\nRAG chat over search results (requires Hanzo Cloud API layer).\n\n```bash\npython3 {baseDir}/scripts/chat.py \\\n  --query \"your question\" \\\n  --store \"store-name\" \\\n  --limit 5 \\\n  --token \"$HANZO_API_KEY\"\n```\n\n## Billing\n\nEach search query is billed per the Hanzo Search pricing tier. RAG chat queries include both the search cost and the LLM generation cost. Usage is tracked automatically through the bot gateway.\n\n## Environment Variables\n\n```bash\nHANZO_SEARCH_KEY=...                                  # Search API key (Meilisearch master key)\nHANZO_API_KEY=...                                  # Fallback API key\nHANZO_SEARCH_BASE_URL=https://search.hanzo.ai      # Override search API base URL\nHANZO_CHAT_BASE_URL=https://search.hanzo.ai        # Override RAG chat API base URL\n```\n"},{"path":"scripts/chat.py","size":6464,"sha256":"6d4cb2ce6b7c47b30e7f2e8dac259c6e8c3458184c3babb3e569e0d02ec7961b","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"RAG chat over search results via the Hanzo Cloud API.\n\nStreams a chat response grounded in documents from a search store.\nThis endpoint requires the Hanzo Cloud API layer (not native Meilisearch).\n\nUsage:\n    python3 chat.py --query \"your question\" --store \"store-name\" [options]\n\nOptions:\n    --query         Chat question (required)\n    --store         Search store name (required)\n    --mode          Search mode: hybrid, fulltext, vector (default: hybrid)\n    --limit         Number of source documents (default: 5)\n    --model         LLM model for generation (optional)\n    --system-prompt Override system prompt (optional)\n    --token         API token (default: $HANZO_API_KEY)\n    --base-url      API base URL (default: $HANZO_CHAT_BASE_URL or https://search.hanzo.ai)\n    --no-stream     Disable streaming, wait for full response\n    --format        Output format: text, json (default: text)\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\nimport urllib.request\nimport urllib.error\n\n\ndef build_request_body(args: argparse.Namespace) -> dict:\n    body: dict = {\n        \"query\": args.query,\n        \"store\": args.store,\n        \"mode\": args.mode,\n        \"limit\": args.limit,\n        \"stream\": not args.no_stream,\n    }\n    if args.model:\n        body[\"model\"] = args.model\n    if args.system_prompt:\n        body[\"system_prompt\"] = args.system_prompt\n    return body\n\n\ndef chat_streaming(args: argparse.Namespace) -> None:\n    base_url = (\n        args.base_url\n        or os.environ.get(\"HANZO_CHAT_BASE_URL\")\n        or os.environ.get(\"HANZO_SEARCH_BASE_URL\")\n        or \"https://search.hanzo.ai\"\n    ).rstrip(\"/\")\n    token = (args.token\n             or os.environ.get(\"HANZO_SEARCH_KEY\", \"\")\n             or os.environ.get(\"HANZO_API_KEY\", \"\"))\n    if not token:\n        print(\"Error: No API token. Set HANZO_SEARCH_KEY, HANZO_API_KEY, or use --token.\", file=sys.stderr)\n        sys.exit(1)\n\n    url = f\"{base_url}/api/chat-docs\"\n    body = build_request_body(args)\n    data = json.dumps(body).encode(\"utf-8\")\n\n    req = urllib.request.Request(\n        url,\n        data=data,\n        headers={\n            \"Content-Type\": \"application/json\",\n            \"Accept\": \"application/json\",\n            \"User-Agent\": \"hanzo-bot/1.0\",\n            \"Authorization\": f\"Bearer {token}\",\n        },\n        method=\"POST\",\n    )\n\n    try:\n        with urllib.request.urlopen(req, timeout=120) as resp:\n            if args.no_stream:\n                result = json.loads(resp.read().decode(\"utf-8\"))\n                if args.format == \"json\":\n                    print(json.dumps(result, indent=2))\n                else:\n                    print_non_streaming_result(result)\n                return\n\n            sources = []\n            full_text = []\n\n            for raw_line in resp:\n                line = raw_line.decode(\"utf-8\").strip()\n                if not line:\n                    continue\n                try:\n                    chunk = json.loads(line)\n                except json.JSONDecodeError:\n                    continue\n\n                chunk_type = chunk.get(\"type\", \"\")\n                chunk_data = chunk.get(\"data\", {})\n\n                if chunk_type == \"source\":\n                    sources.append(chunk_data)\n                    if args.format == \"text\":\n                        title = chunk_data.get(\"title\", \"\")\n                        score = chunk_data.get(\"score\", 0)\n                        sys.stderr.write(f\"  [source] {title} (score: {score:.3f})\\n\")\n                elif chunk_type == \"chunk\":\n                    text = chunk_data.get(\"text\", \"\")\n                    full_text.append(text)\n                    if args.format == \"text\":\n                        sys.stdout.write(text)\n                        sys.stdout.flush()\n                elif chunk_type == \"done\":\n                    if args.format == \"text\":\n                        sys.stdout.write(\"\\n\")\n                        sources_count = chunk_data.get(\"sources_count\", len(sources))\n                        tokens_used = chunk_data.get(\"tokens_used\", 0)\n                        sys.stderr.write(\n                            f\"\\n--- {sources_count} sources | {tokens_used} tokens ---\\n\"\n                        )\n\n            if args.format == \"json\":\n                print(json.dumps({\n                    \"answer\": \"\".join(full_text),\n                    \"sources\": sources,\n                }, indent=2))\n\n    except urllib.error.HTTPError as e:\n        error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n        print(f\"Error: HTTP {e.code} from Hanzo Chat API\", file=sys.stderr)\n        if error_body:\n            print(error_body[:500], file=sys.stderr)\n        sys.exit(1)\n    except urllib.error.URLError as e:\n        print(f\"Error: Failed to connect to Hanzo Chat API: {e.reason}\", file=sys.stderr)\n        sys.exit(1)\n\n\ndef print_non_streaming_result(result: dict) -> None:\n    answer = result.get(\"answer\", \"\")\n    sources = result.get(\"sources\", [])\n\n    if sources:\n        print(\"Sources:\")\n        for s in sources:\n            title = s.get(\"title\", \"Untitled\")\n            url = s.get(\"url\", \"\")\n            score = s.get(\"score\", 0)\n            print(f\"  - {title} (score: {score:.3f}){' ' + url if url else ''}\")\n        print()\n\n    print(answer)\n\n\ndef main() -> None:\n    parser = argparse.ArgumentParser(description=\"RAG chat via Hanzo Cloud API\")\n    parser.add_argument(\"--query\", required=True, help=\"Chat question\")\n    parser.add_argument(\"--store\", required=True, help=\"Search store name\")\n    parser.add_argument(\"--mode\", default=\"hybrid\", choices=[\"hybrid\", \"fulltext\", \"vector\"],\n                        help=\"Search mode (default: hybrid)\")\n    parser.add_argument(\"--limit\", type=int, default=5, help=\"Number of source documents (default: 5)\")\n    parser.add_argument(\"--model\", default=None, help=\"LLM model for generation\")\n    parser.add_argument(\"--system-prompt\", default=None, help=\"Override system prompt\")\n    parser.add_argument(\"--token\", default=None, help=\"API token\")\n    parser.add_argument(\"--base-url\", default=None, help=\"API base URL\")\n    parser.add_argument(\"--no-stream\", action=\"store_true\", help=\"Disable streaming\")\n    parser.add_argument(\"--format\", default=\"text\", choices=[\"text\", \"json\"],\n                        help=\"Output format (default: text)\")\n\n    args = parser.parse_args()\n    chat_streaming(args)\n\n\nif __name__ == \"__main__\":\n    main()\n"},{"path":"scripts/search.py","size":4567,"sha256":"d507ffedb1e539f57d19b083b165d8e8b9daa42e962d5d3267fb5fb7f096c340","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"Search indexed documents via the Hanzo Search API (Meilisearch).\n\nUsage:\n    python3 search.py --query \"search terms\" --store \"index-name\" [options]\n\nOptions:\n    --query     Search query string (required)\n    --store     Meilisearch index name (required)\n    --limit     Max results (default: 10)\n    --offset    Pagination offset (default: 0)\n    --filter    Meilisearch filter expression (optional, e.g. \"category = 'deployment'\")\n    --token     API token (default: $HANZO_SEARCH_KEY or $HANZO_API_KEY)\n    --base-url  API base URL (default: $HANZO_SEARCH_BASE_URL or https://search.hanzo.ai)\n    --format    Output format: text, json (default: text)\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\nimport urllib.request\nimport urllib.error\n\n\ndef build_request_body(args: argparse.Namespace) -> dict:\n    body: dict = {\n        \"q\": args.query,\n        \"limit\": args.limit,\n    }\n    if args.offset > 0:\n        body[\"offset\"] = args.offset\n    if args.filter:\n        body[\"filter\"] = args.filter\n    return body\n\n\ndef search(args: argparse.Namespace) -> dict:\n    base_url = (\n        args.base_url\n        or os.environ.get(\"HANZO_SEARCH_BASE_URL\")\n        or \"https://search.hanzo.ai\"\n    ).rstrip(\"/\")\n    token = (args.token\n             or os.environ.get(\"HANZO_SEARCH_KEY\", \"\")\n             or os.environ.get(\"HANZO_API_KEY\", \"\"))\n    if not token:\n        print(\"Error: No API token. Set HANZO_SEARCH_KEY, HANZO_API_KEY, or use --token.\", file=sys.stderr)\n        sys.exit(1)\n\n    url = f\"{base_url}/indexes/{args.store}/search\"\n    body = build_request_body(args)\n    data = json.dumps(body).encode(\"utf-8\")\n\n    req = urllib.request.Request(\n        url,\n        data=data,\n        headers={\n            \"Content-Type\": \"application/json\",\n            \"Accept\": \"application/json\",\n            \"Authorization\": f\"Bearer {token}\",\n            \"User-Agent\": \"hanzo-bot/1.0\",\n        },\n        method=\"POST\",\n    )\n\n    try:\n        with urllib.request.urlopen(req, timeout=30) as resp:\n            return json.loads(resp.read().decode(\"utf-8\"))\n    except urllib.error.HTTPError as e:\n        error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n        print(f\"Error: HTTP {e.code} from Meilisearch API\", file=sys.stderr)\n        if error_body:\n            print(error_body[:500], file=sys.stderr)\n        sys.exit(1)\n    except urllib.error.URLError as e:\n        print(f\"Error: Failed to connect to Meilisearch API: {e.reason}\", file=sys.stderr)\n        sys.exit(1)\n\n\ndef format_text(result: dict) -> str:\n    lines = []\n    hits = result.get(\"hits\", [])\n    total = result.get(\"estimatedTotalHits\", len(hits))\n    query = result.get(\"query\", \"\")\n    processing_ms = result.get(\"processingTimeMs\", 0)\n\n    lines.append(f\"Query: {query}\")\n    lines.append(f\"Found: {total} estimated total | Showing: {len(hits)} | Time: {processing_ms}ms\")\n    lines.append(\"\")\n\n    for i, hit in enumerate(hits, 1):\n        title = hit.get(\"title\", hit.get(\"_id\", \"Untitled\"))\n        url = hit.get(\"url\", \"\")\n        content = hit.get(\"content\", hit.get(\"text\", \"\"))\n        snippet = content[:200].replace(\"\\n\", \" \").strip()\n        if len(content) > 200:\n            snippet += \"...\"\n\n        lines.append(f\"{i}. {title}\")\n        if url:\n            lines.append(f\"   URL: {url}\")\n        if snippet:\n            lines.append(f\"   {snippet}\")\n        lines.append(\"\")\n\n    return \"\\n\".join(lines)\n\n\ndef main() -> None:\n    parser = argparse.ArgumentParser(description=\"Search documents via Meilisearch API\")\n    parser.add_argument(\"--query\", required=True, help=\"Search query string\")\n    parser.add_argument(\"--store\", required=True, help=\"Meilisearch index name\")\n    parser.add_argument(\"--limit\", type=int, default=10, help=\"Max results (default: 10)\")\n    parser.add_argument(\"--offset\", type=int, default=0, help=\"Pagination offset (default: 0)\")\n    parser.add_argument(\"--filter\", default=None,\n                        help=\"Meilisearch filter expression (e.g. \\\"category = 'docs'\\\")\")\n    parser.add_argument(\"--token\", default=None, help=\"API token (HANZO_SEARCH_KEY)\")\n    parser.add_argument(\"--base-url\", default=None, help=\"API base URL\")\n    parser.add_argument(\"--format\", default=\"text\", choices=[\"text\", \"json\"],\n                        help=\"Output format (default: text)\")\n\n    args = parser.parse_args()\n    result = search(args)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        print(format_text(result))\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"hanzo-storage","displayName":"hanzo-storage","summary":"S3-compatible object storage with Hanzo S3. Upload, download, and manage files, model artifacts, and datasets with erasure coding, encryption, and lifecycle rules.","version":"1.0.0","sha256hash":"c8177965c0f688b02f0c3f3d73118e990628bff53a19a06270ec16001363b625","files":[{"path":"SKILL.md","size":4976,"sha256":"60e5b9308928d4a43b0443f0f80f96810a293310883ae9c548718bf61c37de79","contentType":"text/markdown","content":"---\nname: hanzo-storage\ndescription: \"S3-compatible object storage with Hanzo S3. Upload, download, and manage files, model artifacts, and datasets with erasure coding, encryption, and lifecycle rules.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"boto3\",\n              \"label\": \"Install AWS SDK for Python (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Storage — Object Storage\n\n`pip install boto3`\n\nS3-compatible object storage for files, model artifacts, datasets, and media.\nServed by [hanzoai/s3](https://github.com/hanzoai/s3) — a SeaweedFS fork\n(Apache-2.0) — with erasure coding, server-side encryption, and lifecycle rules.\n\nThe wire protocol is standard S3, so any S3 SDK works: `boto3` (Python),\n`aws-sdk-go-v2` (Go), `@aws-sdk/client-s3` (JS/TS). Use those. For the small\nHanzo-branded Python surface see the `hanzo-s3` skill.\n\n## Quick Start\n\n```python\nimport os\n\nimport boto3\nfrom botocore.client import Config\nfrom botocore.exceptions import ClientError\n\ns3 = boto3.client(\n    \"s3\",\n    endpoint_url=os.environ[\"S3_ENDPOINT\"],\n    aws_access_key_id=os.environ[\"AWS_ACCESS_KEY_ID\"],\n    aws_secret_access_key=os.environ[\"AWS_SECRET_ACCESS_KEY\"],\n    config=Config(signature_version=\"s3v4\", s3={\"addressing_style\": \"path\"}),\n)\n\n# Create bucket if absent — create_bucket errors when it already exists\ntry:\n    s3.head_bucket(Bucket=\"models\")\nexcept ClientError:\n    s3.create_bucket(Bucket=\"models\")\n\n# Upload file\ns3.upload_file(\"/path/to/model.bin\", \"models\", \"llama3-8b.bin\")\n\n# Download file\ns3.download_file(\"models\", \"llama3-8b.bin\", \"/tmp/model.bin\")\n```\n\nPath-style addressing is required — a self-hosted endpoint has no per-bucket\nDNS. Signature v4 is the only version to use.\n\n## Upload Operations\n\n```python\nfrom io import BytesIO\n\n# Upload from bytes\ns3.put_object(Bucket=\"bucket\", Key=\"path/file.txt\", Body=b\"file content here\")\n\n# Upload from a stream\ns3.put_object(Bucket=\"bucket\", Key=\"path/file.txt\", Body=BytesIO(b\"file content here\"))\n\n# Upload with content type and user metadata.\n# boto3 prefixes Metadata keys with `x-amz-meta-` on the wire.\ns3.upload_file(\n    \"/local/image.png\", \"bucket\", \"image.png\",\n    ExtraArgs={\"ContentType\": \"image/png\", \"Metadata\": {\"project\": \"hanzo-bot\"}},\n)\n\n# Multipart is automatic in upload_file for large objects\ns3.upload_file(\"/path/to/50gb-model.bin\", \"models\", \"large-model.bin\")\n```\n\n## Download Operations\n\n```python\n# Download to file (multipart-aware)\ns3.download_file(\"bucket\", \"file.txt\", \"/local/file.txt\")\n\n# Stream download\nresponse = s3.get_object(Bucket=\"bucket\", Key=\"file.txt\")\ndata = response[\"Body\"].read()\nresponse[\"Body\"].close()\n```\n\n## List & Search\n\n```python\n# List objects (paginated — buckets can hold more than one page)\npaginator = s3.get_paginator(\"list_objects_v2\")\nfor page in paginator.paginate(Bucket=\"bucket\", Prefix=\"models/\"):\n    for obj in page.get(\"Contents\", []):\n        print(f\"{obj['Key']} ({obj['Size']} bytes)\")\n\n# List buckets\nfor bucket in s3.list_buckets()[\"Buckets\"]:\n    print(f\"{bucket['Name']} (created: {bucket['CreationDate']})\")\n```\n\nPass `Delimiter=\"/\"` to list one \"directory\" level instead of recursing;\nprefixes then come back under `page[\"CommonPrefixes\"]`.\n\n## Delete Operations\n\n```python\n# Delete single object\ns3.delete_object(Bucket=\"bucket\", Key=\"path/file.txt\")\n\n# Delete up to 1000 objects per call\ns3.delete_objects(\n    Bucket=\"bucket\",\n    Delete={\"Objects\": [{\"Key\": \"file1.txt\"}, {\"Key\": \"file2.txt\"}]},\n)\n```\n\n## Presigned URLs\n\n```python\n# Download URL (1 hour)\nurl = s3.generate_presigned_url(\n    \"get_object\", Params={\"Bucket\": \"bucket\", \"Key\": \"file.pdf\"}, ExpiresIn=3600\n)\n\n# Upload URL (1 hour)\nurl = s3.generate_presigned_url(\n    \"put_object\", Params={\"Bucket\": \"bucket\", \"Key\": \"upload.txt\"}, ExpiresIn=3600\n)\n```\n\n## CLI\n\n```bash\naws --endpoint-url http://localhost:9000 s3 ls\naws --endpoint-url http://localhost:9000 s3 cp ./model.bin s3://models/model.bin\n```\n\n## Run a local server\n\n```bash\ndocker run -p 9000:9000 \\\n  -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY \\\n  -v s3_data:/data \\\n  ghcr.io/hanzoai/s3:v1.0.14\n```\n\nThe image entrypoint is `s3`; the default command is\n`server -s3 -s3.port=9000 -dir=/data`. The server reads `AWS_ACCESS_KEY_ID` /\n`AWS_SECRET_ACCESS_KEY` from the environment and creates a matching admin\nidentity. Published for `linux/amd64` only.\n\n## Ports\n\n| Port | Service |\n| ---- | ------- |\n| 9000 | S3 API  |\n| 8888 | Filer   |\n| 9333 | Master  |\n| 8080 | Volume  |\n\nThere is no web console. Health: `GET :9000/healthz` (also `/readyz`, `/status`).\n\n## Environment Variables\n\n```bash\nS3_ENDPOINT=http://localhost:9000        # in-cluster: http://s3.hanzo.svc:9000\nAWS_ACCESS_KEY_ID=${S3_ACCESS_KEY}       # inject from KMS, never hardcode\nAWS_SECRET_ACCESS_KEY=${S3_SECRET_KEY}\nS3_BUCKET=default\n```\n"}]},{"slug":"hanzo-studio","displayName":"hanzo-studio","summary":"Visual AI engine for image, video, audio, and 3D generation. Node-based Stable Diffusion workflows with Flux, SDXL, SD3, ControlNet, and LoRA support.","version":"1.0.0","sha256hash":"cb330079e869a805c94358af3acdbd7dce204781415ccdfc86ce172cbe90f78d","files":[{"path":"SKILL.md","size":2379,"sha256":"741804ff0f48aa7cca0b722de765f57927c778b6ad261823ce784618643f1ad8","contentType":"text/markdown","content":"---\nname: hanzo-studio\ndescription: \"Visual AI engine for image, video, audio, and 3D generation. Node-based Stable Diffusion workflows with Flux, SDXL, SD3, ControlNet, and LoRA support.\"\nmetadata: { \"bot\": { \"requires\": { \"bins\": [\"curl\"] } } }\n---\n\n# Hanzo Studio — Visual AI Engine\n\nNode-based AI engine for image, video, audio, and 3D generation. Built on ComfyUI with support for Flux, SDXL, SD3, Stable Cascade, and more.\n\n## Quick Start\n\n```bash\n# Docker\ndocker run -p 8188:8188 ghcr.io/hanzoai/studio:latest --listen\n\n# With GPU\ndocker run --gpus all -p 8188:8188 ghcr.io/hanzoai/studio:latest --listen\n```\n\n## API Usage\n\n```python\nimport requests\nimport json\n\nSTUDIO_URL = \"http://localhost:8188\"\n\n# Queue a workflow\nworkflow = {\n    \"prompt\": {\n        \"3\": {\"class_type\": \"KSampler\", \"inputs\": {...}},\n        \"6\": {\"class_type\": \"CLIPTextEncode\", \"inputs\": {\"text\": \"a beautiful sunset\"}},\n        ...\n    }\n}\n\nresponse = requests.post(f\"{STUDIO_URL}/prompt\", json=workflow)\nprompt_id = response.json()[\"prompt_id\"]\n\n# Check status\nstatus = requests.get(f\"{STUDIO_URL}/history/{prompt_id}\").json()\n```\n\n## WebSocket (Real-time Progress)\n\n```python\nimport websocket\n\nws = websocket.create_connection(f\"ws://localhost:8188/ws\")\n# Receive progress updates as workflow executes\nwhile True:\n    result = ws.recv()\n    data = json.loads(result)\n    if data[\"type\"] == \"progress\":\n        print(f\"Progress: {data['data']['value']}/{data['data']['max']}\")\n    elif data[\"type\"] == \"executed\":\n        print(\"Done!\")\n        break\n```\n\n## Supported Models\n\n### Image Generation\n\n- **Flux** (Dev, Schnell) — Latest diffusion model\n- **SDXL** — Stable Diffusion XL\n- **SD3** — Stable Diffusion 3\n- **Stable Cascade** — Multi-stage generation\n- **Pixart**, **HunyuanDiT**, **AuraFlow**\n\n### Video Generation\n\n- **Stable Video Diffusion**\n- **Mochi**, **LTX-Video**\n- **Hunyuan Video**\n\n### Audio Generation\n\n- **Stable Audio**\n- **ACE Step**\n\n### 3D Generation\n\n- **Hunyuan3D 2.0**\n\n## Features\n\n- Node-based visual workflow editor\n- GPU auto-offloading (works with 1GB VRAM)\n- LoRA, ControlNet, T2I-Adapter support\n- Inpainting and outpainting\n- Area composition\n- Model merging\n- Async queue system\n- Workflow save/load/share\n\n## Port\n\n- API/WebUI: `8188`\n\n## Environment Variables\n\n```bash\nCOMFYUI_PORT=8188\nCOMFYUI_MODELS_PATH=/models     # Model storage path\n```\n"}]},{"slug":"hanzo-telemetry","displayName":"hanzo-telemetry","summary":"OpenTelemetry-based observability with distributed tracing, metrics, and logs. Instrument applications with OTLP, Prometheus, and Zipkin exporters.","version":"1.0.0","sha256hash":"44a1ba90e975bc9de42b16a1611dae388c14e369494847b7ea2257e10be7052b","files":[{"path":"SKILL.md","size":3265,"sha256":"fe5bc1257700970442f0b84ed4528039b336f51de1611d7edd66c27143ac8659","contentType":"text/markdown","content":"---\nname: hanzo-telemetry\ndescription: \"OpenTelemetry-based observability with distributed tracing, metrics, and logs. Instrument applications with OTLP, Prometheus, and Zipkin exporters.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"opentelemetry-api\",\n              \"label\": \"Install OpenTelemetry (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Telemetry — Observability\n\n`pip install opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp`\n\nOpenTelemetry-based distributed tracing, metrics, and logs for Hanzo services.\n\n## Quick Start\n\n```python\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter\n\n# Set up tracing\nprovider = TracerProvider()\nexporter = OTLPSpanExporter(endpoint=\"http://localhost:4317\")\nprovider.add_span_processor(BatchSpanProcessor(exporter))\ntrace.set_tracer_provider(provider)\n\ntracer = trace.get_tracer(\"my-service\")\n\n# Create spans\nwith tracer.start_as_current_span(\"process_request\") as span:\n    span.set_attribute(\"user.id\", \"123\")\n    result = do_work()\n    span.set_attribute(\"result.status\", \"success\")\n```\n\n## Metrics\n\n```python\nfrom opentelemetry import metrics\nfrom opentelemetry.sdk.metrics import MeterProvider\nfrom opentelemetry.exporter.otlp.proto.grpc.metric_exporter import OTLPMetricExporter\n\nprovider = MeterProvider()\nmetrics.set_meter_provider(provider)\n\nmeter = metrics.get_meter(\"my-service\")\n\n# Counter\nrequest_counter = meter.create_counter(\"requests_total\")\nrequest_counter.add(1, {\"method\": \"GET\", \"path\": \"/api/chat\"})\n\n# Histogram\nlatency = meter.create_histogram(\"request_duration_ms\")\nlatency.record(42.5, {\"method\": \"POST\"})\n\n# Gauge\nactive_connections = meter.create_up_down_counter(\"active_connections\")\nactive_connections.add(1)\n```\n\n## Automatic Instrumentation\n\n```python\n# Auto-instrument popular frameworks\npip install opentelemetry-instrumentation-fastapi\npip install opentelemetry-instrumentation-requests\npip install opentelemetry-instrumentation-redis\n\nfrom opentelemetry.instrumentation.fastapi import FastAPIInstrumentor\nFastAPIInstrumentor.instrument_app(app)\n```\n\n## Logging\n\n```python\nfrom opentelemetry._logs import set_logger_provider\nfrom opentelemetry.sdk._logs import LoggerProvider\nfrom opentelemetry.sdk._logs.export import BatchLogRecordProcessor\nfrom opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter\n\nprovider = LoggerProvider()\nprovider.add_log_record_processor(BatchLogRecordProcessor(OTLPLogExporter()))\nset_logger_provider(provider)\n```\n\n## Exporters\n\n| Exporter   | Protocol      | Port |\n| ---------- | ------------- | ---- |\n| OTLP gRPC  | gRPC          | 4317 |\n| OTLP HTTP  | HTTP/protobuf | 4318 |\n| Prometheus | HTTP scrape   | 8888 |\n| Zipkin     | HTTP          | 9411 |\n\n## Environment Variables\n\n```bash\nOTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318\nOTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf\nOTEL_SERVICE_NAME=my-service\nOTEL_RESOURCE_ATTRIBUTES=environment=production\n```\n"}]},{"slug":"hanzo-vector","displayName":"hanzo-vector","summary":"Direct vector similarity search via Hanzo Vector (Qdrant). Store embeddings with metadata, search by similarity, manage collections, and build RAG pipelines. Use when a bot needs to store or query vector embeddings, perform semantic similarity search, or manage vector collections.","version":"1.0.0","sha256hash":"32e9f3d910ff8ae4c9cb1a7ea0bdab244eb1d5f03a234281ab6cbaef0b7b4fb4","files":[{"path":"SKILL.md","size":5098,"sha256":"8e82c748b96e6138ca4272ad04cd4980de37d17e0c205f3e1bfe7d386344d2ab","contentType":"text/markdown","content":"---\nname: hanzo-vector\ndescription: \"Direct vector similarity search via Hanzo Vector (Qdrant). Store embeddings with metadata, search by similarity, manage collections, and build RAG pipelines. Use when a bot needs to store or query vector embeddings, perform semantic similarity search, or manage vector collections.\"\nmetadata:\n  { \"bot\": { \"requires\": { \"bins\": [\"python3\"] }, \"primaryEnv\": \"HANZO_API_KEY\", \"emoji\": \"🧮\" } }\n---\n\n# Hanzo Vector -- Similarity Search Engine\n\nDirect vector operations on Hanzo's managed Qdrant instance. Store embeddings, search by similarity, manage collections, and build RAG pipelines.\n\n## Endpoint\n\nQdrant REST API at `https://vector.hanzo.ai` (standard HTTPS port 443 via K8s ingress, or internal at `vector.hanzo.svc:6333`).\n\n## Authentication\n\nPass the API key as the `api-key` header or via the Qdrant client's `api_key` parameter.\n\n```\napi-key: <token>\n```\n\n## Collections\n\n### Create a Collection\n\n```bash\npython3 {baseDir}/scripts/vector.py collection create \\\n  --name documents \\\n  --dimension 384 \\\n  --distance cosine\n```\n\n### List Collections\n\n```bash\npython3 {baseDir}/scripts/vector.py collection list\n```\n\n### Delete a Collection\n\n```bash\npython3 {baseDir}/scripts/vector.py collection delete --name documents\n```\n\n### Collection Info\n\n```bash\npython3 {baseDir}/scripts/vector.py collection info --name documents\n```\n\n## Store Embeddings\n\n### Upsert Points\n\n```bash\npython3 {baseDir}/scripts/vector.py upsert \\\n  --collection documents \\\n  --input points.json\n```\n\nInput JSON format:\n\n```json\n{\n  \"points\": [\n    {\n      \"id\": 1,\n      \"vector\": [0.1, 0.2, 0.3, ...],\n      \"payload\": {\n        \"text\": \"Hello world\",\n        \"category\": \"greeting\",\n        \"source\": \"docs\"\n      }\n    }\n  ]\n}\n```\n\nOr pipe from stdin:\n\n```bash\necho '{\"points\": [...]}' | python3 {baseDir}/scripts/vector.py upsert \\\n  --collection documents \\\n  --input -\n```\n\n## Search by Similarity\n\n```bash\npython3 {baseDir}/scripts/vector.py search \\\n  --collection documents \\\n  --vector \"[0.1, 0.2, 0.3, ...]\" \\\n  --limit 10\n```\n\n### Search with Filters\n\n```bash\npython3 {baseDir}/scripts/vector.py search \\\n  --collection documents \\\n  --vector \"[0.1, 0.2, ...]\" \\\n  --filter '{\"must\": [{\"key\": \"category\", \"match\": {\"value\": \"tech\"}}]}' \\\n  --limit 10\n```\n\n### Filter Syntax\n\nQdrant filter conditions:\n\n```json\n{\n  \"must\": [\n    { \"key\": \"category\", \"match\": { \"value\": \"tech\" } },\n    { \"key\": \"year\", \"range\": { \"gte\": 2024 } }\n  ],\n  \"should\": [{ \"key\": \"author\", \"match\": { \"value\": \"hanzo\" } }],\n  \"must_not\": [{ \"key\": \"status\", \"match\": { \"value\": \"draft\" } }]\n}\n```\n\n## Scripts Reference\n\n### `scripts/vector.py`\n\nUnified CLI for all vector operations.\n\n#### Collection Management\n\n```bash\n# Create collection\npython3 {baseDir}/scripts/vector.py collection create \\\n  --name <name> --dimension <dim> --distance <cosine|euclid|dot>\n\n# List collections\npython3 {baseDir}/scripts/vector.py collection list\n\n# Get collection info\npython3 {baseDir}/scripts/vector.py collection info --name <name>\n\n# Delete collection\npython3 {baseDir}/scripts/vector.py collection delete --name <name>\n```\n\n#### Point Operations\n\n```bash\n# Upsert points from JSON file or stdin\npython3 {baseDir}/scripts/vector.py upsert \\\n  --collection <name> --input <file.json or ->\n\n# Search by vector\npython3 {baseDir}/scripts/vector.py search \\\n  --collection <name> --vector \"<json array>\" --limit 10\n\n# Search with filter\npython3 {baseDir}/scripts/vector.py search \\\n  --collection <name> --vector \"<json array>\" \\\n  --filter '<json filter>' --limit 10\n\n# Get points by ID\npython3 {baseDir}/scripts/vector.py get \\\n  --collection <name> --ids \"1,2,3\"\n\n# Delete points by ID\npython3 {baseDir}/scripts/vector.py delete \\\n  --collection <name> --ids \"1,2,3\"\n\n# Count points\npython3 {baseDir}/scripts/vector.py count --collection <name>\n```\n\n### Common Options\n\nAll commands accept:\n\n```\n--host       Qdrant host (default: $HANZO_VECTOR_HOST or https://vector.hanzo.ai)\n--port       Qdrant port (only for non-standard ports; HTTPS uses standard 443)\n--api-key    API key (default: $HANZO_API_KEY)\n--format     Output: text, json (default: text)\n```\n\n## RAG Pipeline Example\n\nGenerate embeddings with the Hanzo API, store in vector DB, and search:\n\n```python\nfrom hanzoai import Hanzo\n\n# 1. Generate embedding\nai = Hanzo(api_key=\"...\")\nembedding = ai.embeddings.create(\n    model=\"text-embedding-3-small\",\n    input=\"What is Hanzo MCP?\"\n).data[0].embedding\n\n# 2. Search vector DB\n# python3 {baseDir}/scripts/vector.py search \\\n#   --collection knowledge --vector \"<embedding>\" --limit 5\n```\n\n## Billing\n\nVector operations are billed per query (search) and per batch (upsert). Collection management operations are free. Usage is tracked automatically through the bot gateway.\n\n## Environment Variables\n\n```bash\nHANZO_API_KEY=...                             # API key for authentication\nHANZO_VECTOR_HOST=https://vector.hanzo.ai     # Qdrant host (standard HTTPS, no port needed)\nHANZO_VECTOR_PORT=                            # Only set for non-standard ports (e.g. 6333 for direct access)\n```\n"},{"path":"scripts/vector.py","size":14584,"sha256":"c8c5250bee4654fd6f906f73b57f824470b4f4210964608a73708e52d4aa5671","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"Hanzo Vector CLI -- manage collections and perform vector operations.\n\nUsage:\n    python3 vector.py <command> [options]\n\nCommands:\n    collection create  Create a new collection\n    collection list    List all collections\n    collection info    Get collection details\n    collection delete  Delete a collection\n    upsert             Upsert points into a collection\n    search             Search by vector similarity\n    get                Get points by ID\n    delete             Delete points by ID\n    count              Count points in a collection\n\nCommon Options:\n    --host       Qdrant host (default: $HANZO_VECTOR_HOST or https://vector.hanzo.ai)\n    --port       Qdrant port (only needed for non-standard ports; HTTPS uses 443 by default)\n    --api-key    API key (default: $HANZO_API_KEY)\n    --format     Output format: text, json (default: text)\n\"\"\"\n\nimport argparse\nimport json\nimport os\nimport sys\nimport urllib.request\nimport urllib.error\n\n\ndef resolve_base_url(args: argparse.Namespace) -> str:\n    host = args.host or os.environ.get(\"HANZO_VECTOR_HOST\", \"https://vector.hanzo.ai\")\n    port = args.port or os.environ.get(\"HANZO_VECTOR_PORT\", \"\")\n    host = host.rstrip(\"/\")\n\n    # Only append a port if explicitly provided. HTTPS uses standard port 443\n    # via K8s ingress, so no port suffix is needed by default.\n    hostname_part = host.split(\"//\")[-1]\n    has_explicit_port = \":\" in hostname_part\n    if port and not has_explicit_port:\n        host = f\"{host}:{port}\"\n\n    return host\n\n\ndef resolve_api_key(args: argparse.Namespace) -> str:\n    return args.api_key or os.environ.get(\"HANZO_API_KEY\", \"\")\n\n\ndef qdrant_request(base_url: str, api_key: str, method: str, path: str,\n                   body: dict | None = None, timeout: int = 30) -> dict:\n    url = f\"{base_url}{path}\"\n    data = json.dumps(body).encode(\"utf-8\") if body is not None else None\n\n    headers = {\n        \"Content-Type\": \"application/json\",\n        \"Accept\": \"application/json\",\n        \"User-Agent\": \"hanzo-bot/1.0\",\n    }\n    if api_key:\n        headers[\"api-key\"] = api_key\n\n    req = urllib.request.Request(\n        url,\n        data=data,\n        headers=headers,\n        method=method,\n    )\n\n    try:\n        with urllib.request.urlopen(req, timeout=timeout) as resp:\n            raw = resp.read().decode(\"utf-8\")\n            return json.loads(raw) if raw.strip() else {}\n    except urllib.error.HTTPError as e:\n        error_body = e.read().decode(\"utf-8\", errors=\"replace\") if e.fp else \"\"\n        print(f\"Error: HTTP {e.code} from Qdrant\", file=sys.stderr)\n        if error_body:\n            print(error_body[:500], file=sys.stderr)\n        sys.exit(1)\n    except urllib.error.URLError as e:\n        print(f\"Error: Failed to connect to Qdrant: {e.reason}\", file=sys.stderr)\n        sys.exit(1)\n\n\n# ---------------------------------------------------------------------------\n# Collection commands\n# ---------------------------------------------------------------------------\n\ndef cmd_collection_create(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    distance_map = {\n        \"cosine\": \"Cosine\",\n        \"euclid\": \"Euclid\",\n        \"dot\": \"Dot\",\n    }\n    distance = distance_map.get(args.distance.lower(), \"Cosine\")\n\n    body = {\n        \"vectors\": {\n            \"size\": args.dimension,\n            \"distance\": distance,\n        }\n    }\n    result = qdrant_request(base_url, api_key, \"PUT\",\n                            f\"/collections/{args.name}\", body)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        status = result.get(\"result\", result.get(\"status\", \"unknown\"))\n        print(f\"Collection '{args.name}' created (status: {status})\")\n\n\ndef cmd_collection_list(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    result = qdrant_request(base_url, api_key, \"GET\", \"/collections\")\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        collections = result.get(\"result\", {}).get(\"collections\", [])\n        if not collections:\n            print(\"No collections found.\")\n            return\n        print(f\"Collections ({len(collections)}):\")\n        for col in collections:\n            name = col.get(\"name\", \"unknown\")\n            print(f\"  - {name}\")\n\n\ndef cmd_collection_info(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    result = qdrant_request(base_url, api_key, \"GET\",\n                            f\"/collections/{args.name}\")\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        info = result.get(\"result\", {})\n        status = info.get(\"status\", \"unknown\")\n        points = info.get(\"points_count\", 0)\n        vectors = info.get(\"vectors_count\", 0)\n        segments = info.get(\"segments_count\", 0)\n        config = info.get(\"config\", {}).get(\"params\", {}).get(\"vectors\", {})\n        dim = config.get(\"size\", \"?\")\n        dist = config.get(\"distance\", \"?\")\n\n        print(f\"Collection: {args.name}\")\n        print(f\"Status: {status}\")\n        print(f\"Points: {points}\")\n        print(f\"Vectors: {vectors}\")\n        print(f\"Segments: {segments}\")\n        print(f\"Dimension: {dim}\")\n        print(f\"Distance: {dist}\")\n\n\ndef cmd_collection_delete(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    result = qdrant_request(base_url, api_key, \"DELETE\",\n                            f\"/collections/{args.name}\")\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        status = result.get(\"result\", result.get(\"status\", \"unknown\"))\n        print(f\"Collection '{args.name}' deleted (status: {status})\")\n\n\n# ---------------------------------------------------------------------------\n# Point commands\n# ---------------------------------------------------------------------------\n\ndef cmd_upsert(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    if args.input == \"-\":\n        raw = sys.stdin.read()\n    else:\n        with open(args.input) as f:\n            raw = f.read()\n\n    data = json.loads(raw)\n    points = data.get(\"points\", data if isinstance(data, list) else [data])\n\n    body = {\"points\": points}\n    result = qdrant_request(base_url, api_key, \"PUT\",\n                            f\"/collections/{args.collection}/points\",\n                            body, timeout=120)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        status = result.get(\"result\", {}).get(\"status\", result.get(\"status\", \"unknown\"))\n        print(f\"Upserted {len(points)} points into '{args.collection}' (status: {status})\")\n\n\ndef cmd_search(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    vector = json.loads(args.vector)\n    body: dict = {\n        \"vector\": vector,\n        \"limit\": args.limit,\n        \"with_payload\": True,\n    }\n    if args.filter:\n        body[\"filter\"] = json.loads(args.filter)\n    if args.score_threshold is not None:\n        body[\"score_threshold\"] = args.score_threshold\n\n    result = qdrant_request(base_url, api_key, \"POST\",\n                            f\"/collections/{args.collection}/points/search\",\n                            body)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        points = result.get(\"result\", [])\n        print(f\"Search results ({len(points)}):\")\n        for pt in points:\n            pt_id = pt.get(\"id\", \"?\")\n            score = pt.get(\"score\", 0)\n            payload = pt.get(\"payload\", {})\n            text = payload.get(\"text\", str(payload)[:100])\n            print(f\"  [{pt_id}] score={score:.4f} {text}\")\n\n\ndef cmd_get(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    ids = []\n    for raw_id in args.ids.split(\",\"):\n        raw_id = raw_id.strip()\n        if not raw_id:\n            continue\n        try:\n            ids.append(int(raw_id))\n        except ValueError:\n            ids.append(raw_id)\n\n    body = {\"ids\": ids, \"with_payload\": True, \"with_vector\": args.with_vector}\n    result = qdrant_request(base_url, api_key, \"POST\",\n                            f\"/collections/{args.collection}/points\",\n                            body)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        points = result.get(\"result\", [])\n        print(f\"Points ({len(points)}):\")\n        for pt in points:\n            pt_id = pt.get(\"id\", \"?\")\n            payload = pt.get(\"payload\", {})\n            print(f\"  [{pt_id}] {json.dumps(payload)[:200]}\")\n\n\ndef cmd_delete_points(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    ids = []\n    for raw_id in args.ids.split(\",\"):\n        raw_id = raw_id.strip()\n        if not raw_id:\n            continue\n        try:\n            ids.append(int(raw_id))\n        except ValueError:\n            ids.append(raw_id)\n\n    body = {\"points\": ids}\n    result = qdrant_request(base_url, api_key, \"POST\",\n                            f\"/collections/{args.collection}/points/delete\",\n                            body)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        status = result.get(\"result\", {}).get(\"status\", result.get(\"status\", \"unknown\"))\n        print(f\"Deleted {len(ids)} points from '{args.collection}' (status: {status})\")\n\n\ndef cmd_count(args: argparse.Namespace) -> None:\n    base_url = resolve_base_url(args)\n    api_key = resolve_api_key(args)\n\n    body: dict = {\"exact\": args.exact}\n    result = qdrant_request(base_url, api_key, \"POST\",\n                            f\"/collections/{args.collection}/points/count\",\n                            body)\n\n    if args.format == \"json\":\n        print(json.dumps(result, indent=2))\n    else:\n        count = result.get(\"result\", {}).get(\"count\", 0)\n        print(f\"Collection '{args.collection}': {count} points\")\n\n\n# ---------------------------------------------------------------------------\n# Argument parser\n# ---------------------------------------------------------------------------\n\ndef build_parser() -> argparse.ArgumentParser:\n    parser = argparse.ArgumentParser(description=\"Hanzo Vector CLI\")\n    parser.add_argument(\"--host\", default=None, help=\"Qdrant host\")\n    parser.add_argument(\"--port\", default=None,\n                        help=\"Qdrant port (only for non-standard ports; HTTPS uses 443)\")\n    parser.add_argument(\"--api-key\", default=None, help=\"API key\")\n    parser.add_argument(\"--format\", default=\"text\", choices=[\"text\", \"json\"],\n                        help=\"Output format\")\n\n    subparsers = parser.add_subparsers(dest=\"command\", required=True)\n\n    # --- collection ---\n    col_parser = subparsers.add_parser(\"collection\", help=\"Collection management\")\n    col_sub = col_parser.add_subparsers(dest=\"col_action\", required=True)\n\n    create_p = col_sub.add_parser(\"create\", help=\"Create a collection\")\n    create_p.add_argument(\"--name\", required=True, help=\"Collection name\")\n    create_p.add_argument(\"--dimension\", type=int, required=True, help=\"Vector dimension\")\n    create_p.add_argument(\"--distance\", default=\"cosine\",\n                          choices=[\"cosine\", \"euclid\", \"dot\"],\n                          help=\"Distance metric (default: cosine)\")\n\n    col_sub.add_parser(\"list\", help=\"List collections\")\n\n    info_p = col_sub.add_parser(\"info\", help=\"Collection info\")\n    info_p.add_argument(\"--name\", required=True, help=\"Collection name\")\n\n    del_col_p = col_sub.add_parser(\"delete\", help=\"Delete a collection\")\n    del_col_p.add_argument(\"--name\", required=True, help=\"Collection name\")\n\n    # --- upsert ---\n    upsert_p = subparsers.add_parser(\"upsert\", help=\"Upsert points\")\n    upsert_p.add_argument(\"--collection\", required=True, help=\"Collection name\")\n    upsert_p.add_argument(\"--input\", required=True, help=\"JSON file or - for stdin\")\n\n    # --- search ---\n    search_p = subparsers.add_parser(\"search\", help=\"Search by vector\")\n    search_p.add_argument(\"--collection\", required=True, help=\"Collection name\")\n    search_p.add_argument(\"--vector\", required=True, help=\"Query vector as JSON array\")\n    search_p.add_argument(\"--limit\", type=int, default=10, help=\"Max results\")\n    search_p.add_argument(\"--filter\", default=None, help=\"JSON filter\")\n    search_p.add_argument(\"--score-threshold\", type=float, default=None,\n                          help=\"Minimum score threshold\")\n\n    # --- get ---\n    get_p = subparsers.add_parser(\"get\", help=\"Get points by ID\")\n    get_p.add_argument(\"--collection\", required=True, help=\"Collection name\")\n    get_p.add_argument(\"--ids\", required=True, help=\"Comma-separated point IDs\")\n    get_p.add_argument(\"--with-vector\", action=\"store_true\",\n                       help=\"Include vectors in response\")\n\n    # --- delete ---\n    del_p = subparsers.add_parser(\"delete\", help=\"Delete points by ID\")\n    del_p.add_argument(\"--collection\", required=True, help=\"Collection name\")\n    del_p.add_argument(\"--ids\", required=True, help=\"Comma-separated point IDs\")\n\n    # --- count ---\n    count_p = subparsers.add_parser(\"count\", help=\"Count points\")\n    count_p.add_argument(\"--collection\", required=True, help=\"Collection name\")\n    count_p.add_argument(\"--exact\", action=\"store_true\",\n                         help=\"Exact count (slower)\")\n\n    return parser\n\n\ndef main() -> None:\n    parser = build_parser()\n    args = parser.parse_args()\n\n    api_key = resolve_api_key(args)\n    if not api_key:\n        print(\"Error: HANZO_API_KEY environment variable or --api-key flag is required.\", file=sys.stderr)\n        sys.exit(1)\n\n    command = args.command\n\n    if command == \"collection\":\n        action = args.col_action\n        if action == \"create\":\n            cmd_collection_create(args)\n        elif action == \"list\":\n            cmd_collection_list(args)\n        elif action == \"info\":\n            cmd_collection_info(args)\n        elif action == \"delete\":\n            cmd_collection_delete(args)\n    elif command == \"upsert\":\n        cmd_upsert(args)\n    elif command == \"search\":\n        cmd_search(args)\n    elif command == \"get\":\n        cmd_get(args)\n    elif command == \"delete\":\n        cmd_delete_points(args)\n    elif command == \"count\":\n        cmd_count(args)\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"hanzo-web3","displayName":"hanzo-web3","summary":"Enterprise blockchain SDK for multi-chain RPC, tokens, NFTs, smart wallets, and ERC-4337 account abstraction via the hanzo-web3 Python SDK.","version":"1.0.0","sha256hash":"d81bd2917a4eb1e9ab8fb9142fe3755d24de5ecc26f539789ae6feb5896c7762","files":[{"path":"SKILL.md","size":2601,"sha256":"b7fcfc92fbde25cb6ebfe59b5db0b85882e9de7254a02fd4931ba8c53ec8226c","contentType":"text/markdown","content":"---\nname: hanzo-web3\ndescription: \"Enterprise blockchain SDK for multi-chain RPC, tokens, NFTs, smart wallets, and ERC-4337 account abstraction via the hanzo-web3 Python SDK.\"\nmetadata:\n  {\n    \"bot\":\n      {\n        \"requires\": { \"bins\": [\"python3\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"pip\",\n              \"kind\": \"pip\",\n              \"package\": \"hanzo-web3\",\n              \"label\": \"Install Hanzo Web3 SDK (pip)\",\n            },\n          ],\n      },\n  }\n---\n\n# Hanzo Web3 — Enterprise Blockchain SDK\n\n`pip install hanzo-web3`\n\nMulti-chain blockchain operations: RPC calls, token/NFT management, smart wallets, ERC-4337 account abstraction.\n\n## Quick Start\n\n```python\nfrom hanzo_web3 import Client\n\nclient = Client(api_key=\"your-api-key\")\n\n# Get ETH balance\nbalance = await client.get_balance(\"0x...\")\nprint(f\"Balance: {balance} ETH\")\n```\n\n## Async Client\n\n```python\nfrom hanzo_web3 import AsyncClient\n\nclient = AsyncClient(\n    api_key=\"your-api-key\",\n    base_url=\"https://api.web3.hanzo.ai\",\n    timeout=30,\n    max_retries=3\n)\n\n# Token operations\ntokens = await client.tokens.list(chain=\"ethereum\")\nbalance = await client.tokens.balance(\"0x...\", token=\"USDC\")\n```\n\n## RPC Operations\n\n```python\nfrom hanzo_web3 import RPCClient\n\nrpc = RPCClient(api_key=\"...\")\n\n# Direct JSON-RPC calls\nblock = await rpc.call(\"eth_getBlockByNumber\", [\"latest\", True])\ntx = await rpc.call(\"eth_getTransactionReceipt\", [tx_hash])\n```\n\n## NFT Operations\n\n```python\n# List NFTs owned by address\nnfts = await client.nfts.list(owner=\"0x...\", chain=\"ethereum\")\n\n# Get NFT metadata\nmetadata = await client.nfts.metadata(contract=\"0x...\", token_id=42)\n```\n\n## Smart Wallets (ERC-4337)\n\n```python\n# Create smart wallet with account abstraction\nwallet = await client.wallets.create(\n    owner=\"0x...\",\n    chain=\"ethereum\"\n)\n\n# Execute gasless transaction\ntx = await wallet.execute(\n    to=\"0x...\",\n    value=0,\n    data=\"0x...\"\n)\n```\n\n## Webhooks\n\n```python\n# Register webhook for on-chain events\nwebhook = await client.webhooks.create(\n    url=\"https://my-app.com/hook\",\n    events=[\"transfer\", \"approval\"],\n    chain=\"ethereum\"\n)\n```\n\n## Supported Chains\n\nEthereum, Polygon, Arbitrum, Optimism, Base, and more EVM-compatible chains.\n\n## Configuration\n\n```python\nfrom hanzo_web3 import ClientConfig\n\nconfig = ClientConfig(\n    api_key=\"your-api-key\",\n    base_url=\"https://api.web3.hanzo.ai\",\n    timeout=30,\n    max_retries=3\n)\n```\n\n## Environment Variables\n\n```bash\nHANZO_WEB3_API_KEY=...                      # API key\nHANZO_WEB3_BASE_URL=https://api.web3.hanzo.ai  # API endpoint\n```\n"}]},{"slug":"harness-hacker","displayName":"harness-hacker","summary":"Self-modify the bot framework — fork, improve, test, and PR changes to any Hanzo component including your own source code, skills, extensions, and tools. Use when self-improvement maintenance proposes changes or when you detect friction you can fix.","version":"1.0.0","sha256hash":"28e42ae7d947c0c6f70c8397d30255f6cac6fc2e297a7356c7d20586713f7203","files":[{"path":"SKILL.md","size":8332,"sha256":"46ccfc9ba8dfe7ec0b971e4424dad81a94f344e0907eb04282a430a617cbc484","contentType":"text/markdown","content":"---\nname: harness-hacker\ndescription: Self-modify the bot framework — fork, improve, test, and PR changes to any Hanzo component including your own source code, skills, extensions, and tools. Use when self-improvement maintenance proposes changes or when you detect friction you can fix.\nmetadata: { \"bot\": { \"emoji\": \"🔧\", \"requires\": { \"bins\": [\"git\", \"pnpm\"] } } }\n---\n\n# Harness Hacker — Self-Modification Protocol\n\nYou have the ability to modify your own source code, create new tools, improve existing skills, and contribute changes back to any Hanzo repository. This is your most powerful capability.\n\n## When to Use\n\n1. **After a maintenance pass** proposes an approved change\n2. **During a Build It Now cycle** (Loop 1) when friction is detected\n3. **When the user explicitly asks** you to improve yourself\n4. **When you identify a pattern** that a specific tool would solve better than `bash`\n\n## Safety Rules\n\n1. **NEVER modify files in the live bot directory while the gateway is running** — use a worktree\n2. **ALWAYS test changes** before committing — run `pnpm test` or the relevant test suite\n3. **ALWAYS create a new branch** — never commit directly to `main`\n4. **ALWAYS explain what you're changing and why** before doing it\n5. **Keep changes small and focused** — one logical change per commit\n6. **Generated tools go in `extensions/self-improvement/tools/generated/`** — they have a 7-day TTL\n\n## Creating a New Extension\n\nExtensions are the primary way to add capabilities. Follow this exact pattern:\n\n```bash\n# 1. Create directory\nmkdir -p ~/botd/extensions/my-extension\n\n# 2. Create package.json\ncat > ~/botd/extensions/my-extension/package.json << 'EOF'\n{\n  \"name\": \"@hanzo/bot-my-extension\",\n  \"version\": \"2026.2.26\",\n  \"private\": true,\n  \"description\": \"What this extension does\",\n  \"type\": \"module\",\n  \"devDependencies\": { \"@hanzo/bot\": \"workspace:*\" },\n  \"peerDependencies\": { \"@hanzo/bot\": \">=2026.1.26\" },\n  \"bot\": { \"extensions\": [\"./index.ts\"] }\n}\nEOF\n\n# 3. Create index.ts\ncat > ~/botd/extensions/my-extension/index.ts << 'EOTS'\nimport type { AnyAgentTool, BotPluginApi } from \"bot/plugin-sdk\";\nimport { emptyPluginConfigSchema } from \"bot/plugin-sdk\";\n\nconst plugin = {\n  id: \"my-extension\",\n  name: \"My Extension\",\n  description: \"What it does\",\n  configSchema: emptyPluginConfigSchema(),\n  register(api: BotPluginApi) {\n    api.registerTool({\n      name: \"my_tool\",\n      description: \"What the tool does\",\n      parameters: {\n        type: \"object\",\n        properties: {\n          input: { type: \"string\", description: \"Input parameter\" }\n        },\n        required: [\"input\"]\n      },\n      async execute(params) {\n        // Implementation here\n        return { content: [{ type: \"text\", text: \"Result\" }] };\n      }\n    } as AnyAgentTool);\n  }\n};\n\nexport default plugin;\nEOTS\n```\n\n## Creating a New Skill\n\nSkills are documentation files that teach you patterns. They're simpler than extensions.\n\n```bash\n# 1. Create directory\nmkdir -p ~/botd/skills/my-skill\n\n# 2. Create SKILL.md\ncat > ~/botd/skills/my-skill/SKILL.md << 'EOF'\n---\nname: my-skill\ndescription: What this skill teaches\nmetadata:\n  { \"bot\": { \"emoji\": \"📚\" } }\n---\n\n# Skill Name\n\n## When to Use\nDescribe the trigger conditions.\n\n## Pattern\nShow the exact steps or commands.\n\n## Rules\n1. Rule one\n2. Rule two\nEOF\n```\n\n## Modifying Existing Extensions\n\nUse git worktrees for safety:\n\n```bash\n# 1. Create worktree from the bot repo\ncd ~/botd\ngit worktree add /tmp/bot-hack-$(date +%s) -b hack/my-improvement\n\n# 2. Make changes in the worktree\ncd /tmp/bot-hack-*\n# Edit files...\n\n# 3. Test\npnpm test\n\n# 4. Commit\ngit add -A\ngit commit -m \"feat(self-improvement): description of change\"\n\n# 5. Push and PR (if user approves)\ngit push -u origin hack/my-improvement\ngh pr create --title \"...\" --body \"...\"\n\n# 6. Cleanup\ncd ~/botd\ngit worktree remove /tmp/bot-hack-*\n```\n\n## Hacking Other Hanzo Components\n\nYou can improve ANY Hanzo repo, not just the bot. Common targets:\n\n| Component       | Path                     | What to Improve                                 |\n| --------------- | ------------------------ | ----------------------------------------------- |\n| **MCP**         | `~/work/hanzo/mcp`       | Add new tools, improve search                   |\n| **Agent SDK**   | `~/work/hanzo/agent`     | Network patterns, memory                        |\n| **LLM Gateway** | `~/work/hanzo/llm`       | Provider support, routing                       |\n| **Operative**   | `~/work/hanzo/operative` | Computer use tools                              |\n| **Universe**    | `~/work/hanzo/universe`  | K8s manifests, infra                            |\n| **Zoo Gym**     | `~/work/zoo/gym`         | GRPO pipeline, SemanticExtractor, BitDelta, DSO |\n| **Zoo Node**    | `~/work/zoo/node`        | Rust BitDelta/GRPO (hanzo-libs/hanzo-llm)       |\n| **Zen Models**  | `~/work/hanzo/zen`       | Model serving, quantization configs             |\n\nPattern for external repos:\n\n```bash\n# 1. Fork/branch\ncd ~/work/hanzo/mcp\ngit checkout -b hack/add-tool-xyz\n\n# 2. Make changes\n# 3. Test: pnpm test (or uv run pytest, cargo test, etc.)\n# 4. Commit and push\n# 5. Create PR\n```\n\n## Runtime Tool Creation (Build It Now — Loop 1)\n\nWhen you detect friction during a session, you have 5 minutes to build a fix:\n\n```bash\n# 1. Identify the pattern (from telemetry)\n#    e.g., \"bash fails 3x trying to parse JSON from package.json\"\n\n# 2. Create a generated tool (these have a 7-day TTL)\nmkdir -p ~/botd/extensions/self-improvement/tools/generated\n\ncat > ~/botd/extensions/self-improvement/tools/generated/read-package-field.ts << 'EOTS'\n// Generated tool: read_package_field\n// Created: $(date -Iseconds)\n// Trigger: bash failed 3x parsing JSON from package.json\n// TTL: 7 days (auto-pruned if unused)\n\nimport { readFileSync, existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport const tool = {\n  name: \"read_package_field\",\n  description: \"Read a specific field from package.json. Safer than bash + jq for JSON extraction.\",\n  parameters: {\n    type: \"object\",\n    properties: {\n      path: { type: \"string\", description: \"Directory containing package.json\" },\n      field: { type: \"string\", description: \"JSON field path (e.g., 'version', 'scripts.build')\" }\n    },\n    required: [\"field\"]\n  },\n  async execute(params: any) {\n    const dir = params.path || process.cwd();\n    const pkgPath = join(dir, \"package.json\");\n    if (!existsSync(pkgPath)) {\n      return { content: [{ type: \"text\", text: `No package.json found at ${dir}` }] };\n    }\n    const pkg = JSON.parse(readFileSync(pkgPath, \"utf-8\"));\n    const parts = (params.field as string).split(\".\");\n    let value: any = pkg;\n    for (const part of parts) {\n      value = value?.[part];\n    }\n    return {\n      content: [{ type: \"text\", text: value !== undefined ? JSON.stringify(value) : \"Field not found\" }]\n    };\n  }\n};\nEOTS\n\n# 3. Hot-reload (the self-improvement extension watches this directory)\n```\n\n## Continuous Improvement Workflow\n\n```\nFriction detected (Loop 1)\n    → Build specific tool (5 min time-box)\n    → Test against failure cases\n    → Hot-reload into session\n\nSession ends (Loop 3)\n    → 3-question reflection\n    → Structured telemetry summary\n\nEvery 5 sessions (Loop 4)\n    → Aggregate telemetry\n    → Generate proposals\n    → Human approves/rejects\n    → YOU implement approved changes using THIS skill\n```\n\n## Telemetry-Driven Decisions\n\nAlways check telemetry before building:\n\n```bash\n# View recent session telemetry\nls -la ~/.hanzo/bot/telemetry/\n\n# View last reflection\ncat ~/.hanzo/bot/self-improvement/reflections/$(ls -t ~/.hanzo/bot/self-improvement/reflections/ | head -1)\n\n# View maintenance proposals\ncat ~/.hanzo/bot/self-improvement/proposals/$(ls -t ~/.hanzo/bot/self-improvement/proposals/ | head -1)\n\n# View learned facts\ncat ~/.hanzo/bot/self-improvement/learned-facts.json\n```\n\n## Remember\n\n- **Specific tools beat generic flexibility.** `read_package_field` at 100% success > `bash + jq` at 84%.\n- **Telemetry is truth.** Don't guess — look at the numbers.\n- **No backlogs.** Build it now or let it live in telemetry for the maintenance pass.\n- **Test everything.** Show tests passing, don't just say \"done.\"\n- **Small changes compound.** 11 tools over 100 sessions is how bmo improved.\n"}]},{"slug":"healthcheck","displayName":"healthcheck","summary":"Host security hardening and risk-tolerance configuration for HanzoBot deployments. Use when a user asks for security audits, firewall/SSH/update hardening, risk posture, exposure review, HanzoBot cron scheduling for periodic checks, or version status checks on a machine running HanzoBot (laptop, workstation, Pi, VPS).","version":"1.0.0","sha256hash":"f41c4aa654f9a4ec131d4d0296382f0f4ec204592933b024e2178aad380042e6","files":[{"path":"SKILL.md","size":10559,"sha256":"c3f27c07ba18abd95662dc86152f9bd2b938cb4e18aab5a3728354247cbc7f81","contentType":"text/markdown","content":"---\nname: healthcheck\ndescription: Host security hardening and risk-tolerance configuration for HanzoBot deployments. Use when a user asks for security audits, firewall/SSH/update hardening, risk posture, exposure review, HanzoBot cron scheduling for periodic checks, or version status checks on a machine running HanzoBot (laptop, workstation, Pi, VPS).\n---\n\n# HanzoBot Host Hardening\n\n## Overview\n\nAssess and harden the host running HanzoBot, then align it to a user-defined risk tolerance without breaking access. Use HanzoBot security tooling as a first-class signal, but treat OS hardening as a separate, explicit set of steps.\n\n## Core rules\n\n- Recommend running this skill with a state-of-the-art model (e.g., Opus 4.5, GPT 5.2+). The agent should self-check the current model and suggest switching if below that level; do not block execution.\n- Require explicit approval before any state-changing action.\n- Do not modify remote access settings without confirming how the user connects.\n- Prefer reversible, staged changes with a rollback plan.\n- Never claim HanzoBot changes the host firewall, SSH, or OS updates; it does not.\n- If role/identity is unknown, provide recommendations only.\n- Formatting: every set of user choices must be numbered so the user can reply with a single digit.\n- System-level backups are recommended; try to verify status.\n\n## Workflow (follow in order)\n\n### 0) Model self-check (non-blocking)\n\nBefore starting, check the current model. If it is below state-of-the-art (e.g., Opus 4.5, GPT 5.2+), recommend switching. Do not block execution.\n\n### 1) Establish context (read-only)\n\nTry to infer 1–5 from the environment before asking. Prefer simple, non-technical questions if you need confirmation.\n\nDetermine (in order):\n\n1. OS and version (Linux/macOS/Windows), container vs host.\n2. Privilege level (root/admin vs user).\n3. Access path (local console, SSH, RDP, tailnet).\n4. Network exposure (public IP, reverse proxy, tunnel).\n5. HanzoBot gateway status and bind address.\n6. Backup system and status (e.g., Time Machine, system images, snapshots).\n7. Deployment context (local mac app, headless gateway host, remote gateway, container/CI).\n8. Disk encryption status (FileVault/LUKS/BitLocker).\n9. OS automatic security updates status.\n   Note: these are not blocking items, but are highly recommended, especially if HanzoBot can access sensitive data.\n10. Usage mode for a personal assistant with full access (local workstation vs headless/remote vs other).\n\nFirst ask once for permission to run read-only checks. If granted, run them by default and only ask questions for items you cannot infer or verify. Do not ask for information already visible in runtime or command output. Keep the permission ask as a single sentence, and list follow-up info needed as an unordered list (not numbered) unless you are presenting selectable choices.\n\nIf you must ask, use non-technical prompts:\n\n- “Are you using a Mac, Windows PC, or Linux?”\n- “Are you logged in directly on the machine, or connecting from another computer?”\n- “Is this machine reachable from the public internet, or only on your home/network?”\n- “Do you have backups enabled (e.g., Time Machine), and are they current?”\n- “Is disk encryption turned on (FileVault/BitLocker/LUKS)?”\n- “Are automatic security updates enabled?”\n- “How do you use this machine?”\n  Examples:\n  - Personal machine shared with the assistant\n  - Dedicated local machine for the assistant\n  - Dedicated remote machine/server accessed remotely (always on)\n  - Something else?\n\nOnly ask for the risk profile after system context is known.\n\nIf the user grants read-only permission, run the OS-appropriate checks by default. If not, offer them (numbered). Examples:\n\n1. OS: `uname -a`, `sw_vers`, `cat /etc/os-release`.\n2. Listening ports:\n   - Linux: `ss -ltnup` (or `ss -ltnp` if `-u` unsupported).\n   - macOS: `lsof -nP -iTCP -sTCP:LISTEN`.\n3. Firewall status:\n   - Linux: `ufw status`, `firewall-cmd --state`, `nft list ruleset` (pick what is installed).\n   - macOS: `/usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate` and `pfctl -s info`.\n4. Backups (macOS): `tmutil status` (if Time Machine is used).\n\n### 2) Run HanzoBot security audits (read-only)\n\nAs part of the default read-only checks, run `hanzo-bot security audit --deep`. Only offer alternatives if the user requests them:\n\n1. `hanzo-bot security audit` (faster, non-probing)\n2. `hanzo-bot security audit --json` (structured output)\n\nOffer to apply HanzoBot safe defaults (numbered):\n\n1. `hanzo-bot security audit --fix`\n\nBe explicit that `--fix` only tightens HanzoBot defaults and file permissions. It does not change host firewall, SSH, or OS update policies.\n\nIf browser control is enabled, recommend that 2FA be enabled on all important accounts, with hardware keys preferred and SMS not sufficient.\n\n### 3) Check HanzoBot version/update status (read-only)\n\nAs part of the default read-only checks, run `hanzo-bot update status`.\n\nReport the current channel and whether an update is available.\n\n### 4) Determine risk tolerance (after system context)\n\nAsk the user to pick or confirm a risk posture and any required open services/ports (numbered choices below).\nDo not pigeonhole into fixed profiles; if the user prefers, capture requirements instead of choosing a profile.\nOffer suggested profiles as optional defaults (numbered). Note that most users pick Home/Workstation Balanced:\n\n1. Home/Workstation Balanced (most common): firewall on with reasonable defaults, remote access restricted to LAN or tailnet.\n2. VPS Hardened: deny-by-default inbound firewall, minimal open ports, key-only SSH, no root login, automatic security updates.\n3. Developer Convenience: more local services allowed, explicit exposure warnings, still audited.\n4. Custom: user-defined constraints (services, exposure, update cadence, access methods).\n\n### 5) Produce a remediation plan\n\nProvide a plan that includes:\n\n- Target profile\n- Current posture summary\n- Gaps vs target\n- Step-by-step remediation with exact commands\n- Access-preservation strategy and rollback\n- Risks and potential lockout scenarios\n- Least-privilege notes (e.g., avoid admin usage, tighten ownership/permissions where safe)\n- Credential hygiene notes (location of HanzoBot creds, prefer disk encryption)\n\nAlways show the plan before any changes.\n\n### 6) Offer execution options\n\nOffer one of these choices (numbered so users can reply with a single digit):\n\n1. Do it for me (guided, step-by-step approvals)\n2. Show plan only\n3. Fix only critical issues\n4. Export commands for later\n\n### 7) Execute with confirmations\n\nFor each step:\n\n- Show the exact command\n- Explain impact and rollback\n- Confirm access will remain available\n- Stop on unexpected output and ask for guidance\n\n### 8) Verify and report\n\nRe-check:\n\n- Firewall status\n- Listening ports\n- Remote access still works\n- HanzoBot security audit (re-run)\n\nDeliver a final posture report and note any deferred items.\n\n## Required confirmations (always)\n\nRequire explicit approval for:\n\n- Firewall rule changes\n- Opening/closing ports\n- SSH/RDP configuration changes\n- Installing/removing packages\n- Enabling/disabling services\n- User/group modifications\n- Scheduling tasks or startup persistence\n- Update policy changes\n- Access to sensitive files or credentials\n\nIf unsure, ask.\n\n## Periodic checks\n\nAfter HanzoBot install or first hardening pass, run at least one baseline audit and version check:\n\n- `hanzo-bot security audit`\n- `hanzo-bot security audit --deep`\n- `hanzo-bot update status`\n\nOngoing monitoring is recommended. Use the HanzoBot cron tool/CLI to schedule periodic audits (Gateway scheduler). Do not create scheduled tasks without explicit approval. Store outputs in a user-approved location and avoid secrets in logs.\nWhen scheduling headless cron runs, include a note in the output that instructs the user to call `healthcheck` so issues can be fixed.\n\n### Required prompt to schedule (always)\n\nAfter any audit or hardening pass, explicitly offer scheduling and require a direct response. Use a short prompt like (numbered):\n\n1. “Do you want me to schedule periodic audits (e.g., daily/weekly) via `hanzo-bot cron add`?”\n\nIf the user says yes, ask for:\n\n- cadence (daily/weekly), preferred time window, and output location\n- whether to also schedule `hanzo-bot update status`\n\nUse a stable cron job name so updates are deterministic. Prefer exact names:\n\n- `healthcheck:security-audit`\n- `healthcheck:update-status`\n\nBefore creating, `hanzo-bot cron list` and match on exact `name`. If found, `hanzo-bot cron edit <id> ...`.\nIf not found, `hanzo-bot cron add --name <name> ...`.\n\nAlso offer a periodic version check so the user can decide when to update (numbered):\n\n1. `hanzo-bot update status` (preferred for source checkouts and channels)\n2. `npm view hanzo-bot version` (published npm version)\n\n## HanzoBot command accuracy\n\nUse only supported commands and flags:\n\n- `hanzo-bot security audit [--deep] [--fix] [--json]`\n- `hanzo-bot status` / `hanzo-bot status --deep`\n- `hanzo-bot health --json`\n- `hanzo-bot update status`\n- `hanzo-bot cron add|list|runs|run`\n\nDo not invent CLI flags or imply HanzoBot enforces host firewall/SSH policies.\n\n## Logging and audit trail\n\nRecord:\n\n- Gateway identity and role\n- Plan ID and timestamp\n- Approved steps and exact commands\n- Exit codes and files modified (best effort)\n\nRedact secrets. Never log tokens or full credential contents.\n\n## Memory writes (conditional)\n\nOnly write to memory files when the user explicitly opts in and the session is a private/local workspace\n(per `docs/reference/templates/AGENTS.md`). Otherwise provide a redacted, paste-ready summary the user can\ndecide to save elsewhere.\n\nFollow the durable-memory prompt format used by HanzoBot compaction:\n\n- Write lasting notes to `memory/YYYY-MM-DD.md`.\n\nAfter each audit/hardening run, if opted-in, append a short, dated summary to `memory/YYYY-MM-DD.md`\n(what was checked, key findings, actions taken, any scheduled cron jobs, key decisions,\nand all commands executed). Append-only: never overwrite existing entries.\nRedact sensitive host details (usernames, hostnames, IPs, serials, service names, tokens).\nIf there are durable preferences or decisions (risk posture, allowed ports, update policy),\nalso update `MEMORY.md` (long-term memory is optional and only used in private sessions).\n\nIf the session cannot write to the workspace, ask for permission or provide exact entries\nthe user can paste into the memory files.\n"}]},{"slug":"himalaya","displayName":"himalaya","summary":"CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).","version":"1.0.0","sha256hash":"8e14b3b35081b29a8fd59f5d1b67089e97e0ce511f1325f54f1cf42a01604401","files":[{"path":"SKILL.md","size":4617,"sha256":"335899bfe56d331b54d46dd22c194a87c1c9da7811a8b518770fd90ba2d0d780","contentType":"text/markdown","content":"---\nname: himalaya\ndescription: \"CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).\"\nhomepage: https://github.com/pimalaya/himalaya\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📧\",\n        \"requires\": { \"bins\": [\"himalaya\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"himalaya\",\n              \"bins\": [\"himalaya\"],\n              \"label\": \"Install Himalaya (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Himalaya Email CLI\n\nHimalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.\n\n## References\n\n- `references/configuration.md` (config file setup + IMAP/SMTP authentication)\n- `references/message-composition.md` (MML syntax for composing emails)\n\n## Prerequisites\n\n1. Himalaya CLI installed (`himalaya --version` to verify)\n2. A configuration file at `~/.config/himalaya/config.toml`\n3. IMAP/SMTP credentials configured (password stored securely)\n\n## Configuration Setup\n\nRun the interactive wizard to set up an account:\n\n```bash\nhimalaya account configure\n```\n\nOr create `~/.config/himalaya/config.toml` manually:\n\n```toml\n[accounts.personal]\nemail = \"[email protected]\"\ndisplay-name = \"Your Name\"\ndefault = true\n\nbackend.type = \"imap\"\nbackend.host = \"imap.example.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"[email protected]\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show email/imap\"  # or use keyring\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.example.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"[email protected]\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show email/smtp\"\n```\n\n## Common Operations\n\n### List Folders\n\n```bash\nhimalaya folder list\n```\n\n### List Emails\n\nList emails in INBOX (default):\n\n```bash\nhimalaya envelope list\n```\n\nList emails in a specific folder:\n\n```bash\nhimalaya envelope list --folder \"Sent\"\n```\n\nList with pagination:\n\n```bash\nhimalaya envelope list --page 1 --page-size 20\n```\n\n### Search Emails\n\n```bash\nhimalaya envelope list from [email protected] subject meeting\n```\n\n### Read an Email\n\nRead email by ID (shows plain text):\n\n```bash\nhimalaya message read 42\n```\n\nExport raw MIME:\n\n```bash\nhimalaya message export 42 --full\n```\n\n### Reply to an Email\n\nInteractive reply (opens $EDITOR):\n\n```bash\nhimalaya message reply 42\n```\n\nReply-all:\n\n```bash\nhimalaya message reply 42 --all\n```\n\n### Forward an Email\n\n```bash\nhimalaya message forward 42\n```\n\n### Write a New Email\n\nInteractive compose (opens $EDITOR):\n\n```bash\nhimalaya message write\n```\n\nSend directly using template:\n\n```bash\ncat << 'EOF' | himalaya template send\nFrom: [email protected]\nTo: [email protected]\nSubject: Test Message\n\nHello from Himalaya!\nEOF\n```\n\nOr with headers flag:\n\n```bash\nhimalaya message write -H \"To:[email protected]\" -H \"Subject:Test\" \"Message body here\"\n```\n\n### Move/Copy Emails\n\nMove to folder:\n\n```bash\nhimalaya message move 42 \"Archive\"\n```\n\nCopy to folder:\n\n```bash\nhimalaya message copy 42 \"Important\"\n```\n\n### Delete an Email\n\n```bash\nhimalaya message delete 42\n```\n\n### Manage Flags\n\nAdd flag:\n\n```bash\nhimalaya flag add 42 --flag seen\n```\n\nRemove flag:\n\n```bash\nhimalaya flag remove 42 --flag seen\n```\n\n## Multiple Accounts\n\nList accounts:\n\n```bash\nhimalaya account list\n```\n\nUse a specific account:\n\n```bash\nhimalaya --account work envelope list\n```\n\n## Attachments\n\nSave attachments from a message:\n\n```bash\nhimalaya attachment download 42\n```\n\nSave to specific directory:\n\n```bash\nhimalaya attachment download 42 --dir ~/Downloads\n```\n\n## Output Formats\n\nMost commands support `--output` for structured output:\n\n```bash\nhimalaya envelope list --output json\nhimalaya envelope list --output plain\n```\n\n## Debugging\n\nEnable debug logging:\n\n```bash\nRUST_LOG=debug himalaya envelope list\n```\n\nFull trace with backtrace:\n\n```bash\nRUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list\n```\n\n## Tips\n\n- Use `himalaya --help` or `himalaya <command> --help` for detailed usage.\n- Message IDs are relative to the current folder; re-list after folder changes.\n- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).\n- Store passwords securely using `pass`, system keyring, or a command that outputs the password.\n"},{"path":"references/configuration.md","size":4084,"sha256":"a1838b3f370abef2c6c45226115158aee095623701a4ffb48ea633bce14ccf0f","contentType":"text/markdown","content":"# Himalaya Configuration Reference\n\nConfiguration file location: `~/.config/himalaya/config.toml`\n\n## Minimal IMAP + SMTP Setup\n\n```toml\n[accounts.default]\nemail = \"[email protected]\"\ndisplay-name = \"Your Name\"\ndefault = true\n\n# IMAP backend for reading emails\nbackend.type = \"imap\"\nbackend.host = \"imap.example.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"[email protected]\"\nbackend.auth.type = \"password\"\nbackend.auth.raw = \"your-password\"\n\n# SMTP backend for sending emails\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.example.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"[email protected]\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.raw = \"your-password\"\n```\n\n## Password Options\n\n### Raw password (testing only, not recommended)\n\n```toml\nbackend.auth.raw = \"your-password\"\n```\n\n### Password from command (recommended)\n\n```toml\nbackend.auth.cmd = \"pass show email/imap\"\n# backend.auth.cmd = \"security find-generic-password -a [email protected] -s imap -w\"\n```\n\n### System keyring (requires keyring feature)\n\n```toml\nbackend.auth.keyring = \"imap-example\"\n```\n\nThen run `himalaya account configure <account>` to store the password.\n\n## Gmail Configuration\n\n```toml\n[accounts.gmail]\nemail = \"[email protected]\"\ndisplay-name = \"Your Name\"\ndefault = true\n\nbackend.type = \"imap\"\nbackend.host = \"imap.gmail.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"[email protected]\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show google/app-password\"\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.gmail.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"[email protected]\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show google/app-password\"\n```\n\n**Note:** Gmail requires an App Password if 2FA is enabled.\n\n## iCloud Configuration\n\n```toml\n[accounts.icloud]\nemail = \"[email protected]\"\ndisplay-name = \"Your Name\"\n\nbackend.type = \"imap\"\nbackend.host = \"imap.mail.me.com\"\nbackend.port = 993\nbackend.encryption.type = \"tls\"\nbackend.login = \"[email protected]\"\nbackend.auth.type = \"password\"\nbackend.auth.cmd = \"pass show icloud/app-password\"\n\nmessage.send.backend.type = \"smtp\"\nmessage.send.backend.host = \"smtp.mail.me.com\"\nmessage.send.backend.port = 587\nmessage.send.backend.encryption.type = \"start-tls\"\nmessage.send.backend.login = \"[email protected]\"\nmessage.send.backend.auth.type = \"password\"\nmessage.send.backend.auth.cmd = \"pass show icloud/app-password\"\n```\n\n**Note:** Generate an app-specific password at appleid.apple.com\n\n## Folder Aliases\n\nMap custom folder names:\n\n```toml\n[accounts.default.folder.alias]\ninbox = \"INBOX\"\nsent = \"Sent\"\ndrafts = \"Drafts\"\ntrash = \"Trash\"\n```\n\n## Multiple Accounts\n\n```toml\n[accounts.personal]\nemail = \"[email protected]\"\ndefault = true\n# ... backend config ...\n\n[accounts.work]\nemail = \"[email protected]\"\n# ... backend config ...\n```\n\nSwitch accounts with `--account`:\n\n```bash\nhimalaya --account work envelope list\n```\n\n## Notmuch Backend (local mail)\n\n```toml\n[accounts.local]\nemail = \"[email protected]\"\n\nbackend.type = \"notmuch\"\nbackend.db-path = \"~/.mail/.notmuch\"\n```\n\n## OAuth2 Authentication (for providers that support it)\n\n```toml\nbackend.auth.type = \"oauth2\"\nbackend.auth.client-id = \"your-client-id\"\nbackend.auth.client-secret.cmd = \"pass show oauth/client-secret\"\nbackend.auth.access-token.cmd = \"pass show oauth/access-token\"\nbackend.auth.refresh-token.cmd = \"pass show oauth/refresh-token\"\nbackend.auth.auth-url = \"https://provider.com/oauth/authorize\"\nbackend.auth.token-url = \"https://provider.com/oauth/token\"\n```\n\n## Additional Options\n\n### Signature\n\n```toml\n[accounts.default]\nsignature = \"Best regards,\\nYour Name\"\nsignature-delim = \"-- \\n\"\n```\n\n### Downloads directory\n\n```toml\n[accounts.default]\ndownloads-dir = \"~/Downloads/himalaya\"\n```\n\n### Editor for composing\n\nSet via environment variable:\n\n```bash\nexport EDITOR=\"vim\"\n```\n"},{"path":"references/message-composition.md","size":3799,"sha256":"84d889972f5f4243d891405b83e67bddc7e835b2c4e434efd77fdc6bca9fe307","contentType":"text/markdown","content":"# Message Composition with MML (MIME Meta Language)\n\nHimalaya uses MML for composing emails. MML is a simple XML-based syntax that compiles to MIME messages.\n\n## Basic Message Structure\n\nAn email message is a list of **headers** followed by a **body**, separated by a blank line:\n\n```\nFrom: [email protected]\nTo: [email protected]\nSubject: Hello World\n\nThis is the message body.\n```\n\n## Headers\n\nCommon headers:\n\n- `From`: Sender address\n- `To`: Primary recipient(s)\n- `Cc`: Carbon copy recipients\n- `Bcc`: Blind carbon copy recipients\n- `Subject`: Message subject\n- `Reply-To`: Address for replies (if different from From)\n- `In-Reply-To`: Message ID being replied to\n\n### Address Formats\n\n```\nTo: [email protected]\nTo: John Doe <[email protected]>\nTo: \"John Doe\" <[email protected]>\nTo: [email protected], [email protected], \"Jane\" <[email protected]>\n```\n\n## Plain Text Body\n\nSimple plain text email:\n\n```\nFrom: alice@localhost\nTo: bob@localhost\nSubject: Plain Text Example\n\nHello, this is a plain text email.\nNo special formatting needed.\n\nBest,\nAlice\n```\n\n## MML for Rich Emails\n\n### Multipart Messages\n\nAlternative text/html parts:\n\n```\nFrom: alice@localhost\nTo: bob@localhost\nSubject: Multipart Example\n\n<#multipart type=alternative>\nThis is the plain text version.\n<#part type=text/html>\n<html><body><h1>This is the HTML version</h1></body></html>\n<#/multipart>\n```\n\n### Attachments\n\nAttach a file:\n\n```\nFrom: alice@localhost\nTo: bob@localhost\nSubject: With Attachment\n\nHere is the document you requested.\n\n<#part filename=/path/to/document.pdf><#/part>\n```\n\nAttachment with custom name:\n\n```\n<#part filename=/path/to/file.pdf name=report.pdf><#/part>\n```\n\nMultiple attachments:\n\n```\n<#part filename=/path/to/doc1.pdf><#/part>\n<#part filename=/path/to/doc2.pdf><#/part>\n```\n\n### Inline Images\n\nEmbed an image inline:\n\n```\nFrom: alice@localhost\nTo: bob@localhost\nSubject: Inline Image\n\n<#multipart type=related>\n<#part type=text/html>\n<html><body>\n<p>Check out this image:</p>\n<img src=\"cid:image1\">\n</body></html>\n<#part disposition=inline id=image1 filename=/path/to/image.png><#/part>\n<#/multipart>\n```\n\n### Mixed Content (Text + Attachments)\n\n```\nFrom: alice@localhost\nTo: bob@localhost\nSubject: Mixed Content\n\n<#multipart type=mixed>\n<#part type=text/plain>\nPlease find the attached files.\n\nBest,\nAlice\n<#part filename=/path/to/file1.pdf><#/part>\n<#part filename=/path/to/file2.zip><#/part>\n<#/multipart>\n```\n\n## MML Tag Reference\n\n### `<#multipart>`\n\nGroups multiple parts together.\n\n- `type=alternative`: Different representations of same content\n- `type=mixed`: Independent parts (text + attachments)\n- `type=related`: Parts that reference each other (HTML + images)\n\n### `<#part>`\n\nDefines a message part.\n\n- `type=<mime-type>`: Content type (e.g., `text/html`, `application/pdf`)\n- `filename=<path>`: File to attach\n- `name=<name>`: Display name for attachment\n- `disposition=inline`: Display inline instead of as attachment\n- `id=<cid>`: Content ID for referencing in HTML\n\n## Composing from CLI\n\n### Interactive compose\n\nOpens your `$EDITOR`:\n\n```bash\nhimalaya message write\n```\n\n### Reply (opens editor with quoted message)\n\n```bash\nhimalaya message reply 42\nhimalaya message reply 42 --all  # reply-all\n```\n\n### Forward\n\n```bash\nhimalaya message forward 42\n```\n\n### Send from stdin\n\n```bash\ncat message.txt | himalaya template send\n```\n\n### Prefill headers from CLI\n\n```bash\nhimalaya message write \\\n  -H \"To:[email protected]\" \\\n  -H \"Subject:Quick Message\" \\\n  \"Message body here\"\n```\n\n## Tips\n\n- The editor opens with a template; fill in headers and body.\n- Save and exit the editor to send; exit without saving to cancel.\n- MML parts are compiled to proper MIME when sending.\n- Use `himalaya message export --full` to inspect the raw MIME structure of received emails.\n"}]},{"slug":"imsg","displayName":"imsg","summary":"iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.","version":"1.0.0","sha256hash":"ba64247e5d545df583188b4c1ad85e423aa0a4cf2e6fecea8ccc1170456706cd","files":[{"path":"SKILL.md","size":2977,"sha256":"9fb04e520ae8b63630de590a044c898e949f3d0b3d1a8b92a1ac1409ad109680","contentType":"text/markdown","content":"---\nname: imsg\ndescription: iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app.\nhomepage: https://imsg.to\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📨\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"imsg\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/imsg\",\n              \"bins\": [\"imsg\"],\n              \"label\": \"Install imsg (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# imsg\n\nUse `imsg` to read and send iMessage/SMS via macOS Messages.app.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- User explicitly asks to send iMessage or SMS\n- Reading iMessage conversation history\n- Checking recent Messages.app chats\n- Sending to phone numbers or Apple IDs\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Telegram messages → use `message` tool with `channel:telegram`\n- Signal messages → use Signal channel if configured\n- WhatsApp messages → use WhatsApp channel if configured\n- Discord messages → use `message` tool with `channel:discord`\n- Slack messages → use `slack` skill\n- Group chat management (adding/removing members) → not supported\n- Bulk/mass messaging → always confirm with user first\n- Replying in current conversation → just reply normally (Clawdbot routes automatically)\n\n## Requirements\n\n- macOS with Messages.app signed in\n- Full Disk Access for terminal\n- Automation permission for Messages.app (for sending)\n\n## Common Commands\n\n### List Chats\n\n```bash\nimsg chats --limit 10 --json\n```\n\n### View History\n\n```bash\n# By chat ID\nimsg history --chat-id 1 --limit 20 --json\n\n# With attachments info\nimsg history --chat-id 1 --limit 20 --attachments --json\n```\n\n### Watch for New Messages\n\n```bash\nimsg watch --chat-id 1 --attachments\n```\n\n### Send Messages\n\n```bash\n# Text only\nimsg send --to \"+14155551212\" --text \"Hello!\"\n\n# With attachment\nimsg send --to \"+14155551212\" --text \"Check this out\" --file /path/to/image.jpg\n\n# Specify service\nimsg send --to \"+14155551212\" --text \"Hi\" --service imessage\nimsg send --to \"+14155551212\" --text \"Hi\" --service sms\n```\n\n## Service Options\n\n- `--service imessage` — Force iMessage (requires recipient has iMessage)\n- `--service sms` — Force SMS (green bubble)\n- `--service auto` — Let Messages.app decide (default)\n\n## Safety Rules\n\n1. **Always confirm recipient and message content** before sending\n2. **Never send to unknown numbers** without explicit user approval\n3. **Be careful with attachments** — confirm file path exists\n4. **Rate limit yourself** — don't spam\n\n## Example Workflow\n\nUser: \"Text mom that I'll be late\"\n\n```bash\n# 1. Find mom's chat\nimsg chats --limit 20 --json | jq '.[] | select(.displayName | contains(\"Mom\"))'\n\n# 2. Confirm with user\n# \"Found Mom at +1555123456. Send 'I'll be late' via iMessage?\"\n\n# 3. Send after confirmation\nimsg send --to \"+1555123456\" --text \"I'll be late\"\n```\n"}]},{"slug":"mcporter","displayName":"mcporter","summary":"Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.","version":"1.0.0","sha256hash":"46a84ee91c991e6db4003eca5a6499fdb7875ca43799a9332d01dc454f20657d","files":[{"path":"SKILL.md","size":1675,"sha256":"6c06d381b90827766c0dd99c29b22cabb58ee5012069f0eb20d171f4da4c2a32","contentType":"text/markdown","content":"---\nname: mcporter\ndescription: Use the mcporter CLI to list, configure, auth, and call MCP servers/tools directly (HTTP or stdio), including ad-hoc servers, config edits, and CLI/type generation.\nhomepage: http://mcporter.dev\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📦\",\n        \"requires\": { \"bins\": [\"mcporter\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"node\",\n              \"kind\": \"node\",\n              \"package\": \"mcporter\",\n              \"bins\": [\"mcporter\"],\n              \"label\": \"Install mcporter (node)\",\n            },\n          ],\n      },\n  }\n---\n\n# mcporter\n\nUse `mcporter` to work with MCP servers directly.\n\nQuick start\n\n- `mcporter list`\n- `mcporter list <server> --schema`\n- `mcporter call <server.tool> key=value`\n\nCall tools\n\n- Selector: `mcporter call linear.list_issues team=ENG limit:5`\n- Function syntax: `mcporter call \"linear.create_issue(title: \\\"Bug\\\")\"`\n- Full URL: `mcporter call https://api.example.com/mcp.fetch url:https://example.com`\n- Stdio: `mcporter call --stdio \"bun run ./server.ts\" scrape url=https://example.com`\n- JSON payload: `mcporter call <server.tool> --args '{\"limit\":5}'`\n\nAuth + config\n\n- OAuth: `mcporter auth <server | url> [--reset]`\n- Config: `mcporter config list|get|add|remove|import|login|logout`\n\nDaemon\n\n- `mcporter daemon start|status|stop|restart`\n\nCodegen\n\n- CLI: `mcporter generate-cli --server <name>` or `--command <url>`\n- Inspect: `mcporter inspect-cli <path> [--json]`\n- TS: `mcporter emit-ts <server> --mode client|types`\n\nNotes\n\n- Config default: `./config/mcporter.json` (override with `--config`).\n- Prefer `--output json` for machine-readable results.\n"}]},{"slug":"model-usage","displayName":"model-usage","summary":"Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.","version":"1.0.0","sha256hash":"14f895e381373004e4e644ce591c7ddd1a3d640986839004419099d426b0f69c","files":[{"path":"SKILL.md","size":2254,"sha256":"78fa1c198642c6ceb3e8eb9bf67b9a889eb3b5c5611691eebe5406cab755a1a8","contentType":"text/markdown","content":"---\nname: model-usage\ndescription: Use CodexBar CLI local cost usage to summarize per-model usage for Codex or Claude, including the current (most recent) model or a full model breakdown. Trigger when asked for model-level usage/cost data from codexbar, or when you need a scriptable per-model summary from codexbar cost JSON.\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📊\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"codexbar\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew-cask\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/codexbar\",\n              \"bins\": [\"codexbar\"],\n              \"label\": \"Install CodexBar (brew cask)\",\n            },\n          ],\n      },\n  }\n---\n\n# Model usage\n\n## Overview\n\nGet per-model usage cost from CodexBar's local cost logs. Supports \"current model\" (most recent daily entry) or \"all models\" summaries for Codex or Claude.\n\nTODO: add Linux CLI support guidance once CodexBar CLI install path is documented for Linux.\n\n## Quick start\n\n1. Fetch cost JSON via CodexBar CLI or pass a JSON file.\n2. Use the bundled script to summarize by model.\n\n```bash\npython {baseDir}/scripts/model_usage.py --provider codex --mode current\npython {baseDir}/scripts/model_usage.py --provider codex --mode all\npython {baseDir}/scripts/model_usage.py --provider claude --mode all --format json --pretty\n```\n\n## Current model logic\n\n- Uses the most recent daily row with `modelBreakdowns`.\n- Picks the model with the highest cost in that row.\n- Falls back to the last entry in `modelsUsed` when breakdowns are missing.\n- Override with `--model <name>` when you need a specific model.\n\n## Inputs\n\n- Default: runs `codexbar cost --format json --provider <codex|claude>`.\n- File or stdin:\n\n```bash\ncodexbar cost --provider codex --format json > /tmp/cost.json\npython {baseDir}/scripts/model_usage.py --input /tmp/cost.json --mode all\ncat /tmp/cost.json | python {baseDir}/scripts/model_usage.py --input - --mode current\n```\n\n## Output\n\n- Text (default) or JSON (`--format json --pretty`).\n- Values are cost-only per model; tokens are not split by model in CodexBar output.\n\n## References\n\n- Read `references/codexbar-cli.md` for CLI flags and cost JSON fields.\n"},{"path":"references/codexbar-cli.md","size":1120,"sha256":"276cc2d8ff141082fb89c8ec136b1e5cc86d169fc79cc07d0211ef1807e37735","contentType":"text/markdown","content":"# CodexBar CLI quick ref (usage + cost)\n\n## Install\n\n- App: Preferences -> Advanced -> Install CLI\n- Repo: ./bin/install-codexbar-cli.sh\n\n## Commands\n\n- Usage snapshot (web/cli sources):\n  - codexbar usage --format json --pretty\n  - codexbar --provider all --format json\n- Local cost usage (Codex + Claude only):\n  - codexbar cost --format json --pretty\n  - codexbar cost --provider codex|claude --format json\n\n## Cost JSON fields\n\nThe payload is an array (one per provider).\n\n- provider, source, updatedAt\n- sessionTokens, sessionCostUSD\n- last30DaysTokens, last30DaysCostUSD\n- daily[]: date, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, totalCost, modelsUsed, modelBreakdowns[]\n- modelBreakdowns[]: modelName, cost\n- totals: totalInputTokens, totalOutputTokens, cacheReadTokens, cacheCreationTokens, totalTokens, totalCost\n\n## Notes\n\n- Cost usage is local-only. It reads JSONL logs under:\n  - Codex: ~/.codex/sessions/\\*_/_.jsonl\n  - Claude: ~/.config/claude/projects/**/\\*.jsonl or ~/.claude/projects/**/\\*.jsonl\n- If web usage is required (non-local), use codexbar usage (not cost).\n"},{"path":"scripts/model_usage.py","size":10764,"sha256":"5e833080809c70bbbe1eee5fa14d9d07d639ca0b16c37253625f4dc46ca1e64f","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nSummarize CodexBar local cost usage by model.\n\nDefaults to current model (most recent daily entry), or list all models.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport os\nimport subprocess\nimport sys\nfrom dataclasses import dataclass\nfrom datetime import date, datetime, timedelta\nfrom typing import Any, Dict, Iterable, List, Optional, Tuple\n\n\ndef positive_int(value: str) -> int:\n    try:\n        parsed = int(value)\n    except ValueError as exc:\n        raise argparse.ArgumentTypeError(\"must be an integer\") from exc\n    if parsed < 1:\n        raise argparse.ArgumentTypeError(\"must be >= 1\")\n    return parsed\n\n\ndef eprint(msg: str) -> None:\n    print(msg, file=sys.stderr)\n\n\ndef run_codexbar_cost(provider: str) -> List[Dict[str, Any]]:\n    cmd = [\"codexbar\", \"cost\", \"--format\", \"json\", \"--provider\", provider]\n    try:\n        output = subprocess.check_output(cmd, text=True)\n    except FileNotFoundError:\n        raise RuntimeError(\"codexbar not found on PATH. Install CodexBar CLI first.\")\n    except subprocess.CalledProcessError as exc:\n        raise RuntimeError(f\"codexbar cost failed (exit {exc.returncode}).\")\n    try:\n        payload = json.loads(output)\n    except json.JSONDecodeError as exc:\n        raise RuntimeError(f\"Failed to parse codexbar JSON output: {exc}\")\n    if not isinstance(payload, list):\n        raise RuntimeError(\"Expected codexbar cost JSON array.\")\n    return payload\n\n\ndef load_payload(input_path: Optional[str], provider: str) -> Dict[str, Any]:\n    if input_path:\n        if input_path == \"-\":\n            raw = sys.stdin.read()\n        else:\n            with open(input_path, \"r\", encoding=\"utf-8\") as handle:\n                raw = handle.read()\n        data = json.loads(raw)\n    else:\n        data = run_codexbar_cost(provider)\n\n    if isinstance(data, dict):\n        return data\n\n    if isinstance(data, list):\n        for entry in data:\n            if isinstance(entry, dict) and entry.get(\"provider\") == provider:\n                return entry\n        raise RuntimeError(f\"Provider '{provider}' not found in codexbar payload.\")\n\n    raise RuntimeError(\"Unsupported JSON input format.\")\n\n\n@dataclass\nclass ModelCost:\n    model: str\n    cost: float\n\n\ndef parse_daily_entries(payload: Dict[str, Any]) -> List[Dict[str, Any]]:\n    daily = payload.get(\"daily\")\n    if not daily:\n        return []\n    if not isinstance(daily, list):\n        return []\n    return [entry for entry in daily if isinstance(entry, dict)]\n\n\ndef parse_date(value: str) -> Optional[date]:\n    try:\n        return datetime.strptime(value, \"%Y-%m-%d\").date()\n    except Exception:\n        return None\n\n\ndef filter_by_days(entries: List[Dict[str, Any]], days: Optional[int]) -> List[Dict[str, Any]]:\n    if not days:\n        return entries\n    cutoff = date.today() - timedelta(days=days - 1)\n    filtered: List[Dict[str, Any]] = []\n    for entry in entries:\n        day = entry.get(\"date\")\n        if not isinstance(day, str):\n            continue\n        parsed = parse_date(day)\n        if parsed and parsed >= cutoff:\n            filtered.append(entry)\n    return filtered\n\n\ndef aggregate_costs(entries: Iterable[Dict[str, Any]]) -> Dict[str, float]:\n    totals: Dict[str, float] = {}\n    for entry in entries:\n        breakdowns = entry.get(\"modelBreakdowns\")\n        if not breakdowns:\n            continue\n        if not isinstance(breakdowns, list):\n            continue\n        for item in breakdowns:\n            if not isinstance(item, dict):\n                continue\n            model = item.get(\"modelName\")\n            cost = item.get(\"cost\")\n            if not isinstance(model, str):\n                continue\n            if not isinstance(cost, (int, float)):\n                continue\n            totals[model] = totals.get(model, 0.0) + float(cost)\n    return totals\n\n\ndef pick_current_model(entries: List[Dict[str, Any]]) -> Tuple[Optional[str], Optional[str]]:\n    if not entries:\n        return None, None\n    sorted_entries = sorted(\n        entries,\n        key=lambda entry: entry.get(\"date\") or \"\",\n    )\n    for entry in reversed(sorted_entries):\n        breakdowns = entry.get(\"modelBreakdowns\")\n        if isinstance(breakdowns, list) and breakdowns:\n            scored: List[ModelCost] = []\n            for item in breakdowns:\n                if not isinstance(item, dict):\n                    continue\n                model = item.get(\"modelName\")\n                cost = item.get(\"cost\")\n                if isinstance(model, str) and isinstance(cost, (int, float)):\n                    scored.append(ModelCost(model=model, cost=float(cost)))\n            if scored:\n                scored.sort(key=lambda item: item.cost, reverse=True)\n                return scored[0].model, entry.get(\"date\") if isinstance(entry.get(\"date\"), str) else None\n        models_used = entry.get(\"modelsUsed\")\n        if isinstance(models_used, list) and models_used:\n            last = models_used[-1]\n            if isinstance(last, str):\n                return last, entry.get(\"date\") if isinstance(entry.get(\"date\"), str) else None\n    return None, None\n\n\ndef usd(value: Optional[float]) -> str:\n    if value is None:\n        return \"—\"\n    return f\"${value:,.2f}\"\n\n\ndef latest_day_cost(entries: List[Dict[str, Any]], model: str) -> Tuple[Optional[str], Optional[float]]:\n    if not entries:\n        return None, None\n    sorted_entries = sorted(\n        entries,\n        key=lambda entry: entry.get(\"date\") or \"\",\n    )\n    for entry in reversed(sorted_entries):\n        breakdowns = entry.get(\"modelBreakdowns\")\n        if not isinstance(breakdowns, list):\n            continue\n        for item in breakdowns:\n            if not isinstance(item, dict):\n                continue\n            if item.get(\"modelName\") == model:\n                cost = item.get(\"cost\") if isinstance(item.get(\"cost\"), (int, float)) else None\n                day = entry.get(\"date\") if isinstance(entry.get(\"date\"), str) else None\n                return day, float(cost) if cost is not None else None\n    return None, None\n\n\ndef render_text_current(\n    provider: str,\n    model: str,\n    latest_date: Optional[str],\n    total_cost: Optional[float],\n    latest_cost: Optional[float],\n    latest_cost_date: Optional[str],\n    entry_count: int,\n) -> str:\n    lines = [f\"Provider: {provider}\", f\"Current model: {model}\"]\n    if latest_date:\n        lines.append(f\"Latest model date: {latest_date}\")\n    lines.append(f\"Total cost (rows): {usd(total_cost)}\")\n    if latest_cost_date:\n        lines.append(f\"Latest day cost: {usd(latest_cost)} ({latest_cost_date})\")\n    lines.append(f\"Daily rows: {entry_count}\")\n    return \"\\n\".join(lines)\n\n\ndef render_text_all(provider: str, totals: Dict[str, float]) -> str:\n    lines = [f\"Provider: {provider}\", \"Models:\"]\n    for model, cost in sorted(totals.items(), key=lambda item: item[1], reverse=True):\n        lines.append(f\"- {model}: {usd(cost)}\")\n    return \"\\n\".join(lines)\n\n\ndef build_json_current(\n    provider: str,\n    model: str,\n    latest_date: Optional[str],\n    total_cost: Optional[float],\n    latest_cost: Optional[float],\n    latest_cost_date: Optional[str],\n    entry_count: int,\n) -> Dict[str, Any]:\n    return {\n        \"provider\": provider,\n        \"mode\": \"current\",\n        \"model\": model,\n        \"latestModelDate\": latest_date,\n        \"totalCostUSD\": total_cost,\n        \"latestDayCostUSD\": latest_cost,\n        \"latestDayCostDate\": latest_cost_date,\n        \"dailyRowCount\": entry_count,\n    }\n\n\ndef build_json_all(provider: str, totals: Dict[str, float]) -> Dict[str, Any]:\n    return {\n        \"provider\": provider,\n        \"mode\": \"all\",\n        \"models\": [\n            {\"model\": model, \"totalCostUSD\": cost}\n            for model, cost in sorted(totals.items(), key=lambda item: item[1], reverse=True)\n        ],\n    }\n\n\ndef main() -> int:\n    parser = argparse.ArgumentParser(description=\"Summarize CodexBar model usage from local cost logs.\")\n    parser.add_argument(\"--provider\", choices=[\"codex\", \"claude\"], default=\"codex\")\n    parser.add_argument(\"--mode\", choices=[\"current\", \"all\"], default=\"current\")\n    parser.add_argument(\"--model\", help=\"Explicit model name to report instead of auto-current.\")\n    parser.add_argument(\"--input\", help=\"Path to codexbar cost JSON (or '-' for stdin).\")\n    parser.add_argument(\"--days\", type=positive_int, help=\"Limit to last N days (based on daily rows).\")\n    parser.add_argument(\"--format\", choices=[\"text\", \"json\"], default=\"text\")\n    parser.add_argument(\"--pretty\", action=\"store_true\", help=\"Pretty-print JSON output.\")\n\n    args = parser.parse_args()\n\n    try:\n        payload = load_payload(args.input, args.provider)\n    except Exception as exc:\n        eprint(str(exc))\n        return 1\n\n    entries = parse_daily_entries(payload)\n    entries = filter_by_days(entries, args.days)\n\n    if args.mode == \"current\":\n        model = args.model\n        latest_date = None\n        if not model:\n            model, latest_date = pick_current_model(entries)\n        if not model:\n            eprint(\"No model data found in codexbar cost payload.\")\n            return 2\n        totals = aggregate_costs(entries)\n        total_cost = totals.get(model)\n        latest_cost_date, latest_cost = latest_day_cost(entries, model)\n\n        if args.format == \"json\":\n            payload_out = build_json_current(\n                provider=args.provider,\n                model=model,\n                latest_date=latest_date,\n                total_cost=total_cost,\n                latest_cost=latest_cost,\n                latest_cost_date=latest_cost_date,\n                entry_count=len(entries),\n            )\n            indent = 2 if args.pretty else None\n            print(json.dumps(payload_out, indent=indent, sort_keys=args.pretty))\n        else:\n            print(\n                render_text_current(\n                    provider=args.provider,\n                    model=model,\n                    latest_date=latest_date,\n                    total_cost=total_cost,\n                    latest_cost=latest_cost,\n                    latest_cost_date=latest_cost_date,\n                    entry_count=len(entries),\n                )\n            )\n        return 0\n\n    totals = aggregate_costs(entries)\n    if not totals:\n        eprint(\"No model breakdowns found in codexbar cost payload.\")\n        return 2\n\n    if args.format == \"json\":\n        payload_out = build_json_all(provider=args.provider, totals=totals)\n        indent = 2 if args.pretty else None\n        print(json.dumps(payload_out, indent=indent, sort_keys=args.pretty))\n    else:\n        print(render_text_all(provider=args.provider, totals=totals))\n    return 0\n\n\nif __name__ == \"__main__\":\n    raise SystemExit(main())\n"},{"path":"scripts/test_model_usage.py","size":1310,"sha256":"95f62a3e3f38308dd9be80e09ec85e4a14455ab95457febb8f915c0f54685141","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nTests for model_usage helpers.\n\"\"\"\n\nimport argparse\nfrom datetime import date, timedelta\nfrom unittest import TestCase, main\n\nfrom model_usage import filter_by_days, positive_int\n\n\nclass TestModelUsage(TestCase):\n    def test_positive_int_accepts_valid_numbers(self):\n        self.assertEqual(positive_int(\"1\"), 1)\n        self.assertEqual(positive_int(\"7\"), 7)\n\n    def test_positive_int_rejects_zero_and_negative(self):\n        with self.assertRaises(argparse.ArgumentTypeError):\n            positive_int(\"0\")\n        with self.assertRaises(argparse.ArgumentTypeError):\n            positive_int(\"-3\")\n\n    def test_filter_by_days_keeps_recent_entries(self):\n        today = date.today()\n        entries = [\n            {\"date\": (today - timedelta(days=5)).strftime(\"%Y-%m-%d\"), \"modelBreakdowns\": []},\n            {\"date\": (today - timedelta(days=1)).strftime(\"%Y-%m-%d\"), \"modelBreakdowns\": []},\n            {\"date\": today.strftime(\"%Y-%m-%d\"), \"modelBreakdowns\": []},\n        ]\n\n        filtered = filter_by_days(entries, 2)\n\n        self.assertEqual(len(filtered), 2)\n        self.assertEqual(filtered[0][\"date\"], (today - timedelta(days=1)).strftime(\"%Y-%m-%d\"))\n        self.assertEqual(filtered[1][\"date\"], today.strftime(\"%Y-%m-%d\"))\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"nano-banana-pro","displayName":"nano-banana-pro","summary":"Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro).","version":"1.0.0","sha256hash":"0523d6775395b8c0c25c09a98ae8b7f152539602c12d37c9017a823439f669c2","files":[{"path":"SKILL.md","size":1967,"sha256":"f27b43613b78a0721d5ceca3a9cf460b11949ad682acc75419a22b14655a8406","contentType":"text/markdown","content":"---\nname: nano-banana-pro\ndescription: Generate or edit images via Gemini 3 Pro Image (Nano Banana Pro).\nhomepage: https://ai.google.dev/\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🍌\",\n        \"requires\": { \"bins\": [\"uv\"], \"env\": [\"GEMINI_API_KEY\"] },\n        \"primaryEnv\": \"GEMINI_API_KEY\",\n        \"install\":\n          [\n            {\n              \"id\": \"uv-brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"uv\",\n              \"bins\": [\"uv\"],\n              \"label\": \"Install uv (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Nano Banana Pro (Gemini 3 Pro Image)\n\nUse the bundled script to generate or edit images.\n\nGenerate\n\n```bash\nuv run {baseDir}/scripts/generate_image.py --prompt \"your image description\" --filename \"output.png\" --resolution 1K\n```\n\nEdit (single image)\n\n```bash\nuv run {baseDir}/scripts/generate_image.py --prompt \"edit instructions\" --filename \"output.png\" -i \"/path/in.png\" --resolution 2K\n```\n\nMulti-image composition (up to 14 images)\n\n```bash\nuv run {baseDir}/scripts/generate_image.py --prompt \"combine these into one scene\" --filename \"output.png\" -i img1.png -i img2.png -i img3.png\n```\n\nAPI key\n\n- `GEMINI_API_KEY` env var\n- Or set `skills.\"nano-banana-pro\".apiKey` / `skills.\"nano-banana-pro\".env.GEMINI_API_KEY` in `~/.hanzo-bot/hanzo-bot.json`\n\nSpecific aspect ratio (optional)\n\n```bash\nuv run {baseDir}/scripts/generate_image.py --prompt \"portrait photo\" --filename \"output.png\" --aspect-ratio 9:16\n```\n\nNotes\n\n- Resolutions: `1K` (default), `2K`, `4K`.\n- Aspect ratios: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. Without `--aspect-ratio` / `-a`, the model picks freely - use this flag for avatars, profile pics, or consistent batch generation.\n- Use timestamps in filenames: `yyyy-mm-dd-hh-mm-ss-name.png`.\n- The script prints a `MEDIA:` line for HanzoBot to auto-attach on supported chat providers.\n- Do not read the image back; report the saved path only.\n"},{"path":"scripts/generate_image.py","size":7103,"sha256":"0b019a014a46eeb8d76f196f4b9bbc399fef167288f2ce2e2470fc65a6a1a4db","contentType":"text/plain","content":"#!/usr/bin/env python3\n# /// script\n# requires-python = \">=3.10\"\n# dependencies = [\n#     \"google-genai>=1.0.0\",\n#     \"pillow>=10.0.0\",\n# ]\n# ///\n\"\"\"\nGenerate images using Google's Nano Banana Pro (Gemini 3 Pro Image) API.\n\nUsage:\n    uv run generate_image.py --prompt \"your image description\" --filename \"output.png\" [--resolution 1K|2K|4K] [--api-key KEY]\n\nMulti-image editing (up to 14 images):\n    uv run generate_image.py --prompt \"combine these images\" --filename \"output.png\" -i img1.png -i img2.png -i img3.png\n\"\"\"\n\nimport argparse\nimport os\nimport sys\nfrom pathlib import Path\n\nSUPPORTED_ASPECT_RATIOS = [\n    \"1:1\",\n    \"2:3\",\n    \"3:2\",\n    \"3:4\",\n    \"4:3\",\n    \"4:5\",\n    \"5:4\",\n    \"9:16\",\n    \"16:9\",\n    \"21:9\",\n]\n\n\ndef get_api_key(provided_key: str | None) -> str | None:\n    \"\"\"Get API key from argument first, then environment.\"\"\"\n    if provided_key:\n        return provided_key\n    return os.environ.get(\"GEMINI_API_KEY\")\n\n\ndef main():\n    parser = argparse.ArgumentParser(\n        description=\"Generate images using Nano Banana Pro (Gemini 3 Pro Image)\"\n    )\n    parser.add_argument(\n        \"--prompt\", \"-p\",\n        required=True,\n        help=\"Image description/prompt\"\n    )\n    parser.add_argument(\n        \"--filename\", \"-f\",\n        required=True,\n        help=\"Output filename (e.g., sunset-mountains.png)\"\n    )\n    parser.add_argument(\n        \"--input-image\", \"-i\",\n        action=\"append\",\n        dest=\"input_images\",\n        metavar=\"IMAGE\",\n        help=\"Input image path(s) for editing/composition. Can be specified multiple times (up to 14 images).\"\n    )\n    parser.add_argument(\n        \"--resolution\", \"-r\",\n        choices=[\"1K\", \"2K\", \"4K\"],\n        default=\"1K\",\n        help=\"Output resolution: 1K (default), 2K, or 4K\"\n    )\n    parser.add_argument(\n        \"--aspect-ratio\", \"-a\",\n        choices=SUPPORTED_ASPECT_RATIOS,\n        default=None,\n        help=f\"Output aspect ratio (default: model decides). Options: {', '.join(SUPPORTED_ASPECT_RATIOS)}\"\n    )\n    parser.add_argument(\n        \"--api-key\", \"-k\",\n        help=\"Gemini API key (overrides GEMINI_API_KEY env var)\"\n    )\n\n    args = parser.parse_args()\n\n    # Get API key\n    api_key = get_api_key(args.api_key)\n    if not api_key:\n        print(\"Error: No API key provided.\", file=sys.stderr)\n        print(\"Please either:\", file=sys.stderr)\n        print(\"  1. Provide --api-key argument\", file=sys.stderr)\n        print(\"  2. Set GEMINI_API_KEY environment variable\", file=sys.stderr)\n        sys.exit(1)\n\n    # Import here after checking API key to avoid slow import on error\n    from google import genai\n    from google.genai import types\n    from PIL import Image as PILImage\n\n    # Initialise client\n    client = genai.Client(api_key=api_key)\n\n    # Set up output path\n    output_path = Path(args.filename)\n    output_path.parent.mkdir(parents=True, exist_ok=True)\n\n    # Load input images if provided (up to 14 supported by Nano Banana Pro)\n    input_images = []\n    output_resolution = args.resolution\n    if args.input_images:\n        if len(args.input_images) > 14:\n            print(f\"Error: Too many input images ({len(args.input_images)}). Maximum is 14.\", file=sys.stderr)\n            sys.exit(1)\n\n        max_input_dim = 0\n        for img_path in args.input_images:\n            try:\n                with PILImage.open(img_path) as img:\n                    copied = img.copy()\n                    width, height = copied.size\n                input_images.append(copied)\n                print(f\"Loaded input image: {img_path}\")\n\n                # Track largest dimension for auto-resolution\n                max_input_dim = max(max_input_dim, width, height)\n            except Exception as e:\n                print(f\"Error loading input image '{img_path}': {e}\", file=sys.stderr)\n                sys.exit(1)\n\n        # Auto-detect resolution from largest input if not explicitly set\n        if args.resolution == \"1K\" and max_input_dim > 0:  # Default value\n            if max_input_dim >= 3000:\n                output_resolution = \"4K\"\n            elif max_input_dim >= 1500:\n                output_resolution = \"2K\"\n            else:\n                output_resolution = \"1K\"\n            print(f\"Auto-detected resolution: {output_resolution} (from max input dimension {max_input_dim})\")\n\n    # Build contents (images first if editing, prompt only if generating)\n    if input_images:\n        contents = [*input_images, args.prompt]\n        img_count = len(input_images)\n        print(f\"Processing {img_count} image{'s' if img_count > 1 else ''} with resolution {output_resolution}...\")\n    else:\n        contents = args.prompt\n        print(f\"Generating image with resolution {output_resolution}...\")\n\n    try:\n        # Build image config with optional aspect ratio\n        image_cfg_kwargs = {\"image_size\": output_resolution}\n        if args.aspect_ratio:\n            image_cfg_kwargs[\"aspect_ratio\"] = args.aspect_ratio\n\n        response = client.models.generate_content(\n            model=\"gemini-3-pro-image-preview\",\n            contents=contents,\n            config=types.GenerateContentConfig(\n                response_modalities=[\"TEXT\", \"IMAGE\"],\n                image_config=types.ImageConfig(**image_cfg_kwargs)\n            )\n        )\n\n        # Process response and convert to PNG\n        image_saved = False\n        for part in response.parts:\n            if part.text is not None:\n                print(f\"Model response: {part.text}\")\n            elif part.inline_data is not None:\n                # Convert inline data to PIL Image and save as PNG\n                from io import BytesIO\n\n                # inline_data.data is already bytes, not base64\n                image_data = part.inline_data.data\n                if isinstance(image_data, str):\n                    # If it's a string, it might be base64\n                    import base64\n                    image_data = base64.b64decode(image_data)\n\n                image = PILImage.open(BytesIO(image_data))\n\n                # Ensure RGB mode for PNG (convert RGBA to RGB with white background if needed)\n                if image.mode == 'RGBA':\n                    rgb_image = PILImage.new('RGB', image.size, (255, 255, 255))\n                    rgb_image.paste(image, mask=image.split()[3])\n                    rgb_image.save(str(output_path), 'PNG')\n                elif image.mode == 'RGB':\n                    image.save(str(output_path), 'PNG')\n                else:\n                    image.convert('RGB').save(str(output_path), 'PNG')\n                image_saved = True\n\n        if image_saved:\n            full_path = output_path.resolve()\n            print(f\"\\nImage saved: {full_path}\")\n            # HanzoBot parses MEDIA tokens and will attach the file on supported providers.\n            print(f\"MEDIA: {full_path}\")\n        else:\n            print(\"Error: No image was generated in the response.\", file=sys.stderr)\n            sys.exit(1)\n\n    except Exception as e:\n        print(f\"Error generating image: {e}\", file=sys.stderr)\n        sys.exit(1)\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"nano-pdf","displayName":"nano-pdf","summary":"Edit PDFs with natural-language instructions using the nano-pdf CLI.","version":"1.0.0","sha256hash":"13a4aeeea1b0ff231264cae62a29fa0a9bb0587e31f184015252654e3944c294","files":[{"path":"SKILL.md","size":955,"sha256":"e0b925804d8ad56be421f3404caea69614351bc19a1dc43efa78f5d9c9ce710f","contentType":"text/markdown","content":"---\nname: nano-pdf\ndescription: Edit PDFs with natural-language instructions using the nano-pdf CLI.\nhomepage: https://pypi.org/project/nano-pdf/\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📄\",\n        \"requires\": { \"bins\": [\"nano-pdf\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"uv\",\n              \"kind\": \"uv\",\n              \"package\": \"nano-pdf\",\n              \"bins\": [\"nano-pdf\"],\n              \"label\": \"Install nano-pdf (uv)\",\n            },\n          ],\n      },\n  }\n---\n\n# nano-pdf\n\nUse `nano-pdf` to apply edits to a specific page in a PDF using a natural-language instruction.\n\n## Quick start\n\n```bash\nnano-pdf edit deck.pdf 1 \"Change the title to 'Q3 Results' and fix the typo in the subtitle\"\n```\n\nNotes:\n\n- Page numbers are 0-based or 1-based depending on the tool’s version/config; if the result looks off by one, retry with the other.\n- Always sanity-check the output PDF before sending it out.\n"}]},{"slug":"notion","displayName":"notion","summary":"Notion API for creating and managing pages, databases, and blocks.","version":"1.0.0","sha256hash":"949706acee7642a9072952dcf040b08b79802e56a42f2582785411b98ab898c2","files":[{"path":"SKILL.md","size":5148,"sha256":"1e7efb20415b01efbe5788863e4676e94ca002513d6a4cc8825d7b5c82111222","contentType":"text/markdown","content":"---\nname: notion\ndescription: Notion API for creating and managing pages, databases, and blocks.\nhomepage: https://developers.notion.com\nmetadata:\n  {\n    \"hanzo-bot\":\n      { \"emoji\": \"📝\", \"requires\": { \"env\": [\"NOTION_API_KEY\"] }, \"primaryEnv\": \"NOTION_API_KEY\" },\n  }\n---\n\n# notion\n\nUse the Notion API to create/read/update pages, data sources (databases), and blocks.\n\n## Setup\n\n1. Create an integration at https://notion.so/my-integrations\n2. Copy the API key (starts with `ntn_` or `secret_`)\n3. Store it:\n\n```bash\nmkdir -p ~/.config/notion\necho \"ntn_your_key_here\" > ~/.config/notion/api_key\n```\n\n4. Share target pages/databases with your integration (click \"...\" → \"Connect to\" → your integration name)\n\n## API Basics\n\nAll requests need:\n\n```bash\nNOTION_KEY=$(cat ~/.config/notion/api_key)\ncurl -X GET \"https://api.notion.com/v1/...\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\"\n```\n\n> **Note:** The `Notion-Version` header is required. This skill uses `2025-09-03` (latest). In this version, databases are called \"data sources\" in the API.\n\n## Common Operations\n\n**Search for pages and data sources:**\n\n```bash\ncurl -X POST \"https://api.notion.com/v1/search\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"page title\"}'\n```\n\n**Get page:**\n\n```bash\ncurl \"https://api.notion.com/v1/pages/{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n**Get page content (blocks):**\n\n```bash\ncurl \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\"\n```\n\n**Create page in a data source:**\n\n```bash\ncurl -X POST \"https://api.notion.com/v1/pages\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"parent\": {\"database_id\": \"xxx\"},\n    \"properties\": {\n      \"Name\": {\"title\": [{\"text\": {\"content\": \"New Item\"}}]},\n      \"Status\": {\"select\": {\"name\": \"Todo\"}}\n    }\n  }'\n```\n\n**Query a data source (database):**\n\n```bash\ncurl -X POST \"https://api.notion.com/v1/data_sources/{data_source_id}/query\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"filter\": {\"property\": \"Status\", \"select\": {\"equals\": \"Active\"}},\n    \"sorts\": [{\"property\": \"Date\", \"direction\": \"descending\"}]\n  }'\n```\n\n**Create a data source (database):**\n\n```bash\ncurl -X POST \"https://api.notion.com/v1/data_sources\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"parent\": {\"page_id\": \"xxx\"},\n    \"title\": [{\"text\": {\"content\": \"My Database\"}}],\n    \"properties\": {\n      \"Name\": {\"title\": {}},\n      \"Status\": {\"select\": {\"options\": [{\"name\": \"Todo\"}, {\"name\": \"Done\"}]}},\n      \"Date\": {\"date\": {}}\n    }\n  }'\n```\n\n**Update page properties:**\n\n```bash\ncurl -X PATCH \"https://api.notion.com/v1/pages/{page_id}\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"properties\": {\"Status\": {\"select\": {\"name\": \"Done\"}}}}'\n```\n\n**Add blocks to page:**\n\n```bash\ncurl -X PATCH \"https://api.notion.com/v1/blocks/{page_id}/children\" \\\n  -H \"Authorization: Bearer $NOTION_KEY\" \\\n  -H \"Notion-Version: 2025-09-03\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"children\": [\n      {\"object\": \"block\", \"type\": \"paragraph\", \"paragraph\": {\"rich_text\": [{\"text\": {\"content\": \"Hello\"}}]}}\n    ]\n  }'\n```\n\n## Property Types\n\nCommon property formats for database items:\n\n- **Title:** `{\"title\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Rich text:** `{\"rich_text\": [{\"text\": {\"content\": \"...\"}}]}`\n- **Select:** `{\"select\": {\"name\": \"Option\"}}`\n- **Multi-select:** `{\"multi_select\": [{\"name\": \"A\"}, {\"name\": \"B\"}]}`\n- **Date:** `{\"date\": {\"start\": \"2024-01-15\", \"end\": \"2024-01-16\"}}`\n- **Checkbox:** `{\"checkbox\": true}`\n- **Number:** `{\"number\": 42}`\n- **URL:** `{\"url\": \"https://...\"}`\n- **Email:** `{\"email\": \"[email protected]\"}`\n- **Relation:** `{\"relation\": [{\"id\": \"page_id\"}]}`\n\n## Key Differences in 2025-09-03\n\n- **Databases → Data Sources:** Use `/data_sources/` endpoints for queries and retrieval\n- **Two IDs:** Each database now has both a `database_id` and a `data_source_id`\n  - Use `database_id` when creating pages (`parent: {\"database_id\": \"...\"}`)\n  - Use `data_source_id` when querying (`POST /v1/data_sources/{id}/query`)\n- **Search results:** Databases return as `\"object\": \"data_source\"` with their `data_source_id`\n- **Parent in responses:** Pages show `parent.data_source_id` alongside `parent.database_id`\n- **Finding the data_source_id:** Search for the database, or call `GET /v1/data_sources/{data_source_id}`\n\n## Notes\n\n- Page/database IDs are UUIDs (with or without dashes)\n- The API cannot set database view filters — that's UI-only\n- Rate limit: ~3 requests/second average\n- Use `is_inline: true` when creating data sources to embed them in pages\n"}]},{"slug":"obsidian","displayName":"obsidian","summary":"Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.","version":"1.0.0","sha256hash":"a6b3780d5b9ee6581a40e9cd5df69fb4d414c4f0f026f8be0e10e1c395037c79","files":[{"path":"SKILL.md","size":2532,"sha256":"fb2bb4a7f5885d578bfc8fb5c3d7844358be3113bc38e627db6dcc0264be82e6","contentType":"text/markdown","content":"---\nname: obsidian\ndescription: Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.\nhomepage: https://help.obsidian.md\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"💎\",\n        \"requires\": { \"bins\": [\"obsidian-cli\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"yakitrak/yakitrak/obsidian-cli\",\n              \"bins\": [\"obsidian-cli\"],\n              \"label\": \"Install obsidian-cli (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Obsidian\n\nObsidian vault = a normal folder on disk.\n\nVault structure (typical)\n\n- Notes: `*.md` (plain text Markdown; edit with any editor)\n- Config: `.obsidian/` (workspace + plugin settings; usually don’t touch from scripts)\n- Canvases: `*.canvas` (JSON)\n- Attachments: whatever folder you chose in Obsidian settings (images/PDFs/etc.)\n\n## Find the active vault(s)\n\nObsidian desktop tracks vaults here (source of truth):\n\n- `~/Library/Application Support/obsidian/obsidian.json`\n\n`obsidian-cli` resolves vaults from that file; vault name is typically the **folder name** (path suffix).\n\nFast “what vault is active / where are the notes?”\n\n- If you’ve already set a default: `obsidian-cli print-default --path-only`\n- Otherwise, read `~/Library/Application Support/obsidian/obsidian.json` and use the vault entry with `\"open\": true`.\n\nNotes\n\n- Multiple vaults common (iCloud vs `~/Documents`, work/personal, etc.). Don’t guess; read config.\n- Avoid writing hardcoded vault paths into scripts; prefer reading the config or using `print-default`.\n\n## obsidian-cli quick start\n\nPick a default vault (once):\n\n- `obsidian-cli set-default \"<vault-folder-name>\"`\n- `obsidian-cli print-default` / `obsidian-cli print-default --path-only`\n\nSearch\n\n- `obsidian-cli search \"query\"` (note names)\n- `obsidian-cli search-content \"query\"` (inside notes; shows snippets + lines)\n\nCreate\n\n- `obsidian-cli create \"Folder/New note\" --content \"...\" --open`\n- Requires Obsidian URI handler (`obsidian://…`) working (Obsidian installed).\n- Avoid creating notes under “hidden” dot-folders (e.g. `.something/...`) via URI; Obsidian may refuse.\n\nMove/rename (safe refactor)\n\n- `obsidian-cli move \"old/path/note\" \"new/path/note\"`\n- Updates `[[wikilinks]]` and common Markdown links across the vault (this is the main win vs `mv`).\n\nDelete\n\n- `obsidian-cli delete \"path/note\"`\n\nPrefer direct edits when appropriate: open the `.md` file and change it; Obsidian will pick it up.\n"}]},{"slug":"openai-image-gen","displayName":"openai-image-gen","summary":"Batch-generate images via OpenAI Images API. Random prompt sampler + `index.html` gallery.","version":"1.0.0","sha256hash":"7e33efcf78d8b88fb2a9bca09e51a1eaee06427c0ae177f9afe62c3c8de9831d","files":[{"path":"SKILL.md","size":3354,"sha256":"44d6255d34e97d64c0582184aba61c4b89496d6220bd656f35cb623408a72d73","contentType":"text/markdown","content":"---\nname: openai-image-gen\ndescription: Batch-generate images via OpenAI Images API. Random prompt sampler + `index.html` gallery.\nhomepage: https://platform.openai.com/docs/api-reference/images\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🖼️\",\n        \"requires\": { \"bins\": [\"python3\"], \"env\": [\"OPENAI_API_KEY\"] },\n        \"primaryEnv\": \"OPENAI_API_KEY\",\n        \"install\":\n          [\n            {\n              \"id\": \"python-brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"python\",\n              \"bins\": [\"python3\"],\n              \"label\": \"Install Python (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# OpenAI Image Gen\n\nGenerate a handful of “random but structured” prompts and render them via the OpenAI Images API.\n\n## Run\n\nNote: Image generation can take longer than common exec timeouts (for example 30 seconds).\nWhen invoking this skill via HanzoBot’s exec tool, set a higher timeout to avoid premature termination/retries (e.g., exec timeout=300).\n\n```bash\npython3 {baseDir}/scripts/gen.py\nopen ~/Projects/tmp/openai-image-gen-*/index.html  # if ~/Projects/tmp exists; else ./tmp/...\n```\n\nUseful flags:\n\n```bash\n# GPT image models with various options\npython3 {baseDir}/scripts/gen.py --count 16 --model gpt-image-1\npython3 {baseDir}/scripts/gen.py --prompt \"ultra-detailed studio photo of a robot astronaut\" --count 4\npython3 {baseDir}/scripts/gen.py --size 1536x1024 --quality high --out-dir ./out/images\npython3 {baseDir}/scripts/gen.py --model gpt-image-1.5 --background transparent --output-format webp\n\n# DALL-E 3 (note: count is automatically limited to 1)\npython3 {baseDir}/scripts/gen.py --model dall-e-3 --quality hd --size 1792x1024 --style vivid\npython3 {baseDir}/scripts/gen.py --model dall-e-3 --style natural --prompt \"serene mountain landscape\"\n\n# DALL-E 2\npython3 {baseDir}/scripts/gen.py --model dall-e-2 --size 512x512 --count 4\n```\n\n## Model-Specific Parameters\n\nDifferent models support different parameter values. The script automatically selects appropriate defaults based on the model.\n\n### Size\n\n- **GPT image models** (`gpt-image-1`, `gpt-image-1-mini`, `gpt-image-1.5`): `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or `auto`\n  - Default: `1024x1024`\n- **dall-e-3**: `1024x1024`, `1792x1024`, or `1024x1792`\n  - Default: `1024x1024`\n- **dall-e-2**: `256x256`, `512x512`, or `1024x1024`\n  - Default: `1024x1024`\n\n### Quality\n\n- **GPT image models**: `auto`, `high`, `medium`, or `low`\n  - Default: `high`\n- **dall-e-3**: `hd` or `standard`\n  - Default: `standard`\n- **dall-e-2**: `standard` only\n  - Default: `standard`\n\n### Other Notable Differences\n\n- **dall-e-3** only supports generating 1 image at a time (`n=1`). The script automatically limits count to 1 when using this model.\n- **GPT image models** support additional parameters:\n  - `--background`: `transparent`, `opaque`, or `auto` (default)\n  - `--output-format`: `png` (default), `jpeg`, or `webp`\n  - Note: `stream` and `moderation` are available via API but not yet implemented in this script\n- **dall-e-3** has a `--style` parameter: `vivid` (hyper-real, dramatic) or `natural` (more natural looking)\n\n## Output\n\n- `*.png`, `*.jpeg`, or `*.webp` images (output format depends on model + `--output-format`)\n- `prompts.json` (prompt → file mapping)\n- `index.html` (thumbnail gallery)\n"},{"path":"scripts/gen.py","size":8135,"sha256":"2835d6600927529e4c59ddf423aaf792cd8e1270c2061958c33a4e3e1189fb53","contentType":"text/plain","content":"#!/usr/bin/env python3\nimport argparse\nimport base64\nimport datetime as dt\nimport json\nimport os\nimport random\nimport re\nimport sys\nimport urllib.error\nimport urllib.request\nfrom html import escape as html_escape\nfrom pathlib import Path\n\n\ndef slugify(text: str) -> str:\n    text = text.lower().strip()\n    text = re.sub(r\"[^a-z0-9]+\", \"-\", text)\n    text = re.sub(r\"-{2,}\", \"-\", text).strip(\"-\")\n    return text or \"image\"\n\n\ndef default_out_dir() -> Path:\n    now = dt.datetime.now().strftime(\"%Y-%m-%d-%H-%M-%S\")\n    preferred = Path.home() / \"Projects\" / \"tmp\"\n    base = preferred if preferred.is_dir() else Path(\"./tmp\")\n    base.mkdir(parents=True, exist_ok=True)\n    return base / f\"openai-image-gen-{now}\"\n\n\ndef pick_prompts(count: int) -> list[str]:\n    subjects = [\n        \"a robot astronaut\",\n        \"a brutalist lighthouse\",\n        \"a cozy reading nook\",\n        \"a cyberpunk noodle shop\",\n        \"a Vienna street at dusk\",\n        \"a minimalist product photo\",\n        \"a surreal underwater library\",\n    ]\n    styles = [\n        \"ultra-detailed studio photo\",\n        \"35mm film still\",\n        \"isometric illustration\",\n        \"editorial photography\",\n        \"soft watercolor\",\n        \"architectural render\",\n        \"high-contrast monochrome\",\n    ]\n    lighting = [\n        \"golden hour\",\n        \"overcast soft light\",\n        \"neon lighting\",\n        \"dramatic rim light\",\n        \"candlelight\",\n        \"foggy atmosphere\",\n    ]\n    prompts: list[str] = []\n    for _ in range(count):\n        prompts.append(\n            f\"{random.choice(styles)} of {random.choice(subjects)}, {random.choice(lighting)}\"\n        )\n    return prompts\n\n\ndef get_model_defaults(model: str) -> tuple[str, str]:\n    \"\"\"Return (default_size, default_quality) for the given model.\"\"\"\n    if model == \"dall-e-2\":\n        # quality will be ignored\n        return (\"1024x1024\", \"standard\")\n    elif model == \"dall-e-3\":\n        return (\"1024x1024\", \"standard\")\n    else:\n        # GPT image or future models\n        return (\"1024x1024\", \"high\")\n\n\ndef request_images(\n    api_key: str,\n    prompt: str,\n    model: str,\n    size: str,\n    quality: str,\n    background: str = \"\",\n    output_format: str = \"\",\n    style: str = \"\",\n) -> dict:\n    url = \"https://api.openai.com/v1/images/generations\"\n    args = {\n        \"model\": model,\n        \"prompt\": prompt,\n        \"size\": size,\n        \"n\": 1,\n    }\n\n    # Quality parameter - dall-e-2 doesn't accept this parameter\n    if model != \"dall-e-2\":\n        args[\"quality\"] = quality\n\n    # Note: response_format no longer supported by OpenAI Images API\n    # dall-e models now return URLs by default\n\n    if model.startswith(\"gpt-image\"):\n        if background:\n            args[\"background\"] = background\n        if output_format:\n            args[\"output_format\"] = output_format\n\n    if model == \"dall-e-3\" and style:\n        args[\"style\"] = style\n\n    body = json.dumps(args).encode(\"utf-8\")\n    req = urllib.request.Request(\n        url,\n        method=\"POST\",\n        headers={\n            \"Authorization\": f\"Bearer {api_key}\",\n            \"Content-Type\": \"application/json\",\n        },\n        data=body,\n    )\n    try:\n        with urllib.request.urlopen(req, timeout=300) as resp:\n            return json.loads(resp.read().decode(\"utf-8\"))\n    except urllib.error.HTTPError as e:\n        payload = e.read().decode(\"utf-8\", errors=\"replace\")\n        raise RuntimeError(f\"OpenAI Images API failed ({e.code}): {payload}\") from e\n\n\ndef write_gallery(out_dir: Path, items: list[dict]) -> None:\n    thumbs = \"\\n\".join(\n        [\n            f\"\"\"\n<figure>\n  <a href=\"{html_escape(it[\"file\"], quote=True)}\"><img src=\"{html_escape(it[\"file\"], quote=True)}\" loading=\"lazy\" /></a>\n  <figcaption>{html_escape(it[\"prompt\"])}</figcaption>\n</figure>\n\"\"\".strip()\n            for it in items\n        ]\n    )\n    html = f\"\"\"<!doctype html>\n<meta charset=\"utf-8\" />\n<title>openai-image-gen</title>\n<style>\n  :root {{ color-scheme: dark; }}\n  body {{ margin: 24px; font: 14px/1.4 ui-sans-serif, system-ui; background: #0b0f14; color: #e8edf2; }}\n  h1 {{ font-size: 18px; margin: 0 0 16px; }}\n  .grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 16px; }}\n  figure {{ margin: 0; padding: 12px; border: 1px solid #1e2a36; border-radius: 14px; background: #0f1620; }}\n  img {{ width: 100%; height: auto; border-radius: 10px; display: block; }}\n  figcaption {{ margin-top: 10px; color: #b7c2cc; }}\n  code {{ color: #9cd1ff; }}\n</style>\n<h1>openai-image-gen</h1>\n<p>Output: <code>{html_escape(out_dir.as_posix())}</code></p>\n<div class=\"grid\">\n{thumbs}\n</div>\n\"\"\"\n    (out_dir / \"index.html\").write_text(html, encoding=\"utf-8\")\n\n\ndef main() -> int:\n    ap = argparse.ArgumentParser(description=\"Generate images via OpenAI Images API.\")\n    ap.add_argument(\"--prompt\", help=\"Single prompt. If omitted, random prompts are generated.\")\n    ap.add_argument(\"--count\", type=int, default=8, help=\"How many images to generate.\")\n    ap.add_argument(\"--model\", default=\"gpt-image-1\", help=\"Image model id.\")\n    ap.add_argument(\"--size\", default=\"\", help=\"Image size (e.g. 1024x1024, 1536x1024). Defaults based on model if not specified.\")\n    ap.add_argument(\"--quality\", default=\"\", help=\"Image quality (e.g. high, standard). Defaults based on model if not specified.\")\n    ap.add_argument(\"--background\", default=\"\", help=\"Background transparency (GPT models only): transparent, opaque, or auto.\")\n    ap.add_argument(\"--output-format\", default=\"\", help=\"Output format (GPT models only): png, jpeg, or webp.\")\n    ap.add_argument(\"--style\", default=\"\", help=\"Image style (dall-e-3 only): vivid or natural.\")\n    ap.add_argument(\"--out-dir\", default=\"\", help=\"Output directory (default: ./tmp/openai-image-gen-<ts>).\")\n    args = ap.parse_args()\n\n    api_key = (os.environ.get(\"OPENAI_API_KEY\") or \"\").strip()\n    if not api_key:\n        print(\"Missing OPENAI_API_KEY\", file=sys.stderr)\n        return 2\n\n    # Apply model-specific defaults if not specified\n    default_size, default_quality = get_model_defaults(args.model)\n    size = args.size or default_size\n    quality = args.quality or default_quality\n\n    count = args.count\n    if args.model == \"dall-e-3\" and count > 1:\n        print(f\"Warning: dall-e-3 only supports generating 1 image at a time. Reducing count from {count} to 1.\", file=sys.stderr)\n        count = 1\n\n    out_dir = Path(args.out_dir).expanduser() if args.out_dir else default_out_dir()\n    out_dir.mkdir(parents=True, exist_ok=True)\n\n    prompts = [args.prompt] * count if args.prompt else pick_prompts(count)\n\n    # Determine file extension based on output format\n    if args.model.startswith(\"gpt-image\") and args.output_format:\n        file_ext = args.output_format\n    else:\n        file_ext = \"png\"\n\n    items: list[dict] = []\n    for idx, prompt in enumerate(prompts, start=1):\n        print(f\"[{idx}/{len(prompts)}] {prompt}\")\n        res = request_images(\n            api_key,\n            prompt,\n            args.model,\n            size,\n            quality,\n            args.background,\n            args.output_format,\n            args.style,\n        )\n        data = res.get(\"data\", [{}])[0]\n        image_b64 = data.get(\"b64_json\")\n        image_url = data.get(\"url\")\n        if not image_b64 and not image_url:\n            raise RuntimeError(f\"Unexpected response: {json.dumps(res)[:400]}\")\n\n        filename = f\"{idx:03d}-{slugify(prompt)[:40]}.{file_ext}\"\n        filepath = out_dir / filename\n        if image_b64:\n            filepath.write_bytes(base64.b64decode(image_b64))\n        else:\n            try:\n                urllib.request.urlretrieve(image_url, filepath)\n            except urllib.error.URLError as e:\n                raise RuntimeError(f\"Failed to download image from {image_url}: {e}\") from e\n\n        items.append({\"prompt\": prompt, \"file\": filename})\n\n    (out_dir / \"prompts.json\").write_text(json.dumps(items, indent=2), encoding=\"utf-8\")\n    write_gallery(out_dir, items)\n    print(f\"\\nWrote: {(out_dir / 'index.html').as_posix()}\")\n    return 0\n\n\nif __name__ == \"__main__\":\n    raise SystemExit(main())\n"},{"path":"scripts/test_gen.py","size":1719,"sha256":"9cf6b6d71b09664e898569707790efa0278c4dd3b7341a93490d1cc4b552a04d","contentType":"text/plain","content":"\"\"\"Tests for write_gallery HTML escaping (fixes #12538 - stored XSS).\"\"\"\n\nimport tempfile\nfrom pathlib import Path\n\nfrom gen import write_gallery\n\n\ndef test_write_gallery_escapes_prompt_xss():\n    with tempfile.TemporaryDirectory() as tmpdir:\n        out = Path(tmpdir)\n        items = [{\"prompt\": '<script>alert(\"xss\")</script>', \"file\": \"001-test.png\"}]\n        write_gallery(out, items)\n        html = (out / \"index.html\").read_text()\n        assert \"<script>\" not in html\n        assert \"&lt;script&gt;\" in html\n\n\ndef test_write_gallery_escapes_filename():\n    with tempfile.TemporaryDirectory() as tmpdir:\n        out = Path(tmpdir)\n        items = [{\"prompt\": \"safe prompt\", \"file\": '\" onload=\"alert(1)'}]\n        write_gallery(out, items)\n        html = (out / \"index.html\").read_text()\n        assert 'onload=\"alert(1)\"' not in html\n        assert \"&quot;\" in html\n\n\ndef test_write_gallery_escapes_ampersand():\n    with tempfile.TemporaryDirectory() as tmpdir:\n        out = Path(tmpdir)\n        items = [{\"prompt\": \"cats & dogs <3\", \"file\": \"001-test.png\"}]\n        write_gallery(out, items)\n        html = (out / \"index.html\").read_text()\n        assert \"cats &amp; dogs &lt;3\" in html\n\n\ndef test_write_gallery_normal_output():\n    with tempfile.TemporaryDirectory() as tmpdir:\n        out = Path(tmpdir)\n        items = [\n            {\"prompt\": \"a robot astronaut, golden hour\", \"file\": \"001-robot.png\"},\n            {\"prompt\": \"a cozy reading nook\", \"file\": \"002-nook.png\"},\n        ]\n        write_gallery(out, items)\n        html = (out / \"index.html\").read_text()\n        assert \"a robot astronaut, golden hour\" in html\n        assert 'src=\"001-robot.png\"' in html\n        assert \"002-nook.png\" in html\n\n"}]},{"slug":"openai-whisper","displayName":"openai-whisper","summary":"Local speech-to-text with the Whisper CLI (no API key).","version":"1.0.0","sha256hash":"87152ac6a9ebd1d74bf7913a9edc713a090a0a401063457af08e0226c42aee0d","files":[{"path":"SKILL.md","size":916,"sha256":"ffc4df716aa51eb6ab16abdfe51fd503ec0c7bd622c411e844c671fe1462eeb2","contentType":"text/markdown","content":"---\nname: openai-whisper\ndescription: Local speech-to-text with the Whisper CLI (no API key).\nhomepage: https://openai.com/research/whisper\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🎙️\",\n        \"requires\": { \"bins\": [\"whisper\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"openai-whisper\",\n              \"bins\": [\"whisper\"],\n              \"label\": \"Install OpenAI Whisper (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Whisper (CLI)\n\nUse `whisper` to transcribe audio locally.\n\nQuick start\n\n- `whisper /path/audio.mp3 --model medium --output_format txt --output_dir .`\n- `whisper /path/audio.m4a --task translate --output_format srt`\n\nNotes\n\n- Models download to `~/.cache/whisper` on first run.\n- `--model` defaults to `turbo` on this install.\n- Use smaller models for speed, larger for accuracy.\n"}]},{"slug":"openai-whisper-api","displayName":"openai-whisper-api","summary":"Transcribe audio via OpenAI Audio Transcriptions API (Whisper).","version":"1.0.0","sha256hash":"2d80c29c52850b0bbc00c10418fbb5c9dc1559c0e36651994cc7d0f34657e178","files":[{"path":"SKILL.md","size":1161,"sha256":"59f1ed44c6f8e552ea18eaa99df1ae4a753a07a09cf41d6ee7da8094d5a339cd","contentType":"text/markdown","content":"---\nname: openai-whisper-api\ndescription: Transcribe audio via OpenAI Audio Transcriptions API (Whisper).\nhomepage: https://platform.openai.com/docs/guides/speech-to-text\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"☁️\",\n        \"requires\": { \"bins\": [\"curl\"], \"env\": [\"OPENAI_API_KEY\"] },\n        \"primaryEnv\": \"OPENAI_API_KEY\",\n      },\n  }\n---\n\n# OpenAI Whisper API (curl)\n\nTranscribe an audio file via OpenAI’s `/v1/audio/transcriptions` endpoint.\n\n## Quick start\n\n```bash\n{baseDir}/scripts/transcribe.sh /path/to/audio.m4a\n```\n\nDefaults:\n\n- Model: `whisper-1`\n- Output: `<input>.txt`\n\n## Useful flags\n\n```bash\n{baseDir}/scripts/transcribe.sh /path/to/audio.ogg --model whisper-1 --out /tmp/transcript.txt\n{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --language en\n{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --prompt \"Speaker names: Peter, Daniel\"\n{baseDir}/scripts/transcribe.sh /path/to/audio.m4a --json --out /tmp/transcript.json\n```\n\n## API key\n\nSet `OPENAI_API_KEY`, or configure it in `~/.hanzo-bot/hanzo-bot.json`:\n\n```json5\n{\n  skills: {\n    \"openai-whisper-api\": {\n      apiKey: \"OPENAI_KEY_HERE\",\n    },\n  },\n}\n```\n"},{"path":"scripts/transcribe.sh","size":1479,"sha256":"06d255cdd1a44ea3098ca1d9400529c641da76b4e9389007904f190e681d5688","contentType":"text/plain","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nUsage:\n  transcribe.sh <audio-file> [--model whisper-1] [--out /path/to/out.txt] [--language en] [--prompt \"hint\"] [--json]\nEOF\n  exit 2\n}\n\nif [[ \"${1:-}\" == \"\" || \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n  usage\nfi\n\nin=\"${1:-}\"\nshift || true\n\nmodel=\"whisper-1\"\nout=\"\"\nlanguage=\"\"\nprompt=\"\"\nresponse_format=\"text\"\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    --model)\n      model=\"${2:-}\"\n      shift 2\n      ;;\n    --out)\n      out=\"${2:-}\"\n      shift 2\n      ;;\n    --language)\n      language=\"${2:-}\"\n      shift 2\n      ;;\n    --prompt)\n      prompt=\"${2:-}\"\n      shift 2\n      ;;\n    --json)\n      response_format=\"json\"\n      shift 1\n      ;;\n    *)\n      echo \"Unknown arg: $1\" >&2\n      usage\n      ;;\n  esac\ndone\n\nif [[ ! -f \"$in\" ]]; then\n  echo \"File not found: $in\" >&2\n  exit 1\nfi\n\nif [[ \"${OPENAI_API_KEY:-}\" == \"\" ]]; then\n  echo \"Missing OPENAI_API_KEY\" >&2\n  exit 1\nfi\n\nif [[ \"$out\" == \"\" ]]; then\n  base=\"${in%.*}\"\n  if [[ \"$response_format\" == \"json\" ]]; then\n    out=\"${base}.json\"\n  else\n    out=\"${base}.txt\"\n  fi\nfi\n\nmkdir -p \"$(dirname \"$out\")\"\n\ncurl -sS https://api.openai.com/v1/audio/transcriptions \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Accept: application/json\" \\\n  -F \"file=@${in}\" \\\n  -F \"model=${model}\" \\\n  -F \"response_format=${response_format}\" \\\n  ${language:+-F \"language=${language}\"} \\\n  ${prompt:+-F \"prompt=${prompt}\"} \\\n  >\"$out\"\n\necho \"$out\"\n"}]},{"slug":"openhue","displayName":"openhue","summary":"Control Philips Hue lights and scenes via the OpenHue CLI.","version":"1.0.0","sha256hash":"e7f2151bb6e323dfe4ef751db11918e0d7a8665d498736292378c426792c6fcc","files":[{"path":"SKILL.md","size":2461,"sha256":"316facd584382f5c22bda22aa6dd5e5159d22ebb7f08b258fc6831bb06f09c6d","contentType":"text/markdown","content":"---\nname: openhue\ndescription: Control Philips Hue lights and scenes via the OpenHue CLI.\nhomepage: https://www.openhue.io/cli\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"💡\",\n        \"requires\": { \"bins\": [\"openhue\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"openhue/cli/openhue-cli\",\n              \"bins\": [\"openhue\"],\n              \"label\": \"Install OpenHue CLI (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# OpenHue CLI\n\nUse `openhue` to control Philips Hue lights and scenes via a Hue Bridge.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- \"Turn on/off the lights\"\n- \"Dim the living room lights\"\n- \"Set a scene\" or \"movie mode\"\n- Controlling specific Hue rooms or zones\n- Adjusting brightness, color, or color temperature\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Non-Hue smart devices (other brands) → not supported\n- HomeKit scenes or Shortcuts → use Apple's ecosystem\n- TV or entertainment system control\n- Thermostat or HVAC\n- Smart plugs (unless Hue smart plugs)\n\n## Common Commands\n\n### List Resources\n\n```bash\nopenhue get light       # List all lights\nopenhue get room        # List all rooms\nopenhue get scene       # List all scenes\n```\n\n### Control Lights\n\n```bash\n# Turn on/off\nopenhue set light \"Bedroom Lamp\" --on\nopenhue set light \"Bedroom Lamp\" --off\n\n# Brightness (0-100)\nopenhue set light \"Bedroom Lamp\" --on --brightness 50\n\n# Color temperature (warm to cool: 153-500 mirek)\nopenhue set light \"Bedroom Lamp\" --on --temperature 300\n\n# Color (by name or hex)\nopenhue set light \"Bedroom Lamp\" --on --color red\nopenhue set light \"Bedroom Lamp\" --on --rgb \"#FF5500\"\n```\n\n### Control Rooms\n\n```bash\n# Turn off entire room\nopenhue set room \"Bedroom\" --off\n\n# Set room brightness\nopenhue set room \"Bedroom\" --on --brightness 30\n```\n\n### Scenes\n\n```bash\n# Activate scene\nopenhue set scene \"Relax\" --room \"Bedroom\"\nopenhue set scene \"Concentrate\" --room \"Office\"\n```\n\n## Quick Presets\n\n```bash\n# Bedtime (dim warm)\nopenhue set room \"Bedroom\" --on --brightness 20 --temperature 450\n\n# Work mode (bright cool)\nopenhue set room \"Office\" --on --brightness 100 --temperature 250\n\n# Movie mode (dim)\nopenhue set room \"Living Room\" --on --brightness 10\n```\n\n## Notes\n\n- Bridge must be on local network\n- First run requires button press on Hue bridge to pair\n- Colors only work on color-capable bulbs (not white-only)\n"}]},{"slug":"oracle","displayName":"oracle","summary":"Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).","version":"1.0.0","sha256hash":"0fa199e02b7f1fc5e3d9ce49e60f3a667f04e4e321de40e13d5152b870894371","files":[{"path":"SKILL.md","size":5074,"sha256":"8bb93dd1ec60ef505251071a56d055e10fc8d335c93d87f5894d2f71bbb374f7","contentType":"text/markdown","content":"---\nname: oracle\ndescription: Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).\nhomepage: https://askoracle.dev\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🧿\",\n        \"requires\": { \"bins\": [\"oracle\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"node\",\n              \"kind\": \"node\",\n              \"package\": \"@steipete/oracle\",\n              \"bins\": [\"oracle\"],\n              \"label\": \"Install oracle (node)\",\n            },\n          ],\n      },\n  }\n---\n\n# oracle — best use\n\nOracle 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.\n\n## Main use case (browser, GPT‑5.2 Pro)\n\nDefault 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.\n\nRecommended defaults:\n\n- Engine: browser (`--engine browser`)\n- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model \"5.2 Pro\"`)\n\n## Golden path\n\n1. Pick a tight file set (fewest files that still contain the truth).\n2. Preview payload + token spend (`--dry-run` + `--files-report`).\n3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.\n4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).\n\n## Commands (preferred)\n\n- Help:\n  - `oracle --help`\n  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).\n\n- Preview (no tokens):\n  - `oracle --dry-run summary -p \"<task>\" --file \"src/**\" --file \"!**/*.test.*\"`\n  - `oracle --dry-run full -p \"<task>\" --file \"src/**\"`\n\n- Token sanity:\n  - `oracle --dry-run summary --files-report -p \"<task>\" --file \"src/**\"`\n\n- Browser run (main path; long-running is normal):\n  - `oracle --engine browser --model gpt-5.2-pro -p \"<task>\" --file \"src/**\"`\n\n- Manual paste fallback:\n  - `oracle --render --copy -p \"<task>\" --file \"src/**\"`\n  - Note: `--copy` is a hidden alias for `--copy-markdown`.\n\n## Attaching files (`--file`)\n\n`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.\n\n- Include:\n  - `--file \"src/**\"`\n  - `--file src/index.ts`\n  - `--file docs --file README.md`\n\n- Exclude:\n  - `--file \"src/**\" --file \"!src/**/*.test.ts\" --file \"!**/*.snap\"`\n\n- Defaults (implementation behavior):\n  - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files).\n  - Honors `.gitignore` when expanding globs.\n  - Does not follow symlinks.\n  - Dotfiles filtered unless opted in via pattern (e.g. `--file \".github/**\"`).\n  - Files > 1 MB rejected.\n\n## Engines (API vs browser)\n\n- Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`.\n- Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/Codex or multi-model runs.\n- Browser attachments:\n  - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads).\n- Remote browser host:\n  - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>`\n  - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p \"<task>\" --file \"src/**\"`\n\n## Sessions + slugs\n\n- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).\n- 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.\n  - List: `oracle status --hours 72`\n  - Attach: `oracle session <id> --render`\n- Use `--slug \"<3-5 words>\"` to keep session IDs readable.\n- Duplicate prompt guard exists; use `--force` only when you truly want a fresh run.\n\n## Prompt template (high signal)\n\nOracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:\n\n- Project briefing (stack + build/test commands + platform constraints).\n- “Where things live” (key directories, entrypoints, config files, boundaries).\n- Exact question + what you tried + the error text (verbatim).\n- Constraints (“don’t change X”, “must keep public API”, etc).\n- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).\n\n## Safety\n\n- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.\n\n## “Exhaustive prompt” restoration pattern\n\nFor long investigations, write a standalone prompt + file set so you can rerun days later:\n\n- 6–30 sentence project briefing + the goal.\n- Repro steps + exact errors + what you tried.\n- Attach all context files needed (entrypoints, configs, key modules, docs).\n\nOracle 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).\n"}]},{"slug":"ordercli","displayName":"ordercli","summary":"Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).","version":"1.0.0","sha256hash":"b56193e4b5e13a0f1dbe5450002a37534cc5a1cebaf694707a5f8724845bb97e","files":[{"path":"SKILL.md","size":2390,"sha256":"643d98866be04b80f7a14333834830ecef003f414c3f01bc6956c57b0216bb1b","contentType":"text/markdown","content":"---\nname: ordercli\ndescription: Foodora-only CLI for checking past orders and active order status (Deliveroo WIP).\nhomepage: https://ordercli.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🛵\",\n        \"requires\": { \"bins\": [\"ordercli\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/ordercli\",\n              \"bins\": [\"ordercli\"],\n              \"label\": \"Install ordercli (brew)\",\n            },\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/ordercli/cmd/ordercli@latest\",\n              \"bins\": [\"ordercli\"],\n              \"label\": \"Install ordercli (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# ordercli\n\nUse `ordercli` to check past orders and track active order status (Foodora only right now).\n\nQuick start (Foodora)\n\n- `ordercli foodora countries`\n- `ordercli foodora config set --country AT`\n- `ordercli foodora login --email [email protected] --password-stdin`\n- `ordercli foodora orders`\n- `ordercli foodora history --limit 20`\n- `ordercli foodora history show <orderCode>`\n\nOrders\n\n- Active list (arrival/status): `ordercli foodora orders`\n- Watch: `ordercli foodora orders --watch`\n- Active order detail: `ordercli foodora order <orderCode>`\n- History detail JSON: `ordercli foodora history show <orderCode> --json`\n\nReorder (adds to cart)\n\n- Preview: `ordercli foodora reorder <orderCode>`\n- Confirm: `ordercli foodora reorder <orderCode> --confirm`\n- Address: `ordercli foodora reorder <orderCode> --confirm --address-id <id>`\n\nCloudflare / bot protection\n\n- Browser login: `ordercli foodora login --email [email protected] --password-stdin --browser`\n- Reuse profile: `--browser-profile \"$HOME/Library/Application Support/ordercli/browser-profile\"`\n- Import Chrome cookies: `ordercli foodora cookies chrome --profile \"Default\"`\n\nSession import (no password)\n\n- `ordercli foodora session chrome --url https://www.foodora.at/ --profile \"Default\"`\n- `ordercli foodora session refresh --client-id android`\n\nDeliveroo (WIP, not working yet)\n\n- Requires `DELIVEROO_BEARER_TOKEN` (optional `DELIVEROO_COOKIE`).\n- `ordercli deliveroo config set --market uk`\n- `ordercli deliveroo history`\n\nNotes\n\n- Use `--config /tmp/ordercli.json` for testing.\n- Confirm before any reorder or cart-changing action.\n"}]},{"slug":"peekaboo","displayName":"peekaboo","summary":"Capture and automate macOS UI with the Peekaboo CLI.","version":"1.0.0","sha256hash":"427fe2c78fa934bd2e4928cf235bce9e159c2298315c7854a5c5b5f723141899","files":[{"path":"SKILL.md","size":5971,"sha256":"f5a65a269df165aa87ced142178448d87de206b1b951da59c631efa23fa09515","contentType":"text/markdown","content":"---\nname: peekaboo\ndescription: Capture and automate macOS UI with the Peekaboo CLI.\nhomepage: https://peekaboo.boo\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"👀\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"peekaboo\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/peekaboo\",\n              \"bins\": [\"peekaboo\"],\n              \"label\": \"Install Peekaboo (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Peekaboo\n\nPeekaboo is a full macOS UI automation CLI: capture/inspect screens, target UI\nelements, drive input, and manage apps/windows/menus. Commands share a snapshot\ncache and support `--json`/`-j` for scripting. Run `peekaboo` or\n`peekaboo <cmd> --help` for flags; `peekaboo --version` prints build metadata.\nTip: run via `polter peekaboo` to ensure fresh builds.\n\n## Features (all CLI capabilities, excluding agent/MCP)\n\nCore\n\n- `bridge`: inspect Peekaboo Bridge host connectivity\n- `capture`: live capture or video ingest + frame extraction\n- `clean`: prune snapshot cache and temp files\n- `config`: init/show/edit/validate, providers, models, credentials\n- `image`: capture screenshots (screen/window/menu bar regions)\n- `learn`: print the full agent guide + tool catalog\n- `list`: apps, windows, screens, menubar, permissions\n- `permissions`: check Screen Recording/Accessibility status\n- `run`: execute `.peekaboo.json` scripts\n- `sleep`: pause execution for a duration\n- `tools`: list available tools with filtering/display options\n\nInteraction\n\n- `click`: target by ID/query/coords with smart waits\n- `drag`: drag & drop across elements/coords/Dock\n- `hotkey`: modifier combos like `cmd,shift,t`\n- `move`: cursor positioning with optional smoothing\n- `paste`: set clipboard -> paste -> restore\n- `press`: special-key sequences with repeats\n- `scroll`: directional scrolling (targeted + smooth)\n- `swipe`: gesture-style drags between targets\n- `type`: text + control keys (`--clear`, delays)\n\nSystem\n\n- `app`: launch/quit/relaunch/hide/unhide/switch/list apps\n- `clipboard`: read/write clipboard (text/images/files)\n- `dialog`: click/input/file/dismiss/list system dialogs\n- `dock`: launch/right-click/hide/show/list Dock items\n- `menu`: click/list application menus + menu extras\n- `menubar`: list/click status bar items\n- `open`: enhanced `open` with app targeting + JSON payloads\n- `space`: list/switch/move-window (Spaces)\n- `visualizer`: exercise Peekaboo visual feedback animations\n- `window`: close/minimize/maximize/move/resize/focus/list\n\nVision\n\n- `see`: annotated UI maps, snapshot IDs, optional analysis\n\nGlobal runtime flags\n\n- `--json`/`-j`, `--verbose`/`-v`, `--log-level <level>`\n- `--no-remote`, `--bridge-socket <path>`\n\n## Quickstart (happy path)\n\n```bash\npeekaboo permissions\npeekaboo list apps --json\npeekaboo see --annotate --path /tmp/peekaboo-see.png\npeekaboo click --on B1\npeekaboo type \"Hello\" --return\n```\n\n## Common targeting parameters (most interaction commands)\n\n- App/window: `--app`, `--pid`, `--window-title`, `--window-id`, `--window-index`\n- Snapshot targeting: `--snapshot` (ID from `see`; defaults to latest)\n- Element/coords: `--on`/`--id` (element ID), `--coords x,y`\n- Focus control: `--no-auto-focus`, `--space-switch`, `--bring-to-current-space`,\n  `--focus-timeout-seconds`, `--focus-retry-count`\n\n## Common capture parameters\n\n- Output: `--path`, `--format png|jpg`, `--retina`\n- Targeting: `--mode screen|window|frontmost`, `--screen-index`,\n  `--window-title`, `--window-id`\n- Analysis: `--analyze \"prompt\"`, `--annotate`\n- Capture engine: `--capture-engine auto|classic|cg|modern|sckit`\n\n## Common motion/typing parameters\n\n- Timing: `--duration` (drag/swipe), `--steps`, `--delay` (type/scroll/press)\n- Human-ish movement: `--profile human|linear`, `--wpm` (typing)\n- Scroll: `--direction up|down|left|right`, `--amount <ticks>`, `--smooth`\n\n## Examples\n\n### See -> click -> type (most reliable flow)\n\n```bash\npeekaboo see --app Safari --window-title \"Login\" --annotate --path /tmp/see.png\npeekaboo click --on B3 --app Safari\npeekaboo type \"[email protected]\" --app Safari\npeekaboo press tab --count 1 --app Safari\npeekaboo type \"supersecret\" --app Safari --return\n```\n\n### Target by window id\n\n```bash\npeekaboo list windows --app \"Visual Studio Code\" --json\npeekaboo click --window-id 12345 --coords 120,160\npeekaboo type \"Hello from Peekaboo\" --window-id 12345\n```\n\n### Capture screenshots + analyze\n\n```bash\npeekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png\npeekaboo image --app Safari --window-title \"Dashboard\" --analyze \"Summarize KPIs\"\npeekaboo see --mode screen --screen-index 0 --analyze \"Summarize the dashboard\"\n```\n\n### Live capture (motion-aware)\n\n```bash\npeekaboo capture live --mode region --region 100,100,800,600 --duration 30 \\\n  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture\n```\n\n### App + window management\n\n```bash\npeekaboo app launch \"Safari\" --open https://example.com\npeekaboo window focus --app Safari --window-title \"Example\"\npeekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800\npeekaboo app quit --app Safari\n```\n\n### Menus, menubar, dock\n\n```bash\npeekaboo menu click --app Safari --item \"New Window\"\npeekaboo menu click --app TextEdit --path \"Format > Font > Show Fonts\"\npeekaboo menu click-extra --title \"WiFi\"\npeekaboo dock launch Safari\npeekaboo menubar list --json\n```\n\n### Mouse + gesture input\n\n```bash\npeekaboo move 500,300 --smooth\npeekaboo drag --from B1 --to T2\npeekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800\npeekaboo scroll --direction down --amount 6 --smooth\n```\n\n### Keyboard input\n\n```bash\npeekaboo hotkey --keys \"cmd,shift,t\"\npeekaboo press escape\npeekaboo type \"Line 1\\nLine 2\" --delay 10\n```\n\nNotes\n\n- Requires Screen Recording + Accessibility permissions.\n- Use `peekaboo see --annotate` to identify targets before clicking.\n"}]},{"slug":"sag","displayName":"sag","summary":"ElevenLabs text-to-speech with mac-style say UX.","version":"1.0.0","sha256hash":"f5c7f6b456d91e4c5f79dfa0b5e6124c5bf4d04a653020cf2309611c9a4ea7b8","files":[{"path":"SKILL.md","size":2301,"sha256":"ff0874aad6a632b39cd7c43d8b6b14be84062f5a30cbb7d2b72f87f2d16f1281","contentType":"text/markdown","content":"---\nname: sag\ndescription: ElevenLabs text-to-speech with mac-style say UX.\nhomepage: https://sag.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🗣️\",\n        \"requires\": { \"bins\": [\"sag\"], \"env\": [\"ELEVENLABS_API_KEY\"] },\n        \"primaryEnv\": \"ELEVENLABS_API_KEY\",\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/sag\",\n              \"bins\": [\"sag\"],\n              \"label\": \"Install sag (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# sag\n\nUse `sag` for ElevenLabs TTS with local playback.\n\nAPI key (required)\n\n- `ELEVENLABS_API_KEY` (preferred)\n- `SAG_API_KEY` also supported by the CLI\n\nQuick start\n\n- `sag \"Hello there\"`\n- `sag speak -v \"Roger\" \"Hello\"`\n- `sag voices`\n- `sag prompting` (model-specific tips)\n\nModel notes\n\n- Default: `eleven_v3` (expressive)\n- Stable: `eleven_multilingual_v2`\n- Fast: `eleven_flash_v2_5`\n\nPronunciation + delivery rules\n\n- First fix: respell (e.g. \"key-note\"), add hyphens, adjust casing.\n- Numbers/units/URLs: `--normalize auto` (or `off` if it harms names).\n- Language bias: `--lang en|de|fr|...` to guide normalization.\n- v3: SSML `<break>` not supported; use `[pause]`, `[short pause]`, `[long pause]`.\n- v2/v2.5: SSML `<break time=\"1.5s\" />` supported; `<phoneme>` not exposed in `sag`.\n\nv3 audio tags (put at the entrance of a line)\n\n- `[whispers]`, `[shouts]`, `[sings]`\n- `[laughs]`, `[starts laughing]`, `[sighs]`, `[exhales]`\n- `[sarcastic]`, `[curious]`, `[excited]`, `[crying]`, `[mischievously]`\n- Example: `sag \"[whispers] keep this quiet. [short pause] ok?\"`\n\nVoice defaults\n\n- `ELEVENLABS_VOICE_ID` or `SAG_VOICE_ID`\n\nConfirm voice + speaker before long output.\n\n## Chat voice responses\n\nWhen Peter asks for a \"voice\" reply (e.g., \"crazy scientist voice\", \"explain in voice\"), generate audio and send it:\n\n```bash\n# Generate audio file\nsag -v Clawd -o /tmp/voice-reply.mp3 \"Your message here\"\n\n# Then include in reply:\n# MEDIA:/tmp/voice-reply.mp3\n```\n\nVoice character tips:\n\n- Crazy scientist: Use `[excited]` tags, dramatic pauses `[short pause]`, vary intensity\n- Calm: Use `[whispers]` or slower pacing\n- Dramatic: Use `[sings]` or `[shouts]` sparingly\n\nDefault voice for Clawd: `lj2rcrvANS3gaWWnczSX` (or just `-v Clawd`)\n"}]},{"slug":"session-logs","displayName":"session-logs","summary":"Search and analyze your own session logs (older/parent conversations) using jq.","version":"1.0.0","sha256hash":"e14256ac5f5ed2d8b9f5284f525af06352526a0f161ec54d94aab817c6d024e8","files":[{"path":"SKILL.md","size":3436,"sha256":"689805dc8d2827df848c0c1286e753985ac9021b66368551c35b0add6eb15aca","contentType":"text/markdown","content":"---\nname: session-logs\ndescription: Search and analyze your own session logs (older/parent conversations) using jq.\nmetadata: { \"hanzo-bot\": { \"emoji\": \"📜\", \"requires\": { \"bins\": [\"jq\", \"rg\"] } } }\n---\n\n# session-logs\n\nSearch your complete conversation history stored in session JSONL files. Use this when a user references older/parent conversations or asks what was said before.\n\n## Trigger\n\nUse this skill when the user asks about prior chats, parent conversations, or historical context that isn't in memory files.\n\n## Location\n\nSession logs live at: `~/.hanzo-bot/agents/<agentId>/sessions/` (use the `agent=<id>` value from the system prompt Runtime line).\n\n- **`sessions.json`** - Index mapping session keys to session IDs\n- **`<session-id>.jsonl`** - Full conversation transcript per session\n\n## Structure\n\nEach `.jsonl` file contains messages with:\n\n- `type`: \"session\" (metadata) or \"message\"\n- `timestamp`: ISO timestamp\n- `message.role`: \"user\", \"assistant\", or \"toolResult\"\n- `message.content[]`: Text, thinking, or tool calls (filter `type==\"text\"` for human-readable content)\n- `message.usage.cost.total`: Cost per response\n\n## Common Queries\n\n### List all sessions by date and size\n\n```bash\nfor f in ~/.hanzo-bot/agents/<agentId>/sessions/*.jsonl; do\n  date=$(head -1 \"$f\" | jq -r '.timestamp' | cut -dT -f1)\n  size=$(ls -lh \"$f\" | awk '{print $5}')\n  echo \"$date $size $(basename $f)\"\ndone | sort -r\n```\n\n### Find sessions from a specific day\n\n```bash\nfor f in ~/.hanzo-bot/agents/<agentId>/sessions/*.jsonl; do\n  head -1 \"$f\" | jq -r '.timestamp' | grep -q \"2026-01-06\" && echo \"$f\"\ndone\n```\n\n### Extract user messages from a session\n\n```bash\njq -r 'select(.message.role == \"user\") | .message.content[]? | select(.type == \"text\") | .text' <session>.jsonl\n```\n\n### Search for keyword in assistant responses\n\n```bash\njq -r 'select(.message.role == \"assistant\") | .message.content[]? | select(.type == \"text\") | .text' <session>.jsonl | rg -i \"keyword\"\n```\n\n### Get total cost for a session\n\n```bash\njq -s '[.[] | .message.usage.cost.total // 0] | add' <session>.jsonl\n```\n\n### Daily cost summary\n\n```bash\nfor f in ~/.hanzo-bot/agents/<agentId>/sessions/*.jsonl; do\n  date=$(head -1 \"$f\" | jq -r '.timestamp' | cut -dT -f1)\n  cost=$(jq -s '[.[] | .message.usage.cost.total // 0] | add' \"$f\")\n  echo \"$date $cost\"\ndone | awk '{a[$1]+=$2} END {for(d in a) print d, \"$\"a[d]}' | sort -r\n```\n\n### Count messages and tokens in a session\n\n```bash\njq -s '{\n  messages: length,\n  user: [.[] | select(.message.role == \"user\")] | length,\n  assistant: [.[] | select(.message.role == \"assistant\")] | length,\n  first: .[0].timestamp,\n  last: .[-1].timestamp\n}' <session>.jsonl\n```\n\n### Tool usage breakdown\n\n```bash\njq -r '.message.content[]? | select(.type == \"toolCall\") | .name' <session>.jsonl | sort | uniq -c | sort -rn\n```\n\n### Search across ALL sessions for a phrase\n\n```bash\nrg -l \"phrase\" ~/.hanzo-bot/agents/<agentId>/sessions/*.jsonl\n```\n\n## Tips\n\n- Sessions are append-only JSONL (one JSON object per line)\n- Large sessions can be several MB - use `head`/`tail` for sampling\n- The `sessions.json` index maps chat providers (discord, whatsapp, etc.) to session IDs\n- Deleted sessions have `.deleted.<timestamp>` suffix\n\n## Fast text-only hint (low noise)\n\n```bash\njq -r 'select(.type==\"message\") | .message.content[]? | select(.type==\"text\") | .text' ~/.hanzo-bot/agents/<agentId>/sessions/<id>.jsonl | rg 'keyword'\n```\n"}]},{"slug":"sherpa-onnx-tts","displayName":"sherpa-onnx-tts","summary":"Local text-to-speech via sherpa-onnx (offline, no cloud)","version":"1.0.0","sha256hash":"3502f6fe0be2ec3cba2d70ae295cd6a15b243787c7b9fee99308d260957fcc9c","files":[{"path":"SKILL.md","size":3411,"sha256":"8a9f904fcd1594ddc6cfc4ff9fe8be4d4dbf9700e4b04f0bdf450f655527abbb","contentType":"text/markdown","content":"---\nname: sherpa-onnx-tts\ndescription: Local text-to-speech via sherpa-onnx (offline, no cloud)\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🗣️\",\n        \"os\": [\"darwin\", \"linux\", \"win32\"],\n        \"requires\": { \"env\": [\"SHERPA_ONNX_RUNTIME_DIR\", \"SHERPA_ONNX_MODEL_DIR\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"download-runtime-macos\",\n              \"kind\": \"download\",\n              \"os\": [\"darwin\"],\n              \"url\": \"https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-osx-universal2-shared.tar.bz2\",\n              \"archive\": \"tar.bz2\",\n              \"extract\": true,\n              \"stripComponents\": 1,\n              \"targetDir\": \"runtime\",\n              \"label\": \"Download sherpa-onnx runtime (macOS)\",\n            },\n            {\n              \"id\": \"download-runtime-linux-x64\",\n              \"kind\": \"download\",\n              \"os\": [\"linux\"],\n              \"url\": \"https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-linux-x64-shared.tar.bz2\",\n              \"archive\": \"tar.bz2\",\n              \"extract\": true,\n              \"stripComponents\": 1,\n              \"targetDir\": \"runtime\",\n              \"label\": \"Download sherpa-onnx runtime (Linux x64)\",\n            },\n            {\n              \"id\": \"download-runtime-win-x64\",\n              \"kind\": \"download\",\n              \"os\": [\"win32\"],\n              \"url\": \"https://github.com/k2-fsa/sherpa-onnx/releases/download/v1.12.23/sherpa-onnx-v1.12.23-win-x64-shared.tar.bz2\",\n              \"archive\": \"tar.bz2\",\n              \"extract\": true,\n              \"stripComponents\": 1,\n              \"targetDir\": \"runtime\",\n              \"label\": \"Download sherpa-onnx runtime (Windows x64)\",\n            },\n            {\n              \"id\": \"download-model-lessac\",\n              \"kind\": \"download\",\n              \"url\": \"https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-piper-en_US-lessac-high.tar.bz2\",\n              \"archive\": \"tar.bz2\",\n              \"extract\": true,\n              \"targetDir\": \"models\",\n              \"label\": \"Download Piper en_US lessac (high)\",\n            },\n          ],\n      },\n  }\n---\n\n# sherpa-onnx-tts\n\nLocal TTS using the sherpa-onnx offline CLI.\n\n## Install\n\n1. Download the runtime for your OS (extracts into `~/.hanzo-bot/tools/sherpa-onnx-tts/runtime`)\n2. Download a voice model (extracts into `~/.hanzo-bot/tools/sherpa-onnx-tts/models`)\n\nUpdate `~/.hanzo-bot/hanzo-bot.json`:\n\n```json5\n{\n  skills: {\n    entries: {\n      \"sherpa-onnx-tts\": {\n        env: {\n          SHERPA_ONNX_RUNTIME_DIR: \"~/.hanzo-bot/tools/sherpa-onnx-tts/runtime\",\n          SHERPA_ONNX_MODEL_DIR: \"~/.hanzo-bot/tools/sherpa-onnx-tts/models/vits-piper-en_US-lessac-high\",\n        },\n      },\n    },\n  },\n}\n```\n\nThe wrapper lives in this skill folder. Run it directly, or add the wrapper to PATH:\n\n```bash\nexport PATH=\"{baseDir}/bin:$PATH\"\n```\n\n## Usage\n\n```bash\n{baseDir}/bin/sherpa-onnx-tts -o ./tts.wav \"Hello from local TTS.\"\n```\n\nNotes:\n\n- Pick a different model from the sherpa-onnx `tts-models` release if you want another voice.\n- If the model dir has multiple `.onnx` files, set `SHERPA_ONNX_MODEL_FILE` or pass `--model-file`.\n- You can also pass `--tokens-file` or `--data-dir` to override the defaults.\n- Windows: run `node {baseDir}\\\\bin\\\\sherpa-onnx-tts -o tts.wav \"Hello from local TTS.\"`\n"},{"path":"bin/sherpa-onnx-tts","size":4811,"sha256":"542d46f42f5ff8d22ed71f58ca052e4e525a337d90bd25664a6237b6da56fd2a","contentType":"text/plain","content":"#!/usr/bin/env node\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport { spawnSync } from \"node:child_process\";\n\nfunction usage(message) {\n  if (message) {\n    console.error(message);\n  }\n  console.error(\n    \"\\nUsage: sherpa-onnx-tts [--runtime-dir <dir>] [--model-dir <dir>] [--model-file <file>] [--tokens-file <file>] [--data-dir <dir>] [--output <file>] \\\"text\\\"\",\n  );\n  console.error(\"\\nRequired env (or flags):\\n  SHERPA_ONNX_RUNTIME_DIR\\n  SHERPA_ONNX_MODEL_DIR\");\n  process.exit(1);\n}\n\nfunction resolveRuntimeDir(explicit) {\n  const value = explicit || process.env.SHERPA_ONNX_RUNTIME_DIR || \"\";\n  return value.trim();\n}\n\nfunction resolveModelDir(explicit) {\n  const value = explicit || process.env.SHERPA_ONNX_MODEL_DIR || \"\";\n  return value.trim();\n}\n\nfunction resolveModelFile(modelDir, explicitFlag) {\n  const explicit = (explicitFlag || process.env.SHERPA_ONNX_MODEL_FILE || \"\").trim();\n  if (explicit) return explicit;\n  try {\n    const candidates = fs\n      .readdirSync(modelDir)\n      .filter((entry) => entry.endsWith(\".onnx\"))\n      .map((entry) => path.join(modelDir, entry));\n    if (candidates.length === 1) return candidates[0];\n  } catch {\n    return \"\";\n  }\n  return \"\";\n}\n\nfunction resolveTokensFile(modelDir, explicitFlag) {\n  const explicit = (explicitFlag || process.env.SHERPA_ONNX_TOKENS_FILE || \"\").trim();\n  if (explicit) return explicit;\n  const candidate = path.join(modelDir, \"tokens.txt\");\n  return fs.existsSync(candidate) ? candidate : \"\";\n}\n\nfunction resolveDataDir(modelDir, explicitFlag) {\n  const explicit = (explicitFlag || process.env.SHERPA_ONNX_DATA_DIR || \"\").trim();\n  if (explicit) return explicit;\n  const candidate = path.join(modelDir, \"espeak-ng-data\");\n  return fs.existsSync(candidate) ? candidate : \"\";\n}\n\nfunction resolveBinary(runtimeDir) {\n  const binName = process.platform === \"win32\" ? \"sherpa-onnx-offline-tts.exe\" : \"sherpa-onnx-offline-tts\";\n  return path.join(runtimeDir, \"bin\", binName);\n}\n\nfunction prependEnvPath(current, next) {\n  if (!next) return current;\n  if (!current) return next;\n  return `${next}${path.delimiter}${current}`;\n}\n\nconst args = process.argv.slice(2);\nlet runtimeDir = \"\";\nlet modelDir = \"\";\nlet modelFile = \"\";\nlet tokensFile = \"\";\nlet dataDir = \"\";\nlet output = \"tts.wav\";\nconst textParts = [];\n\nfor (let i = 0; i < args.length; i += 1) {\n  const arg = args[i];\n  if (arg === \"--runtime-dir\") {\n    runtimeDir = args[i + 1] || \"\";\n    i += 1;\n    continue;\n  }\n  if (arg === \"--model-dir\") {\n    modelDir = args[i + 1] || \"\";\n    i += 1;\n    continue;\n  }\n  if (arg === \"--model-file\") {\n    modelFile = args[i + 1] || \"\";\n    i += 1;\n    continue;\n  }\n  if (arg === \"--tokens-file\") {\n    tokensFile = args[i + 1] || \"\";\n    i += 1;\n    continue;\n  }\n  if (arg === \"--data-dir\") {\n    dataDir = args[i + 1] || \"\";\n    i += 1;\n    continue;\n  }\n  if (arg === \"-o\" || arg === \"--output\") {\n    output = args[i + 1] || output;\n    i += 1;\n    continue;\n  }\n  if (arg === \"--text\") {\n    textParts.push(args[i + 1] || \"\");\n    i += 1;\n    continue;\n  }\n  textParts.push(arg);\n}\n\nruntimeDir = resolveRuntimeDir(runtimeDir);\nmodelDir = resolveModelDir(modelDir);\n\nif (!runtimeDir || !modelDir) {\n  usage(\"Missing runtime/model directory.\");\n}\n\nmodelFile = resolveModelFile(modelDir, modelFile);\ntokensFile = resolveTokensFile(modelDir, tokensFile);\ndataDir = resolveDataDir(modelDir, dataDir);\n\nif (!modelFile || !tokensFile || !dataDir) {\n  usage(\n    \"Model directory is missing required files. Set SHERPA_ONNX_MODEL_FILE, SHERPA_ONNX_TOKENS_FILE, SHERPA_ONNX_DATA_DIR or pass --model-file/--tokens-file/--data-dir.\",\n  );\n}\n\nconst text = textParts.join(\" \").trim();\nif (!text) {\n  usage(\"Missing text.\");\n}\n\nconst bin = resolveBinary(runtimeDir);\nif (!fs.existsSync(bin)) {\n  usage(`TTS binary not found: ${bin}`);\n}\n\nconst env = { ...process.env };\nconst libDir = path.join(runtimeDir, \"lib\");\nif (process.platform === \"darwin\") {\n  env.DYLD_LIBRARY_PATH = prependEnvPath(env.DYLD_LIBRARY_PATH || \"\", libDir);\n} else if (process.platform === \"win32\") {\n  env.PATH = prependEnvPath(env.PATH || \"\", [path.join(runtimeDir, \"bin\"), libDir].join(path.delimiter));\n} else {\n  env.LD_LIBRARY_PATH = prependEnvPath(env.LD_LIBRARY_PATH || \"\", libDir);\n}\n\nconst outputPath = path.isAbsolute(output) ? output : path.join(process.cwd(), output);\nfs.mkdirSync(path.dirname(outputPath), { recursive: true });\n\nconst child = spawnSync(\n  bin,\n  [\n    `--vits-model=${modelFile}`,\n    `--vits-tokens=${tokensFile}`,\n    `--vits-data-dir=${dataDir}`,\n    `--output-filename=${outputPath}`,\n    text,\n  ],\n  {\n    stdio: \"inherit\",\n    env,\n  },\n);\n\nif (typeof child.status === \"number\") {\n  process.exit(child.status);\n}\nif (child.error) {\n  console.error(child.error.message || String(child.error));\n}\nprocess.exit(1);\n"}]},{"slug":"skill-creator","displayName":"skill-creator","summary":"Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.","version":"1.0.0","sha256hash":"1e052291e98c15d0418b5b53b73238a42ebf06d05a608f28d321c36b0a3d0c5b","files":[{"path":"SKILL.md","size":18452,"sha256":"4a9bb47629ca9ef89428c0c47c18fdff9765a03a2b42d908495c5075c918571a","contentType":"text/markdown","content":"---\nname: skill-creator\ndescription: Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.\n---\n\n# Skill Creator\n\nThis skill provides guidance for creating effective skills.\n\n## About Skills\n\nSkills are modular, self-contained packages that extend Codex's capabilities by providing\nspecialized knowledge, workflows, and tools. Think of them as \"onboarding guides\" for specific\ndomains or tasks—they transform Codex from a general-purpose agent into a specialized agent\nequipped with procedural knowledge that no model can fully possess.\n\n### What Skills Provide\n\n1. Specialized workflows - Multi-step procedures for specific domains\n2. Tool integrations - Instructions for working with specific file formats or APIs\n3. Domain expertise - Company-specific knowledge, schemas, business logic\n4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks\n\n## Core Principles\n\n### Concise is Key\n\nThe context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.\n\n**Default assumption: Codex is already very smart.** Only add context Codex doesn't already have. Challenge each piece of information: \"Does Codex really need this explanation?\" and \"Does this paragraph justify its token cost?\"\n\nPrefer concise examples over verbose explanations.\n\n### Set Appropriate Degrees of Freedom\n\nMatch the level of specificity to the task's fragility and variability:\n\n**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.\n\n**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.\n\n**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.\n\nThink of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).\n\n### Anatomy of a Skill\n\nEvery skill consists of a required SKILL.md file and optional bundled resources:\n\n```\nskill-name/\n├── SKILL.md (required)\n│   ├── YAML frontmatter metadata (required)\n│   │   ├── name: (required)\n│   │   └── description: (required)\n│   └── Markdown instructions (required)\n└── Bundled Resources (optional)\n    ├── scripts/          - Executable code (Python/Bash/etc.)\n    ├── references/       - Documentation intended to be loaded into context as needed\n    └── assets/           - Files used in output (templates, icons, fonts, etc.)\n```\n\n#### SKILL.md (required)\n\nEvery SKILL.md consists of:\n\n- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.\n- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).\n\n#### Bundled Resources (optional)\n\n##### Scripts (`scripts/`)\n\nExecutable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.\n\n- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed\n- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks\n- **Benefits**: Token efficient, deterministic, may be executed without loading into context\n- **Note**: Scripts may still need to be read by Codex for patching or environment-specific adjustments\n\n##### References (`references/`)\n\nDocumentation and reference material intended to be loaded as needed into context to inform Codex's process and thinking.\n\n- **When to include**: For documentation that Codex should reference while working\n- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications\n- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides\n- **Benefits**: Keeps SKILL.md lean, loaded only when Codex determines it's needed\n- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md\n- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.\n\n##### Assets (`assets/`)\n\nFiles not intended to be loaded into context, but rather used within the output Codex produces.\n\n- **When to include**: When the skill needs files that will be used in the final output\n- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography\n- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified\n- **Benefits**: Separates output resources from documentation, enables Codex to use files without loading them into context\n\n#### What to Not Include in a Skill\n\nA skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:\n\n- README.md\n- INSTALLATION_GUIDE.md\n- QUICK_REFERENCE.md\n- CHANGELOG.md\n- etc.\n\nThe skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxiliary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.\n\n### Progressive Disclosure Design Principle\n\nSkills use a three-level loading system to manage context efficiently:\n\n1. **Metadata (name + description)** - Always in context (~100 words)\n2. **SKILL.md body** - When skill triggers (<5k words)\n3. **Bundled resources** - As needed by Codex (Unlimited because scripts can be executed without reading into context window)\n\n#### Progressive Disclosure Patterns\n\nKeep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.\n\n**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.\n\n**Pattern 1: High-level guide with references**\n\n```markdown\n# PDF Processing\n\n## Quick start\n\nExtract text with pdfplumber:\n[code example]\n\n## Advanced features\n\n- **Form filling**: See [FORMS.md](FORMS.md) for complete guide\n- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods\n- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns\n```\n\nCodex loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.\n\n**Pattern 2: Domain-specific organization**\n\nFor Skills with multiple domains, organize content by domain to avoid loading irrelevant context:\n\n```\nbigquery-skill/\n├── SKILL.md (overview and navigation)\n└── reference/\n    ├── finance.md (revenue, billing metrics)\n    ├── sales.md (opportunities, pipeline)\n    ├── product.md (API usage, features)\n    └── marketing.md (campaigns, attribution)\n```\n\nWhen a user asks about sales metrics, Codex only reads sales.md.\n\nSimilarly, for skills supporting multiple frameworks or variants, organize by variant:\n\n```\ncloud-deploy/\n├── SKILL.md (workflow + provider selection)\n└── references/\n    ├── aws.md (AWS deployment patterns)\n    ├── gcp.md (GCP deployment patterns)\n    └── azure.md (Azure deployment patterns)\n```\n\nWhen the user chooses AWS, Codex only reads aws.md.\n\n**Pattern 3: Conditional details**\n\nShow basic content, link to advanced content:\n\n```markdown\n# DOCX Processing\n\n## Creating documents\n\nUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).\n\n## Editing documents\n\nFor simple edits, modify the XML directly.\n\n**For tracked changes**: See [REDLINING.md](REDLINING.md)\n**For OOXML details**: See [OOXML.md](OOXML.md)\n```\n\nCodex reads REDLINING.md or OOXML.md only when the user needs those features.\n\n**Important guidelines:**\n\n- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.\n- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Codex can see the full scope when previewing.\n\n## Skill Creation Process\n\nSkill creation involves these steps:\n\n1. Understand the skill with concrete examples\n2. Plan reusable skill contents (scripts, references, assets)\n3. Initialize the skill (run init_skill.py)\n4. Edit the skill (implement resources and write SKILL.md)\n5. Package the skill (run package_skill.py)\n6. Iterate based on real usage\n\nFollow these steps in order, skipping only if there is a clear reason why they are not applicable.\n\n### Skill Naming\n\n- Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., \"Plan Mode\" -> `plan-mode`).\n- When generating names, generate a name under 64 characters (letters, digits, hyphens).\n- Prefer short, verb-led phrases that describe the action.\n- Namespace by tool when it improves clarity or triggering (e.g., `gh-address-comments`, `linear-address-issue`).\n- Name the skill folder exactly after the skill name.\n\n### Step 1: Understanding the Skill with Concrete Examples\n\nSkip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.\n\nTo create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.\n\nFor example, when building an image-editor skill, relevant questions include:\n\n- \"What functionality should the image-editor skill support? Editing, rotating, anything else?\"\n- \"Can you give some examples of how this skill would be used?\"\n- \"I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?\"\n- \"What would a user say that should trigger this skill?\"\n\nTo avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.\n\nConclude this step when there is a clear sense of the functionality the skill should support.\n\n### Step 2: Planning the Reusable Skill Contents\n\nTo turn concrete examples into an effective skill, analyze each example by:\n\n1. Considering how to execute on the example from scratch\n2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly\n\nExample: When building a `pdf-editor` skill to handle queries like \"Help me rotate this PDF,\" the analysis shows:\n\n1. Rotating a PDF requires re-writing the same code each time\n2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill\n\nExample: When designing a `frontend-webapp-builder` skill for queries like \"Build me a todo app\" or \"Build me a dashboard to track my steps,\" the analysis shows:\n\n1. Writing a frontend webapp requires the same boilerplate HTML/React each time\n2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill\n\nExample: When building a `big-query` skill to handle queries like \"How many users have logged in today?\" the analysis shows:\n\n1. Querying BigQuery requires re-discovering the table schemas and relationships each time\n2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill\n\nTo establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.\n\n### Step 3: Initializing the Skill\n\nAt this point, it is time to actually create the skill.\n\nSkip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.\n\nWhen creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.\n\nUsage:\n\n```bash\nscripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]\n```\n\nExamples:\n\n```bash\nscripts/init_skill.py my-skill --path skills/public\nscripts/init_skill.py my-skill --path skills/public --resources scripts,references\nscripts/init_skill.py my-skill --path skills/public --resources scripts --examples\n```\n\nThe script:\n\n- Creates the skill directory at the specified path\n- Generates a SKILL.md template with proper frontmatter and TODO placeholders\n- Optionally creates resource directories based on `--resources`\n- Optionally adds example files when `--examples` is set\n\nAfter initialization, customize the SKILL.md and add resources as needed. If you used `--examples`, replace or delete placeholder files.\n\n### Step 4: Edit the Skill\n\nWhen editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Codex to use. Include information that would be beneficial and non-obvious to Codex. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Codex instance execute these tasks more effectively.\n\n#### Learn Proven Design Patterns\n\nConsult these helpful guides based on your skill's needs:\n\n- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic\n- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns\n\nThese files contain established best practices for effective skill design.\n\n#### Start with Reusable Skill Contents\n\nTo begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.\n\nAdded scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.\n\nIf you used `--examples`, delete any placeholder files that are not needed for the skill. Only create resource directories that are actually required.\n\n#### Update SKILL.md\n\n**Writing Guidelines:** Always use imperative/infinitive form.\n\n##### Frontmatter\n\nWrite the YAML frontmatter with `name` and `description`:\n\n- `name`: The skill name\n- `description`: This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.\n  - Include both what the Skill does and specific triggers/contexts for when to use it.\n  - Include all \"when to use\" information here - Not in the body. The body is only loaded after triggering, so \"When to Use This Skill\" sections in the body are not helpful to Codex.\n  - Example description for a `docx` skill: \"Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Codex needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks\"\n\nDo not include any other fields in YAML frontmatter.\n\n##### Body\n\nWrite instructions for using the skill and its bundled resources.\n\n### Step 5: Packaging a Skill\n\nOnce development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:\n\n```bash\nscripts/package_skill.py <path/to/skill-folder>\n```\n\nOptional output directory specification:\n\n```bash\nscripts/package_skill.py <path/to/skill-folder> ./dist\n```\n\nThe packaging script will:\n\n1. **Validate** the skill automatically, checking:\n   - YAML frontmatter format and required fields\n   - Skill naming conventions and directory structure\n   - Description completeness and quality\n   - File organization and resource references\n\n2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.\n\n   Security restriction: symlinks are rejected and packaging fails when any symlink is present.\n\nIf validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.\n\n### Step 6: Iterate\n\nAfter testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.\n\n**Iteration workflow:**\n\n1. Use the skill on real tasks\n2. Notice struggles or inefficiencies\n3. Identify how SKILL.md or bundled resources should be updated\n4. Implement changes and test again\n"},{"path":"license.txt","size":11358,"sha256":"cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30","contentType":"text/plain","content":"\n                                 Apache License\n                           Version 2.0, January 2004\n                        http://www.apache.org/licenses/\n\n   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n   1. Definitions.\n\n      \"License\" shall mean the terms and conditions for use, reproduction,\n      and distribution as defined by Sections 1 through 9 of this document.\n\n      \"Licensor\" shall mean the copyright owner or entity authorized by\n      the copyright owner that is granting the License.\n\n      \"Legal Entity\" shall mean the union of the acting entity and all\n      other entities that control, are controlled by, or are under common\n      control with that entity. For the purposes of this definition,\n      \"control\" means (i) the power, direct or indirect, to cause the\n      direction or management of such entity, whether by contract or\n      otherwise, or (ii) ownership of fifty percent (50%) or more of the\n      outstanding shares, or (iii) beneficial ownership of such entity.\n\n      \"You\" (or \"Your\") shall mean an individual or Legal Entity\n      exercising permissions granted by this License.\n\n      \"Source\" form shall mean the preferred form for making modifications,\n      including but not limited to software source code, documentation\n      source, and configuration files.\n\n      \"Object\" form shall mean any form resulting from mechanical\n      transformation or translation of a Source form, including but\n      not limited to compiled object code, generated documentation,\n      and conversions to other media types.\n\n      \"Work\" shall mean the work of authorship, whether in Source or\n      Object form, made available under the License, as indicated by a\n      copyright notice that is included in or attached to the work\n      (an example is provided in the Appendix below).\n\n      \"Derivative Works\" shall mean any work, whether in Source or Object\n      form, that is based on (or derived from) the Work and for which the\n      editorial revisions, annotations, elaborations, or other modifications\n      represent, as a whole, an original work of authorship. For the purposes\n      of this License, Derivative Works shall not include works that remain\n      separable from, or merely link (or bind by name) to the interfaces of,\n      the Work and Derivative Works thereof.\n\n      \"Contribution\" shall mean any work of authorship, including\n      the original version of the Work and any modifications or additions\n      to that Work or Derivative Works thereof, that is intentionally\n      submitted to Licensor for inclusion in the Work by the copyright owner\n      or by an individual or Legal Entity authorized to submit on behalf of\n      the copyright owner. For the purposes of this definition, \"submitted\"\n      means any form of electronic, verbal, or written communication sent\n      to the Licensor or its representatives, including but not limited to\n      communication on electronic mailing lists, source code control systems,\n      and issue tracking systems that are managed by, or on behalf of, the\n      Licensor for the purpose of discussing and improving the Work, but\n      excluding communication that is conspicuously marked or otherwise\n      designated in writing by the copyright owner as \"Not a Contribution.\"\n\n      \"Contributor\" shall mean Licensor and any individual or Legal Entity\n      on behalf of whom a Contribution has been received by Licensor and\n      subsequently incorporated within the Work.\n\n   2. Grant of Copyright License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      copyright license to reproduce, prepare Derivative Works of,\n      publicly display, publicly perform, sublicense, and distribute the\n      Work and such Derivative Works in Source or Object form.\n\n   3. Grant of Patent License. Subject to the terms and conditions of\n      this License, each Contributor hereby grants to You a perpetual,\n      worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n      (except as stated in this section) patent license to make, have made,\n      use, offer to sell, sell, import, and otherwise transfer the Work,\n      where such license applies only to those patent claims licensable\n      by such Contributor that are necessarily infringed by their\n      Contribution(s) alone or by combination of their Contribution(s)\n      with the Work to which such Contribution(s) was submitted. If You\n      institute patent litigation against any entity (including a\n      cross-claim or counterclaim in a lawsuit) alleging that the Work\n      or a Contribution incorporated within the Work constitutes direct\n      or contributory patent infringement, then any patent licenses\n      granted to You under this License for that Work shall terminate\n      as of the date such litigation is filed.\n\n   4. Redistribution. You may reproduce and distribute copies of the\n      Work or Derivative Works thereof in any medium, with or without\n      modifications, and in Source or Object form, provided that You\n      meet the following conditions:\n\n      (a) You must give any other recipients of the Work or\n          Derivative Works a copy of this License; and\n\n      (b) You must cause any modified files to carry prominent notices\n          stating that You changed the files; and\n\n      (c) You must retain, in the Source form of any Derivative Works\n          that You distribute, all copyright, patent, trademark, and\n          attribution notices from the Source form of the Work,\n          excluding those notices that do not pertain to any part of\n          the Derivative Works; and\n\n      (d) If the Work includes a \"NOTICE\" text file as part of its\n          distribution, then any Derivative Works that You distribute must\n          include a readable copy of the attribution notices contained\n          within such NOTICE file, excluding those notices that do not\n          pertain to any part of the Derivative Works, in at least one\n          of the following places: within a NOTICE text file distributed\n          as part of the Derivative Works; within the Source form or\n          documentation, if provided along with the Derivative Works; or,\n          within a display generated by the Derivative Works, if and\n          wherever such third-party notices normally appear. The contents\n          of the NOTICE file are for informational purposes only and\n          do not modify the License. You may add Your own attribution\n          notices within Derivative Works that You distribute, alongside\n          or as an addendum to the NOTICE text from the Work, provided\n          that such additional attribution notices cannot be construed\n          as modifying the License.\n\n      You may add Your own copyright statement to Your modifications and\n      may provide additional or different license terms and conditions\n      for use, reproduction, or distribution of Your modifications, or\n      for any such Derivative Works as a whole, provided Your use,\n      reproduction, and distribution of the Work otherwise complies with\n      the conditions stated in this License.\n\n   5. Submission of Contributions. Unless You explicitly state otherwise,\n      any Contribution intentionally submitted for inclusion in the Work\n      by You to the Licensor shall be under the terms and conditions of\n      this License, without any additional terms or conditions.\n      Notwithstanding the above, nothing herein shall supersede or modify\n      the terms of any separate license agreement you may have executed\n      with Licensor regarding such Contributions.\n\n   6. Trademarks. This License does not grant permission to use the trade\n      names, trademarks, service marks, or product names of the Licensor,\n      except as required for reasonable and customary use in describing the\n      origin of the Work and reproducing the content of the NOTICE file.\n\n   7. Disclaimer of Warranty. Unless required by applicable law or\n      agreed to in writing, Licensor provides the Work (and each\n      Contributor provides its Contributions) on an \"AS IS\" BASIS,\n      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n      implied, including, without limitation, any warranties or conditions\n      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n      PARTICULAR PURPOSE. You are solely responsible for determining the\n      appropriateness of using or redistributing the Work and assume any\n      risks associated with Your exercise of permissions under this License.\n\n   8. Limitation of Liability. In no event and under no legal theory,\n      whether in tort (including negligence), contract, or otherwise,\n      unless required by applicable law (such as deliberate and grossly\n      negligent acts) or agreed to in writing, shall any Contributor be\n      liable to You for damages, including any direct, indirect, special,\n      incidental, or consequential damages of any character arising as a\n      result of this License or out of the use or inability to use the\n      Work (including but not limited to damages for loss of goodwill,\n      work stoppage, computer failure or malfunction, or any and all\n      other commercial damages or losses), even if such Contributor\n      has been advised of the possibility of such damages.\n\n   9. Accepting Warranty or Additional Liability. While redistributing\n      the Work or Derivative Works thereof, You may choose to offer,\n      and charge a fee for, acceptance of support, warranty, indemnity,\n      or other liability obligations and/or rights consistent with this\n      License. However, in accepting such obligations, You may act only\n      on Your own behalf and on Your sole responsibility, not on behalf\n      of any other Contributor, and only if You agree to indemnify,\n      defend, and hold each Contributor harmless for any liability\n      incurred by, or claims asserted against, such Contributor by reason\n      of your accepting any such warranty or additional liability.\n\n   END OF TERMS AND CONDITIONS\n\n   APPENDIX: How to apply the Apache License to your work.\n\n      To apply the Apache License to your work, attach the following\n      boilerplate notice, with the fields enclosed by brackets \"[]\"\n      replaced with your own identifying information. (Don't include\n      the brackets!)  The text should be enclosed in the appropriate\n      comment syntax for the file format. We also recommend that a\n      file or class name and description of purpose be included on the\n      same \"printed page\" as the copyright notice for easier\n      identification within third-party archives.\n\n   Copyright [yyyy] [name of copyright owner]\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n"},{"path":"scripts/init_skill.py","size":13753,"sha256":"bcd6b802c400a9e89319844c6c3d965855c8b0555e982eb72cd4accb7ee67e3e","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nSkill Initializer - Creates a new skill from template\n\nUsage:\n    init_skill.py <skill-name> --path <path> [--resources scripts,references,assets] [--examples]\n\nExamples:\n    init_skill.py my-new-skill --path skills/public\n    init_skill.py my-new-skill --path skills/public --resources scripts,references\n    init_skill.py my-api-helper --path skills/private --resources scripts --examples\n    init_skill.py custom-skill --path /custom/location\n\"\"\"\n\nimport argparse\nimport re\nimport sys\nfrom pathlib import Path\n\nMAX_SKILL_NAME_LENGTH = 64\nALLOWED_RESOURCES = {\"scripts\", \"references\", \"assets\"}\n\nSKILL_TEMPLATE = \"\"\"---\nname: {skill_name}\ndescription: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]\n---\n\n# {skill_title}\n\n## Overview\n\n[TODO: 1-2 sentences explaining what this skill enables]\n\n## Structuring This Skill\n\n[TODO: Choose the structure that best fits this skill's purpose. Common patterns:\n\n**1. Workflow-Based** (best for sequential processes)\n- Works well when there are clear step-by-step procedures\n- Example: DOCX skill with \"Workflow Decision Tree\" -> \"Reading\" -> \"Creating\" -> \"Editing\"\n- Structure: ## Overview -> ## Workflow Decision Tree -> ## Step 1 -> ## Step 2...\n\n**2. Task-Based** (best for tool collections)\n- Works well when the skill offers different operations/capabilities\n- Example: PDF skill with \"Quick Start\" -> \"Merge PDFs\" -> \"Split PDFs\" -> \"Extract Text\"\n- Structure: ## Overview -> ## Quick Start -> ## Task Category 1 -> ## Task Category 2...\n\n**3. Reference/Guidelines** (best for standards or specifications)\n- Works well for brand guidelines, coding standards, or requirements\n- Example: Brand styling with \"Brand Guidelines\" -> \"Colors\" -> \"Typography\" -> \"Features\"\n- Structure: ## Overview -> ## Guidelines -> ## Specifications -> ## Usage...\n\n**4. Capabilities-Based** (best for integrated systems)\n- Works well when the skill provides multiple interrelated features\n- Example: Product Management with \"Core Capabilities\" -> numbered capability list\n- Structure: ## Overview -> ## Core Capabilities -> ### 1. Feature -> ### 2. Feature...\n\nPatterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).\n\nDelete this entire \"Structuring This Skill\" section when done - it's just guidance.]\n\n## [TODO: Replace with the first main section based on chosen structure]\n\n[TODO: Add content here. See examples in existing skills:\n- Code samples for technical skills\n- Decision trees for complex workflows\n- Concrete examples with realistic user requests\n- References to scripts/templates/references as needed]\n\n## Resources (optional)\n\nCreate only the resource directories this skill actually needs. Delete this section if no resources are required.\n\n### scripts/\nExecutable code (Python/Bash/etc.) that can be run directly to perform specific operations.\n\n**Examples from other skills:**\n- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation\n- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing\n\n**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.\n\n**Note:** Scripts may be executed without loading into context, but can still be read by Codex for patching or environment adjustments.\n\n### references/\nDocumentation and reference material intended to be loaded into context to inform Codex's process and thinking.\n\n**Examples from other skills:**\n- Product management: `communication.md`, `context_building.md` - detailed workflow guides\n- BigQuery: API reference documentation and query examples\n- Finance: Schema documentation, company policies\n\n**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Codex should reference while working.\n\n### assets/\nFiles not intended to be loaded into context, but rather used within the output Codex produces.\n\n**Examples from other skills:**\n- Brand styling: PowerPoint template files (.pptx), logo files\n- Frontend builder: HTML/React boilerplate project directories\n- Typography: Font files (.ttf, .woff2)\n\n**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.\n\n---\n\n**Not every skill requires all three types of resources.**\n\"\"\"\n\nEXAMPLE_SCRIPT = '''#!/usr/bin/env python3\n\"\"\"\nExample helper script for {skill_name}\n\nThis is a placeholder script that can be executed directly.\nReplace with actual implementation or delete if not needed.\n\nExample real scripts from other skills:\n- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields\n- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images\n\"\"\"\n\ndef main():\n    print(\"This is an example script for {skill_name}\")\n    # TODO: Add actual script logic here\n    # This could be data processing, file conversion, API calls, etc.\n\nif __name__ == \"__main__\":\n    main()\n'''\n\nEXAMPLE_REFERENCE = \"\"\"# Reference Documentation for {skill_title}\n\nThis is a placeholder for detailed reference documentation.\nReplace with actual reference content or delete if not needed.\n\nExample real reference docs from other skills:\n- product-management/references/communication.md - Comprehensive guide for status updates\n- product-management/references/context_building.md - Deep-dive on gathering context\n- bigquery/references/ - API references and query examples\n\n## When Reference Docs Are Useful\n\nReference docs are ideal for:\n- Comprehensive API documentation\n- Detailed workflow guides\n- Complex multi-step processes\n- Information too lengthy for main SKILL.md\n- Content that's only needed for specific use cases\n\n## Structure Suggestions\n\n### API Reference Example\n- Overview\n- Authentication\n- Endpoints with examples\n- Error codes\n- Rate limits\n\n### Workflow Guide Example\n- Prerequisites\n- Step-by-step instructions\n- Common patterns\n- Troubleshooting\n- Best practices\n\"\"\"\n\nEXAMPLE_ASSET = \"\"\"# Example Asset File\n\nThis placeholder represents where asset files would be stored.\nReplace with actual asset files (templates, images, fonts, etc.) or delete if not needed.\n\nAsset files are NOT intended to be loaded into context, but rather used within\nthe output Codex produces.\n\nExample asset files from other skills:\n- Brand guidelines: logo.png, slides_template.pptx\n- Frontend builder: hello-world/ directory with HTML/React boilerplate\n- Typography: custom-font.ttf, font-family.woff2\n- Data: sample_data.csv, test_dataset.json\n\n## Common Asset Types\n\n- Templates: .pptx, .docx, boilerplate directories\n- Images: .png, .jpg, .svg, .gif\n- Fonts: .ttf, .otf, .woff, .woff2\n- Boilerplate code: Project directories, starter files\n- Icons: .ico, .svg\n- Data files: .csv, .json, .xml, .yaml\n\nNote: This is a text placeholder. Actual assets can be any file type.\n\"\"\"\n\n\ndef normalize_skill_name(skill_name):\n    \"\"\"Normalize a skill name to lowercase hyphen-case.\"\"\"\n    normalized = skill_name.strip().lower()\n    normalized = re.sub(r\"[^a-z0-9]+\", \"-\", normalized)\n    normalized = normalized.strip(\"-\")\n    normalized = re.sub(r\"-{2,}\", \"-\", normalized)\n    return normalized\n\n\ndef title_case_skill_name(skill_name):\n    \"\"\"Convert hyphenated skill name to Title Case for display.\"\"\"\n    return \" \".join(word.capitalize() for word in skill_name.split(\"-\"))\n\n\ndef parse_resources(raw_resources):\n    if not raw_resources:\n        return []\n    resources = [item.strip() for item in raw_resources.split(\",\") if item.strip()]\n    invalid = sorted({item for item in resources if item not in ALLOWED_RESOURCES})\n    if invalid:\n        allowed = \", \".join(sorted(ALLOWED_RESOURCES))\n        print(f\"[ERROR] Unknown resource type(s): {', '.join(invalid)}\")\n        print(f\"   Allowed: {allowed}\")\n        sys.exit(1)\n    deduped = []\n    seen = set()\n    for resource in resources:\n        if resource not in seen:\n            deduped.append(resource)\n            seen.add(resource)\n    return deduped\n\n\ndef create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples):\n    for resource in resources:\n        resource_dir = skill_dir / resource\n        resource_dir.mkdir(exist_ok=True)\n        if resource == \"scripts\":\n            if include_examples:\n                example_script = resource_dir / \"example.py\"\n                example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))\n                example_script.chmod(0o755)\n                print(\"[OK] Created scripts/example.py\")\n            else:\n                print(\"[OK] Created scripts/\")\n        elif resource == \"references\":\n            if include_examples:\n                example_reference = resource_dir / \"api_reference.md\"\n                example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))\n                print(\"[OK] Created references/api_reference.md\")\n            else:\n                print(\"[OK] Created references/\")\n        elif resource == \"assets\":\n            if include_examples:\n                example_asset = resource_dir / \"example_asset.txt\"\n                example_asset.write_text(EXAMPLE_ASSET)\n                print(\"[OK] Created assets/example_asset.txt\")\n            else:\n                print(\"[OK] Created assets/\")\n\n\ndef init_skill(skill_name, path, resources, include_examples):\n    \"\"\"\n    Initialize a new skill directory with template SKILL.md.\n\n    Args:\n        skill_name: Name of the skill\n        path: Path where the skill directory should be created\n        resources: Resource directories to create\n        include_examples: Whether to create example files in resource directories\n\n    Returns:\n        Path to created skill directory, or None if error\n    \"\"\"\n    # Determine skill directory path\n    skill_dir = Path(path).resolve() / skill_name\n\n    # Check if directory already exists\n    if skill_dir.exists():\n        print(f\"[ERROR] Skill directory already exists: {skill_dir}\")\n        return None\n\n    # Create skill directory\n    try:\n        skill_dir.mkdir(parents=True, exist_ok=False)\n        print(f\"[OK] Created skill directory: {skill_dir}\")\n    except Exception as e:\n        print(f\"[ERROR] Error creating directory: {e}\")\n        return None\n\n    # Create SKILL.md from template\n    skill_title = title_case_skill_name(skill_name)\n    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)\n\n    skill_md_path = skill_dir / \"SKILL.md\"\n    try:\n        skill_md_path.write_text(skill_content)\n        print(\"[OK] Created SKILL.md\")\n    except Exception as e:\n        print(f\"[ERROR] Error creating SKILL.md: {e}\")\n        return None\n\n    # Create resource directories if requested\n    if resources:\n        try:\n            create_resource_dirs(skill_dir, skill_name, skill_title, resources, include_examples)\n        except Exception as e:\n            print(f\"[ERROR] Error creating resource directories: {e}\")\n            return None\n\n    # Print next steps\n    print(f\"\\n[OK] Skill '{skill_name}' initialized successfully at {skill_dir}\")\n    print(\"\\nNext steps:\")\n    print(\"1. Edit SKILL.md to complete the TODO items and update the description\")\n    if resources:\n        if include_examples:\n            print(\"2. Customize or delete the example files in scripts/, references/, and assets/\")\n        else:\n            print(\"2. Add resources to scripts/, references/, and assets/ as needed\")\n    else:\n        print(\"2. Create resource directories only if needed (scripts/, references/, assets/)\")\n    print(\"3. Run the validator when ready to check the skill structure\")\n\n    return skill_dir\n\n\ndef main():\n    parser = argparse.ArgumentParser(\n        description=\"Create a new skill directory with a SKILL.md template.\",\n    )\n    parser.add_argument(\"skill_name\", help=\"Skill name (normalized to hyphen-case)\")\n    parser.add_argument(\"--path\", required=True, help=\"Output directory for the skill\")\n    parser.add_argument(\n        \"--resources\",\n        default=\"\",\n        help=\"Comma-separated list: scripts,references,assets\",\n    )\n    parser.add_argument(\n        \"--examples\",\n        action=\"store_true\",\n        help=\"Create example files inside the selected resource directories\",\n    )\n    args = parser.parse_args()\n\n    raw_skill_name = args.skill_name\n    skill_name = normalize_skill_name(raw_skill_name)\n    if not skill_name:\n        print(\"[ERROR] Skill name must include at least one letter or digit.\")\n        sys.exit(1)\n    if len(skill_name) > MAX_SKILL_NAME_LENGTH:\n        print(\n            f\"[ERROR] Skill name '{skill_name}' is too long ({len(skill_name)} characters). \"\n            f\"Maximum is {MAX_SKILL_NAME_LENGTH} characters.\"\n        )\n        sys.exit(1)\n    if skill_name != raw_skill_name:\n        print(f\"Note: Normalized skill name from '{raw_skill_name}' to '{skill_name}'.\")\n\n    resources = parse_resources(args.resources)\n    if args.examples and not resources:\n        print(\"[ERROR] --examples requires --resources to be set.\")\n        sys.exit(1)\n\n    path = args.path\n\n    print(f\"Initializing skill: {skill_name}\")\n    print(f\"   Location: {path}\")\n    if resources:\n        print(f\"   Resources: {', '.join(resources)}\")\n        if args.examples:\n            print(\"   Examples: enabled\")\n    else:\n        print(\"   Resources: none (create as needed)\")\n    print()\n\n    result = init_skill(skill_name, path, resources, args.examples)\n\n    if result:\n        sys.exit(0)\n    else:\n        sys.exit(1)\n\n\nif __name__ == \"__main__\":\n    main()\n"},{"path":"scripts/package_skill.py","size":4398,"sha256":"f290101073ee6a167f46edadda164d2c88affc03c554135fe101a4e422c44c22","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nSkill Packager - Creates a distributable .skill file of a skill folder\n\nUsage:\n    python utils/package_skill.py <path/to/skill-folder> [output-directory]\n\nExample:\n    python utils/package_skill.py skills/public/my-skill\n    python utils/package_skill.py skills/public/my-skill ./dist\n\"\"\"\n\nimport sys\nimport zipfile\nfrom pathlib import Path\n\nfrom quick_validate import validate_skill\n\n\ndef _is_within(path: Path, root: Path) -> bool:\n    try:\n        path.relative_to(root)\n        return True\n    except ValueError:\n        return False\n\n\ndef package_skill(skill_path, output_dir=None):\n    \"\"\"\n    Package a skill folder into a .skill file.\n\n    Args:\n        skill_path: Path to the skill folder\n        output_dir: Optional output directory for the .skill file (defaults to current directory)\n\n    Returns:\n        Path to the created .skill file, or None if error\n    \"\"\"\n    skill_path = Path(skill_path).resolve()\n\n    # Validate skill folder exists\n    if not skill_path.exists():\n        print(f\"[ERROR] Skill folder not found: {skill_path}\")\n        return None\n\n    if not skill_path.is_dir():\n        print(f\"[ERROR] Path is not a directory: {skill_path}\")\n        return None\n\n    # Validate SKILL.md exists\n    skill_md = skill_path / \"SKILL.md\"\n    if not skill_md.exists():\n        print(f\"[ERROR] SKILL.md not found in {skill_path}\")\n        return None\n\n    # Run validation before packaging\n    print(\"Validating skill...\")\n    valid, message = validate_skill(skill_path)\n    if not valid:\n        print(f\"[ERROR] Validation failed: {message}\")\n        print(\"   Please fix the validation errors before packaging.\")\n        return None\n    print(f\"[OK] {message}\\n\")\n\n    # Determine output location\n    skill_name = skill_path.name\n    if output_dir:\n        output_path = Path(output_dir).resolve()\n        output_path.mkdir(parents=True, exist_ok=True)\n    else:\n        output_path = Path.cwd()\n\n    skill_filename = output_path / f\"{skill_name}.skill\"\n\n    EXCLUDED_DIRS = {\".git\", \".svn\", \".hg\", \"__pycache__\", \"node_modules\"}\n\n    # Create the .skill file (zip format)\n    try:\n        with zipfile.ZipFile(skill_filename, \"w\", zipfile.ZIP_DEFLATED) as zipf:\n            # Walk through the skill directory\n            for file_path in skill_path.rglob(\"*\"):\n                # Security: never follow or package symlinks.\n                if file_path.is_symlink():\n                    print(f\"[WARN] Skipping symlink: {file_path}\")\n                    continue\n\n                rel_parts = file_path.relative_to(skill_path).parts\n                if any(part in EXCLUDED_DIRS for part in rel_parts):\n                    continue\n\n                if file_path.is_file():\n                    resolved_file = file_path.resolve()\n                    if not _is_within(resolved_file, skill_path):\n                        print(f\"[ERROR] File escapes skill root: {file_path}\")\n                        return None\n                    # If output lives under skill_path, avoid writing archive into itself.\n                    if resolved_file == skill_filename.resolve():\n                        print(f\"[WARN] Skipping output archive: {file_path}\")\n                        continue\n\n                    # Calculate the relative path within the zip.\n                    arcname = Path(skill_name) / file_path.relative_to(skill_path)\n                    zipf.write(file_path, arcname)\n                    print(f\"  Added: {arcname}\")\n\n        print(f\"\\n[OK] Successfully packaged skill to: {skill_filename}\")\n        return skill_filename\n\n    except Exception as e:\n        print(f\"[ERROR] Error creating .skill file: {e}\")\n        return None\n\n\ndef main():\n    if len(sys.argv) < 2:\n        print(\"Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]\")\n        print(\"\\nExample:\")\n        print(\"  python utils/package_skill.py skills/public/my-skill\")\n        print(\"  python utils/package_skill.py skills/public/my-skill ./dist\")\n        sys.exit(1)\n\n    skill_path = sys.argv[1]\n    output_dir = sys.argv[2] if len(sys.argv) > 2 else None\n\n    print(f\"Packaging skill: {skill_path}\")\n    if output_dir:\n        print(f\"   Output directory: {output_dir}\")\n    print()\n\n    result = package_skill(skill_path, output_dir)\n\n    if result:\n        sys.exit(0)\n    else:\n        sys.exit(1)\n\n\nif __name__ == \"__main__\":\n    main()\n"},{"path":"scripts/quick_validate.py","size":5189,"sha256":"3e3cdceba2daa893e260551c8c5f09937f94be1153307185c7fc7c24c0896750","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nQuick validation script for skills - minimal version\n\"\"\"\n\nimport re\nimport sys\nfrom pathlib import Path\nfrom typing import Optional\n\ntry:\n    import yaml\nexcept ModuleNotFoundError:\n    yaml = None\n\nMAX_SKILL_NAME_LENGTH = 64\n\n\ndef _extract_frontmatter(content: str) -> Optional[str]:\n    lines = content.splitlines()\n    if not lines or lines[0].strip() != \"---\":\n        return None\n    for i in range(1, len(lines)):\n        if lines[i].strip() == \"---\":\n            return \"\\n\".join(lines[1:i])\n    return None\n\n\ndef _parse_simple_frontmatter(frontmatter_text: str) -> Optional[dict[str, str]]:\n    \"\"\"\n    Minimal fallback parser used when PyYAML is unavailable.\n    Supports simple `key: value` mappings used by SKILL.md frontmatter.\n    \"\"\"\n    parsed: dict[str, str] = {}\n    current_key: Optional[str] = None\n    for raw_line in frontmatter_text.splitlines():\n        stripped = raw_line.strip()\n        if not stripped or stripped.startswith(\"#\"):\n            continue\n\n        is_indented = raw_line[:1].isspace()\n        if is_indented:\n            if current_key is None:\n                return None\n            current_value = parsed[current_key]\n            parsed[current_key] = (\n                f\"{current_value}\\n{stripped}\" if current_value else stripped\n            )\n            continue\n\n        if \":\" not in stripped:\n            return None\n        key, value = stripped.split(\":\", 1)\n        key = key.strip()\n        value = value.strip()\n        if not key:\n            return None\n        if (value.startswith('\"') and value.endswith('\"')) or (\n            value.startswith(\"'\") and value.endswith(\"'\")\n        ):\n            value = value[1:-1]\n        parsed[key] = value\n        current_key = key\n    return parsed\n\n\ndef validate_skill(skill_path):\n    \"\"\"Basic validation of a skill\"\"\"\n    skill_path = Path(skill_path)\n\n    skill_md = skill_path / \"SKILL.md\"\n    if not skill_md.exists():\n        return False, \"SKILL.md not found\"\n\n    try:\n        content = skill_md.read_text(encoding=\"utf-8\")\n    except OSError as e:\n        return False, f\"Could not read SKILL.md: {e}\"\n\n    frontmatter_text = _extract_frontmatter(content)\n    if frontmatter_text is None:\n        return False, \"Invalid frontmatter format\"\n    if yaml is not None:\n        try:\n            frontmatter = yaml.safe_load(frontmatter_text)\n            if not isinstance(frontmatter, dict):\n                return False, \"Frontmatter must be a YAML dictionary\"\n        except yaml.YAMLError as e:\n            return False, f\"Invalid YAML in frontmatter: {e}\"\n    else:\n        frontmatter = _parse_simple_frontmatter(frontmatter_text)\n        if frontmatter is None:\n            return (\n                False,\n                \"Invalid YAML in frontmatter: unsupported syntax without PyYAML installed\",\n            )\n\n    allowed_properties = {\"name\", \"description\", \"license\", \"allowed-tools\", \"metadata\"}\n\n    unexpected_keys = set(frontmatter.keys()) - allowed_properties\n    if unexpected_keys:\n        allowed = \", \".join(sorted(allowed_properties))\n        unexpected = \", \".join(sorted(unexpected_keys))\n        return (\n            False,\n            f\"Unexpected key(s) in SKILL.md frontmatter: {unexpected}. Allowed properties are: {allowed}\",\n        )\n\n    if \"name\" not in frontmatter:\n        return False, \"Missing 'name' in frontmatter\"\n    if \"description\" not in frontmatter:\n        return False, \"Missing 'description' in frontmatter\"\n\n    name = frontmatter.get(\"name\", \"\")\n    if not isinstance(name, str):\n        return False, f\"Name must be a string, got {type(name).__name__}\"\n    name = name.strip()\n    if name:\n        if not re.match(r\"^[a-z0-9-]+$\", name):\n            return (\n                False,\n                f\"Name '{name}' should be hyphen-case (lowercase letters, digits, and hyphens only)\",\n            )\n        if name.startswith(\"-\") or name.endswith(\"-\") or \"--\" in name:\n            return (\n                False,\n                f\"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens\",\n            )\n        if len(name) > MAX_SKILL_NAME_LENGTH:\n            return (\n                False,\n                f\"Name is too long ({len(name)} characters). \"\n                f\"Maximum is {MAX_SKILL_NAME_LENGTH} characters.\",\n            )\n\n    description = frontmatter.get(\"description\", \"\")\n    if not isinstance(description, str):\n        return False, f\"Description must be a string, got {type(description).__name__}\"\n    description = description.strip()\n    if description:\n        if \"<\" in description or \">\" in description:\n            return False, \"Description cannot contain angle brackets (< or >)\"\n        if len(description) > 1024:\n            return (\n                False,\n                f\"Description is too long ({len(description)} characters). Maximum is 1024 characters.\",\n            )\n\n    return True, \"Skill is valid!\"\n\n\nif __name__ == \"__main__\":\n    if len(sys.argv) != 2:\n        print(\"Usage: python quick_validate.py <skill_directory>\")\n        sys.exit(1)\n\n    valid, message = validate_skill(sys.argv[1])\n    print(message)\n    sys.exit(0 if valid else 1)\n"},{"path":"scripts/test_package_skill.py","size":5866,"sha256":"6b261a50fe632846e59e96b1c3e1f6787ffd534f7204d14bd7df8784873ac691","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nRegression tests for skill packaging security behavior.\n\"\"\"\n\nimport sys\nimport tempfile\nimport types\nimport zipfile\nfrom pathlib import Path\nfrom unittest import TestCase, main\nfrom unittest.mock import patch\n\nSCRIPT_DIR = Path(__file__).resolve().parent\nif str(SCRIPT_DIR) not in sys.path:\n    sys.path.insert(0, str(SCRIPT_DIR))\n\n\nfake_quick_validate = types.ModuleType(\"quick_validate\")\nfake_quick_validate.validate_skill = lambda _path: (True, \"Skill is valid!\")\noriginal_quick_validate = sys.modules.get(\"quick_validate\")\nsys.modules[\"quick_validate\"] = fake_quick_validate\n\nimport package_skill as package_skill_module\nfrom package_skill import package_skill\n\nif original_quick_validate is not None:\n    sys.modules[\"quick_validate\"] = original_quick_validate\nelse:\n    sys.modules.pop(\"quick_validate\", None)\n\n\nclass TestPackageSkillSecurity(TestCase):\n    def setUp(self):\n        self.temp_dir = Path(tempfile.mkdtemp(prefix=\"test_skill_\"))\n\n    def tearDown(self):\n        import shutil\n\n        if self.temp_dir.exists():\n            shutil.rmtree(self.temp_dir)\n\n    def create_skill(self, name=\"test-skill\"):\n        skill_dir = self.temp_dir / name\n        skill_dir.mkdir(parents=True, exist_ok=True)\n        (skill_dir / \"SKILL.md\").write_text(\"---\\nname: test-skill\\ndescription: test\\n---\\n\")\n        (skill_dir / \"script.py\").write_text(\"print('ok')\\n\")\n        return skill_dir\n\n    def test_packages_normal_files(self):\n        skill_dir = self.create_skill(\"normal-skill\")\n        out_dir = self.temp_dir / \"out\"\n        out_dir.mkdir()\n\n        result = package_skill(str(skill_dir), str(out_dir))\n\n        self.assertIsNotNone(result)\n        skill_file = out_dir / \"normal-skill.skill\"\n        self.assertTrue(skill_file.exists())\n        with zipfile.ZipFile(skill_file, \"r\") as archive:\n            names = set(archive.namelist())\n        self.assertIn(\"normal-skill/SKILL.md\", names)\n        self.assertIn(\"normal-skill/script.py\", names)\n\n    def test_skips_symlink_to_external_file(self):\n        skill_dir = self.create_skill(\"symlink-file-skill\")\n        outside = self.temp_dir / \"outside-secret.txt\"\n        outside.write_text(\"super-secret\\n\")\n        link = skill_dir / \"loot.txt\"\n        out_dir = self.temp_dir / \"out\"\n        out_dir.mkdir()\n\n        try:\n            link.symlink_to(outside)\n        except (OSError, NotImplementedError):\n            self.skipTest(\"symlink unsupported on this platform\")\n\n        result = package_skill(str(skill_dir), str(out_dir))\n        self.assertIsNotNone(result)\n        skill_file = out_dir / \"symlink-file-skill.skill\"\n        self.assertTrue(skill_file.exists())\n        with zipfile.ZipFile(skill_file, \"r\") as archive:\n            names = set(archive.namelist())\n        self.assertIn(\"symlink-file-skill/SKILL.md\", names)\n        self.assertIn(\"symlink-file-skill/script.py\", names)\n        self.assertNotIn(\"symlink-file-skill/loot.txt\", names)\n\n    def test_skips_symlink_directory(self):\n        skill_dir = self.create_skill(\"symlink-dir-skill\")\n        outside_dir = self.temp_dir / \"outside\"\n        outside_dir.mkdir()\n        (outside_dir / \"secret.txt\").write_text(\"secret\\n\")\n        link = skill_dir / \"docs\"\n        out_dir = self.temp_dir / \"out\"\n        out_dir.mkdir()\n\n        try:\n            link.symlink_to(outside_dir, target_is_directory=True)\n        except (OSError, NotImplementedError):\n            self.skipTest(\"symlink unsupported on this platform\")\n\n        result = package_skill(str(skill_dir), str(out_dir))\n        self.assertIsNotNone(result)\n        skill_file = out_dir / \"symlink-dir-skill.skill\"\n        with zipfile.ZipFile(skill_file, \"r\") as archive:\n            names = set(archive.namelist())\n        self.assertIn(\"symlink-dir-skill/SKILL.md\", names)\n        self.assertIn(\"symlink-dir-skill/script.py\", names)\n        self.assertNotIn(\"symlink-dir-skill/docs/secret.txt\", names)\n\n    def test_rejects_resolved_path_outside_skill_root(self):\n        skill_dir = self.create_skill(\"escape-skill\")\n        out_dir = self.temp_dir / \"out\"\n        out_dir.mkdir()\n\n        original_within = package_skill_module._is_within\n\n        def fake_is_within(path_obj: Path, root: Path):\n            if path_obj.name == \"script.py\":\n                return False\n            return original_within(path_obj, root)\n\n        with patch.object(package_skill_module, \"_is_within\", fake_is_within):\n            result = package_skill(str(skill_dir), str(out_dir))\n\n        self.assertIsNone(result)\n\n    def test_allows_nested_regular_files(self):\n        skill_dir = self.create_skill(\"nested-skill\")\n        nested = skill_dir / \"lib\" / \"helpers\"\n        nested.mkdir(parents=True, exist_ok=True)\n        (nested / \"util.py\").write_text(\"def run():\\n    return 1\\n\")\n        out_dir = self.temp_dir / \"out\"\n        out_dir.mkdir()\n\n        result = package_skill(str(skill_dir), str(out_dir))\n\n        self.assertIsNotNone(result)\n        skill_file = out_dir / \"nested-skill.skill\"\n        with zipfile.ZipFile(skill_file, \"r\") as archive:\n            names = set(archive.namelist())\n        self.assertIn(\"nested-skill/lib/helpers/util.py\", names)\n\n    def test_skips_output_archive_when_output_dir_is_skill_dir(self):\n        skill_dir = self.create_skill(\"self-output-skill\")\n\n        result = package_skill(str(skill_dir), str(skill_dir))\n\n        self.assertIsNotNone(result)\n        skill_file = skill_dir / \"self-output-skill.skill\"\n        self.assertTrue(skill_file.exists())\n        with zipfile.ZipFile(skill_file, \"r\") as archive:\n            names = set(archive.namelist())\n        self.assertIn(\"self-output-skill/SKILL.md\", names)\n        self.assertIn(\"self-output-skill/script.py\", names)\n        self.assertNotIn(\"self-output-skill/self-output-skill.skill\", names)\n\n\nif __name__ == \"__main__\":\n    main()\n"},{"path":"scripts/test_quick_validate.py","size":2078,"sha256":"27b4dd7308cf7eb8ebb10ac61ea0e3171e7c4ae6c9578d2a27046d4cac22782d","contentType":"text/plain","content":"#!/usr/bin/env python3\n\"\"\"\nRegression tests for quick skill validation.\n\"\"\"\n\nimport tempfile\nfrom pathlib import Path\nfrom unittest import TestCase, main\n\nimport quick_validate\n\n\nclass TestQuickValidate(TestCase):\n    def setUp(self):\n        self.temp_dir = Path(tempfile.mkdtemp(prefix=\"test_quick_validate_\"))\n\n    def tearDown(self):\n        import shutil\n\n        if self.temp_dir.exists():\n            shutil.rmtree(self.temp_dir)\n\n    def test_accepts_crlf_frontmatter(self):\n        skill_dir = self.temp_dir / \"crlf-skill\"\n        skill_dir.mkdir(parents=True, exist_ok=True)\n        content = \"---\\r\\nname: crlf-skill\\r\\ndescription: ok\\r\\n---\\r\\n# Skill\\r\\n\"\n        (skill_dir / \"SKILL.md\").write_text(content, encoding=\"utf-8\")\n\n        valid, message = quick_validate.validate_skill(skill_dir)\n\n        self.assertTrue(valid, message)\n\n    def test_rejects_missing_frontmatter_closing_fence(self):\n        skill_dir = self.temp_dir / \"bad-skill\"\n        skill_dir.mkdir(parents=True, exist_ok=True)\n        content = \"---\\nname: bad-skill\\ndescription: missing end\\n# no closing fence\\n\"\n        (skill_dir / \"SKILL.md\").write_text(content, encoding=\"utf-8\")\n\n        valid, message = quick_validate.validate_skill(skill_dir)\n\n        self.assertFalse(valid)\n        self.assertEqual(message, \"Invalid frontmatter format\")\n\n    def test_fallback_parser_handles_multiline_frontmatter_without_pyyaml(self):\n        skill_dir = self.temp_dir / \"multiline-skill\"\n        skill_dir.mkdir(parents=True, exist_ok=True)\n        content = \"\"\"---\nname: multiline-skill\ndescription: Works without pyyaml\nallowed-tools:\n  - gh\nmetadata: |\n  {\n    \"owners\": [\"team-hanzo-bot\"]\n  }\n---\n# Skill\n\"\"\"\n        (skill_dir / \"SKILL.md\").write_text(content, encoding=\"utf-8\")\n\n        previous_yaml = quick_validate.yaml\n        quick_validate.yaml = None\n        try:\n            valid, message = quick_validate.validate_skill(skill_dir)\n        finally:\n            quick_validate.yaml = previous_yaml\n\n        self.assertTrue(valid, message)\n\n\nif __name__ == \"__main__\":\n    main()\n"}]},{"slug":"slack","displayName":"slack","summary":"Use when you need to control Slack from HanzoBot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.","version":"1.0.0","sha256hash":"e4d7f8402dcbdb86ae5c0cce3841d74289083cb41db9ae0dde2709c899dad6c8","files":[{"path":"SKILL.md","size":2502,"sha256":"2af77b10f0b85f2d27fa88b4aff7ac199a1b8766687a4713786a459fde8fff8a","contentType":"text/markdown","content":"---\nname: slack\ndescription: Use when you need to control Slack from HanzoBot via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.\nmetadata: { \"hanzo-bot\": { \"emoji\": \"💬\", \"requires\": { \"config\": [\"channels.slack\"] } } }\n---\n\n# Slack Actions\n\n## Overview\n\nUse `slack` to react, manage pins, send/edit/delete messages, and fetch member info. The tool uses the bot token configured for HanzoBot.\n\n## Inputs to collect\n\n- `channelId` and `messageId` (Slack message timestamp, e.g. `1712023032.1234`).\n- For reactions, an `emoji` (Unicode or `:name:`).\n- For message sends, a `to` target (`channel:<id>` or `user:<id>`) and `content`.\n\nMessage context lines include `slack message id` and `channel` fields you can reuse directly.\n\n## Actions\n\n### Action groups\n\n| Action group | Default | Notes                  |\n| ------------ | ------- | ---------------------- |\n| reactions    | enabled | React + list reactions |\n| messages     | enabled | Read/send/edit/delete  |\n| pins         | enabled | Pin/unpin/list         |\n| memberInfo   | enabled | Member info            |\n| emojiList    | enabled | Custom emoji list      |\n\n### React to a message\n\n```json\n{\n  \"action\": \"react\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\",\n  \"emoji\": \"✅\"\n}\n```\n\n### List reactions\n\n```json\n{\n  \"action\": \"reactions\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\"\n}\n```\n\n### Send a message\n\n```json\n{\n  \"action\": \"sendMessage\",\n  \"to\": \"channel:C123\",\n  \"content\": \"Hello from HanzoBot\"\n}\n```\n\n### Edit a message\n\n```json\n{\n  \"action\": \"editMessage\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\",\n  \"content\": \"Updated text\"\n}\n```\n\n### Delete a message\n\n```json\n{\n  \"action\": \"deleteMessage\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\"\n}\n```\n\n### Read recent messages\n\n```json\n{\n  \"action\": \"readMessages\",\n  \"channelId\": \"C123\",\n  \"limit\": 20\n}\n```\n\n### Pin a message\n\n```json\n{\n  \"action\": \"pinMessage\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\"\n}\n```\n\n### Unpin a message\n\n```json\n{\n  \"action\": \"unpinMessage\",\n  \"channelId\": \"C123\",\n  \"messageId\": \"1712023032.1234\"\n}\n```\n\n### List pinned items\n\n```json\n{\n  \"action\": \"listPins\",\n  \"channelId\": \"C123\"\n}\n```\n\n### Member info\n\n```json\n{\n  \"action\": \"memberInfo\",\n  \"userId\": \"U123\"\n}\n```\n\n### Emoji list\n\n```json\n{\n  \"action\": \"emojiList\"\n}\n```\n\n## Ideas to try\n\n- React with ✅ to mark completed tasks.\n- Pin key decisions or weekly status updates.\n"}]},{"slug":"songsee","displayName":"songsee","summary":"Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.","version":"1.0.0","sha256hash":"9e781a0af162e41f9fc89276bfec5bf590959af17ab9459c188401ce3a1cfac0","files":[{"path":"SKILL.md","size":1315,"sha256":"eecde21e0ed2779de055b4fa0d743c13f0f79b96f113ec3c73a58582fc6e0142","contentType":"text/markdown","content":"---\nname: songsee\ndescription: Generate spectrograms and feature-panel visualizations from audio with the songsee CLI.\nhomepage: https://github.com/steipete/songsee\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🌊\",\n        \"requires\": { \"bins\": [\"songsee\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/songsee\",\n              \"bins\": [\"songsee\"],\n              \"label\": \"Install songsee (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# songsee\n\nGenerate spectrograms + feature panels from audio.\n\nQuick start\n\n- Spectrogram: `songsee track.mp3`\n- Multi-panel: `songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux`\n- Time slice: `songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg`\n- Stdin: `cat track.mp3 | songsee - --format png -o out.png`\n\nCommon flags\n\n- `--viz` list (repeatable or comma-separated)\n- `--style` palette (classic, magma, inferno, viridis, gray)\n- `--width` / `--height` output size\n- `--window` / `--hop` FFT settings\n- `--min-freq` / `--max-freq` frequency range\n- `--start` / `--duration` time slice\n- `--format` jpg|png\n\nNotes\n\n- WAV/MP3 decode native; other formats use ffmpeg if available.\n- Multiple `--viz` renders a grid.\n"}]},{"slug":"sonoscli","displayName":"sonoscli","summary":"Control Sonos speakers (discover/status/play/volume/group).","version":"1.0.0","sha256hash":"faeab39f8f6fb1230c4ba9a1d44b2e8189f08cedd77b10e231b6d2213918c6e5","files":[{"path":"SKILL.md","size":2456,"sha256":"e47ecb1c6f2c68c72a66f79999a64fcdeb473f0f425e92fff7221f1ed179b323","contentType":"text/markdown","content":"---\nname: sonoscli\ndescription: Control Sonos speakers (discover/status/play/volume/group).\nhomepage: https://sonoscli.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🔊\",\n        \"requires\": { \"bins\": [\"sonos\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/sonoscli/cmd/sonos@latest\",\n              \"bins\": [\"sonos\"],\n              \"label\": \"Install sonoscli (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# Sonos CLI\n\nUse `sonos` to control Sonos speakers on the local network.\n\n## Quick start\n\n- `sonos discover`\n- `sonos status --name \"Kitchen\"`\n- `sonos play|pause|stop --name \"Kitchen\"`\n- `sonos volume set 15 --name \"Kitchen\"`\n\n## Common tasks\n\n- Grouping: `sonos group status|join|unjoin|party|solo`\n- Favorites: `sonos favorites list|open`\n- Queue: `sonos queue list|play|clear`\n- Spotify search (via SMAPI): `sonos smapi search --service \"Spotify\" --category tracks \"query\"`\n\n## Notes\n\n- If SSDP fails, specify `--ip <speaker-ip>`.\n- Spotify Web API search is optional and requires `SPOTIFY_CLIENT_ID/SECRET`.\n- If there is an error, check the troubleshooting section and offer advice if there is a decent match.\n\n## Troubleshooting\n\n### `sonos discover` - `no route to host`\n\n- On error `Error: write udp4 0.0.0.0:64326->239.255.255.250:1900: sendto: no route to host (Command exited with code 1)`\n  - Note that the port number after `0.0.0.0:` is ephemeral and will change and the netmask may not match exactly either\n  - The `sendto: no route to host` should stay consistent\n- Advise the user that in `direct` (no Docker sandbox) mode on Mac OS that Settings -> Privacy & Security -> Local Network will need to be enabled for the top-level host parent process of the Gateway\n  - `node` if running via `launchd`\n  - `Terminal` if running the gateway directly in the terminal\n  - `Visual Studio Code` if running via terminal in VS Code\n- An alternative option is to use `sandbox` (docker container) with network access allowed for that sandbox\n\n### `sonos discover` - `bind: operation not permitted`\n\n- On error `Error: listen udp4 0.0.0.0:0: bind: operation not permitted`\n- Advise the user that they may be running via a Codex or other sandbox that does not permit network access (this can be replicated by running `sonos discover` within a Codex CLI session with sandbox enabled and not approving the escalation request)\n"}]},{"slug":"spotify-player","displayName":"spotify-player","summary":"Terminal Spotify playback/search via spogo (preferred) or spotify_player.","version":"1.0.0","sha256hash":"da13ba2994193847451741862f12b80216522d2a3dca08c7c7c0d3f9bd33f80e","files":[{"path":"SKILL.md","size":1687,"sha256":"7532ebc48fc20f0b572080adf53929fea2b0c8adf9f39e5bf1ca16067c43c9ca","contentType":"text/markdown","content":"---\nname: spotify-player\ndescription: Terminal Spotify playback/search via spogo (preferred) or spotify_player.\nhomepage: https://www.spotify.com\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🎵\",\n        \"requires\": { \"anyBins\": [\"spogo\", \"spotify_player\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"spogo\",\n              \"tap\": \"steipete/tap\",\n              \"bins\": [\"spogo\"],\n              \"label\": \"Install spogo (brew)\",\n            },\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"spotify_player\",\n              \"bins\": [\"spotify_player\"],\n              \"label\": \"Install spotify_player (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# spogo / spotify_player\n\nUse `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.\n\nRequirements\n\n- Spotify Premium account.\n- Either `spogo` or `spotify_player` installed.\n\nspogo setup\n\n- Import cookies: `spogo auth import --browser chrome`\n\nCommon CLI commands\n\n- Search: `spogo search track \"query\"`\n- Playback: `spogo play|pause|next|prev`\n- Devices: `spogo device list`, `spogo device set \"<name|id>\"`\n- Status: `spogo status`\n\nspotify_player commands (fallback)\n\n- Search: `spotify_player search \"query\"`\n- Playback: `spotify_player playback play|pause|next|previous`\n- Connect device: `spotify_player connect`\n- Like track: `spotify_player like`\n\nNotes\n\n- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).\n- For Spotify Connect integration, set a user `client_id` in config.\n- TUI shortcuts are available via `?` in the app.\n"}]},{"slug":"summarize","displayName":"summarize","summary":"Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).","version":"1.0.0","sha256hash":"ed8cec1f2cf0e65792f81654cd9cda080ca682a693845cb63e9be0cd99a39e58","files":[{"path":"SKILL.md","size":2233,"sha256":"cd813e842c8fcd08235d029e830698fb83c54e023c64eac9887fc6d5682e2778","contentType":"text/markdown","content":"---\nname: summarize\ndescription: Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).\nhomepage: https://summarize.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🧾\",\n        \"requires\": { \"bins\": [\"summarize\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/summarize\",\n              \"bins\": [\"summarize\"],\n              \"label\": \"Install summarize (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Summarize\n\nFast CLI to summarize URLs, local files, and YouTube links.\n\n## When to use (trigger phrases)\n\nUse this skill immediately when the user asks any of:\n\n- “use summarize.sh”\n- “what’s this link/video about?”\n- “summarize this URL/article”\n- “transcribe this YouTube/video” (best-effort transcript extraction; no `yt-dlp` needed)\n\n## Quick start\n\n```bash\nsummarize \"https://example.com\" --model google/gemini-3-flash-preview\nsummarize \"/path/to/file.pdf\" --model google/gemini-3-flash-preview\nsummarize \"https://youtu.be/dQw4w9WgXcQ\" --youtube auto\n```\n\n## YouTube: summary vs transcript\n\nBest-effort transcript (URLs only):\n\n```bash\nsummarize \"https://youtu.be/dQw4w9WgXcQ\" --youtube auto --extract-only\n```\n\nIf the user asked for a transcript but it’s huge, return a tight summary first, then ask which section/time range to expand.\n\n## Model + keys\n\nSet the API key for your chosen provider:\n\n- OpenAI: `OPENAI_API_KEY`\n- Anthropic: `ANTHROPIC_API_KEY`\n- xAI: `XAI_API_KEY`\n- Google: `GEMINI_API_KEY` (aliases: `GOOGLE_GENERATIVE_AI_API_KEY`, `GOOGLE_API_KEY`)\n\nDefault model is `google/gemini-3-flash-preview` if none is set.\n\n## Useful flags\n\n- `--length short|medium|long|xl|xxl|<chars>`\n- `--max-output-tokens <count>`\n- `--extract-only` (URLs only)\n- `--json` (machine readable)\n- `--firecrawl auto|off|always` (fallback extraction)\n- `--youtube auto` (Apify fallback if `APIFY_API_TOKEN` set)\n\n## Config\n\nOptional config file: `~/.summarize/config.json`\n\n```json\n{ \"model\": \"openai/gpt-5.2\" }\n```\n\nOptional services:\n\n- `FIRECRAWL_API_KEY` for blocked sites\n- `APIFY_API_TOKEN` for YouTube fallback\n"}]},{"slug":"things-mac","displayName":"things-mac","summary":"Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks HanzoBot to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.","version":"1.0.0","sha256hash":"11ac7ca25ed1e10714711d21533104a0b57290601999d9747ec00402fcb75722","files":[{"path":"SKILL.md","size":3556,"sha256":"e9ed4ebd8c047712ea2b6d64806daa6fbf7a7fcd6013c02028357de0c5a55f07","contentType":"text/markdown","content":"---\nname: things-mac\ndescription: Manage Things 3 via the `things` CLI on macOS (add/update projects+todos via URL scheme; read/search/list from the local Things database). Use when a user asks HanzoBot to add a task to Things, list inbox/today/upcoming, search tasks, or inspect projects/areas/tags.\nhomepage: https://github.com/ossianhempel/things3-cli\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"✅\",\n        \"os\": [\"darwin\"],\n        \"requires\": { \"bins\": [\"things\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/ossianhempel/things3-cli/cmd/things@latest\",\n              \"bins\": [\"things\"],\n              \"label\": \"Install things3-cli (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# Things 3 CLI\n\nUse `things` to read your local Things database (inbox/today/search/projects/areas/tags) and to add/update todos via the Things URL scheme.\n\nSetup\n\n- Install (recommended, Apple Silicon): `GOBIN=/opt/homebrew/bin go install github.com/ossianhempel/things3-cli/cmd/things@latest`\n- If DB reads fail: grant **Full Disk Access** to the calling app (Terminal for manual runs; `HanzoBot.app` for gateway runs).\n- Optional: set `THINGSDB` (or pass `--db`) to point at your `ThingsData-*` folder.\n- Optional: set `THINGS_AUTH_TOKEN` to avoid passing `--auth-token` for update ops.\n\nRead-only (DB)\n\n- `things inbox --limit 50`\n- `things today`\n- `things upcoming`\n- `things search \"query\"`\n- `things projects` / `things areas` / `things tags`\n\nWrite (URL scheme)\n\n- Prefer safe preview: `things --dry-run add \"Title\"`\n- Add: `things add \"Title\" --notes \"...\" --when today --deadline 2026-01-02`\n- Bring Things to front: `things --foreground add \"Title\"`\n\nExamples: add a todo\n\n- Basic: `things add \"Buy milk\"`\n- With notes: `things add \"Buy milk\" --notes \"2% + bananas\"`\n- Into a project/area: `things add \"Book flights\" --list \"Travel\"`\n- Into a project heading: `things add \"Pack charger\" --list \"Travel\" --heading \"Before\"`\n- With tags: `things add \"Call dentist\" --tags \"health,phone\"`\n- Checklist: `things add \"Trip prep\" --checklist-item \"Passport\" --checklist-item \"Tickets\"`\n- From STDIN (multi-line => title + notes):\n  - `cat <<'EOF' | things add -`\n  - `Title line`\n  - `Notes line 1`\n  - `Notes line 2`\n  - `EOF`\n\nExamples: modify a todo (needs auth token)\n\n- First: get the ID (UUID column): `things search \"milk\" --limit 5`\n- Auth: set `THINGS_AUTH_TOKEN` or pass `--auth-token <TOKEN>`\n- Title: `things update --id <UUID> --auth-token <TOKEN> \"New title\"`\n- Notes replace: `things update --id <UUID> --auth-token <TOKEN> --notes \"New notes\"`\n- Notes append/prepend: `things update --id <UUID> --auth-token <TOKEN> --append-notes \"...\"` / `--prepend-notes \"...\"`\n- Move lists: `things update --id <UUID> --auth-token <TOKEN> --list \"Travel\" --heading \"Before\"`\n- Tags replace/add: `things update --id <UUID> --auth-token <TOKEN> --tags \"a,b\"` / `things update --id <UUID> --auth-token <TOKEN> --add-tags \"a,b\"`\n- Complete/cancel (soft-delete-ish): `things update --id <UUID> --auth-token <TOKEN> --completed` / `--canceled`\n- Safe preview: `things --dry-run update --id <UUID> --auth-token <TOKEN> --completed`\n\nDelete a todo?\n\n- Not supported by `things3-cli` right now (no “delete/move-to-trash” write command; `things trash` is read-only listing).\n- Options: use Things UI to delete/trash, or mark as `--completed` / `--canceled` via `things update`.\n\nNotes\n\n- macOS-only.\n- `--dry-run` prints the URL and does not open Things.\n"}]},{"slug":"tmux","displayName":"tmux","summary":"Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.","version":"1.0.0","sha256hash":"c1b14d3fde36837365fbac67c8e5caf27f73bea5d14644c8e7ce684a20f999fa","files":[{"path":"SKILL.md","size":3486,"sha256":"b09f612cd4599840f5e460ab37e5cd7198b0d805c6103b2766708e643fde1580","contentType":"text/markdown","content":"---\nname: tmux\ndescription: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.\nmetadata:\n  { \"hanzo-bot\": { \"emoji\": \"🧵\", \"os\": [\"darwin\", \"linux\"], \"requires\": { \"bins\": [\"tmux\"] } } }\n---\n\n# tmux Session Control\n\nControl tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- Monitoring Claude/Codex sessions in tmux\n- Sending input to interactive terminal applications\n- Scraping output from long-running processes in tmux\n- Navigating tmux panes/windows programmatically\n- Checking on background work in existing sessions\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Running one-off shell commands → use `exec` tool directly\n- Starting new background processes → use `exec` with `background:true`\n- Non-interactive scripts → use `exec` tool\n- The process isn't in tmux\n- You need to create a new tmux session → use `exec` with `tmux new-session`\n\n## Example Sessions\n\n| Session                 | Purpose                     |\n| ----------------------- | --------------------------- |\n| `shared`                | Primary interactive session |\n| `worker-2` - `worker-8` | Parallel worker sessions    |\n\n## Common Commands\n\n### List Sessions\n\n```bash\ntmux list-sessions\ntmux ls\n```\n\n### Capture Output\n\n```bash\n# Last 20 lines of pane\ntmux capture-pane -t shared -p | tail -20\n\n# Entire scrollback\ntmux capture-pane -t shared -p -S -\n\n# Specific pane in window\ntmux capture-pane -t shared:0.0 -p\n```\n\n### Send Keys\n\n```bash\n# Send text (doesn't press Enter)\ntmux send-keys -t shared \"hello\"\n\n# Send text + Enter\ntmux send-keys -t shared \"y\" Enter\n\n# Send special keys\ntmux send-keys -t shared Enter\ntmux send-keys -t shared Escape\ntmux send-keys -t shared C-c          # Ctrl+C\ntmux send-keys -t shared C-d          # Ctrl+D (EOF)\ntmux send-keys -t shared C-z          # Ctrl+Z (suspend)\n```\n\n### Window/Pane Navigation\n\n```bash\n# Select window\ntmux select-window -t shared:0\n\n# Select pane\ntmux select-pane -t shared:0.1\n\n# List windows\ntmux list-windows -t shared\n```\n\n### Session Management\n\n```bash\n# Create new session\ntmux new-session -d -s newsession\n\n# Kill session\ntmux kill-session -t sessionname\n\n# Rename session\ntmux rename-session -t old new\n```\n\n## Sending Input Safely\n\nFor interactive TUIs (Claude Code, Codex, etc.), split text and Enter into separate sends to avoid paste/multiline edge cases:\n\n```bash\ntmux send-keys -t shared -l -- \"Please apply the patch in src/foo.ts\"\nsleep 0.1\ntmux send-keys -t shared Enter\n```\n\n## Claude Code Session Patterns\n\n### Check if Session Needs Input\n\n```bash\n# Look for prompts\ntmux capture-pane -t worker-3 -p | tail -10 | grep -E \"❯|Yes.*No|proceed|permission\"\n```\n\n### Approve Claude Code Prompt\n\n```bash\n# Send 'y' and Enter\ntmux send-keys -t worker-3 'y' Enter\n\n# Or select numbered option\ntmux send-keys -t worker-3 '2' Enter\n```\n\n### Check All Sessions Status\n\n```bash\nfor s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do\n  echo \"=== $s ===\"\n  tmux capture-pane -t $s -p 2>/dev/null | tail -5\ndone\n```\n\n### Send Task to Session\n\n```bash\ntmux send-keys -t worker-4 \"Fix the bug in auth.js\" Enter\n```\n\n## Notes\n\n- Use `capture-pane -p` to print to stdout (essential for scripting)\n- `-S -` captures entire scrollback history\n- Target format: `session:window.pane` (e.g., `shared:0.0`)\n- Sessions persist across SSH disconnects\n"},{"path":"scripts/find-sessions.sh","size":2965,"sha256":"469d4dedf81b1a7d5c0bbc9193b371875b2c91a3304b9ef8969a4bbad99d65e4","contentType":"text/plain","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat <<'USAGE'\nUsage: find-sessions.sh [-L socket-name|-S socket-path|-A] [-q pattern]\n\nList tmux sessions on a socket (default tmux socket if none provided).\n\nOptions:\n  -L, --socket       tmux socket name (passed to tmux -L)\n  -S, --socket-path  tmux socket path (passed to tmux -S)\n  -A, --all          scan all sockets under BOT_TMUX_SOCKET_DIR\n  -q, --query        case-insensitive substring to filter session names\n  -h, --help         show this help\nUSAGE\n}\n\nsocket_name=\"\"\nsocket_path=\"\"\nquery=\"\"\nscan_all=false\nsocket_dir=\"${BOT_TMUX_SOCKET_DIR:-${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/hanzo-bot-tmux-sockets}}\"\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    -L|--socket)      socket_name=\"${2-}\"; shift 2 ;;\n    -S|--socket-path) socket_path=\"${2-}\"; shift 2 ;;\n    -A|--all)         scan_all=true; shift ;;\n    -q|--query)       query=\"${2-}\"; shift 2 ;;\n    -h|--help)        usage; exit 0 ;;\n    *) echo \"Unknown option: $1\" >&2; usage; exit 1 ;;\n  esac\ndone\n\nif [[ \"$scan_all\" == true && ( -n \"$socket_name\" || -n \"$socket_path\" ) ]]; then\n  echo \"Cannot combine --all with -L or -S\" >&2\n  exit 1\nfi\n\nif [[ -n \"$socket_name\" && -n \"$socket_path\" ]]; then\n  echo \"Use either -L or -S, not both\" >&2\n  exit 1\nfi\n\nif ! command -v tmux >/dev/null 2>&1; then\n  echo \"tmux not found in PATH\" >&2\n  exit 1\nfi\n\nlist_sessions() {\n  local label=\"$1\"; shift\n  local tmux_cmd=(tmux \"$@\")\n\n  if ! sessions=\"$(\"${tmux_cmd[@]}\" list-sessions -F '#{session_name}\\t#{session_attached}\\t#{session_created_string}' 2>/dev/null)\"; then\n    echo \"No tmux server found on $label\" >&2\n    return 1\n  fi\n\n  if [[ -n \"$query\" ]]; then\n    sessions=\"$(printf '%s\\n' \"$sessions\" | grep -i -- \"$query\" || true)\"\n  fi\n\n  if [[ -z \"$sessions\" ]]; then\n    echo \"No sessions found on $label\"\n    return 0\n  fi\n\n  echo \"Sessions on $label:\"\n  printf '%s\\n' \"$sessions\" | while IFS=$'\\t' read -r name attached created; do\n    attached_label=$([[ \"$attached\" == \"1\" ]] && echo \"attached\" || echo \"detached\")\n    printf '  - %s (%s, started %s)\\n' \"$name\" \"$attached_label\" \"$created\"\n  done\n}\n\nif [[ \"$scan_all\" == true ]]; then\n  if [[ ! -d \"$socket_dir\" ]]; then\n    echo \"Socket directory not found: $socket_dir\" >&2\n    exit 1\n  fi\n\n  shopt -s nullglob\n  sockets=(\"$socket_dir\"/*)\n  shopt -u nullglob\n\n  if [[ \"${#sockets[@]}\" -eq 0 ]]; then\n    echo \"No sockets found under $socket_dir\" >&2\n    exit 1\n  fi\n\n  exit_code=0\n  for sock in \"${sockets[@]}\"; do\n    if [[ ! -S \"$sock\" ]]; then\n      continue\n    fi\n    list_sessions \"socket path '$sock'\" -S \"$sock\" || exit_code=$?\n  done\n  exit \"$exit_code\"\nfi\n\ntmux_cmd=(tmux)\nsocket_label=\"default socket\"\n\nif [[ -n \"$socket_name\" ]]; then\n  tmux_cmd+=(-L \"$socket_name\")\n  socket_label=\"socket name '$socket_name'\"\nelif [[ -n \"$socket_path\" ]]; then\n  tmux_cmd+=(-S \"$socket_path\")\n  socket_label=\"socket path '$socket_path'\"\nfi\n\nlist_sessions \"$socket_label\" \"${tmux_cmd[@]:1}\"\n"},{"path":"scripts/wait-for-text.sh","size":2139,"sha256":"96bc42702f7353c32233c223d61dd11f2f99033267aeefac838aea8983a67735","contentType":"text/plain","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat <<'USAGE'\nUsage: wait-for-text.sh -t target -p pattern [options]\n\nPoll a tmux pane for text and exit when found.\n\nOptions:\n  -t, --target    tmux target (session:window.pane), required\n  -p, --pattern   regex pattern to look for, required\n  -F, --fixed     treat pattern as a fixed string (grep -F)\n  -T, --timeout   seconds to wait (integer, default: 15)\n  -i, --interval  poll interval in seconds (default: 0.5)\n  -l, --lines     number of history lines to inspect (integer, default: 1000)\n  -h, --help      show this help\nUSAGE\n}\n\ntarget=\"\"\npattern=\"\"\ngrep_flag=\"-E\"\ntimeout=15\ninterval=0.5\nlines=1000\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    -t|--target)   target=\"${2-}\"; shift 2 ;;\n    -p|--pattern)  pattern=\"${2-}\"; shift 2 ;;\n    -F|--fixed)    grep_flag=\"-F\"; shift ;;\n    -T|--timeout)  timeout=\"${2-}\"; shift 2 ;;\n    -i|--interval) interval=\"${2-}\"; shift 2 ;;\n    -l|--lines)    lines=\"${2-}\"; shift 2 ;;\n    -h|--help)     usage; exit 0 ;;\n    *) echo \"Unknown option: $1\" >&2; usage; exit 1 ;;\n  esac\ndone\n\nif [[ -z \"$target\" || -z \"$pattern\" ]]; then\n  echo \"target and pattern are required\" >&2\n  usage\n  exit 1\nfi\n\nif ! [[ \"$timeout\" =~ ^[0-9]+$ ]]; then\n  echo \"timeout must be an integer number of seconds\" >&2\n  exit 1\nfi\n\nif ! [[ \"$lines\" =~ ^[0-9]+$ ]]; then\n  echo \"lines must be an integer\" >&2\n  exit 1\nfi\n\nif ! command -v tmux >/dev/null 2>&1; then\n  echo \"tmux not found in PATH\" >&2\n  exit 1\nfi\n\n# End time in epoch seconds (integer, good enough for polling)\nstart_epoch=$(date +%s)\ndeadline=$((start_epoch + timeout))\n\nwhile true; do\n  # -J joins wrapped lines, -S uses negative index to read last N lines\n  pane_text=\"$(tmux capture-pane -p -J -t \"$target\" -S \"-${lines}\" 2>/dev/null || true)\"\n\n  if printf '%s\\n' \"$pane_text\" | grep $grep_flag -- \"$pattern\" >/dev/null 2>&1; then\n    exit 0\n  fi\n\n  now=$(date +%s)\n  if (( now >= deadline )); then\n    echo \"Timed out after ${timeout}s waiting for pattern: $pattern\" >&2\n    echo \"Last ${lines} lines from $target:\" >&2\n    printf '%s\\n' \"$pane_text\" >&2\n    exit 1\n  fi\n\n  sleep \"$interval\"\ndone\n"}]},{"slug":"trello","displayName":"trello","summary":"Manage Trello boards, lists, and cards via the Trello REST API.","version":"1.0.0","sha256hash":"7fac3281c1451018a9b4b6a6155fca4df6e1ff2a1648a2f79e8113dfcdbb0584","files":[{"path":"SKILL.md","size":2688,"sha256":"b1f0254d656f528854815f2587fad8c8b3c0ad85c4e41b9819173474251ccc57","contentType":"text/markdown","content":"---\nname: trello\ndescription: Manage Trello boards, lists, and cards via the Trello REST API.\nhomepage: https://developer.atlassian.com/cloud/trello/rest/\nmetadata:\n  {\n    \"hanzo-bot\":\n      { \"emoji\": \"📋\", \"requires\": { \"bins\": [\"jq\"], \"env\": [\"TRELLO_API_KEY\", \"TRELLO_TOKEN\"] } },\n  }\n---\n\n# Trello Skill\n\nManage Trello boards, lists, and cards directly from HanzoBot.\n\n## Setup\n\n1. Get your API key: https://trello.com/app-key\n2. Generate a token (click \"Token\" link on that page)\n3. Set environment variables:\n   ```bash\n   export TRELLO_API_KEY=\"your-api-key\"\n   export TRELLO_TOKEN=\"your-token\"\n   ```\n\n## Usage\n\nAll commands use curl to hit the Trello REST API.\n\n### List boards\n\n```bash\ncurl -s \"https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" | jq '.[] | {name, id}'\n```\n\n### List lists in a board\n\n```bash\ncurl -s \"https://api.trello.com/1/boards/{boardId}/lists?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" | jq '.[] | {name, id}'\n```\n\n### List cards in a list\n\n```bash\ncurl -s \"https://api.trello.com/1/lists/{listId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" | jq '.[] | {name, id, desc}'\n```\n\n### Create a card\n\n```bash\ncurl -s -X POST \"https://api.trello.com/1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" \\\n  -d \"idList={listId}\" \\\n  -d \"name=Card Title\" \\\n  -d \"desc=Card description\"\n```\n\n### Move a card to another list\n\n```bash\ncurl -s -X PUT \"https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" \\\n  -d \"idList={newListId}\"\n```\n\n### Add a comment to a card\n\n```bash\ncurl -s -X POST \"https://api.trello.com/1/cards/{cardId}/actions/comments?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" \\\n  -d \"text=Your comment here\"\n```\n\n### Archive a card\n\n```bash\ncurl -s -X PUT \"https://api.trello.com/1/cards/{cardId}?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" \\\n  -d \"closed=true\"\n```\n\n## Notes\n\n- Board/List/Card IDs can be found in the Trello URL or via the list commands\n- The API key and token provide full access to your Trello account - keep them secret!\n- 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\n\n## Examples\n\n```bash\n# Get all boards\ncurl -s \"https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN&fields=name,id\" | jq\n\n# Find a specific board by name\ncurl -s \"https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" | jq '.[] | select(.name | contains(\"Work\"))'\n\n# Get all cards on a board\ncurl -s \"https://api.trello.com/1/boards/{boardId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\" | jq '.[] | {name, list: .idList}'\n```\n"}]},{"slug":"video-frames","displayName":"video-frames","summary":"Extract frames or short clips from videos using ffmpeg.","version":"1.0.0","sha256hash":"03d2e67a6b8bfbca4e29909081610b6a43ee899bc28621cf1ed2fac11b39fafd","files":[{"path":"SKILL.md","size":965,"sha256":"a37a0574840fb16c3aff9e1e5b746ae6c458b292f269ce29ee235e06b82690d3","contentType":"text/markdown","content":"---\nname: video-frames\ndescription: Extract frames or short clips from videos using ffmpeg.\nhomepage: https://ffmpeg.org\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"🎞️\",\n        \"requires\": { \"bins\": [\"ffmpeg\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"ffmpeg\",\n              \"bins\": [\"ffmpeg\"],\n              \"label\": \"Install ffmpeg (brew)\",\n            },\n          ],\n      },\n  }\n---\n\n# Video Frames (ffmpeg)\n\nExtract a single frame from a video, or create quick thumbnails for inspection.\n\n## Quick start\n\nFirst frame:\n\n```bash\n{baseDir}/scripts/frame.sh /path/to/video.mp4 --out /tmp/frame.jpg\n```\n\nAt a timestamp:\n\n```bash\n{baseDir}/scripts/frame.sh /path/to/video.mp4 --time 00:00:10 --out /tmp/frame-10s.jpg\n```\n\n## Notes\n\n- Prefer `--time` for “what is happening around here?”.\n- Use a `.jpg` for quick share; use `.png` for crisp UI frames.\n"},{"path":"scripts/frame.sh","size":1347,"sha256":"b339455e9e618c836ccf2e3732e4fec9897f079730d8814eadb716e2459df453","contentType":"text/plain","content":"#!/usr/bin/env bash\nset -euo pipefail\n\nusage() {\n  cat >&2 <<'EOF'\nUsage:\n  frame.sh <video-file> [--time HH:MM:SS] [--index N] --out /path/to/frame.jpg\n\nExamples:\n  frame.sh video.mp4 --out /tmp/frame.jpg\n  frame.sh video.mp4 --time 00:00:10 --out /tmp/frame-10s.jpg\n  frame.sh video.mp4 --index 0 --out /tmp/frame0.png\nEOF\n  exit 2\n}\n\nif [[ \"${1:-}\" == \"\" || \"${1:-}\" == \"-h\" || \"${1:-}\" == \"--help\" ]]; then\n  usage\nfi\n\nin=\"${1:-}\"\nshift || true\n\ntime=\"\"\nindex=\"\"\nout=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n  case \"$1\" in\n    --time)\n      time=\"${2:-}\"\n      shift 2\n      ;;\n    --index)\n      index=\"${2:-}\"\n      shift 2\n      ;;\n    --out)\n      out=\"${2:-}\"\n      shift 2\n      ;;\n    *)\n      echo \"Unknown arg: $1\" >&2\n      usage\n      ;;\n  esac\ndone\n\nif [[ ! -f \"$in\" ]]; then\n  echo \"File not found: $in\" >&2\n  exit 1\nfi\n\nif [[ \"$out\" == \"\" ]]; then\n  echo \"Missing --out\" >&2\n  usage\nfi\n\nmkdir -p \"$(dirname \"$out\")\"\n\nif [[ \"$index\" != \"\" ]]; then\n  ffmpeg -hide_banner -loglevel error -y \\\n    -i \"$in\" \\\n    -vf \"select=eq(n\\\\,${index})\" \\\n    -vframes 1 \\\n    \"$out\"\nelif [[ \"$time\" != \"\" ]]; then\n  ffmpeg -hide_banner -loglevel error -y \\\n    -ss \"$time\" \\\n    -i \"$in\" \\\n    -frames:v 1 \\\n    \"$out\"\nelse\n  ffmpeg -hide_banner -loglevel error -y \\\n    -i \"$in\" \\\n    -vf \"select=eq(n\\\\,0)\" \\\n    -vframes 1 \\\n    \"$out\"\nfi\n\necho \"$out\"\n"}]},{"slug":"voice-call","displayName":"voice-call","summary":"Start voice calls via the HanzoBot voice-call plugin.","version":"1.0.0","sha256hash":"b53735833da5949182c9ae343a9d238beed8179db1ba157f72e25d3a86312c72","files":[{"path":"SKILL.md","size":1162,"sha256":"9585206e9e90fe3893d97f8860c454b65cfe6047489c3d2c105f3e22e3b8cf02","contentType":"text/markdown","content":"---\nname: voice-call\ndescription: Start voice calls via the HanzoBot voice-call plugin.\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📞\",\n        \"skillKey\": \"voice-call\",\n        \"requires\": { \"config\": [\"plugins.entries.voice-call.enabled\"] },\n      },\n  }\n---\n\n# Voice Call\n\nUse the voice-call plugin to start or inspect calls (Twilio, Telnyx, Plivo, or mock).\n\n## CLI\n\n```bash\nhanzo-bot voicecall call --to \"+15555550123\" --message \"Hello from HanzoBot\"\nhanzo-bot voicecall status --call-id <id>\n```\n\n## Tool\n\nUse `voice_call` for agent-initiated calls.\n\nActions:\n\n- `initiate_call` (message, to?, mode?)\n- `continue_call` (callId, message)\n- `speak_to_user` (callId, message)\n- `end_call` (callId)\n- `get_status` (callId)\n\nNotes:\n\n- Requires the voice-call plugin to be enabled.\n- Plugin config lives under `plugins.entries.voice-call.config`.\n- Twilio config: `provider: \"twilio\"` + `twilio.accountSid/authToken` + `fromNumber`.\n- Telnyx config: `provider: \"telnyx\"` + `telnyx.apiKey/connectionId` + `fromNumber`.\n- Plivo config: `provider: \"plivo\"` + `plivo.authId/authToken` + `fromNumber`.\n- Dev fallback: `provider: \"mock\"` (no network).\n"}]},{"slug":"wacli","displayName":"wacli","summary":"Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).","version":"1.0.0","sha256hash":"6cf02af07faa9fed51e40cc5b92f39f2995f608a29bcbd9e0a2f98532f937c19","files":[{"path":"SKILL.md","size":2386,"sha256":"fd5e3bad4e1dc697f680e9c4593d0076b803807c59d3397a8ec9624cf873ec2b","contentType":"text/markdown","content":"---\nname: wacli\ndescription: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI (not for normal user chats).\nhomepage: https://wacli.sh\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"📱\",\n        \"requires\": { \"bins\": [\"wacli\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"steipete/tap/wacli\",\n              \"bins\": [\"wacli\"],\n              \"label\": \"Install wacli (brew)\",\n            },\n            {\n              \"id\": \"go\",\n              \"kind\": \"go\",\n              \"module\": \"github.com/steipete/wacli/cmd/wacli@latest\",\n              \"bins\": [\"wacli\"],\n              \"label\": \"Install wacli (go)\",\n            },\n          ],\n      },\n  }\n---\n\n# wacli\n\nUse `wacli` only when the user explicitly asks you to message someone else on WhatsApp or when they ask to sync/search WhatsApp history.\nDo NOT use `wacli` for normal user chats; HanzoBot routes WhatsApp conversations automatically.\nIf the user is chatting with you on WhatsApp, you should not reach for this tool unless they ask you to contact a third party.\n\nSafety\n\n- Require explicit recipient + message text.\n- Confirm recipient + message before sending.\n- If anything is ambiguous, ask a clarifying question.\n\nAuth + sync\n\n- `wacli auth` (QR login + initial sync)\n- `wacli sync --follow` (continuous sync)\n- `wacli doctor`\n\nFind chats + messages\n\n- `wacli chats list --limit 20 --query \"name or number\"`\n- `wacli messages search \"query\" --limit 20 --chat <jid>`\n- `wacli messages search \"invoice\" --after 2025-01-01 --before 2025-12-31`\n\nHistory backfill\n\n- `wacli history backfill --chat <jid> --requests 2 --count 50`\n\nSend\n\n- Text: `wacli send text --to \"+14155551212\" --message \"Hello! Are you free at 3pm?\"`\n- Group: `wacli send text --to \"[email protected]\" --message \"Running 5 min late.\"`\n- File: `wacli send file --to \"+14155551212\" --file /path/agenda.pdf --caption \"Agenda\"`\n\nNotes\n\n- Store dir: `~/.wacli` (override with `--store`).\n- Use `--json` for machine-readable output when parsing.\n- Backfill requires your phone online; results are best-effort.\n- WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.\n- JIDs: direct chats look like `<number>@s.whatsapp.net`; groups look like `<id>@g.us` (use `wacli chats list` to find).\n"}]},{"slug":"weather","displayName":"weather","summary":"Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed.","version":"1.0.0","sha256hash":"58e461dedc2d86f1d1f415a25fafcd20fc17a256a14096bb4ae1ae479519c1db","files":[{"path":"SKILL.md","size":2292,"sha256":"71f6642c87eaafc2687ec674a454ba6d7660a10e5624d964fffb5977bbbeb3e8","contentType":"text/markdown","content":"---\nname: weather\ndescription: \"Get current weather and forecasts via wttr.in or Open-Meteo. Use when: user asks about weather, temperature, or forecasts for any location. NOT for: historical weather data, severe weather alerts, or detailed meteorological analysis. No API key needed.\"\nhomepage: https://wttr.in/:help\nmetadata: { \"hanzo-bot\": { \"emoji\": \"🌤️\", \"requires\": { \"bins\": [\"curl\"] } } }\n---\n\n# Weather Skill\n\nGet current weather conditions and forecasts.\n\n## When to Use\n\n✅ **USE this skill when:**\n\n- \"What's the weather?\"\n- \"Will it rain today/tomorrow?\"\n- \"Temperature in [city]\"\n- \"Weather forecast for the week\"\n- Travel planning weather checks\n\n## When NOT to Use\n\n❌ **DON'T use this skill when:**\n\n- Historical weather data → use weather archives/APIs\n- Climate analysis or trends → use specialized data sources\n- Hyper-local microclimate data → use local sensors\n- Severe weather alerts → check official NWS sources\n- Aviation/marine weather → use specialized services (METAR, etc.)\n\n## Location\n\nAlways include a city, region, or airport code in weather queries.\n\n## Commands\n\n### Current Weather\n\n```bash\n# One-line summary\ncurl \"wttr.in/London?format=3\"\n\n# Detailed current conditions\ncurl \"wttr.in/London?0\"\n\n# Specific city\ncurl \"wttr.in/New+York?format=3\"\n```\n\n### Forecasts\n\n```bash\n# 3-day forecast\ncurl \"wttr.in/London\"\n\n# Week forecast\ncurl \"wttr.in/London?format=v2\"\n\n# Specific day (0=today, 1=tomorrow, 2=day after)\ncurl \"wttr.in/London?1\"\n```\n\n### Format Options\n\n```bash\n# One-liner\ncurl \"wttr.in/London?format=%l:+%c+%t+%w\"\n\n# JSON output\ncurl \"wttr.in/London?format=j1\"\n\n# PNG image\ncurl \"wttr.in/London.png\"\n```\n\n### Format Codes\n\n- `%c` — Weather condition emoji\n- `%t` — Temperature\n- `%f` — \"Feels like\"\n- `%w` — Wind\n- `%h` — Humidity\n- `%p` — Precipitation\n- `%l` — Location\n\n## Quick Responses\n\n**\"What's the weather?\"**\n\n```bash\ncurl -s \"wttr.in/London?format=%l:+%c+%t+(feels+like+%f),+%w+wind,+%h+humidity\"\n```\n\n**\"Will it rain?\"**\n\n```bash\ncurl -s \"wttr.in/London?format=%l:+%c+%p\"\n```\n\n**\"Weekend forecast\"**\n\n```bash\ncurl \"wttr.in/London?format=v2\"\n```\n\n## Notes\n\n- No API key needed (uses wttr.in)\n- Rate limited; don't spam requests\n- Works for most global cities\n- Supports airport codes: `curl wttr.in/ORD`\n"}]},{"slug":"xurl","displayName":"xurl","summary":"A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint.","version":"1.0.0","sha256hash":"7071cc82f1409be8b78d86d9da9cb8616ea7867860b2c363cb6cfa901d97d10d","files":[{"path":"SKILL.md","size":14721,"sha256":"2113fc486b152abb0039ee5e95dcde7ed90cc35f322850b1cfe432b081343fcb","contentType":"text/markdown","content":"---\nname: xurl\ndescription: A CLI tool for making authenticated requests to the X (Twitter) API. Use this skill when you need to post tweets, reply, quote, search, read posts, manage followers, send DMs, upload media, or interact with any X API v2 endpoint.\nmetadata:\n  {\n    \"hanzo-bot\":\n      {\n        \"emoji\": \"𝕏\",\n        \"requires\": { \"bins\": [\"xurl\"] },\n        \"install\":\n          [\n            {\n              \"id\": \"brew\",\n              \"kind\": \"brew\",\n              \"formula\": \"xdevplatform/tap/xurl\",\n              \"bins\": [\"xurl\"],\n              \"label\": \"Install xurl (brew)\",\n            },\n            {\n              \"id\": \"npm\",\n              \"kind\": \"npm\",\n              \"package\": \"@xdevplatform/xurl\",\n              \"bins\": [\"xurl\"],\n              \"label\": \"Install xurl (npm)\",\n            },\n          ],\n      },\n  }\n---\n\n# xurl — Agent Skill Reference\n\n`xurl` is a CLI tool for the X API. It supports both **shortcut commands** (human/agent‑friendly one‑liners) and **raw curl‑style** access to any v2 endpoint. All commands return JSON to stdout.\n\n---\n\n## Installation\n\n### Homebrew (macOS)\n\n```bash\nbrew install --cask xdevplatform/tap/xurl\n```\n\n### npm\n\n```bash\nnpm install -g @xdevplatform/xurl\n```\n\n### Shell script\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash\n```\n\nInstalls to `~/.local/bin`. If it's not in your PATH, the script will tell you what to add.\n\n### Go\n\n```bash\ngo install github.com/xdevplatform/xurl@latest\n```\n\n---\n\n## Prerequisites\n\nThis skill requires the `xurl` CLI utility: <https://github.com/xdevplatform/xurl>.\n\nBefore using any command you must be authenticated. Run `xurl auth status` to check.\n\n### Secret Safety (Mandatory)\n\n- Never read, print, parse, summarize, upload, or send `~/.xurl` (or copies of it) to the LLM context.\n- Never ask the user to paste credentials/tokens into chat.\n- The user must fill `~/.xurl` with required secrets manually on their own machine.\n- Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.\n- Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).\n- Never use `--verbose` / `-v` in agent/LLM sessions; it can expose sensitive headers/tokens in output.\n- Sensitive flags that must never be used in agent commands: `--bearer-token`, `--consumer-key`, `--consumer-secret`, `--access-token`, `--token-secret`, `--client-id`, `--client-secret`.\n- To verify whether at least one app with credentials is already registered, run: `xurl auth status`.\n\n### Register an app (recommended)\n\nApp credential registration must be done manually by the user outside the agent/LLM session.\nAfter credentials are registered, authenticate with:\n\n```bash\nxurl auth oauth2\n```\n\nFor multiple pre-configured apps, switch between them:\n\n```bash\nxurl auth default prod-app          # set default app\nxurl auth default prod-app alice    # set default app + user\nxurl --app dev-app /2/users/me      # one-off override\n```\n\n### Other auth methods\n\nExamples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.\n\nTokens are persisted to `~/.xurl` in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right `Authorization` header.\n\n---\n\n## Quick Reference\n\n| Action                    | Command                                               |\n| ------------------------- | ----------------------------------------------------- |\n| Post                      | `xurl post \"Hello world!\"`                            |\n| Reply                     | `xurl reply POST_ID \"Nice post!\"`                     |\n| Quote                     | `xurl quote POST_ID \"My take\"`                        |\n| Delete a post             | `xurl delete POST_ID`                                 |\n| Read a post               | `xurl read POST_ID`                                   |\n| Search posts              | `xurl search \"QUERY\" -n 10`                           |\n| Who am I                  | `xurl whoami`                                         |\n| Look up a user            | `xurl user @handle`                                   |\n| Home timeline             | `xurl timeline -n 20`                                 |\n| Mentions                  | `xurl mentions -n 10`                                 |\n| Like                      | `xurl like POST_ID`                                   |\n| Unlike                    | `xurl unlike POST_ID`                                 |\n| Repost                    | `xurl repost POST_ID`                                 |\n| Undo repost               | `xurl unrepost POST_ID`                               |\n| Bookmark                  | `xurl bookmark POST_ID`                               |\n| Remove bookmark           | `xurl unbookmark POST_ID`                             |\n| List bookmarks            | `xurl bookmarks -n 10`                                |\n| List likes                | `xurl likes -n 10`                                    |\n| Follow                    | `xurl follow @handle`                                 |\n| Unfollow                  | `xurl unfollow @handle`                               |\n| List following            | `xurl following -n 20`                                |\n| List followers            | `xurl followers -n 20`                                |\n| Block                     | `xurl block @handle`                                  |\n| Unblock                   | `xurl unblock @handle`                                |\n| Mute                      | `xurl mute @handle`                                   |\n| Unmute                    | `xurl unmute @handle`                                 |\n| Send DM                   | `xurl dm @handle \"message\"`                           |\n| List DMs                  | `xurl dms -n 10`                                      |\n| Upload media              | `xurl media upload path/to/file.mp4`                  |\n| Media status              | `xurl media status MEDIA_ID`                          |\n| **App Management**        |                                                       |\n| Register app              | Manual, outside agent (do not pass secrets via agent) |\n| List apps                 | `xurl auth apps list`                                 |\n| Update app creds          | Manual, outside agent (do not pass secrets via agent) |\n| Remove app                | `xurl auth apps remove NAME`                          |\n| Set default (interactive) | `xurl auth default`                                   |\n| Set default (command)     | `xurl auth default APP_NAME [USERNAME]`               |\n| Use app per-request       | `xurl --app NAME /2/users/me`                         |\n| Auth status               | `xurl auth status`                                    |\n\n> **Post IDs vs URLs:** Anywhere `POST_ID` appears above you can also paste a full post URL (e.g. `https://x.com/user/status/1234567890`) — xurl extracts the ID automatically.\n\n> **Usernames:** Leading `@` is optional. `@elonmusk` and `elonmusk` both work.\n\n---\n\n## Command Details\n\n### Posting\n\n```bash\n# Simple post\nxurl post \"Hello world!\"\n\n# Post with media (upload first, then attach)\nxurl media upload photo.jpg          # → note the media_id from response\nxurl post \"Check this out\" --media-id MEDIA_ID\n\n# Multiple media\nxurl post \"Thread pics\" --media-id 111 --media-id 222\n\n# Reply to a post (by ID or URL)\nxurl reply 1234567890 \"Great point!\"\nxurl reply https://x.com/user/status/1234567890 \"Agreed!\"\n\n# Reply with media\nxurl reply 1234567890 \"Look at this\" --media-id MEDIA_ID\n\n# Quote a post\nxurl quote 1234567890 \"Adding my thoughts\"\n\n# Delete your own post\nxurl delete 1234567890\n```\n\n### Reading\n\n```bash\n# Read a single post (returns author, text, metrics, entities)\nxurl read 1234567890\nxurl read https://x.com/user/status/1234567890\n\n# Search recent posts (default 10 results)\nxurl search \"golang\"\nxurl search \"from:elonmusk\" -n 20\nxurl search \"#buildinpublic lang:en\" -n 15\n```\n\n### User Info\n\n```bash\n# Your own profile\nxurl whoami\n\n# Look up any user\nxurl user elonmusk\nxurl user @XDevelopers\n```\n\n### Timelines & Mentions\n\n```bash\n# Home timeline (reverse chronological)\nxurl timeline\nxurl timeline -n 25\n\n# Your mentions\nxurl mentions\nxurl mentions -n 20\n```\n\n### Engagement\n\n```bash\n# Like / unlike\nxurl like 1234567890\nxurl unlike 1234567890\n\n# Repost / undo\nxurl repost 1234567890\nxurl unrepost 1234567890\n\n# Bookmark / remove\nxurl bookmark 1234567890\nxurl unbookmark 1234567890\n\n# List your bookmarks / likes\nxurl bookmarks -n 20\nxurl likes -n 20\n```\n\n### Social Graph\n\n```bash\n# Follow / unfollow\nxurl follow @XDevelopers\nxurl unfollow @XDevelopers\n\n# List who you follow / your followers\nxurl following -n 50\nxurl followers -n 50\n\n# List another user's following/followers\nxurl following --of elonmusk -n 20\nxurl followers --of elonmusk -n 20\n\n# Block / unblock\nxurl block @spammer\nxurl unblock @spammer\n\n# Mute / unmute\nxurl mute @annoying\nxurl unmute @annoying\n```\n\n### Direct Messages\n\n```bash\n# Send a DM\nxurl dm @someuser \"Hey, saw your post!\"\n\n# List recent DM events\nxurl dms\nxurl dms -n 25\n```\n\n### Media Upload\n\n```bash\n# Upload a file (auto‑detects type for images/videos)\nxurl media upload photo.jpg\nxurl media upload video.mp4\n\n# Specify type and category explicitly\nxurl media upload --media-type image/jpeg --category tweet_image photo.jpg\n\n# Check processing status (videos need server‑side processing)\nxurl media status MEDIA_ID\nxurl media status --wait MEDIA_ID    # poll until done\n\n# Full workflow: upload then post\nxurl media upload meme.png           # response includes media id\nxurl post \"lol\" --media-id MEDIA_ID\n```\n\n---\n\n## Global Flags\n\nThese flags work on every command:\n\n| Flag         | Short | Description                                                        |\n| ------------ | ----- | ------------------------------------------------------------------ |\n| `--app`      |       | Use a specific registered app for this request (overrides default) |\n| `--auth`     |       | Force auth type: `oauth1`, `oauth2`, or `app`                      |\n| `--username` | `-u`  | Which OAuth2 account to use (if you have multiple)                 |\n| `--verbose`  | `-v`  | Forbidden in agent/LLM sessions (can leak auth headers/tokens)     |\n| `--trace`    | `-t`  | Add `X-B3-Flags: 1` trace header                                   |\n\n---\n\n## Raw API Access\n\nThe shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with **any** X API v2 endpoint:\n\n```bash\n# GET request (default)\nxurl /2/users/me\n\n# POST with JSON body\nxurl -X POST /2/tweets -d '{\"text\":\"Hello world!\"}'\n\n# PUT, PATCH, DELETE\nxurl -X DELETE /2/tweets/1234567890\n\n# Custom headers\nxurl -H \"Content-Type: application/json\" /2/some/endpoint\n\n# Force streaming mode\nxurl -s /2/tweets/search/stream\n\n# Full URLs also work\nxurl https://api.x.com/2/users/me\n```\n\n---\n\n## Streaming\n\nStreaming endpoints are auto‑detected. Known streaming endpoints include:\n\n- `/2/tweets/search/stream`\n- `/2/tweets/sample/stream`\n- `/2/tweets/sample10/stream`\n\nYou can force streaming on any endpoint with `-s`:\n\n```bash\nxurl -s /2/some/endpoint\n```\n\n---\n\n## Output Format\n\nAll commands return **JSON** to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:\n\n```json\n{\n  \"data\": {\n    \"id\": \"1234567890\",\n    \"text\": \"Hello world!\"\n  }\n}\n```\n\nErrors are also returned as JSON:\n\n```json\n{\n  \"errors\": [\n    {\n      \"message\": \"Not authorized\",\n      \"code\": 403\n    }\n  ]\n}\n```\n\n---\n\n## Common Workflows\n\n### Post with an image\n\n```bash\n# 1. Upload the image\nxurl media upload photo.jpg\n# 2. Copy the media_id from the response, then post\nxurl post \"Check out this photo!\" --media-id MEDIA_ID\n```\n\n### Reply to a conversation\n\n```bash\n# 1. Read the post to understand context\nxurl read https://x.com/user/status/1234567890\n# 2. Reply\nxurl reply 1234567890 \"Here are my thoughts...\"\n```\n\n### Search and engage\n\n```bash\n# 1. Search for relevant posts\nxurl search \"topic of interest\" -n 10\n# 2. Like an interesting one\nxurl like POST_ID_FROM_RESULTS\n# 3. Reply to it\nxurl reply POST_ID_FROM_RESULTS \"Great point!\"\n```\n\n### Check your activity\n\n```bash\n# See who you are\nxurl whoami\n# Check your mentions\nxurl mentions -n 20\n# Check your timeline\nxurl timeline -n 20\n```\n\n### Set up multiple apps\n\n```bash\n# App credentials must already be configured manually outside agent/LLM context.\n# Authenticate users on each pre-configured app\nxurl auth default prod\nxurl auth oauth2                       # authenticates on prod app\n\nxurl auth default staging\nxurl auth oauth2                       # authenticates on staging app\n\n# Switch between them\nxurl auth default prod alice           # prod app, alice user\nxurl --app staging /2/users/me         # one-off request against staging\n```\n\n---\n\n## Error Handling\n\n- Non‑zero exit code on any error.\n- API errors are printed as JSON to stdout (so you can still parse them).\n- Auth errors suggest re‑running `xurl auth oauth2` or checking your tokens.\n- If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via `/2/users/me`. If that fails, you'll see an auth error.\n\n---\n\n## Notes\n\n- **Rate limits:** The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.\n- **Scopes:** OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run `xurl auth oauth2` to get a fresh token.\n- **Token refresh:** OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.\n- **Multiple apps:** Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with `xurl auth default` or `--app`.\n- **Multiple accounts:** You can authenticate multiple OAuth 2.0 accounts per app and switch between them with `--username` / `-u` or set a default with `xurl auth default APP USER`.\n- **Default user:** When no `-u` flag is given, xurl uses the default user for the active app (set via `xurl auth default`). If no default user is set, it uses the first available token.\n- **Token storage:** `~/.xurl` is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.\n"}]}]
   const users = app.findCollectionByNameOrId("users")
   const hanzo = new Record(users, {
     handle: "hanzo",
     displayName: "Hanzo",
     name: "Hanzo AI",
     role: "admin",
     trustedPublisher: true,
     image: "https://hanzo.ai/favicon.svg",
   })
   hanzo.setEmail("[email protected]")
   hanzo.setVerified(true)
   hanzo.set("password", $security.randomString(48))
   app.save(hanzo)
   const skills = app.findCollectionByNameOrId("skills")
   const versions = app.findCollectionByNameOrId("skill_versions")
   for (const s of catalog) {
     const skill = new Record(skills, {
       slug: s.slug,
       displayName: s.displayName,
       summary: s.summary,
       ownerUserId: hanzo.id,
       tags: {},
       badges: { official: { byUserId: hanzo.id, at: Date.now() } },
       moderationStatus: "active",
       statsDownloads: 0,
       statsStars: 0,
       statsVersions: 1,
       statsComments: 0,
     })
     app.save(skill)
     const version = new Record(versions, {
       skillId: skill.id,
       version: s.version,
       changelog: "Published from github.com/hanzoai/bot@8be8f1dc7bfa.",
       changelogSource: "auto",
       files: s.files,
       parsed: { frontmatter: { name: s.displayName, description: s.summary } },
       createdBy: hanzo.id,
       sha256hash: s.sha256hash,
     })
     app.save(version)
     skill.set("latestVersionId", version.id)
     app.save(skill)
   }
 }, (app) => {
   const hanzo = app.findFirstRecordByData("users", "handle", "hanzo")
   for (const skill of app.findRecordsByFilter("skills", "ownerUserId = {:id}", "", 0, 0, { id: hanzo.id })) {
     app.delete(skill)
   }
   app.delete(hanzo)
 })

65 lines 506 KiB JavaScript Raw Permalink Blame History Unescape Escape

65 lines

506 KiB

JavaScript

Raw Permalink Blame History