Documentation Index
Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
Use this file to discover all available pages before exploring further.
Hermes Tweet is the native Hermes Agent plugin for using Xquik as a structured X automation toolset. It packages the Xquik endpoint catalog, read tools, optional action tools, slash commands, and a bundled Hermes skill into a Python plugin.
Use Hermes Tweet when a Hermes Agent workflow needs X search, account reads, tweet posting, replies, likes, retweets, follows, DMs, monitors, webhooks, giveaway draws, extraction jobs, media operations, or trend reads.
Prerequisites
- Python
3.11 or newer
- Hermes Agent with plugin support
- Xquik API key
Hermes plugins are opt-in. The official Hermes plugin docs describe pip entry points through the hermes_agent.plugins group and require plugins to be enabled before they load.
Install
Use Hermes’ plugin installer for the public GitHub repo:
hermes plugins install Xquik-dev/hermes-tweet --enable
XQUIK_API_KEY during an interactive install and stores it
in ~/.hermes/.env. Non-interactive installs skip the prompt. Set the key in
the process environment or ~/.hermes/.env before calling tweet_read.
Install the published PyPI package directly into the Hermes Python environment
when you manage package installation yourself:
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
hermes plugins enable hermes-tweet
pip, this path is also valid:
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet
hermes plugins enable hermes-tweet
0.1.6. The plugin name is hermes-tweet, and the Python entry point is hermes-tweet = hermes_tweet.
Set your Xquik API key before starting Hermes:
export XQUIK_API_KEY="xq_..."
~/.hermes/.env:
Optional environment variables:
export XQUIK_BASE_URL="https://xquik.com"
export HERMES_TWEET_ENABLE_ACTIONS="false"
HERMES_TWEET_ENABLE_ACTIONS=false for unattended sessions. Enable actions only for workflows with an explicit approval step:
export HERMES_TWEET_ENABLE_ACTIONS="true"
~/.hermes/.env, run /reload in
an interactive CLI session, or restart gateway and cron sessions before calling
tweet_read.
| Tool | Purpose | Enabled By Default |
|---|
tweet_explore | Search the bundled Xquik endpoint catalog without making an API call | Yes |
tweet_read | Call catalog-listed read-only endpoints | Yes |
tweet_action | Call write-like or private endpoints | No |
tweet_explore so the agent can discover the right method, path, parameters, and response shape before it calls an endpoint.
Use tweet_explore to find the endpoint for user lookup, then call tweet_read for @xquikcom.
Slash Commands
| Command | Purpose |
|---|
/xstatus | Show Xquik account, subscription, and usage status |
/xtrends | Show current X trends |
Safety Model
Hermes Tweet reads auth from environment variables and injects it at request time. The model does not receive the API key as a tool argument.
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 stays hidden unless HERMES_TWEET_ENABLE_ACTIONS=true.
For unattended jobs, keep action tools disabled and use only tweet_explore plus tweet_read.
API Coverage
Hermes Tweet includes 99 agent-callable Xquik endpoints generated from the OpenAPI contract, plus 31 MPP-tagged read endpoints in the bundled catalog.
| Area | Examples |
|---|
| Public reads | Tweet search, tweet lookup, user lookup, timelines, articles, trends |
| Private reads | Account status, connected accounts, usage, events |
| Monitoring | Account monitors, keyword monitors, events, webhooks |
| Workflows | Extractions, giveaway draws, exports, compose, drafts, styles |
| Actions | Tweet, reply, like, retweet, follow, DM, profile, media, communities |
Local Development
For local plugin development, regenerate the bundled catalog from the Xquik OpenAPI contract:
python scripts/build_catalog.py ../xquik/openapi.yaml
hermes-tweet repository after the Xquik OpenAPI file changes.
Verify
After installing, enabling, and setting XQUIK_API_KEY, run:
For scriptable diagnostics, list the plugin toolset:
Then test a read workflow:
Use tweet_explore to find X trends, then use tweet_read to return current trends.
tweet_action.
Troubleshooting
| Symptom | Fix |
|---|
| Plugin appears but tools are missing | Run hermes plugins enable hermes-tweet, then hermes tools list |
| Auth fails | Confirm XQUIK_API_KEY is exported in the same environment that starts Hermes, or stored in ~/.hermes/.env |
| Env file changed but auth still fails | Run /reload in the interactive CLI, or restart gateway and cron sessions |
| Action tool is hidden | Set HERMES_TWEET_ENABLE_ACTIONS=true only for approved action workflows |
| Endpoint is missing | Regenerate the catalog from the current Xquik OpenAPI file in local development |
| Writes are too risky for the workflow | Keep HERMES_TWEET_ENABLE_ACTIONS=false and use read tools only |
References
Compare