Hermes XAPI for Hermes Agent

Install and configure the Hermes XAPI plugin for Twexapi-powered X/Twitter automation in Hermes Agent.

Hermes XAPI is the native Hermes Agent plugin for using Twexapi as a structured X/Twitter automation toolset. It packages the Twexapi endpoint catalog, read tools, optional action tools, slash commands, and a bundled Hermes skill into a Python plugin.

Use Hermes XAPI when a Hermes Agent workflow needs X/Twitter search, account reads, profile lookups, trends, followers, replies, articles, DMs, tweet posting, likes, retweets, follows, or account status checks.

Prerequisites

Python 3.11 or newer
Hermes Agent with plugin support
A Twexapi API key from the dashboard

Hermes plugins are opt-in. Install and enable the plugin before expecting the hermes-xapi toolset to appear.

Install

Use Hermes’ plugin installer for the public GitHub repo:

hermes plugins install twexapi-dev/hermes-xapi --enable

Hermes prompts for TWEXAPI_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 xapi_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-xapi
hermes plugins enable hermes-xapi

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

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

The current package version is 0.1.6. The plugin name is hermes-xapi, and the Python entry point is hermes-xapi = hermes_xapi.

Configure

Set your Twexapi API key before starting Hermes:

export TWEXAPI_KEY="twitterx_..."

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

TWEXAPI_KEY=twitterx_...

Optional environment variables:

export TWEXAPI_BASE_URL="https://api.twexapi.io"
export HERMES_XAPI_ENABLE_ACTIONS="false"

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

export HERMES_XAPI_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 xapi_read.

Tools

Tool	Purpose
`xapi_explore`	Search the bundled Twexapi endpoint catalog without making an API call. Use it before every live endpoint call.
`xapi_read`	Call catalog-listed read-only endpoints after `TWEXAPI_KEY` is configured.
`xapi_action`	Call private, paid-bulk, or write-like endpoints only when `HERMES_XAPI_ENABLE_ACTIONS=true`.

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

Use xapi_explore to find the endpoint for user lookup, then call xapi_read for @username.

Workflow handoffs

Use xapi_explore first, then choose xapi_read for public reads or xapi_action for approved jobs that create or change state.

Tweet search read

Use xapi_read with /twitter/advanced_search/page or another catalog-listed search endpoint. Return tweet IDs, text, author usernames, timestamps, engagement metrics, has_more, and next_cursor when present.

Use xapi_explore to find tweet search endpoints.
Use xapi_read for /twitter/advanced_search/page with searchTerms ["AI agents"] and maxItems 25.
Return tweet_id, text, author_username, created_at, and engagement counts.

Trend research

Use xapi_explore to find trending routes, then call xapi_read for country, topic, content, or trend endpoints.

Use xapi_explore to find X/Twitter trend endpoints.
Use xapi_read to return current trends for worldwide.
Preserve the country, topic, content, rank, has_more, and next_cursor fields when present.

Follower export

Use xapi_explore to find follower endpoints. Use xapi_read for bounded reads and xapi_action only when the catalog marks the route as private, paid-bulk, or action-like.

Use xapi_explore to find follower export endpoints.
Fetch followers for @username with a bounded count.
If the response returns a task_id, store it and poll the documented status and next-page routes.

Controlled write action

Use xapi_action only after approval. Keep action tools disabled in unattended sessions.

Use xapi_explore with include_actions true to find tweet posting endpoints.
Draft the exact request body.
Ask for explicit approval.
Only after approval, call xapi_action.
Return tweet_id, status, charged_credits, and any write action ID.

Runtime diagnostics

For scriptable checks, use hermes tools list. Bare hermes tools opens the interactive tool UI and requires a TTY.

hermes tools list

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

hermes -z "Use xapi_explore, then read /twitter/elonmusk/about. Do not call xapi_action." --toolsets hermes-xapi

Expected behavior:

xapi_explore can inspect catalog endpoints without an API key.
Without TWEXAPI_KEY, a non-mutating Hermes probe exposes xapi_explore only.
After TWEXAPI_KEY is configured and the CLI is reloaded, or the gateway or cron process is restarted, xapi_read can read /twitter/elonmusk/about.
xapi_action stays hidden or disabled unless HERMES_XAPI_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, TUI, Desktop, or gateway session, and use hermes -z for tool-call probes.

Non-interactive installs cannot prompt for credentials; set TWEXAPI_KEY in the process environment or ~/.hermes/.env.

Slash commands

Command	Purpose
`/xstatus`	Show Twexapi account, subscription, and usage status in an active Hermes session.
`/xtrends`	Show current X/Twitter trends from the plugin command registry.

Safety model

Hermes XAPI 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 cookie/token helper routes, engagement-purchase routes, auto-cookie posting, profile mutation, list creation, and sentiment routes from the agent catalog. Private reads, paid-bulk endpoints, and write-like endpoints go through xapi_action, which stays hidden unless HERMES_XAPI_ENABLE_ACTIONS=true.

For unattended jobs, keep action tools disabled and use only xapi_explore plus xapi_read.

API coverage

Hermes XAPI includes 76 agent-callable Twexapi endpoints generated from the OpenAPI contract.

Area	Common uses
Public reads	Tweet search, tweet lookup, user lookup, timelines, articles, replies, and trends.
Private reads	Account status, balance, and account-level checks.
Relationship data	Followers, following, retweeters, quote tweets, and favoriters.
Communities and lists	Community metadata, members, tweets, list tweets, subscribers, and members.
Actions	Tweet, reply, like, retweet, follow, DM, media, bookmarks, articles, and account operations when enabled.

Local development

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

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

Run that command from the hermes-xapi repository after the Twexapi OpenAPI file changes.

Verify

After installing, enabling, and setting TWEXAPI_KEY, run:

/xstatus

For scriptable diagnostics, list the plugin toolset:

hermes tools list

Then test a read workflow:

Use xapi_explore to find X/Twitter trends, then use xapi_read to return current trends.

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

Troubleshooting

Problem	Fix
Tools missing	Run `hermes plugins enable hermes-xapi`, then confirm `hermes-xapi` appears in `hermes tools list`.
Auth fails	Confirm `TWEXAPI_KEY` is exported in the same environment that starts Hermes, or stored in `~/.hermes/.env`.
Env changes not picked up	Run `/reload` in the interactive CLI, or restart gateway and cron sessions.
Action tool hidden	Set `HERMES_XAPI_ENABLE_ACTIONS=true` only for approved action workflows.
Endpoint missing	Regenerate the catalog from the current Twexapi OpenAPI file in local development.
Risky writes	Keep `HERMES_XAPI_ENABLE_ACTIONS=false` and use read tools only.

Relationship to XApiClaw

XApiClaw is the OpenClaw-native npm plugin. Hermes XAPI is the Hermes-native Python plugin. Both use the same Twexapi API contract and expose agent-safe catalog discovery before live endpoint calls.