Hermes Tweet for Hermes Agent

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

Hermes prompts for 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

If your Hermes Python environment includes pip, this path is also valid:

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

The current package version is 0.1.8. The plugin name is hermes-tweet, and the Python entry point is hermes-tweet = hermes_tweet.

Configure

Set your Xquik API key before starting Hermes:

export XQUIK_API_KEY="xq_..."

For persistent Hermes sessions, add the key to ~/.hermes/.env:

XQUIK_API_KEY=xq_...

Optional environment variables:

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

Keep HERMES_TWEET_ENABLE_ACTIONS=false for unattended sessions. Enable actions only for workflows with an explicit approval step:

export HERMES_TWEET_ENABLE_ACTIONS="true"

If Hermes is already running after you edit ~/.hermes/.env, run /reload in an interactive CLI session, or restart gateway and cron sessions before calling tweet_read.

Tools

tweet_explore

Search the bundled Xquik endpoint catalog without making an API call. Use it before every live endpoint call.

tweet_read

Call catalog-listed read-only endpoints after XQUIK_API_KEY is configured.

tweet_action

Call write-like or private endpoints only when HERMES_TWEET_ENABLE_ACTIONS=true.

Start with 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 @username.

Workflow Handoffs

Use tweet_explore first, then choose tweet_read for public reads or tweet_action for approved jobs that create or change state.

Tweet Search Read

Use tweet_read with GET /api/v1/x/tweets/search, a concrete q, and a bounded limit to return tweet IDs, text, authors, timestamps, and metrics.

Follower Export Action

Use tweet_action to estimate and create follower_explorer, then use tweet_read to poll the job and export CSV, JSON, or XLSX results.

Monitor Webhook Action

Use tweet_explore with include_actions true to find monitor and webhook endpoints, then use tweet_action for POST /api/v1/monitors or POST /api/v1/monitors/keywords and POST /api/v1/webhooks only after approval. Store the webhook secret in a secret manager. In receivers, verify X-Xquik-Signature, store deliveryId and streamEventId, return 2xx for accepted duplicates, and keep endpoint signing values, raw request body, raw signature, and full headers out of Hermes transcripts and shared workflow outputs.

Media Tweet or DM Action

Use public media URLs in media for tweet or reply actions. Store tweetId when confirmed; if the response includes writeActionId, poll GET /api/v1/x/write-actions/{id} with tweet_read before retrying. For DM attachments, upload media first, pass one returned mediaId in media_ids, then store messageId. Keep full DM bodies out of shared outputs and leave reply_to_message_id unset.

Use tweet_explore to find tweet search endpoints.
Use tweet_read for GET /api/v1/x/tweets/search with q "AI agents" and limit 25.
Return tweet id, text, author username, createdAt, and engagement counts.

Use tweet_explore with include_actions true to find follower export endpoints.
Estimate follower_explorer for @username with resultsLimit 10000.
Create the job with tweet_action only after approval.
Poll /api/v1/extractions/{id}, then export CSV, JSON, and XLSX with tweet_read.

Use tweet_explore with include_actions true to find monitor and webhook endpoints.
Create an account monitor or keyword monitor with tweet_action only after approval.
Register the receiver URL with tweet_action for POST /api/v1/webhooks.
Store the webhook secret in a secret manager.
Verify X-Xquik-Signature, store deliveryId and streamEventId, and return 2xx for accepted duplicates.
Keep endpoint signing values, raw request body, raw signature, and full headers out of Hermes transcripts and shared workflow outputs.

Use tweet_explore with include_actions true to find media write endpoints.
For a tweet or reply, call tweet_action for POST /api/v1/x/tweets with media set to public HTTPS image or MP4 URLs. Do not send media_ids.
If tweet_action for POST /api/v1/x/tweets returns writeActionId, store write_action_id, status, charged_credits, and poll GET /api/v1/x/write-actions/{id} with tweet_read before retrying.
For a DM attachment, call tweet_action for POST /api/v1/x/media first, then POST /api/v1/x/dm/{userId} with one media_ids value. Leave reply_to_message_id unset.
Return tweetId for confirmed posts, writeActionId for pending posts, and mediaId plus messageId for DMs.
Keep full DM bodies out of shared outputs.

Runtime Diagnostics

For scriptable checks, use hermes tools list. Bare hermes tools opens the interactive tool UI and requires a TTY. The list command reports plugin toolsets, so confirm hermes-tweet appears before testing calls.

hermes tools list

Run a non-mutating one-shot probe after the plugin is enabled:

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

Expected behavior:

tweet_explore can inspect catalog endpoints without an API key.
Without XQUIK_API_KEY, a non-mutating Hermes probe exposes tweet_explore only.
After XQUIK_API_KEY is configured and the CLI is reloaded, or the gateway or cron process is restarted, tweet_read can read /api/v1/account.
tweet_action stays hidden or disabled unless HERMES_TWEET_ENABLE_ACTIONS=true.
/xstatus and /xtrends appear in the Hermes plugin command registry.

Hermes one-shot prompts do not dispatch /xstatus as an interactive slash command. Verify slash commands in an active CLI or gateway session, and use hermes -z for tool-call probes. Non-interactive installs cannot prompt for credentials; set XQUIK_API_KEY in the process environment or ~/.hermes/.env.

Slash Commands

/xstatus

Show Xquik account, subscription, and usage status in an active Hermes CLI or gateway session.

/xtrends

Show current X trends from the plugin command registry.

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 106 agent-callable Xquik endpoints generated from the OpenAPI contract. The catalog includes 7 MPP-tagged read endpoints at fixed prices.

Public Reads

Tweet search, tweet lookup, user lookup, timelines, articles, and trends.

Private Reads

Account status, connected accounts, usage, and events.

Monitoring

Account monitors, keyword monitors, events, and webhooks.

Workflows

Extractions, giveaway draws, exports, compose, drafts, and styles.

Actions

Tweet, reply, like, retweet, follow, DM, profile, media, and communities.

Local Development

For local plugin development, regenerate the bundled catalog from the Xquik OpenAPI contract:

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

Run that command from the hermes-tweet repository after the Xquik OpenAPI file changes.

Verify

After installing, enabling, and setting XQUIK_API_KEY, run:

/xstatus

For scriptable diagnostics, list the plugin toolset:

hermes tools list

Then test a read workflow:

Use tweet_explore to find X trends, then use tweet_read to return current trends.

For action workflows, require an explicit draft and approval step before enabling tweet_action.

Troubleshooting

Tools Missing

Run hermes plugins enable hermes-tweet, then confirm hermes-tweet appears in hermes tools list.

Auth Fails

Confirm XQUIK_API_KEY is exported in the same environment that starts Hermes, or stored in ~/.hermes/.env.

Env Reload

Run /reload in the interactive CLI, or restart gateway and cron sessions.

Action Tool Hidden

Set HERMES_TWEET_ENABLE_ACTIONS=true only for approved action workflows.

Endpoint Missing

Regenerate the catalog from the current Xquik OpenAPI file in local development.

Risky Writes

Keep HERMES_TWEET_ENABLE_ACTIONS=false and use read tools only.

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 and expose agent-safe catalog discovery before live endpoint calls.

​Prerequisites

​Install

​Configure

​Tools