> ## 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 for Hermes Agent Twitter tools
> Install Hermes Tweet for Hermes Agent. Search tweets, export followers and replies, monitor X accounts, and run approved Twitter actions through Xquik.
For the complete documentation index, see llms.txt.
Hermes Tweet is Xquik's native Hermes Agent Twitter plugin. It provides a structured X automation toolset.
The plugin adds catalog-guided Twitter tools to the Hermes Agent runtime.
The Python package includes read tools, optional action tools, and 2 slash commands. It also bundles a reusable Hermes Twitter skill.
That reusable skill explains supported tweet and profile workflows.
Use Hermes Tweet for X search, profiles, followers, replies, monitors, and approved actions.
Every live call starts from the bundled OpenAPI catalog. This design helps Hermes choose documented methods, paths, parameters, and response shapes.
Each AI agent starts with catalog discovery. It then executes only a matching tool call.
## Why add Twitter tools to Hermes Agent
Hermes Agent handles planning, memory, tools, and long-running workflows. Hermes Tweet adds focused X and Twitter API access through Xquik.
The plugin exposes 102 agent-callable endpoints. Those endpoints cover tweets, profiles, timelines, followers, following, replies, media, monitors, and webhooks.
Hermes Tweet separates discovery, reads, and approved actions. This separation reduces guessed routes and unintended writes.
Use the plugin for these Hermes Agent Twitter tasks:
* Search tweets by keyword, phrase, hashtag, or account.
* Read tweet details, replies, quotes, and engagement counts.
* Inspect profiles, timelines, followers, following, and mentions.
* Export followers, following accounts, or tweet replies.
* Monitor accounts or keywords and deliver webhook events.
* Draft, post, reply, like, repost, follow, or send DMs.
The read tool keeps complete JSON payloads. It does not drop tweet, profile, media, or pagination fields.
## Prerequisites
* Python `3.11` or newer
* Hermes Agent with plugin support
* [Xquik API key](/x-api-quickstart)
Hermes exposes pip plugins through the `hermes_agent.plugins` entry-point group. Enable each third-party plugin before loading it.
## Install
For an existing Hermes Agent install, use the plugin installer:
```bash theme={null}
hermes plugins install Xquik-dev/hermes-tweet --enable
```
Hermes records plugin enablement in `~/.hermes/config.yaml`. The Hermes home directory is `~/.hermes`.
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:
```bash theme={null}
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:
```bash theme={null}
~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet
hermes plugins enable hermes-tweet
```
The current package version is `0.1.12`. 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:
```bash theme={null}
export XQUIK_API_KEY="xq_..."
```
For persistent Hermes sessions, add the key to `~/.hermes/.env`:
```bash theme={null}
XQUIK_API_KEY=xq_...
```
Optional environment variables:
```bash theme={null}
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:
```bash theme={null}
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`.
New agent runs read the updated environment after restart.
## Tools
Search the bundled Xquik endpoint catalog without making an API call. Use it before every live endpoint call.
Call catalog-listed read-only endpoints after you configure `XQUIK_API_KEY`.
Call write-like or private endpoints only when `HERMES_TWEET_ENABLE_ACTIONS=true`.
Start with `tweet_explore`. Discover the method, path, parameters, and response shape before any endpoint call.
```text theme={null}
Use tweet_explore to find the endpoint for user lookup, then call tweet_read for @username.
```
## Hermes Agent Twitter search
Start a tweet search with a concrete question. Ask `tweet_explore` for the catalog route before making a live call.
For keyword searches, use `GET /api/v1/x/tweets/search`. Pass a specific `q` value and a bounded `limit`.
Useful queries combine a topic with intent. Examples include product feedback, support complaints, launches, hiring, or competitor mentions.
Return fields needed by the next workflow step. Typical fields include tweet IDs, text, authors, timestamps, metrics, media, and entities.
Keep `next_cursor` whenever `has_next_page` is true. Continue only when the workflow needs another page.
Do not treat every matching tweet as equally relevant. Filter results by the task's topic, author, language, date, or engagement criteria.
For a tweet search agent, summarize patterns after collecting the selected pages. Keep source tweet IDs beside each conclusion.
## Profiles, followers, following, and replies
Hermes Tweet can inspect an account before starting a larger export. Use catalog-listed reads for profiles, timelines, followers, following, and mentions.
For small lists, use the matching read endpoint. Follow the returned cursor until the requested result count is complete.
For bulk work, use the extraction workflow. Available extraction types include `follower_explorer`, `following_explorer`, and `reply_extractor`.
Estimate each extraction before creating it. Confirm the target username, tweet ID, result limit, format, and expected scope.
After approval, create the extraction with `tweet_action`. Poll its status with `tweet_read` until the job becomes terminal.
Export completed results as CSV, JSON, or XLSX. Retain stable tweet or user IDs for later joins.
A Twitter follower export supports audience analysis and CRM enrichment. A following export lists accounts that the target follows.
A reply export supports conversation analysis, support triage, and giveaway review. Never infer sentiment from usernames alone.
## Monitors and webhook delivery
Use an account monitor for new posts from selected profiles. Use a keyword monitor for matching tweets across X.
Create monitors only after confirming the target and cadence. Register a webhook only after reviewing its receiver URL.
Store the webhook secret outside Hermes transcripts. Verify `X-Xquik-Signature` against the exact raw request body.
Store `deliveryId` and `streamEventId` for deduplication. Return `2xx` for duplicates you already accepted.
Monitor events can trigger summaries, alerts, CRM updates, or research queues. Keep each downstream action separately approved.
## Approved Twitter actions
Hermes Tweet keeps `tweet_action` unavailable by default. Enable it only for workflows that can change state.
Before every action, review the method, path, payload, account, and expected effect. Require explicit approval for the exact request.
Supported action areas include tweets, replies, likes, reposts, follows, DMs, profiles, media, communities, and lists.
Use a unique `Idempotency-Key` for durable write actions. Store the returned action ID and status URL.
Poll while `terminal` is false. Retry only when `safeToRetry` is true.
For tweet media, pass public HTTPS image or MP4 URLs in `media`. For DM media, upload first and pass its `mediaId`.
Keep full DM bodies out of shared outputs. Return only the fields needed for confirmation.
## Workflow handoffs
Use `tweet_explore` first, then choose `tweet_read` for public reads or
`tweet_action` for approved jobs that create or change state.
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.
Use `tweet_action` to estimate and create `follower_explorer`, then use
`tweet_read` to poll the job and export CSV, JSON, or XLSX results.
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. Keep endpoint signing values, raw
request body, raw signature, and full headers out of Hermes transcripts and
shared workflow outputs.
Use public media URLs in `media` for tweet or reply actions. Store the
durable action `id`, `status`, `billing`, `result`, and `statusUrl`. Poll
with `tweet_read` while `terminal` is false. For DM attachments, upload
media first, pass one returned `mediaId` in `media_ids`, then store the DM
action. Keep full DM bodies out of shared outputs and leave
`reply_to_message_id` unset.
```text theme={null}
Use tweet_explore to find tweet search endpoints.
Use tweet_read for GET /api/v1/x/tweets/search with q "AI agents". Set limit 25.
Return tweet id, text, author username, createdAt, and engagement counts.
```
```text theme={null}
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.
```
```text theme={null}
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 and raw request bodies out of Hermes transcripts.
Also exclude raw signatures and full headers from shared workflow outputs.
```
```text theme={null}
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.
Set media to public HTTPS image or MP4 URLs. Do not send media_ids.
For tweet_action, send a unique Idempotency-Key. Store id, status, billing, result, and statusUrl. Poll with tweet_read while terminal is false. Retry only when safeToRetry is true, using a new key.
For a DM attachment, call tweet_action for POST /api/v1/x/media first.
Then call POST /api/v1/x/dm/{userId} with one media_ids value. Leave reply_to_message_id unset.
Return the complete action record. Read the confirmed resource ID from result.id.
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. Confirm `hermes-tweet` appears before testing calls.
```bash theme={null}
hermes tools list
```
Run a non-mutating one-shot probe after you enable the plugin:
```bash theme={null}
hermes -z "Use tweet_explore, then read /api/v1/x/trends. 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 configuration and restart, `tweet_read` can read `/api/v1/x/trends`.
* `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.
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
Show Xquik account, subscription, and usage status in an active Hermes CLI or gateway session.
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 administrative endpoints from the catalog. It also blocks billing, credits, support, API-key, and reauthentication endpoints.
Private reads and write-like endpoints use `tweet_action`. The tool 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 102 agent-callable Xquik endpoints. OpenAPI generates the catalog.
The catalog includes MPP-tagged read endpoints at fixed prices.
Tweet search, tweet lookup, user lookup, timelines, articles, and trends.
Account status, connected accounts, usage, and events.
Account monitors, keyword monitors, events, and webhooks.
Extractions, giveaway draws, exports, compose, drafts, and styles.
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:
```bash theme={null}
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:
```text theme={null}
/xstatus
```
For scriptable diagnostics, list the plugin toolset:
```bash theme={null}
hermes tools list
```
Then test a read workflow:
```text theme={null}
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
Run `hermes plugins enable hermes-tweet`, then confirm `hermes-tweet` appears in `hermes tools list`.
Confirm you export `XQUIK_API_KEY` in the same environment that starts Hermes, or store it in `~/.hermes/.env`.
Run `/reload` in the interactive CLI, or restart gateway and cron sessions.
Set `HERMES_TWEET_ENABLE_ACTIONS=true` only for approved action workflows.
Regenerate the catalog from the current Xquik OpenAPI file in local development.
Keep `HERMES_TWEET_ENABLE_ACTIONS=false` and use read tools only.
## Hermes Agent Twitter FAQ
### What is Hermes Agent?
Hermes Agent is an open-source agent runtime from Nous Research. It supports tools, skills, plugins, memory, scheduled work, and gateway sessions.
Hermes Tweet extends that runtime with Xquik's Twitter API tools. It does not replace Hermes Agent itself.
### How do I install Hermes tweet?
Install the GitHub package with `hermes plugins install Xquik-dev/hermes-tweet --enable`. This command installs and enables the plugin.
You can also install `hermes-tweet` from PyPI. Install it inside Hermes' Python environment, then enable the plugin.
Restart Hermes after changing environment variables. Run `hermes tools list` before testing a live Twitter workflow.
### Is Hermes tweet a Hermes Agent skill or plugin?
Hermes Tweet is an executable Hermes Agent plugin. It registers `tweet_explore`, `tweet_read`, and `tweet_action`.
The package also bundles a Hermes skill. That skill teaches endpoint discovery, read selection, approvals, and secret handling.
A skill supplies operating guidance. The plugin supplies the Python tools that make API calls.
### How does Hermes Agent search Twitter?
Hermes first calls `tweet_explore` with the search goal. The catalog returns a matching method, route, parameters, and response shape.
Hermes then calls `tweet_read` for `GET /api/v1/x/tweets/search`. The `q` parameter contains the keyword, phrase, hashtag, or account query.
The result can include tweets, authors, timestamps, engagement metrics, media, and pagination fields. The exact payload follows the Xquik API response.
### Can Hermes Agent export Twitter followers?
Yes. Use `tweet_explore` to find `follower_explorer`, then estimate the requested result count.
Create the extraction only after approval. Poll the extraction and export the completed followers as CSV, JSON, or XLSX.
The same workflow supports `following_explorer`. Choose it when the task needs accounts followed by a profile.
### Can Hermes Agent export tweet replies?
Yes. Use `reply_extractor` for a bounded reply export. Confirm the target tweet ID and result limit before creation.
Store tweet IDs, author IDs, timestamps, reply text, and available metrics. Keep cursors or job status for reproducible collection.
Use the exported replies for support triage, conversation research, or giveaway review. Apply project-specific privacy and retention rules.
### Can Hermes Agent monitor X accounts?
Yes. Account monitors watch selected profiles. Keyword monitors watch matching tweets.
Send monitor events to a verified webhook receiver. Deduplicate events before triggering alerts or downstream actions.
### Does Hermes tweet need X developer credentials?
No. It needs no X developer credentials. Hermes Tweet authenticates with an Xquik API key.
Keep `XQUIK_API_KEY` in the Hermes runtime environment. Never pass that key through a model-visible tool argument.
### Hermes Agent vs OpenClaw: which plugin should I use?
Choose Hermes Tweet for Hermes Agent. Choose TweetClaw for OpenClaw.
Hermes Tweet is a Python entry-point plugin. TweetClaw is an npm plugin for OpenClaw.
Both use the Xquik API contract. Both start with catalog discovery before live Twitter calls.
Do not install both for one runtime. Pick the plugin that matches the agent host.
### Is Hermes tweet an MCP server?
No. Hermes Tweet runs inside Hermes Agent and registers native Python tools.
Use the [Xquik MCP server](/mcp/overview) when your client supports MCP. Use Hermes Tweet for native Hermes plugin loading.
### Why are Hermes tweet tools missing?
Confirm installation with `hermes plugins`. Enable the plugin with `hermes plugins enable hermes-tweet`.
Then run `hermes tools list`. Confirm the `hermes-tweet` toolset appears.
Restart Hermes after configuration changes. Check the startup output for a plugin registration failure.
An open Hermes Agent issue reports some import-time failures can remain cached. Restart after fixing the registration error.
### Where is Hermes tweet on GitHub?
The official repository is [Xquik-dev/hermes-tweet](https://github.com/Xquik-dev/hermes-tweet). It contains source, tests, release notes, security policy, and plugin metadata.
Use the repository issue tracker for reproducible plugin defects. Use these docs for supported Xquik workflows and API routes.
## References
* [Hermes Tweet GitHub repo](https://github.com/Xquik-dev/hermes-tweet)
* [Hermes Tweet on PyPI](https://pypi.org/project/hermes-tweet/)
* [Hermes Agent plugin docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins)
* [TweetClaw for OpenClaw](/guides/tweetclaw)
* [API Reference](/api-reference/overview)
* [MCP Server](/mcp/overview)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.