{"id":50824400,"url":"https://github.com/Xquik-dev/hermes-tweet","last_synced_at":"2026-06-19T20:00:59.566Z","repository":{"id":355947661,"uuid":"1230366935","full_name":"Xquik-dev/hermes-tweet","owner":"Xquik-dev","description":"Native Hermes Agent plugin for X/Twitter automation through Xquik","archived":false,"fork":false,"pushed_at":"2026-06-14T04:53:19.000Z","size":536,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-14T06:09:32.216Z","etag":null,"topics":["agent-skill","agent-tools","ai-agent","automation","hermes","hermes-agent","hermes-plugin","mcp","python","social-media","social-media-api","social-media-automation","tweet","twitter","twitter-api","twitter-automation","x-api","x-automation","x-twitter","xquik"],"latest_commit_sha":null,"homepage":"https://github.com/Xquik-dev/hermes-tweet#readme","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xquik-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"Xquik-dev"}},"created_at":"2026-05-05T23:42:53.000Z","updated_at":"2026-06-14T04:53:22.000Z","dependencies_parsed_at":"2026-05-10T08:01:50.846Z","dependency_job_id":null,"html_url":"https://github.com/Xquik-dev/hermes-tweet","commit_stats":null,"previous_names":["xquik-dev/hermes-tweet"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Xquik-dev/hermes-tweet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xquik-dev%2Fhermes-tweet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xquik-dev%2Fhermes-tweet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xquik-dev%2Fhermes-tweet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xquik-dev%2Fhermes-tweet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xquik-dev","download_url":"https://codeload.github.com/Xquik-dev/hermes-tweet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xquik-dev%2Fhermes-tweet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34546199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","agent-tools","ai-agent","automation","hermes","hermes-agent","hermes-plugin","mcp","python","social-media","social-media-api","social-media-automation","tweet","twitter","twitter-api","twitter-automation","x-api","x-automation","x-twitter","xquik"],"created_at":"2026-06-13T17:01:12.842Z","updated_at":"2026-06-19T20:00:59.510Z","avatar_url":"https://github.com/Xquik-dev.png","language":"Python","funding_links":["https://github.com/sponsors/Xquik-dev"],"categories":["Skills \u0026 Plugins","Domain-Specific Skills"],"sub_categories":["Plugins","Compliance \u0026 Auditing"],"readme":"# Hermes Tweet\n\n[![CI](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml/badge.svg)](https://github.com/Xquik-dev/hermes-tweet/actions/workflows/ci.yml)\n[![Docs](https://img.shields.io/badge/docs-README-blue.svg)](https://github.com/Xquik-dev/hermes-tweet#readme)\n\u003ca href=\"https://nothumansearch.ai/site/xquik.com\" target=\"_blank\" rel=\"noopener\"\u003e\u003cimg src=\"https://nothumansearch.ai/badge/xquik.com.svg\" alt=\"NHS Agentic Readiness Score\" height=\"28\"\u003e\u003c/a\u003e\n[![Ask DeepWiki](https://deepwiki.com/badge.svg?url=https%3A%2F%2Fgithub.com%2FXquik-dev%2Fhermes-tweet)](https://deepwiki.com/Xquik-dev/hermes-tweet)\n[![PyPI](https://img.shields.io/pypi/v/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)\n[![piwheels](https://img.shields.io/piwheels/v/hermes-tweet.svg)](https://piwheels.org/project/hermes-tweet/)\n[![Python](https://img.shields.io/pypi/pyversions/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)\n[![PyPI Status](https://img.shields.io/pypi/status/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)\n[![Wheel](https://img.shields.io/pypi/wheel/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/#files)\n[![Downloads](https://img.shields.io/pypi/dm/hermes-tweet.svg)](https://pypi.org/project/hermes-tweet/)\n[![Release](https://img.shields.io/github/v/release/Xquik-dev/hermes-tweet?sort=semver)](https://github.com/Xquik-dev/hermes-tweet/releases)\n[![Apify Actor](https://apify.com/actor-badge?actor=xquik/x-tweet-scraper)](https://apify.com/xquik/x-tweet-scraper)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nNative [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin for\nX automation through [Xquik](https://xquik.com).\n\nHermes Tweet brings X search, account reads, tweet posting, replies, likes,\nretweets, follows, DMs, monitors, webhooks, draws, extraction jobs, media, and\ntrend reads into Hermes as structured tools.\n\nUse it when you need a Hermes Agent Twitter plugin, Hermes X automation, social\nmedia automation for agents, or a native Hermes toolset for X/Twitter.\n\n## Highlights\n\n- Published Python package with a native Hermes plugin entry point.\n- Installable from PyPI as `hermes-tweet`.\n- 99 agent-callable Xquik endpoints generated from OpenAPI.\n- 31 MPP-tagged read endpoints in the bundled catalog.\n- Read and action tools are split for least-privilege operation.\n- Action endpoints are disabled by default.\n- Bundled Hermes skill for agent-facing usage guidance.\n- Slash commands for account status and trends.\n- Current guidance for Hermes Agent v0.16.0 Desktop, remote gateway, and\n  dashboard credential workflows.\n- Strict CI with formatting, linting, type checking, tests, coverage, security\n  scan, dependency audit, and package build checks.\n\n## Install\n\nRecommended Hermes plugin install:\n\n```bash\nhermes plugins install Xquik-dev/hermes-tweet --enable\n```\n\nHermes Agent treats third-party plugins as opt-in. Without `--enable`, the\ninstaller can discover Hermes Tweet, but it may leave the plugin in the\n`not enabled` state until you run `hermes plugins enable hermes-tweet` or toggle\nit in the interactive `hermes plugins` UI. Use `hermes plugins list` when a\nfresh install does not show the `hermes-tweet` toolset.\n\nHermes will prompt for `XQUIK_API_KEY` during an interactive install and save it\nto `~/.hermes/.env`. In non-interactive installs the prompt is skipped; set the\nkey through the environment or `~/.hermes/.env` before running `tweet_read`.\nIf you edit `~/.hermes/.env` while Hermes is already running, use `/reload` in\nan interactive CLI session, or restart gateway and cron sessions before calling\n`tweet_read`.\nWhen `XQUIK_API_KEY` is not configured, Hermes should expose only the no-network\n`tweet_explore` tool from this plugin. That is expected safe gating, not an\ninstall failure.\n\nInstall the published Python package from PyPI into the Hermes Python\nenvironment:\n\n```bash\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet\nhermes plugins enable hermes-tweet\n```\n\nIf your Hermes venv includes `pip`, this path is also valid:\n\n```bash\n~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet\nhermes plugins enable hermes-tweet\n```\n\nFrom a local checkout:\n\n```bash\nhermes plugins install file:///absolute/path/to/hermes-tweet --force --enable\n```\n\nIf you are testing from a project-local `.hermes/plugins/` directory instead of\ninstalling the plugin into `~/.hermes/plugins/` or through the PyPI entry point,\nstart Hermes with `HERMES_ENABLE_PROJECT_PLUGINS=true` only for trusted\nrepositories.\n\nHermes Agent v0.16.0 adds a native desktop app and remote gateway profiles.\nFor a remote gateway profile, install and enable Hermes Tweet on the remote\nHermes host because that is where plugin code executes and where\n`XQUIK_API_KEY` must be available. The desktop app is the chat surface; it\nshould not receive or store the key unless it is also running the Hermes\nruntime locally.\n\n## Python Package\n\n| Field | Value |\n| --- | --- |\n| PyPI | [`hermes-tweet`](https://pypi.org/project/hermes-tweet/) |\n| Official guide | [`github.com/Xquik-dev/hermes-tweet#readme`](https://github.com/Xquik-dev/hermes-tweet#readme) |\n| Context7 | [`context7.com/xquik-dev/hermes-tweet`](https://context7.com/xquik-dev/hermes-tweet) |\n| piwheels | [`hermes-tweet`](https://piwheels.org/project/hermes-tweet/) |\n| Latest release | [`v0.1.6`](https://github.com/Xquik-dev/hermes-tweet/releases/tag/v0.1.6) |\n| Supported Python | `\u003e=3.11` |\n| Package format | Wheel and source distribution |\n| Hermes entry point | `hermes-tweet = hermes_tweet` |\n| Entry point group | `hermes_agent.plugins` |\n| Included assets | `plugin.yaml`, `catalog_data.json`, bundled Hermes skill, Codex/Claude manifests |\n| Claude plugin manifest | [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) |\n| Codex plugin manifest | [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) |\n| Registry skill path | [`skills/hermes-tweet/SKILL.md`](skills/hermes-tweet/SKILL.md) |\n| Context7 guide | [`docs/CONTEXT7.md`](docs/CONTEXT7.md) |\n| Hermes surface guide | [`docs/HERMES_SURFACES.md`](docs/HERMES_SURFACES.md) |\n| Integration patterns | [`docs/INTEGRATION_PATTERNS.md`](docs/INTEGRATION_PATTERNS.md) |\n| Submission readiness | [`docs/SUBMISSION_READINESS.md`](docs/SUBMISSION_READINESS.md) |\n\nHermes Tweet also ships source-native `.codex-plugin` metadata, a root\nsecurity policy, a local composer icon, and a HOL Plugin Scanner workflow for\nCodex plugin catalogs that require local validation evidence before listing.\n\n## Configure\n\nCreate an API key in the Xquik dashboard, then set:\n\n```bash\nexport XQUIK_API_KEY=\"xq_...\"\n```\n\nOptional settings:\n\n```bash\nexport XQUIK_BASE_URL=\"https://xquik.com\"\nexport HERMES_TWEET_ENABLE_ACTIONS=\"false\"\n```\n\nAction endpoints are disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.\nIf you configure keys through `~/.hermes/.env` during an active Hermes session,\nuse `/reload` in the interactive CLI, or restart gateway and cron sessions so\nthey pick up the new values.\n\n## Security Model\n\nHermes Tweet never accepts credentials through tool arguments. Auth is read from\nenvironment variables and injected by the plugin at request time.\n\nThe plugin blocks dashboard-only admin, billing, credit top-up, support-ticket,\nAPI-key, and account re-authentication endpoints from the catalog. Private reads\nand write-like endpoints go through `tweet_action`, which is hidden unless\n`HERMES_TWEET_ENABLE_ACTIONS=true`.\n\n## Tools\n\n| Tool | Purpose |\n| --- | --- |\n| `tweet_explore` | Search the bundled Xquik endpoint catalog. No API call. |\n| `tweet_read` | Call catalog-listed read-only endpoints. |\n| `tweet_action` | Call write-like or private endpoints. Disabled by default. |\n\nUse `tweet_explore` first, then call `tweet_read` or `tweet_action` with a\nconcrete `/api/v1/...` path.\nCopied endpoint URLs are accepted, but Hermes Tweet matches only catalog-listed\npaths.\n\n## Hermes Agent Workflows\n\nHermes Tweet is best used as the X context layer for Hermes Agent workflows that\nneed current public signal, authenticated account context, or approval-gated\naccount actions:\n\n| Workflow | Recommended Path |\n| --- | --- |\n| Social listening | Use `tweet_explore` to find search, user, trend, monitor, or radar routes, then use `tweet_read` for public reads. |\n| Launch monitoring | Keep `tweet_action` disabled, schedule Hermes cron sessions around read-only trend, mention, and account checks. |\n| Support triage | Read public mentions and user timelines, summarize issues in Hermes, then hand off account-changing responses for explicit approval. |\n| Creator or brand research | Combine X search, user profile, follower, media, and trend reads before drafting content or campaign briefs. |\n| Giveaway and community audits | Use read routes for tweet, reply, follower, list, draw, and export evidence before any action route. |\n| Controlled publishing | Enable `HERMES_TWEET_ENABLE_ACTIONS=true` only in sessions that require posting, DMs, follows, webhooks, monitors, or media changes. |\n| Desktop operator sessions | Use Hermes Desktop for interactive review, then keep action calls explicit and approval-gated. |\n| Remote gateway teams | Install Hermes Tweet and set `XQUIK_API_KEY` on the remote gateway host, then connect Desktop profiles to that host. |\n| Dashboard-administered agents | Use the dashboard for gateway and credential operations, but keep Hermes Tweet secrets in the runtime environment. |\n\nFor marketing or user education, position Hermes Tweet as a native Hermes Agent\nplugin, not a generic API wrapper: it ships a PyPI entry point, a `plugin.yaml`\nmanifest with interactive secret prompts, slash commands for quick diagnostics,\nand a bundled skill registered through Hermes' plugin skill system.\n\n## Hermes Runtime Fit\n\nHermes Tweet registers a dedicated `hermes-tweet` plugin toolset. Hermes can\nshow and manage those tools through its normal `hermes tools` and platform\ntoolset flows, so teams can keep X automation available only where it belongs.\nCurrent Hermes Agent releases discover third-party plugins but do not execute\nthem until they are enabled in `plugins.enabled`, through `hermes plugins enable`,\nor by installing with `--enable`. This is expected safety behavior for user and\nPyPI entry-point plugins.\n\nHermes Agent v0.16.0 expands the surfaces where the same toolset can appear:\nthe native Desktop app, remote gateway profiles, the web dashboard, the TUI,\nand the CLI can all route work to the enabled runtime. Hermes Tweet does not\nneed a different plugin entry point for those surfaces. It needs the same\nenabled plugin, the same runtime environment, and the same read/action split.\n\nThe v0.16.0 Desktop command palette surfaces skills and quick-command slash\ncommands. Treat `/xstatus` and `/xtrends` as interactive runtime commands for\nactive CLI, TUI, Desktop, or gateway sessions; keep `hermes -z` for tool-call\nsmoke tests.\n\nThe v0.16.0 dashboard added broader administration and credential-management\nsurfaces. Those are useful for gateway operations, but Hermes Tweet still reads\n`XQUIK_API_KEY` and `HERMES_TWEET_ENABLE_ACTIONS` from the runtime environment.\nDo not paste API keys into prompts, issue bodies, PR comments, or tool inputs.\n\nFor non-interactive smoke tests and CI-style diagnostics, use\n`hermes tools list`; bare `hermes tools` opens the interactive tool UI and\nrequires a TTY. In current Hermes Agent releases, `hermes tools list` reports plugin toolsets,\nnot every individual plugin tool name.\n\nUse the read-only path for social listening, trend research, account checks,\ngiveaway audits, and draft planning. Keep `HERMES_TWEET_ENABLE_ACTIONS=false`\nfor unattended cron or gateway sessions unless the workflow has an explicit\napproval step for posting, DMs, follows, monitor changes, webhook changes, or\nother account actions.\n\nRuntime smoke test:\n\n```bash\nhermes -z \"Use tweet_explore, then read /api/v1/account. Do not call tweet_action.\" --toolsets hermes-tweet\n```\n\nExpected results:\n\n- `tweet_explore` discovers catalog endpoints without using the API key.\n- Without `XQUIK_API_KEY`, a non-mutating Hermes probe exposes `tweet_explore`\n  only.\n- After `XQUIK_API_KEY` is configured and the CLI is reloaded, or the gateway\n  or cron process is restarted, `tweet_read` can read `/api/v1/account`.\n- `tweet_action` stays hidden or disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.\n- `/xstatus` and `/xtrends` appear in the Hermes plugin command registry.\n\nHermes one-shot `hermes -z \"/xstatus\"` can run as a model prompt, not as the\ninteractive slash-command dispatcher. Verify slash commands in an active CLI,\nTUI, Desktop, or gateway session, or through the plugin registry tests, and use\n`hermes -z` for tool-call probes.\n\nIf `hermes plugins install` runs without a TTY, Hermes cannot safely prompt for\nsecrets and will skip API-key storage. This is expected; set `XQUIK_API_KEY`\nin the process environment or `~/.hermes/.env`.\n\n## Slash Commands\n\n| Command | Purpose |\n| --- | --- |\n| `/xstatus` | Show Xquik account, subscription, and usage status. |\n| `/xtrends` | Show current X trends. |\n\n## Development\n\nGenerate the bundled catalog from Xquik OpenAPI:\n\n```bash\npython scripts/build_catalog.py ../xquik/openapi.yaml\n```\n\nRun checks:\n\n```bash\nuv run --python 3.12 --extra dev ruff format --check .\nuv run --python 3.12 --extra dev ruff check .\nuv run --python 3.12 --extra dev basedpyright\nuv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100\nuv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts\nuv run --python 3.12 --extra dev pip-audit\nuv run --python 3.12 --extra dev python -m build\nuv run --python 3.12 --extra dev twine check dist/*\n```\n\nFor a single local quality gate:\n\n```bash\nuv run --python 3.12 --extra dev ruff format --check . \u0026\u0026 \\\nuv run --python 3.12 --extra dev ruff check . \u0026\u0026 \\\nuv run --python 3.12 --extra dev basedpyright \u0026\u0026 \\\nuv run --python 3.12 --extra dev pytest --cov=hermes_tweet --cov=tests --cov-report=term-missing --cov-fail-under=100 \u0026\u0026 \\\nuv run --python 3.12 --extra dev bandit -c pyproject.toml -r hermes_tweet scripts \u0026\u0026 \\\nuv run --python 3.12 --extra dev pip-audit \u0026\u0026 \\\nuv run --python 3.12 --extra dev python -m build \u0026\u0026 \\\nuv run --python 3.12 --extra dev twine check dist/*\n```\n\n## Relationship To TweetClaw\n\nTweetClaw is the OpenClaw-native npm plugin. Hermes Tweet is the Hermes-native\nPython plugin. Both use the same Xquik API contract.\n\n## Public Repo Metadata\n\nRecommended GitHub description:\n\n\u003e Native Hermes Agent plugin for X/Twitter automation through Xquik.\n\nRecommended topics:\n\n`hermes-agent`, `hermes-plugin`, `hermes`, `twitter`, `x-api`,\n`x-automation`, `xquik`, `tweet`, `automation`, `social-media`,\n`social-media-automation`, `ai-agent`, `mcp`, `agent-tools`, `twitter-api`,\n`twitter-automation`, `x-twitter`, `social-media-api`, `agent-skill`, `python`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FXquik-dev%2Fhermes-tweet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FXquik-dev%2Fhermes-tweet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FXquik-dev%2Fhermes-tweet/lists"}