> ## 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

> Install Hermes Tweet. Search tweets, export followers, and run approved X actions from Hermes Agent.

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

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](/quickstart)

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:

```bash theme={null}
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:

```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.11`. 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`.

## Tools

<CardGroup cols={3}>
  <Card title="tweet_explore" icon="search">
    Search the bundled Xquik endpoint catalog without making an API call. Use it before every live endpoint call.
  </Card>

  <Card title="tweet_read" icon="book-open">
    Call catalog-listed read-only endpoints after `XQUIK_API_KEY` is configured.
  </Card>

  <Card title="tweet_action" icon="shield-check">
    Call write-like or private endpoints only when `HERMES_TWEET_ENABLE_ACTIONS=true`.
  </Card>
</CardGroup>

Start with `tweet_explore` so the agent can discover the right method, path, parameters, and response shape before it calls an endpoint.

```text theme={null}
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.

<CardGroup cols={2}>
  <Card title="Tweet Search Read" icon="search">
    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.
  </Card>

  <Card title="Follower Export Action" icon="users">
    Use `tweet_action` to estimate and create `follower_explorer`, then use
    `tweet_read` to poll the job and export CSV, JSON, or XLSX results.
  </Card>

  <Card title="Monitor Webhook Action" icon="radio">
    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.
  </Card>

  <Card title="Media Tweet or DM Action" icon="image">
    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.
  </Card>
</CardGroup>

```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" and 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, raw request body, raw signature, and full headers out of Hermes transcripts and 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 with media set 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 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, so confirm `hermes-tweet` appears before testing calls.

```bash theme={null}
hermes tools list
```

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="/xstatus" icon="terminal">
    Show Xquik account, subscription, and usage status in an active Hermes CLI or gateway session.
  </Card>

  <Card title="/xtrends" icon="trending-up">
    Show current X trends from the plugin command registry.
  </Card>
</CardGroup>

## 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 102 agent-callable Xquik endpoints. OpenAPI generates the catalog.

The catalog includes 7 MPP-tagged read endpoints at fixed prices.

<CardGroup cols={2}>
  <Card title="Public Reads" icon="search">
    Tweet search, tweet lookup, user lookup, timelines, articles, and trends.
  </Card>

  <Card title="Private Reads" icon="shield-check">
    Account status, connected accounts, usage, and events.
  </Card>

  <Card title="Monitoring" icon="activity">
    Account monitors, keyword monitors, events, and webhooks.
  </Card>

  <Card title="Workflows" icon="terminal">
    Extractions, giveaway draws, exports, compose, drafts, and styles.
  </Card>

  <Card title="Actions" icon="trending-up">
    Tweet, reply, like, retweet, follow, DM, profile, media, and communities.
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Tools Missing" icon="terminal">
    Run `hermes plugins enable hermes-tweet`, then confirm `hermes-tweet` appears in `hermes tools list`.
  </Card>

  <Card title="Auth Fails" icon="shield-check">
    Confirm `XQUIK_API_KEY` is exported in the same environment that starts Hermes, or stored in `~/.hermes/.env`.
  </Card>

  <Card title="Env Reload" icon="activity">
    Run `/reload` in the interactive CLI, or restart gateway and cron sessions.
  </Card>

  <Card title="Action Tool Hidden" icon="shield-check">
    Set `HERMES_TWEET_ENABLE_ACTIONS=true` only for approved action workflows.
  </Card>

  <Card title="Endpoint Missing" icon="search">
    Regenerate the catalog from the current Xquik OpenAPI file in local development.
  </Card>

  <Card title="Risky Writes" icon="shield-check">
    Keep `HERMES_TWEET_ENABLE_ACTIONS=false` and use read tools only.
  </Card>
</CardGroup>

## 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.

## 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)