{"id":49649698,"url":"https://github.com/xquik-dev/hermes-tweet","last_synced_at":"2026-05-12T10:01:38.360Z","repository":{"id":355947661,"uuid":"1230366935","full_name":"Xquik-dev/hermes-tweet","owner":"Xquik-dev","description":"Native Hermes Agent plugin for X automation through Xquik","archived":false,"fork":false,"pushed_at":"2026-05-07T23:12:20.000Z","size":247,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-08T06:03:21.369Z","etag":null,"topics":["agent-tools","ai-agent","apify","automation","hermes","hermes-agent","hermes-plugin","mcp","python","social-media","social-media-automation","tweet","twitter","twitter-api","twitter-automation","x-api","x-automation","x-twitter","xquik"],"latest_commit_sha":null,"homepage":"https://docs.xquik.com/guides/hermes-tweet","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-05-07T23:12:23.000Z","dependencies_parsed_at":"2026-05-08T06:02:36.243Z","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":32810381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T08:22:46.396Z","status":"online","status_checked_at":"2026-05-09T02:00:06.633Z","response_time":123,"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-tools","ai-agent","apify","automation","hermes","hermes-agent","hermes-plugin","mcp","python","social-media","social-media-automation","tweet","twitter","twitter-api","twitter-automation","x-api","x-automation","x-twitter","xquik"],"created_at":"2026-05-06T04:03:56.031Z","updated_at":"2026-05-09T07:01:10.343Z","avatar_url":"https://github.com/Xquik-dev.png","language":"Python","funding_links":["https://github.com/sponsors/Xquik-dev"],"categories":[],"sub_categories":[],"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[![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://www.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- 32 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- 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 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\nthe session or start a new session before calling `tweet_read`.\n\nInstall the published Python package from PyPI:\n\n```bash\n~/.hermes/hermes-agent/venv/bin/python -m pip install hermes-tweet\nhermes plugins enable hermes-tweet\n```\n\nUse `uv` inside your Hermes Python environment:\n\n```bash\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python 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\n## Python Package\n\n| Field | Value |\n| --- | --- |\n| PyPI | [`hermes-tweet`](https://pypi.org/project/hermes-tweet/) |\n| piwheels | [`hermes-tweet`](https://www.piwheels.org/project/hermes-tweet/) |\n| Latest release | [`v0.1.2`](https://github.com/Xquik-dev/hermes-tweet/releases/tag/v0.1.2) |\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 |\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` so the session picks 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.\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.\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.\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- `tweet_read` can read `/api/v1/account` when `XQUIK_API_KEY` is configured.\n- `tweet_action` reports disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.\n- `/xstatus` and `/xtrends` appear in the Hermes plugin command registry.\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`, `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`, `apify`, `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"}