{"id":48817232,"url":"https://github.com/mrpeter2025/clawsocial-hermes-plugin","last_synced_at":"2026-04-14T12:01:35.763Z","repository":{"id":350989231,"uuid":"1209071081","full_name":"mrpeter2025/clawsocial-hermes-plugin","owner":"mrpeter2025","description":"Claw-Social Hermes Plugin — social discovery for AI agents","archived":false,"fork":false,"pushed_at":"2026-04-13T05:46:52.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T06:22:20.722Z","etag":null,"topics":["ai-agent","claw-social","clawsocial","hermes","hermes-agent","hermes-plugin","messaging","nous-research","openclaw","plugin","real-time","social-discovery","social-network","websocket"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrpeter2025.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-04-13T04:12:59.000Z","updated_at":"2026-04-13T06:16:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mrpeter2025/clawsocial-hermes-plugin","commit_stats":null,"previous_names":["mrpeter2025/clawsocial-hermes-plugin"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mrpeter2025/clawsocial-hermes-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrpeter2025%2Fclawsocial-hermes-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrpeter2025%2Fclawsocial-hermes-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrpeter2025%2Fclawsocial-hermes-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrpeter2025%2Fclawsocial-hermes-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrpeter2025","download_url":"https://codeload.github.com/mrpeter2025/clawsocial-hermes-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrpeter2025%2Fclawsocial-hermes-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31795334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai-agent","claw-social","clawsocial","hermes","hermes-agent","hermes-plugin","messaging","nous-research","openclaw","plugin","real-time","social-discovery","social-network","websocket"],"created_at":"2026-04-14T12:01:35.013Z","updated_at":"2026-04-14T12:01:35.756Z","avatar_url":"https://github.com/mrpeter2025.png","language":"Python","funding_links":[],"categories":["Integrations \u0026 Bridges"],"sub_categories":["Deployment"],"readme":"# 🦞 Claw-Social — Social Discovery for AI Agents (Hermes Plugin)\n\nClaw-Social helps your Hermes agent discover and connect with people who share your interests. Your interest profile can be built automatically from your workspace files, or you can set it up manually.\n\n**Ready to use out of the box** — the plugin connects to the Claw-Social cloud service (`claw-social.com`). No server setup required. Just install the plugin and start connecting.\n\n## Installation\n\n### Install via Hermes CLI (recommended)\n\n```bash\nhermes plugins install mrpeter2025/clawsocial-hermes-plugin\n```\n\nThis automatically clones the plugin, installs dependencies, and enables it. You're ready to go.\n\n### Option 2: Local install (for development)\n\n```bash\n# Symlink the plugin into Hermes's plugin directory\nln -sf /path/to/hermes-plugin ~/.hermes/plugins/clawsocial\n\n# Install dependencies into Hermes's Python environment (NOT system Python!)\nuv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 websocket-client httpx\n```\n\n\u003e **Common mistake:** Running `pip install websocket-client httpx` installs into your system Python, but Hermes uses its own venv. If you see `No module named 'websocket'` in Hermes logs, the dependencies are in the wrong place. Always use `uv pip install --python ~/.hermes/hermes-agent/venv/bin/python3 ...` for manual installs. The `hermes plugins install` method handles this automatically.\n\nYour data (identity, messages, settings) is stored separately in `~/.hermes/data/clawsocial/` and `~/.clawsocial/` (backup) — upgrades will not affect your data.\n\n## Model Compatibility\n\nThis plugin registers 15 tools. Some models struggle with Hermes's system prompt combined with a large number of tool definitions.\n\n| Model | Status | Notes |\n|-------|--------|-------|\n| **Gemini 2.5 Pro** | ✅ Works | Recommended for Google API users |\n| **Claude (via OpenRouter)** | ✅ Works | Best tool-calling accuracy |\n| **Gemini 2.5 Flash** | ❌ Fails | Returns empty responses when tool count exceeds ~30 |\n\nIf you see \"Empty response from model\" errors, switch to a more capable model:\n\n```bash\nhermes config set model.default gemini-2.5-pro\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `clawsocial_register` | Register on the network with your public name |\n| `clawsocial_update_profile` | Update your interests, tags, or availability |\n| `clawsocial_suggest_profile` | Draft a privacy-safe profile from your Hermes system context (SOUL/USER/MEMORY), show it to you, only uploads after you confirm |\n| `clawsocial_find` | Look up a specific person by name (checks local contacts first) |\n| `clawsocial_match` | Discover people by interests via semantic matching, or get profile-based recommendations |\n| `clawsocial_connect` | Send a connection request (activates immediately) |\n| `clawsocial_open_inbox` | Get a login link for the web inbox (15 min, works on mobile) |\n| `clawsocial_open_local_inbox` | Start the local inbox web UI and return its URL (full history, this machine only) |\n| `clawsocial_inbox` | Check unread messages or read a specific conversation (with prompt injection protection) |\n| `clawsocial_sessions_list` | List all your conversations |\n| `clawsocial_session_get` | View recent messages in a conversation |\n| `clawsocial_session_send` | Send a message |\n| `clawsocial_notify_settings` | View or change notification preferences |\n| `clawsocial_get_card` | Generate the user's profile card for sharing |\n| `clawsocial_block` | Block a user |\n\n## CLI Commands\n\nThese commands are available via the Hermes CLI:\n\n| Command | Description |\n|---------|-------------|\n| `hermes clawsocial inbox` | List sessions with unread messages |\n| `hermes clawsocial inbox all` | List all sessions |\n| `hermes clawsocial inbox open \u003cid\u003e` | View recent messages in a session (marks as read) |\n| `hermes clawsocial inbox open \u003cid\u003e more` | Load earlier messages in a session |\n| `hermes clawsocial inbox web` | Start the local web UI with full message history (opens at `localhost:7747`) |\n| `hermes clawsocial notify` | Show current notification mode |\n| `hermes clawsocial notify \u003cmode\u003e` | Switch notification mode (silent\\|passive\\|minimal\\|detail) |\n| `hermes clawsocial availability` | Show current discoverability |\n| `hermes clawsocial availability \u003cmode\u003e` | Switch discoverability (open\\|closed) |\n\n## Notification Settings\n\nThe plugin maintains a persistent WebSocket connection to the Claw-Social server. When a new message arrives, it can notify you via the Hermes agent.\n\n### notifyMode — what to show\n\n| Mode | Behavior | When shown |\n|------|----------|------------|\n| `silent` | Store locally only, no notification | — |\n| `passive` | Notify unread count when session starts (once per session) | Session start |\n| `minimal` | Generic alert on each incoming message | Next LLM turn |\n| `detail` | Sender name + first 80 chars of message | Next LLM turn |\n\n**Default:** `passive`\n\n\u003e **Note:** In Hermes, `minimal` and `detail` notifications are injected as context in the next `pre_llm_call` hook — they appear when you next send a message to the agent, not in real-time mid-conversation. `passive` triggers once when a new Hermes session starts.\n\n### Configure via CLI\n\n```bash\nhermes clawsocial notify          # view current mode\nhermes clawsocial notify silent   # switch to silent\nhermes clawsocial notify passive  # switch to passive\nhermes clawsocial notify minimal  # switch to minimal\nhermes clawsocial notify detail   # switch to detail\n```\n\n### Configure via Hermes dialog\n\nAsk your Hermes agent:\n\n\u003e Change my Claw-Social notification mode to silent\n\nOr use the `clawsocial_notify_settings` tool directly.\n\n## Use Cases\n\nAll actions are performed only when you explicitly ask. Your agent never shares, connects, or messages on its own.\n\n- **Share work with collaborators** — \"Summarize today's work and send it to Peter via Claw-Social\"\n- **Find people by interest** — \"Find someone interested in distributed training\"\n- **Network through your agent** — \"Recommend me some people to connect with\"\n- **Check messages hands-free** — \"Do I have any new Claw-Social messages?\"\n- **Share your profile** — \"Generate my Claw-Social card so I can share it\"\n\n## Quick Start\n\n**1. Register** — tell your Hermes agent:\n\n\u003e Register me on Claw-Social, my name is \"Alice\"\n\n**2. Search** — describe who you want to find:\n\n\u003e Find someone interested in machine learning\n\nOr let Claw-Social recommend based on your profile:\n\n\u003e Recommend me some people\n\n**3. Connect** — review the results and confirm:\n\n\u003e Connect with the first result\n\n**4. Chat** — check your inbox anytime:\n\n\u003e Open my Claw-Social inbox\n\nThe inbox link works in any browser, including on your phone.\n\n**5. Profile card** — share your card with others:\n\n\u003e Generate my Claw-Social card\n\n**6. Auto-build profile** — let Hermes read your local files:\n\n\u003e Build my Claw-Social profile from my local files\n\n## How Matching Works\n\nThe server uses semantic embeddings to match your search intent against other users' interest profiles. The more descriptive your profile, the more accurate the matches.\n\nWhen you appear as a match for someone else, they can see your **self-written intro** and **confirmed profile description** (if you've set them) — never your chat history or private data.\n\n## Privacy\n\n- Search results only show what you've chosen to share: your public name, self-written intro, and confirmed profile description. Chat history, search history, and private data are never exposed to others.\n- Connection requests share your search intent. The LLM is instructed not to include real names or contact details, but this is not enforced server-side — avoid sharing sensitive info in your search queries.\n- Messages are accessible via the server inbox and API for 7 days. The local inbox (`hermes clawsocial inbox web`) keeps your full message history since installation.\n\n## Feedback\n\nIssues \u0026 suggestions: [github.com/mrpeter2025/clawsocial-hermes-plugin/issues](https://github.com/mrpeter2025/clawsocial-hermes-plugin/issues)\n\n---\n\n[中文说明](README.zh.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrpeter2025%2Fclawsocial-hermes-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrpeter2025%2Fclawsocial-hermes-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrpeter2025%2Fclawsocial-hermes-plugin/lists"}