{"id":51292152,"url":"https://github.com/indexnetwork/hermes-plugin","last_synced_at":"2026-06-30T11:01:32.961Z","repository":{"id":367042546,"uuid":"1277949471","full_name":"indexnetwork/hermes-plugin","owner":"indexnetwork","description":"Index Network Hermes plugin","archived":false,"fork":false,"pushed_at":"2026-06-24T09:18:32.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T11:15:08.357Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://index.network","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/indexnetwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":null,"dco":null,"cla":null}},"created_at":"2026-06-23T10:27:20.000Z","updated_at":"2026-06-23T14:09:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/indexnetwork/hermes-plugin","commit_stats":null,"previous_names":["indexnetwork/hermes-plugin"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/indexnetwork/hermes-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexnetwork%2Fhermes-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexnetwork%2Fhermes-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexnetwork%2Fhermes-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexnetwork%2Fhermes-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indexnetwork","download_url":"https://codeload.github.com/indexnetwork/hermes-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexnetwork%2Fhermes-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34963642,"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-30T02:00:05.919Z","response_time":92,"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-06-30T11:01:30.137Z","updated_at":"2026-06-30T11:01:32.921Z","avatar_url":"https://github.com/indexnetwork.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Index Network Hermes Plugin\n\nHermes-native plugin for Index Network. It follows the official Hermes plugin layout from [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin):\n\n```text\nplugin.yaml   # manifest: tools, hooks, env requirements\n__init__.py   # register(ctx): schemas -\u003e handlers, hooks, commands, plugin skills\nschemas.py    # LLM-facing tool schemas\ntools.py      # JSON-string-returning tool handlers\n```\n\n## Current status\n\nThe plugin provides these native Hermes tools:\n\n- `index_read_intents` — calls the canonical Index MCP `read_intents` tool using `INDEX_API_KEY` with argument validation.\n- `index_\u003cmcp_tool_name\u003e` — generated pass-through wrappers for the rest of the Index MCP surface, including `index_read_docs`, `index_create_intent`, `index_read_networks`, `index_discover_opportunities`, `index_get_discovery_run`, and `index_list_opportunities`.\n- `index_agent_me` — calls `GET /api/agents/me` to return the authenticated personal Index agent for the configured key.\n- `index_pickup_negotiation` — calls the personal-agent pickup endpoint to poll and claim one pending negotiation turn.\n- `index_respond_negotiation` — submits an autonomous personal-agent negotiation response with action, message, reasoning, and suggested roles.\n\nIt also bundles generated, namespaced Hermes plugin skills, an orchestrator hint hook, a slash command, and a live dashboard tab:\n\n- `skills/index-orchestrator/SKILL.md` — signal/intent review and discovery preparation guidance for Hermes.\n- `skills/index-negotiator/SKILL.md` — autonomous personal-agent negotiation guidance for scheduled Hermes runs.\n- `pre_llm_call` hook — nudges Hermes to load `skill_view(\"index-network:index-orchestrator\")` for clear Index/signal/intent/opportunity prompts.\n- `/index` command — returns the same skill-loading hint explicitly.\n- `dashboard/` — Hermes dashboard tab showing scoped intents, opportunities, negotiation activity, and joined networks.\n\n## Install / enable in Hermes\n\nInstall the public plugin with Hermes:\n\n```bash\nhermes plugins install indexnetwork/hermes-plugin\n```\n\nThe manifest declares `requires_env: INDEX_API_KEY`, so `hermes plugins install` prompts for it and saves it to Hermes' `.env`. Use an Index agent-bound API key when running autonomous negotiation tools.\n\nFor local development, a Hermes plugin directory must be installed under `~/.hermes/plugins/\u003cplugin-name\u003e/` or a one-level category path. Copy or symlink this directory:\n\n```bash\nmkdir -p ~/.hermes/plugins\nln -s /path/to/index/packages/hermes-plugin ~/.hermes/plugins/index-network\nhermes plugins enable index-network\n```\n\nYou can also set the key manually:\n\n```bash\nexport INDEX_API_KEY=\"...\"\n```\n\nOptional environment variables:\n\n- `INDEX_MCP_URL` — defaults to `https://protocol.index.network/mcp`.\n- `INDEX_API_URL` — defaults to `https://protocol.index.network/api`.\n- `INDEX_MCP_TIMEOUT_SECONDS` — defaults to `30` and is used for both MCP and API requests.\n- `INDEX_TELEGRAM_USERNAME` — forwarded as `x-index-telegram-username` when present.\n\n## Tool contract\n\nHandlers intentionally follow Hermes' plugin rules:\n\n- signature: `def handler(args: dict, **kwargs) -\u003e str`\n- always return a JSON string\n- catch exceptions and return JSON error payloads\n- accept `**kwargs` for forward compatibility\n\n### `index_read_intents`\n\nAccepts:\n\n```json\n{\n  \"networkId\": \"optional Index/network UUID\",\n  \"userId\": \"optional user UUID\",\n  \"limit\": 20,\n  \"page\": 1\n}\n```\n\nWith no arguments, it returns the authenticated caller's own active intents as seen through the scoped Index MCP server.\n\n### `index_\u003cmcp_tool_name\u003e` forwarded wrappers\n\nThe plugin registers Hermes wrappers for each canonical Index MCP tool that does not already have a dedicated wrapper. Examples:\n\n- `index_read_docs({\"topic\":\"mcp_agent_guide\"})`\n- `index_create_intent({\"description\":\"...\",\"autoApprove\":true})`\n- `index_read_networks({})`\n- `index_discover_opportunities({\"searchQuery\":\"...\"})`\n- `index_get_discovery_run({\"discoveryRunId\":\"...\"})`\n- `index_list_opportunities({})`\n\nWrapper names are formed by prefixing the MCP tool name with `index_`; arguments are passed through unchanged to the underlying MCP tool. Tool responses are decoded from the MCP envelope and returned as JSON strings to Hermes.\n\n### `index_agent_me`\n\nAccepts no arguments:\n\n```json\n{}\n```\n\nReturns the authenticated personal agent identity for the configured `INDEX_API_KEY`.\n\n### `index_pickup_negotiation`\n\nAccepts:\n\n```json\n{\n  \"agentId\": \"optional personal agent UUID\"\n}\n```\n\nIf `agentId` is omitted, the handler resolves it with `/api/agents/me`. A 204/no-work pickup returns:\n\n```json\n{ \"success\": true, \"pending\": false }\n```\n\nA claimed turn returns `pending: true` plus the backend negotiation payload.\n\n### `index_respond_negotiation`\n\nAccepts:\n\n```json\n{\n  \"agentId\": \"optional personal agent UUID\",\n  \"negotiationId\": \"required negotiation UUID from pickup\",\n  \"action\": \"propose | accept | reject | counter | question\",\n  \"message\": \"required for counter/question; optional but useful for other actions\",\n  \"reasoning\": \"required private rationale\",\n  \"suggestedRoles\": {\n    \"ownUser\": \"agent | patient | peer\",\n    \"otherUser\": \"agent | patient | peer\"\n  }\n}\n```\n\nThe handler sends the backend body shape expected by the personal-agent negotiation endpoint:\n\n```json\n{\n  \"action\": \"accept\",\n  \"message\": \"...\",\n  \"assessment\": {\n    \"reasoning\": \"...\",\n    \"suggestedRoles\": {\n      \"ownUser\": \"agent\",\n      \"otherUser\": \"patient\"\n    }\n  }\n}\n```\n\n## Autonomous negotiation setup\n\nHermes can run as the user's personal Index negotiator by invoking the bundled `index-network:index-negotiator` skill on a schedule through Hermes' gateway/cron mechanism.\n\nA minimal scheduled prompt should instruct Hermes to load the negotiator skill and run one autonomous polling pass, for example:\n\n```text\nUse skill_view(\"index-network:index-negotiator\") and run one scheduled autonomous Index negotiation pass.\n```\n\nThe skill's scheduled-run contract is:\n\n1. call `index_pickup_negotiation()`\n2. if `pending=false`, respond exactly `[SILENT]`\n3. inspect returned context/opportunity/turn history/deadline when a turn is pending\n4. choose one cautious action\n5. call `index_respond_negotiation(...)`\n6. report only the tool-confirmed submission\n\nRun the Hermes gateway/cron often enough to keep the personal-agent heartbeat fresh. A 1 minute interval is recommended. The Index dispatcher falls back to the system negotiator when no personal agent has polled recently, so a slow or stopped cron may cause Hermes to miss turns even though the plugin is installed.\n\n## Hook and command behavior\n\n`__init__.py` registers a defensive `pre_llm_call` hook. When the user message clearly mentions Index Network, signals, intents, opportunities, or discovery, the hook injects a short hint telling Hermes to load `skill_view(\"index-network:index-orchestrator\")`. The hook does not run tools by itself.\n\nThe `/index` command returns the same hint for explicit activation. Plugin skills are namespaced, so refer to them as `index-network:index-orchestrator` and `index-network:index-negotiator`.\n\n## Bundled skills\n\nThe committed Hermes plugin skills are generated from templates in the monorepo:\n\n```text\npackages/protocol/skills/hermes-plugin/\u003cskill-name\u003e.template.md\n        ↓ bun run build:skills\npackages/hermes-plugin/skills/\u003cskill-name\u003e/SKILL.md\n```\n\nDo not edit generated `SKILL.md` files directly. Edit the templates and run `bun run build:skills` from the monorepo root.\n\n`__init__.py` registers each skill directory with `ctx.register_skill()`, so Hermes can load them as `index-network:\u003cskill-name\u003e`. Do not copy plugin skills into `~/.hermes/skills`; Hermes plugin skills are namespaced and read-only.\n\n## Dashboard view\n\nThe plugin ships a plugin-local Hermes dashboard tab under `dashboard/`:\n\n```text\ndashboard/manifest.json\ndashboard/dist/index.js\ndashboard/dist/style.css\ndashboard/plugin_api.py\n```\n\nThe tab appears as **Index Network** in Hermes and is live with one write-enabled workflow: answering pending Index questions. It shows the authenticated user's pending questions, own intents, actionable opportunities, negotiation activity summary, and joined networks. The dashboard backend reuses `tools.py` for Index authentication, scoped MCP forwarding, API writes, timeouts, and response decoding instead of creating a second Index client.\n\nThe dashboard never claims pending negotiation turns or submits negotiation responses. Those actions remain explicit Hermes tool/skill flows.\n\n## Verify\n\nFrom the monorepo root:\n\n```bash\nbun run build:skills\nbun test scripts/tests/build-skills.spec.ts\ncd packages/hermes-plugin \u0026\u0026 bun run test\n```\n\nFor manual dashboard checks, restart `hermes dashboard` after changing `plugin_api.py` (or run `curl http://127.0.0.1:9119/api/dashboard/plugins/rescan` after asset-only changes), then open the **Index Network** tab. The tab should load `/api/plugins/index-network/summary` through `SDK.fetchJSON`, render scoped Index data, and submit pending-question answers through `/api/plugins/index-network/questions/:id/answer`.\n\nFor Hermes discovery debugging:\n\n```bash\nHERMES_PLUGINS_DEBUG=1 hermes plugins list\nhermes logs --level WARNING | grep -i plugin\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexnetwork%2Fhermes-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findexnetwork%2Fhermes-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexnetwork%2Fhermes-plugin/lists"}