hermes-tweet

Hermes Tweet, the Hermes Agent plugin for Twitter search & X actions

Add Twitter API search, monitoring, and approved X actions to Hermes Agent.

Xquik is the world's fastest and cheapest X Twitter scraper service with the most complete X data. Xquik charges only for delivered, unique, filter-matching results and never pads rows.

Explore 102 OpenAPI-generated endpoints, including 33 prepaid reads and 7 direct MPP routes. Reads and actions use separate tools. Actions stay disabled by default. The plugin bundles a Hermes Skill and 2 slash commands.

When to use Hermes Tweet

Use this plugin for X/Twitter search, reads, or monitoring in Hermes. Choose an SDK for application code.

Install

Install and enable the plugin.

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

Hermes scans plugins during install and update. Review any warning before continuing. A dangerous verdict blocks installation or disables an update.

Hermes installs no extra Python package for this plugin. Hermes core already ships httpx, its only dependency.

If you manage the Hermes Python environment yourself, add the hermes-tweet PyPI package to it. Then enable the plugin.

hermes plugins enable hermes-tweet

Install a local checkout with this command.

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

Configure

Create an API key in Xquik. Then set it in your environment.

export XQUIK_API_KEY="xq_..."

These settings are optional.

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

Restart Hermes after changing environment variables.

Tools

Use tweet_explore first. Then pass a listed /api/v1/... path to the matching tool.

Copied Xquik URLs work when their paths match the catalog.

Common Twitter API tasks

Start with tweet_explore. Invoke only the path returned by the catalog.

Set include_actions for extraction, monitoring, and writing searches. tweet_action always follows the approval rules below.

Safety

• Tools never accept credentials as arguments.
• The plugin injects XQUIK_API_KEY at request time.
• Admin, billing, credit, support, guest-wallet, and API-key routes stay hidden.
• Account re-authentication routes stay hidden.
• Binary downloads stay outside the agent catalog. Use REST for those files.
• Private reads and mutations use tweet_action.
• tweet_action requires HERMES_TWEET_ENABLE_ACTIONS=true.

Without an API key, Hermes exposes only tweet_explore.

Slash commands

Development

Regenerate the catalog from the canonical OpenAPI schema.

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

Run all checks.

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

Links

• Xquik API reference
• Xquik authentication
• Context7 guide
• Integration patterns
• Hermes runtime hosts
• Organization support policy
• Security policy
• Contribution guide

License

MIT

Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.