{"id":51417674,"url":"https://github.com/offendingcommit/hermes-plugin-discord-tools","last_synced_at":"2026-07-04T21:30:21.273Z","repository":{"id":364394444,"uuid":"1267373300","full_name":"offendingcommit/hermes-plugin-discord-tools","owner":"offendingcommit","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-12T21:09:09.000Z","size":99,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T22:22:35.769Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/offendingcommit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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}},"created_at":"2026-06-12T13:34:14.000Z","updated_at":"2026-06-12T21:09:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/offendingcommit/hermes-plugin-discord-tools","commit_stats":null,"previous_names":["offendingcommit/hermes-plugin-discord-tools"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/offendingcommit/hermes-plugin-discord-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Fhermes-plugin-discord-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Fhermes-plugin-discord-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Fhermes-plugin-discord-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Fhermes-plugin-discord-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/offendingcommit","download_url":"https://codeload.github.com/offendingcommit/hermes-plugin-discord-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/offendingcommit%2Fhermes-plugin-discord-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35136712,"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-07-04T02:00:05.987Z","response_time":113,"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":[],"created_at":"2026-07-04T21:30:20.688Z","updated_at":"2026-07-04T21:30:21.264Z","avatar_url":"https://github.com/offendingcommit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hermes-plugin-discord-tools\n\nRead-only Discord tools for Hermes Discord-facing agents.\n\nThe plugin lets a bot use its existing Discord bot token to read a channel,\nthread, or linked message that the bot can already access. It is intended as a\nbackstop when Hindsight or other memory processing is behind, especially for\nstory channels where the bot should be able to inspect the current source of\ntruth before answering.\n\n## Tools\n\n- `discord_read_channel`: read recent messages from a Discord channel URL or ID\n  (`channel_id_or_url`).\n- `discord_read_thread`: read recent messages from a Discord thread URL or ID\n  (`thread_id_or_url`).\n- `discord_get_message`: fetch one linked message plus bounded prior context\n  (`message_id_or_url`).\n- `discord_read_story`: read a **preconfigured** story thread by `name` (or with\n  no arguments when only one is configured). No Discord URL/ID needed — the\n  thread ID comes from env config, so the agent never has to supply a snowflake\n  it does not have. See `DISCORD_TOOLS_STORY_THREADS_JSON` below.\n\nAll tools return JSON with a `success` flag. They never write to Discord or to\nmemory. Each tool's required argument name is repeated in its description (not\nonly the JSON schema) so the agent can call it correctly even when a runtime\nsurfaces the schema's `properties` as empty.\n\n## Logging\n\nThe plugin logs under the `discord-tools` logger. On a rejected argument it logs\na `WARNING` with the offending value (truncated, never the token), and on a\nsuccessful read an `INFO` line with the resolved target. To watch it in a pod:\n\n```bash\nkubectl logs -f \u003cpod\u003e | grep discord-tools\n```\n\n## Hook\n\n`pre_llm_call` injects a compact hint when the current turn mentions a Discord\nchannel/message link. It can also surface static story hints from\n`DISCORD_TOOLS_STORY_HINTS` or `DISCORD_TOOLS_STORY_HINTS_JSON`.\n\nExample inline story hint config:\n\n```json\n[\n  {\n    \"name\": \"Bea's House of Tea\",\n    \"keywords\": [\"bea's house of tea\", \"house of tea\", \"ember revealed\"],\n    \"hint\": \"Use discord_read_channel or discord_get_message on linked source channels before relying on stale memory.\"\n  }\n]\n```\n\nIf `DISCORD_TOOLS_STORY_HINTS_JSON` is a JSON string it is parsed directly. If\nit is a filesystem path, the hook reads that local JSON file.\n\n## Environment\n\n- `DISCORD_BOT_TOKEN`: the bot token the Hermes gateway already loads — reused\n  for live Discord reads. `DISCORD_TOKEN` is accepted as a fallback alias for\n  standalone use.\n- `DISCORD_TOOLS_ALLOWED_GUILDS`: optional comma-separated guild allowlist. If\n  unset, Discord access is bounded only by the bot token's existing visibility.\n- `DISCORD_TOOLS_MAX_MESSAGES`: optional default/max message limit, default 100.\n- `DISCORD_TOOLS_MAX_CHARS`: optional result character budget, default 12000.\n- `DISCORD_TOOLS_TIMEOUT_SECONDS`: optional live API timeout, default 20.\n- `DISCORD_TOOLS_STORY_HINTS`: optional inline story hint JSON.\n- `DISCORD_TOOLS_STORY_HINTS_JSON`: optional inline story hint JSON or path to a\n  local JSON file.\n- `DISCORD_TOOLS_STORY_THREADS_JSON`: optional inline JSON (or path to a local\n  JSON file) listing preconfigured story threads for `discord_read_story`, e.g.\n  `[{\"name\":\"House of Tea\",\"thread_id\":\"123456789012345678\",\"aliases\":[\"bea\"]}]`.\n- `DISCORD_TOOLS_STORY_THREAD_ID`: optional single story thread ID for\n  `discord_read_story` when only one story is needed.\n\n## Shared helper\n\nFor new tools or substantial schema/registration rewrites, prefer\n[`hermes-plugin-kit`](https://github.com/offendingcommit/hermes-plugin-kit) so\nHermes tool schema, handler, validation, logging, and JSON-envelope conventions\nstay consistent.\n\n## Validation\n\n```bash\nmake install\nmake test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffendingcommit%2Fhermes-plugin-discord-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foffendingcommit%2Fhermes-plugin-discord-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foffendingcommit%2Fhermes-plugin-discord-tools/lists"}