Hermes Tweet: X Search, Timelines, Followers & Actions for AI Agents

OpenSSF Best Practices CI PyPI

Add native Xquik tools to Hermes Agent.

Hermes Tweet includes:

  • 102 agent-callable Xquik endpoints, generated from OpenAPI.
  • 33 prepaid read endpoints, including 7 direct MPP routes.
  • Separate read and action tools.
  • Actions disabled by default.
  • A bundled Hermes Skill and 2 slash commands.

Choose Hermes Tweet

Choose this plugin when Hermes needs catalog-guided Xquik tools. It separates discovery, reads, and confirmed actions. Use an SDK for application code outside Hermes.

Install

Install and enable the plugin:

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

Or install the PyPI package into Hermes:

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

Install a local checkout:

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

Configure

Create an API key in Xquik. Then set:

export XQUIK_API_KEY="xq_..."

Optional settings:

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

Restart Hermes after changing environment variables.

Tools

Tool Purpose
tweet_explore Search the bundled catalog. Makes no API call.
tweet_read Call catalog-listed read endpoints.
tweet_action Call private or mutating endpoints. Disabled by default.

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 Agent Tasks

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

Customer Question Catalog Query Live Tool
How can an agent search X posts? search tweets by query tweet_read
How can an agent read profile timelines? list recent tweets posted by a user tweet_read
How can an agent export followers? run extraction tweet_action
How can an agent export following accounts? run extraction tweet_action
How can an agent monitor an account? create monitor tweet_action
How can an agent post or reply? create tweet tweet_action

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

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

Develop

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

License

MIT

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