hermes-tweet 0.1.1

Native Hermes Agent plugin for X automation through Xquik

Hermes Tweet

Native Hermes Agent plugin for X automation through Xquik.

Hermes Tweet brings X search, account reads, tweet posting, replies, likes, retweets, follows, DMs, monitors, webhooks, draws, extraction jobs, media, and trend reads into Hermes as structured tools.

Use it when you need a Hermes Agent Twitter plugin, Hermes X automation, social media automation for agents, or a native Hermes toolset for X/Twitter.

Highlights

• Published Python package with a native Hermes plugin entry point.
• Installable from PyPI as hermes-tweet.
• 99 agent-callable Xquik endpoints generated from OpenAPI.
• 32 MPP-tagged read endpoints in the bundled catalog.
• Read and action tools are split for least-privilege operation.
• Action endpoints are disabled by default.
• Bundled Hermes skill for agent-facing usage guidance.
• Slash commands for account status and trends.
• Strict CI with formatting, linting, type checking, tests, coverage, security scan, dependency audit, and package build checks.

Install

Recommended Hermes plugin install:

hermes plugins install Xquik-dev/hermes-tweet --enable

Hermes will prompt for XQUIK_API_KEY during an interactive install and save it to ~/.hermes/.env. In non-interactive installs the prompt is skipped; set the key through the environment or ~/.hermes/.env before running tweet_read.

Install the published Python package from PyPI:

~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet
hermes plugins enable hermes-tweet

Use uv inside your Hermes Python environment:

uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
hermes plugins enable hermes-tweet

From a local checkout:

hermes plugins install file:///absolute/path/to/hermes-tweet --force --enable

Python Package

Field	Value
PyPI	hermes-tweet
Latest release	v0.1.1
Supported Python	>=3.11
Package format	Wheel and source distribution
Hermes entry point	hermes-tweet = hermes_tweet
Entry point group	hermes_agent.plugins
Included assets	plugin.yaml, catalog_data.json, bundled Hermes skill

Configure

Create an API key in the Xquik dashboard, then set:

export XQUIK_API_KEY="xq_..."

Optional settings:

export XQUIK_BASE_URL="https://xquik.com"
export HERMES_TWEET_ENABLE_ACTIONS="false"

Action endpoints are disabled unless HERMES_TWEET_ENABLE_ACTIONS=true.

Security Model

Hermes Tweet never accepts credentials through tool arguments. Auth is read from environment variables and injected by the plugin at request time.

The plugin blocks dashboard-only admin, billing, credit top-up, support-ticket, API-key, and account re-authentication endpoints from the catalog. Private reads and write-like endpoints go through tweet_action, which is hidden unless HERMES_TWEET_ENABLE_ACTIONS=true.

Tools

Tool	Purpose
tweet_explore	Search the bundled Xquik endpoint catalog. No API call.
tweet_read	Call catalog-listed read-only endpoints.
tweet_action	Call write-like or private endpoints. Disabled by default.

Use tweet_explore first, then call tweet_read or tweet_action with a concrete /api/v1/... path.

Hermes Runtime Fit

Hermes Tweet registers a dedicated hermes-tweet plugin toolset. Hermes can show and manage those tools through its normal hermes tools and platform toolset flows, so teams can keep X automation available only where it belongs.

Use the read-only path for social listening, trend research, account checks, giveaway audits, and draft planning. Keep HERMES_TWEET_ENABLE_ACTIONS=false for unattended cron or gateway sessions unless the workflow has an explicit approval step for posting, DMs, follows, monitor changes, webhook changes, or other account actions.

Runtime smoke test:

hermes -z "Use tweet_explore, then read /api/v1/account. Do not call tweet_action." --toolsets hermes-tweet

Expected results:

• tweet_explore discovers catalog endpoints without using the API key.
• tweet_read can read /api/v1/account when XQUIK_API_KEY is configured.
• tweet_action reports disabled unless HERMES_TWEET_ENABLE_ACTIONS=true.
• /xstatus and /xtrends appear in the Hermes plugin command registry.

If hermes plugins install runs without a TTY, Hermes cannot safely prompt for secrets and will skip API-key storage. This is expected; set XQUIK_API_KEY in the process environment or ~/.hermes/.env.

Slash Commands

Command	Purpose
/xstatus	Show Xquik account, subscription, and usage status.
/xtrends	Show current X trends.

Development

Generate the bundled catalog from Xquik OpenAPI:

python scripts/build_catalog.py ../xquik/openapi.yaml

Run checks:

uv run --python 3.12 --extra dev ruff format --check .
uv run --python 3.12 --extra dev ruff check .
uv run --python 3.12 --extra dev basedpyright
uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100
uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts
uv run --python 3.12 --extra dev pip-audit
uv run --python 3.12 --extra dev python -m build
uv run --python 3.12 --extra dev twine check dist/*

For a single local quality gate:

uv run --python 3.12 --extra dev ruff format --check . && \
uv run --python 3.12 --extra dev ruff check . && \
uv run --python 3.12 --extra dev basedpyright && \
uv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100 && \
uv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts && \
uv run --python 3.12 --extra dev pip-audit && \
uv run --python 3.12 --extra dev python -m build && \
uv run --python 3.12 --extra dev twine check dist/*

Relationship To TweetClaw

TweetClaw is the OpenClaw-native npm plugin. Hermes Tweet is the Hermes-native Python plugin. Both use the same Xquik API contract.

Public Repo Metadata

Recommended GitHub description:

Native Hermes Agent plugin for X/Twitter automation through Xquik.

Recommended topics:

hermes-agent, hermes-plugin, hermes, twitter, x, x-api, x-automation, xquik, tweet, automation, social-media, social-media-automation, ai-agent, mcp, agent-tools, twitter-api, twitter-automation, x-twitter, apify, python