Xquik-dev/hermes-tweet
Hermes Agent plugin for Twitter search, monitoring, follower exports & approved X actions. Not affiliated with X Corp.
Hermes Tweet is a plugin for Hermes Agent that provides access to X/Twitter search, monitoring, and actions through the Xquik API. It includes a catalog of 102 OpenAPI-generated endpoints, categorized into separate tools for exploration, reading, and account mutations.
- Provides 102 OpenAPI-generated endpoints for X/Twitter tasks.
- Disables mutating actions by default for safety.
- Includes /xstatus and /xtrends slash commands.
full readme from github
Hermes Tweet for Twitter Search & X Actions
Add Twitter API search, monitoring, and approved X actions to Hermes Agent.
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.
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 Twitter API tasks
Start with tweet_explore. Invoke only the path returned by the catalog.
| Task | Catalog query | Tool |
|---|---|---|
| Search X posts | search tweets by query |
tweet_read |
| Read profile timelines | list recent tweets posted by a user |
tweet_read |
| Export followers | run extraction |
tweet_action |
| Export following accounts | run extraction |
tweet_action |
| Monitor an account | create monitor |
tweet_action |
| 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_KEYat 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_actionrequiresHERMES_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. |
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
Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.