@clawpump/claw-agent 0.1.4 → 0.1.6

package/agent/setup.py

@@ -2,13 +2,68 @@ from __future__ import annotations
 
 from collections import defaultdict
 from pathlib import Path
+import tempfile
 
 from setuptools import setup
+from setuptools.command.build import build as _build
+from setuptools.command.egg_info import egg_info as _egg_info
 
 
 REPO_ROOT = Path(__file__).parent.resolve()
 
 
+def _source_tree_is_writable() -> bool:
+    probe = REPO_ROOT / ".setuptools-write-probe"
+    try:
+        with probe.open("w", encoding="utf-8") as handle:
+            handle.write("")
+        probe.unlink()
+    except OSError:
+        try:
+            probe.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return False
+    return True
+
+
+def _temporary_build_dir(kind: str) -> str:
+    return tempfile.mkdtemp(prefix=f"hermes-agent-{kind}-")
+
+
+def _would_write_under_source(path_value: str | None) -> bool:
+    if path_value is None:
+        return True
+    path = Path(path_value)
+    if not path.is_absolute():
+        path = REPO_ROOT / path
+    try:
+        path.resolve().relative_to(REPO_ROOT)
+    except ValueError:
+        return False
+    return True
+
+
+class ReadOnlySourceBuild(_build):
+    def finalize_options(self) -> None:
+        if (
+            not _source_tree_is_writable()
+            and _would_write_under_source(self.build_base)
+        ):
+            self.build_base = _temporary_build_dir("build")
+        super().finalize_options()
+
+
+class ReadOnlySourceEggInfo(_egg_info):
+    def finalize_options(self) -> None:
+        if (
+            not _source_tree_is_writable()
+            and _would_write_under_source(self.egg_base)
+        ):
+            self.egg_base = _temporary_build_dir("egg-info")
+        super().finalize_options()
+
+
 def _data_file_tree(root_name: str) -> list[tuple[str, list[str]]]:
     root = REPO_ROOT / root_name
     grouped: defaultdict[str, list[str]] = defaultdict(list)
@@ -21,6 +76,10 @@ def _data_file_tree(root_name: str) -> list[tuple[str, list[str]]]:
 
 
 setup(
+    cmdclass={
+        "build": ReadOnlySourceBuild,
+        "egg_info": ReadOnlySourceEggInfo,
+    },
     data_files=[
         *_data_file_tree("skills"),
         *_data_file_tree("optional-skills"),

package/agent/skills/autonomous-ai-agents/codex/SKILL.md

@@ -74,6 +74,25 @@ process(action="kill", session_id="<id>")
 | `exec "prompt"` | One-shot execution, exits when done |
 | `--full-auto` | Sandboxed but auto-approves file changes in workspace |
 | `--yolo` | No sandbox, no approvals (fastest, most dangerous) |
+| `--sandbox danger-full-access` | No Codex sandbox; useful when the host service context breaks bubblewrap |
+
+## Hermes Gateway Caveat
+
+When invoking the Codex CLI from a Hermes gateway/service context (for example,
+Telegram-driven agent sessions), Codex `workspace-write` sandboxing may fail even
+when the same command works in the user's interactive shell. A typical symptom is
+bubblewrap/user-namespace errors such as `setting up uid map: Permission denied`
+or `loopback: Failed RTM_NEWADDR: Operation not permitted`.
+
+In that context, prefer:
+
+```
+codex exec --sandbox danger-full-access "<task>"
+```
+
+Use process boundaries as the safety layer instead: explicit `workdir`, clean git
+status before launch, narrow task prompts, `git diff` review, targeted tests, and
+human/agent confirmation before committing broad changes.
 
 ## PR Reviews
 

package/agent/skills/autonomous-ai-agents/hermes-agent/SKILL.md

@@ -35,7 +35,7 @@ People use Hermes for software development, research, system administration, dat
 
 ```bash
 # Install
-curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
 
 # Interactive chat (default)
 hermes
@@ -140,6 +140,10 @@ hermes mcp test NAME        Test connection
 hermes mcp configure NAME   Toggle tool selection
 ```
 
+How the built-in MCP client connects servers (stdio/HTTP), auto-discovers
+their tools, and exposes them as first-class tools, plus catalog install
+(`hermes mcp install <name>`): `skill_view(name="hermes-agent", file_path="references/native-mcp.md")`.
+
 ### Gateway (Messaging Platforms)
 
 ```
@@ -188,6 +192,9 @@ hermes webhook remove NAME  Remove a subscription
 hermes webhook test NAME    Send a test POST
 ```
 
+Full setup, route config, payload templating, and event-driven agent-run
+patterns: `skill_view(name="hermes-agent", file_path="references/webhooks.md")`.
+
 ### Profiles
 
 ```
@@ -336,7 +343,7 @@ The registry of record is `hermes_cli/commands.py` — every consumer
 
 ```
 ~/.hermes/config.yaml       Main configuration
-~/.hermes/.env              API keys and secrets
+~/.hermes/.env              API keys and secrets (under $HERMES_HOME if set)
 $HERMES_HOME/skills/        Installed skills
 ~/.hermes/sessions/         Gateway routing index, request dumps, *.jsonl transcripts (and optional per-session JSON snapshots when sessions.write_json_snapshots: true)
 ~/.hermes/state.db          Canonical session store (SQLite + FTS5)
@@ -901,7 +908,7 @@ hermes-agent/
 └── website/              # Docusaurus docs site
 ```
 
-Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys).
+Config: `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys) — both under `$HERMES_HOME` when it is set.
 
 ### Adding a Tool (3 files)
 

package/agent/skills/{mcp/native-mcp/SKILL.md → autonomous-ai-agents/hermes-agent/references/native-mcp.md}

@@ -1,16 +1,3 @@
----
-name: native-mcp
-description: "MCP client: connect servers, register tools (stdio/HTTP)."
-version: 1.0.0
-author: Hermes Agent
-license: MIT
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [MCP, Tools, Integrations]
-    related_skills: [mcporter]
----
-
 # Native MCP Client
 
 Hermes Agent has a built-in MCP client that connects to MCP servers at startup, discovers their tools, and makes them available as first-class tools the agent can call directly. No bridge CLI needed -- tools from MCP servers appear alongside built-in tools like `terminal`, `read_file`, etc.

package/agent/skills/{devops/webhook-subscriptions/SKILL.md → autonomous-ai-agents/hermes-agent/references/webhooks.md}

@@ -1,13 +1,3 @@
----
-name: webhook-subscriptions
-description: "Webhook subscriptions: event-driven agent runs."
-version: 1.1.0
-platforms: [linux, macos, windows]
-metadata:
-  hermes:
-    tags: [webhook, events, automation, integrations, notifications, push]
----
-
 # Webhook Subscriptions
 
 Create dynamic webhook subscriptions so external services (GitHub, GitLab, Stripe, CI/CD, IoT sensors, monitoring tools) can trigger Hermes agent runs by POSTing events to a URL.
@@ -40,7 +30,7 @@ platforms:
 ```
 
 ### Option 3: Environment variables
-Add to `~/.hermes/.env`:
+Add to `${HERMES_HOME:-~/.hermes}/.env`:
 ```bash
 WEBHOOK_ENABLED=true
 WEBHOOK_PORT=8644

package/agent/skills/clawpump/SKILL.md

@@ -14,7 +14,7 @@ metadata:
 ClawPump is a Solana platform for AI agents: each agent has a wallet and can
 trade, run perps, DCA, lend, launch tokens, buy gift cards, send email from
 its own inbox, and be bought/sold on a marketplace. Its full feature set
-reaches Hermes through the **ClawPump MCP server** (131 tools, 10 resources,
+reaches Hermes through the **ClawPump MCP server** (134 tools, 10 resources,
 10 prompts).
 
 ## Enabling ClawPump
@@ -44,7 +44,7 @@ Most tools act on a specific agent. Resolve it once with `list_agents`, then
 pass `agent_id`. If the user set `CLAWPUMP_DEFAULT_AGENT` (or has exactly one
 agent), `agent_id` can usually be omitted. When unsure which agent, ask.
 
-## What's available (131 tools, 20 groups)
+## What's available (134 tools, 21 groups)
 
 | Group | Representative tools |
 |-------|----------------------|
@@ -62,7 +62,9 @@ agent), `agent_id` can usually be omitted. When unsure which agent, ask.
 | Agent cards (Laso) | `agent_card_search_merchants`, `agent_card_search_gift_cards`, `agent_card_quote`, `agent_card_create`, `agent_card_list`, `agent_card_get`, `agent_card_status`, `agent_card_data`, `agent_card_balance`, `agent_card_reveal`, `agent_card_cancel`, `agent_card_refresh`, `agent_card_withdraw`, `agent_card_withdrawals`, `agent_card_connect`, `agent_card_connect_link` |
 | Agent mail | `agent_mail_create`, `agent_mail_get_address`, `agent_mail_send`, `agent_mail_list`, `agent_mail_read` |
 | Pay.sh x402 (agent-wallet paid APIs) | `pay_sh_search`, `pay_sh_provider_details`, `pay_sh_prepare_call`, `pay_sh_execute_approved` |
-| UsePod (pay inference from the wallet) | `usepod_deposit` |
+| Dexter x402 marketplace (discovery) | `dexter_search` |
+| Open x402 (pay any URL) | `x402_pay_check`, `x402_pay` |
+| UsePod (run + fund your own inference pod) | `usepod_provision`, `usepod_deposit` |
 | Wallet & billing | `get_balance`, `get_budget`, `get_usage`, `get_transactions`, `get_wallet_summaries`, `get_wallet_history`, `get_private_wallet_balance`, `get_balance_history`, `sync_billing`, `wallet_transfer` |
 | Market intelligence | `intelligence_capabilities`, `intelligence_market`, `intelligence_signals`, `intelligence_macro`, `intelligence_perps` |
 | Integrations | `list_integrations`, `save_integration`, `remove_integration`, `get_linked_accounts` |
@@ -70,8 +72,10 @@ agent), `agent_id` can usually be omitted. When unsure which agent, ask.
 | Whitelist | `get_whitelist`, `add_to_whitelist`, `remove_from_whitelist` |
 | Utility | `get_model_catalog`, `get_news_feed` |
 
-By default only the **94 read-mostly** tools are enabled. The financial ones
-below are opt-in via `hermes mcp configure clawpump`.
+By default only the **95 read-mostly** tools are enabled (including
+`usepod_provision`, whose only fund-moving path is double-gated by
+`confirm_deposit`). The financial ones below are opt-in via
+`hermes mcp configure clawpump`.
 
 ## ⚠️ FINANCIAL & IRREVERSIBLE TOOLS — confirmation is mandatory
 
@@ -138,4 +142,48 @@ Common patterns:
   - **Deliverability (avoid spam):** write genuine, complete messages — a specific subject, a greeting, 2–4 sentences of real purpose, and a sign-off. Never send one-word/empty bodies or test-like "hello": low-content mail from a fresh sender domain is the #1 spam trigger. Do **not** use fake-urgent or deceptive subjects ("IMPORTANT!!", "URGENT") to game filters — that backfires and is deceptive. Tell first-time recipients to mark "Not spam" + add the address to contacts; that trains their inbox fastest.
 - **Fund an external wallet (e.g. a pay.sh allowance):** `get_balance` → `add_to_whitelist` (user-approved address) → (confirm) `wallet_transfer`. See the `pay-sh` skill.
 - **Paid x402 API call (agent wallet pays):** `pay_sh_search` → `pay_sh_provider_details` (price) → `pay_sh_prepare_call` → (confirm price with user) → `pay_sh_execute_approved`. The agent needs the `x402` skill (`update_agent` with `enabled_skills`).
+- **Discover x402 APIs on Dexter:** `dexter_search` (free, by capability — e.g. "ETH price", "image generation") returns matching resources with their payable `resourceUrl`, HTTP method, per-call USDC price, and input schema. No separate Dexter wallet.
+- **Pay ANY x402 URL (open, not just a catalog):** `x402_pay_check` (free — fetch the URL's 402 challenge → price + input schema) → quote the price to the user → `x402_pay` (pays from the agent's ClawPump wallet, `confirm_payment: true`, `max_amount_usd` = the cap the user approved). Works on any x402 endpoint, including a `resourceUrl` from `dexter_search`. The wallet signs server-side; spend is hard-capped. Needs the `x402` skill (`update_agent` with `enabled_skills`).
 - **Pay your Hermes inference from the ClawPump wallet (UsePod):** if the user runs Hermes on their own UsePod pod (`USEPOD_API_KEY` in `~/.hermes/.env`), they can top that pod up straight from their ClawPump wallet instead of funding it manually at usepod.ai. Flow: `get_balance` (confirm the agent wallet holds enough USDC) → ask for the amount + their 16-hex `deposit_code` (from UsePod `/v1/register`) → quote both back → (confirm) `usepod_deposit` with `confirm_deposit: true`. The full amount goes on-chain into that pod (no fee); UsePod then draws inference cost from it. This is **separate** from ClawPump's own hosted chat/credits — it just pays the user's own pod from their wallet.
+
+## Setting up Pod (UsePod) — auto flow
+
+When a user picks **Pod** in the `/provider` (or `/model`) picker and it isn't
+configured, the picker hands you a request to set it up. Pod is a drop-in
+inference provider whose usage is paid in USDC from the user's ClawPump wallet.
+**Make this as automatic as possible — there is nothing to paste and nothing to
+restart: the CLI auto-applies the token and switches the session onto Pod the
+moment `usepod_provision` returns.**
+
+1. **Ask the amount + which agent wallet.** "How much USDC do you want to put on
+   your Pod? (e.g. 5)" — optionally check `get_balance` first so you know it can
+   cover it. Then "Which ClawPump agent wallet should fund it?" — call
+   `list_agents` and let the user pick one; use its `agent_id`. (If there is only
+   one agent you may skip the question and omit `agent_id`.)
+2. **Create + fund in one call** — `usepod_provision` registers a brand-new pod
+   (no signup, no human step) and funds it from the chosen agent wallet. After
+   the user approves the amount, call `usepod_provision` with that `amount`, the
+   selected `agent_id`, and `confirm_deposit: true`. It returns `api_token` (the
+   pod credential) + `deposit_code` and the funding `signature`.
+3. **It's applied automatically** — in the interactive Hermes CLI, the instant
+   `usepod_provision` returns, Hermes writes `USEPOD_API_KEY` (+
+   `USEPOD_DEPOSIT_CODE`) to `~/.hermes/.env` and switches this session onto
+   Pod. No `claw model`, no paste, no restart. Watch for Hermes' own
+   confirmation line (`✓ Now running on Pod: …`) and then tell the user "Your
+   pod is funded and this session is now running on Pod — the next message bills
+   from your pod." Report the funding `signature`. Do **not** print the
+   `api_token` (it's a secret and is already applied). (On non-interactive
+   runtimes — bots/API — the credential is saved but the live switch happens on
+   the next start; say "restart to run on Pod" instead of claiming it switched.)
+
+Notes:
+- **Top up an existing pod** (user already set Pod up before): skip provisioning
+  — ask for the amount + their 16-hex `deposit_code`, then `usepod_deposit` with
+  `confirm_deposit: true`. (`usepod_deposit` is a fund-mover and is opt-in: if
+  it isn't available, the user enables it via `hermes mcp configure clawpump`.)
+- `usepod_provision` registers the pod first and funds best-effort, so if funding
+  fails the user still gets a valid `api_token` (look for `funding_error`) — the
+  token is still auto-applied; fund it afterward with `usepod_deposit`.
+- This is **separate** from ClawPump's hosted chat/credits — it pays the user's
+  own pod from their wallet. Always confirm the amount before the on-chain spend
+  and report the tx signature.

package/agent/skills/devops/kanban-orchestrator/SKILL.md

@@ -3,6 +3,7 @@ name: kanban-orchestrator
 description: Decomposition playbook + anti-temptation rules for an orchestrator profile routing work through Kanban. The "don't do the work yourself" rule and the basic lifecycle are auto-injected into every kanban worker's system prompt; this skill is the deeper playbook when you're specifically playing the orchestrator role.
 version: 3.0.0
 platforms: [linux, macos, windows]
+environments: [kanban]
 metadata:
   hermes:
     tags: [kanban, multi-agent, orchestration, routing]

package/agent/skills/devops/kanban-worker/SKILL.md

@@ -3,6 +3,7 @@ name: kanban-worker
 description: Pitfalls, examples, and edge cases for Hermes Kanban workers. The lifecycle itself is auto-injected into every worker's system prompt as KANBAN_GUIDANCE (from agent/prompt_builder.py); this skill is what you load when you want deeper detail on specific scenarios.
 version: 2.0.0
 platforms: [linux, macos, windows]
+environments: [kanban]
 metadata:
   hermes:
     tags: [kanban, multi-agent, collaboration, workflow, pitfalls]

package/agent/skills/github/github-auth/SKILL.md

@@ -220,8 +220,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
   echo "AUTH_METHOD=gh"
 elif [ -n "$GITHUB_TOKEN" ]; then
   echo "AUTH_METHOD=curl"
-elif [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+elif _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+  export GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
   echo "AUTH_METHOD=curl"
 elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
   export GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')

package/agent/skills/github/github-auth/scripts/gh-env.sh

@@ -23,8 +23,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
     GH_USER=$(gh api user --jq '.login' 2>/dev/null)
 elif [ -n "$GITHUB_TOKEN" ]; then
     GH_AUTH_METHOD="curl"
-elif [ -f "$HOME/.hermes/.env" ] && grep -q "^GITHUB_TOKEN=" "$HOME/.hermes/.env" 2>/dev/null; then
-    GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$HOME/.hermes/.env" | head -1 | cut -d= -f2 | tr -d '\n\r')
+elif _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env" 2>/dev/null; then
+    GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     if [ -n "$GITHUB_TOKEN" ]; then
         GH_AUTH_METHOD="curl"
     fi

package/agent/skills/github/github-code-review/SKILL.md

@@ -28,8 +28,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

package/agent/skills/github/github-issues/SKILL.md

@@ -28,8 +28,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

package/agent/skills/github/github-pr-workflow/SKILL.md

@@ -30,8 +30,8 @@ else
   AUTH="git"
   # Ensure we have a token for API calls
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

package/agent/skills/github/github-repo-management/SKILL.md

@@ -27,8 +27,8 @@ if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 else
   AUTH="git"
   if [ -z "$GITHUB_TOKEN" ]; then
-    if [ -f ~/.hermes/.env ] && grep -q "^GITHUB_TOKEN=" ~/.hermes/.env; then
-      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" ~/.hermes/.env | head -1 | cut -d= -f2 | tr -d '\n\r')
+    if _hermes_env="${HERMES_HOME:-$HOME/.hermes}/.env"; [ -f "$_hermes_env" ] && grep -q "^GITHUB_TOKEN=" "$_hermes_env"; then
+      GITHUB_TOKEN=$(grep "^GITHUB_TOKEN=" "$_hermes_env" | head -1 | cut -d= -f2 | tr -d '\n\r')
     elif grep -q "github.com" ~/.git-credentials 2>/dev/null; then
       GITHUB_TOKEN=$(grep "github.com" ~/.git-credentials 2>/dev/null | head -1 | sed 's|https://[^:]*:\([^@]*\)@.*|\1|')
     fi

package/agent/skills/media/gif-search/SKILL.md

@@ -23,7 +23,7 @@ Useful for finding reaction GIFs, creating visual content, and sending GIFs in c
 
 ## Setup
 
-Set your Tenor API key in your environment (add to `~/.hermes/.env`):
+Set your Tenor API key in your environment (add to `${HERMES_HOME:-~/.hermes}/.env`):
 
 ```bash
 TENOR_API_KEY=your_key_here

package/agent/skills/media/youtube-content/SKILL.md

@@ -14,8 +14,11 @@ Extract transcripts from YouTube videos and convert them into useful formats.
 
 ## Setup
 
+Use `uv` so the dependency is installed into the same Hermes-managed environment
+that runs the helper script:
+
 ```bash
-pip install youtube-transcript-api
+uv pip install youtube-transcript-api
 ```
 
 ## Helper Script
@@ -24,16 +27,16 @@ pip install youtube-transcript-api
 
 ```bash
 # JSON output with metadata
-python3 SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"
+uv run python3 SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"
 
 # Plain text (good for piping into further processing)
-python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only
+uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only
 
 # With timestamps
-python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps
+uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps
 
 # Specific language with fallback chain
-python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en
+uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en
 ```
 
 ## Output Formats
@@ -59,7 +62,7 @@ After fetching the transcript, format it based on what the user asks for:
 
 ## Workflow
 
-1. **Fetch** the transcript using the helper script with `--text-only --timestamps`.
+1. **Fetch** the transcript using the helper script with `--text-only --timestamps` via `uv run python3`.
 2. **Validate**: confirm the output is non-empty and in the expected language. If empty, retry without `--language` to get any available transcript. If still empty, tell the user the video likely has transcripts disabled.
 3. **Chunk if needed**: if the transcript exceeds ~50K characters, split into overlapping chunks (~40K with 2K overlap) and summarize each chunk before merging.
 4. **Transform** into the requested output format. If the user did not specify a format, default to a summary.
@@ -70,4 +73,4 @@ After fetching the transcript, format it based on what the user asks for:
 - **Transcript disabled**: tell the user; suggest they check if subtitles are available on the video page.
 - **Private/unavailable video**: relay the error and ask the user to verify the URL.
 - **No matching language**: retry without `--language` to fetch any available transcript, then note the actual language to the user.
-- **Dependency missing**: run `pip install youtube-transcript-api` and retry.
+- **Dependency missing**: run `uv pip install youtube-transcript-api` and retry.

package/agent/skills/media/youtube-content/scripts/fetch_transcript.py

@@ -3,7 +3,7 @@
 Fetch a YouTube video transcript and output it as structured JSON.
 
 Usage:
-    python fetch_transcript.py <url_or_video_id> [--language en,tr] [--timestamps]
+    uv run python3 fetch_transcript.py <url_or_video_id> [--language en,tr] [--timestamps]
 
 Output (JSON):
     {
@@ -14,7 +14,7 @@ Output (JSON):
         "timestamped_text": "00:00 first line\n00:05 second line\n..."
     }
 
-Install dependency:  pip install youtube-transcript-api
+Install dependency:  uv pip install youtube-transcript-api
 """
 
 import argparse
@@ -56,7 +56,7 @@ def fetch_transcript(video_id: str, languages: list = None):
     try:
         from youtube_transcript_api import YouTubeTranscriptApi
     except ImportError:
-        print("Error: youtube-transcript-api not installed. Run: pip install youtube-transcript-api",
+        print("Error: youtube-transcript-api not installed. Run: uv pip install youtube-transcript-api",
               file=sys.stderr)
         sys.exit(1)
 

package/agent/skills/note-taking/obsidian/SKILL.md

@@ -12,7 +12,7 @@ Use this skill for filesystem-first Obsidian vault work: reading notes, listing
 
 Use a known or resolved vault path before calling file tools.
 
-The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
+The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `${HERMES_HOME:-~/.hermes}/.env`. If it is unset, use `~/Documents/Obsidian Vault`.
 
 File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.
 

package/agent/skills/productivity/airtable/SKILL.md

@@ -26,7 +26,7 @@ Work with Airtable's REST API directly via `curl` using the `terminal` tool. No
    - `data.records:write` — create / update / delete rows
    - `schema.bases:read` — list bases and tables
 3. **Important:** in the same token UI, add each base you want to access to the token's **Access** list. PATs are scoped per-base — a valid token on the wrong base returns `403`.
-4. Store the token in `~/.hermes/.env` (or via `hermes setup`):
+4. Store the token in `${HERMES_HOME:-~/.hermes}/.env` (or via `hermes setup`):
    ```
    AIRTABLE_API_KEY=pat_your_token_here
    ```
@@ -222,7 +222,7 @@ done
 ## Important Notes for Hermes
 
 - **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow).
-- **`AIRTABLE_API_KEY` flows from `~/.hermes/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
+- **`AIRTABLE_API_KEY` flows from `${HERMES_HOME:-~/.hermes}/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
 - **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL.
 - **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection.
 - **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent.

package/agent/skills/productivity/google-workspace/scripts/setup.py

@@ -26,6 +26,7 @@ from __future__ import annotations  # allow PEP 604 `X | None` on Python 3.9+
 import argparse
 import json
 import os
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -103,6 +104,8 @@ def install_deps():
         pass
 
     print("Installing Google API dependencies...")
+
+    # First choice: pip in the current interpreter. Works for most installs.
     try:
         subprocess.check_call(
             [sys.executable, "-m", "pip", "install", "--quiet"] + REQUIRED_PACKAGES,
@@ -111,13 +114,36 @@ def install_deps():
         print("Dependencies installed.")
         return True
     except subprocess.CalledProcessError as e:
-        print(f"ERROR: Failed to install dependencies: {e}")
-        print(
-            "On environments without pip (e.g. Nix), install the optional extra instead:"
-        )
-        print("  pip install 'hermes-agent[google]'")
-        print(f"Or manually: {sys.executable} -m pip install {' '.join(REQUIRED_PACKAGES)}")
-        return False
+        pip_error = e
+
+    # Fallback: the interpreter has no pip (the Hermes Docker image's venv is
+    # built with `uv sync`, which does not bootstrap pip). `uv pip install
+    # --python <interpreter>` installs into that exact interpreter without
+    # needing pip present. Targeting sys.executable keeps us on the venv the
+    # script is actually running under, rather than guessing.
+    uv = shutil.which("uv")
+    if uv:
+        try:
+            subprocess.check_call(
+                [uv, "pip", "install", "--python", sys.executable, "--quiet"]
+                + REQUIRED_PACKAGES,
+                stdout=subprocess.DEVNULL,
+            )
+            print("Dependencies installed.")
+            return True
+        except subprocess.CalledProcessError as e:
+            print(f"ERROR: Failed to install dependencies via uv: {e}")
+            print(f"Manually: {uv} pip install --python {sys.executable} {' '.join(REQUIRED_PACKAGES)}")
+            return False
+
+    print(f"ERROR: Failed to install dependencies: {pip_error}")
+    print(
+        "On environments without pip (e.g. Nix, or the Hermes Docker image's "
+        "uv-managed venv), install the optional extra instead:"
+    )
+    print("  pip install 'hermes-agent[google]'")
+    print(f"Or manually: {sys.executable} -m pip install {' '.join(REQUIRED_PACKAGES)}")
+    return False
 
 
 def _ensure_deps():

package/agent/skills/productivity/notion/SKILL.md

@@ -26,7 +26,7 @@ Talk to Notion two ways. Same integration token works for both — pick by what'
 
 1. Create an integration at https://notion.so/my-integrations
 2. Copy the API key (starts with `ntn_` or `secret_`)
-3. Store in `~/.hermes/.env`:
+3. Store in `${HERMES_HOME:-~/.hermes}/.env`:
    ```
    NOTION_API_KEY=ntn_your_key_here
    ```
@@ -50,7 +50,7 @@ export NOTION_API_TOKEN=$NOTION_API_KEY      # ntn reads NOTION_API_TOKEN
 export NOTION_KEYRING=0                       # don't try to use the OS keychain
 ```
 
-Add those exports to your shell profile (or to `~/.hermes/.env`) so every session inherits them.
+Add those exports to your shell profile (or to `${HERMES_HOME:-~/.hermes}/.env`) so every session inherits them.
 
 ### 3. Choose path at runtime
 

package/agent/skills/productivity/teams-meeting-pipeline/SKILL.md

@@ -39,7 +39,7 @@ Multilingual trigger examples (not exhaustive):
 
 ## Prerequisites
 
-Before using the pipeline, verify these are set in `~/.hermes/.env`:
+Before using the pipeline, verify these are set in `${HERMES_HOME:-~/.hermes}/.env`:
 
 ```bash
 MSGRAPH_TENANT_ID=...

package/agent/skills/research/llm-wiki/SKILL.md

@@ -35,7 +35,7 @@ Use this skill when the user:
 
 ## Wiki Location
 
-**Location:** Set via `WIKI_PATH` environment variable (e.g. in `~/.hermes/.env`).
+**Location:** Set via `WIKI_PATH` environment variable (e.g. in `${HERMES_HOME:-~/.hermes}/.env`).
 
 If unset, defaults to `~/wiki`.
 

package/agent/skills/social-media/xurl/SKILL.md

@@ -192,6 +192,15 @@ xurl search "from:elonmusk" -n 20
 xurl search "#buildinpublic lang:en" -n 15
 ```
 
+For X Articles, use raw API mode instead of the `read` shortcut. `xurl read`
+expects a post ID or post URL; do not put `read` before a `/2/tweets/...`
+endpoint. Request the `article` tweet field and ingest `data.article.plain_text`
+from the JSON response:
+
+```bash
+xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'
+```
+
 ### Users, Timeline, Mentions
 
 ```bash

package/agent/skills/software-development/hermes-agent-skill-authoring/SKILL.md

@@ -8,7 +8,7 @@ platforms: [linux, macos, windows]
 metadata:
   hermes:
     tags: [skills, authoring, hermes-agent, conventions, skill-md]
-    related_skills: [writing-plans, requesting-code-review]
+    related_skills: [plan, requesting-code-review]
 ---
 
 # Authoring Hermes-Agent Skills (in-repo)